match-structure git:20260729.a439653A

Immutable. This exact content never changes and is served at /api/v1/blob/c17468847b8c2f29.

---
name: match-structure
description: >-
  Paragraph and sentence-level style metrics for a research corpus.
  Computes quantitative profiles (sentence/paragraph distributions,
  passive voice, hedging, word/phrase/idiom frequencies, per-section
  metrics), corpus aggregation, term over/underuse comparison, and a
  plagiarism similarity guard (n-gram shingling with baseline exclusion).
  Provides voice anchor retrieval from writing-voice exemplars via tf-idf.
  The section-level driver (compare, blueprint, rewrite) moved to
  match-outline. Triggers: style profile, quantitative metrics, sentence
  stats, frequency tables, plagiarism check, similarity check, voice
  anchors, corpus profile, word frequency.
---

*Split from the original match-structure (GH-291, 2026-07): the
section-level driver (compare, blueprint extraction, section-by-section
rewrite) moved to `match-outline`. This skill retains the quantitative
metrics engine, corpus aggregation, frequency analysis, and the similarity
guard that other prose skills import.*

# Match structure (paragraph/sentence-level metrics)

This skill provides the quantitative style measurement layer that other
prose skills depend on. It profiles markdown papers at the sentence and
paragraph level — distributions, passive voice, hedging, citation density,
word and phrase frequencies, stock idiom usage — and aggregates those into
a corpus profile. It also provides the similarity plagiarism guard used by
`match-outline`'s rewrite mode and `match-voice`'s verify step.

## Where things live

- **Corpus:** `<db-dir>/papers/*.md` — the markdown conversions fetched by
  `update-references`, selected via entries in `references.yaml`. Default
  selection is entries with `status: summarized`; pass `--all` to `style.py
  corpus` to include every entry with an `md_path`.
- **Quantitative profile:** `<db-dir>/voice-profile.json`, written by
  `style.py corpus`. Regenerate only when the corpus changes.
- **Voice anchors:** passage-level tf-idf retrieval from `writing-voice/`
  exemplars, via `voice_anchors.py`.
- **Venue profiles:** `writing-voice/venues/<name>.yaml` — per-venue parameter
  bundles (anchor query, blueprint, targets, tell lexicon, gates) consumed by
  humanize/filter-tells/tighten-style. Schema in the `writing-voice` repository
  rule; loader/validator is `venue_profile.py`.

## Running the scripts

```bash
RUN="pixi run --manifest-path <skill>/../../pixi.toml python"
```

## style.py subcommands

```bash
$RUN <skill>/scripts/style.py --db <db-path> profile <paper.md>   # one paper, full JSON
$RUN <skill>/scripts/style.py --db <db-path> corpus                # aggregate, write voice-profile.json
$RUN <skill>/scripts/style.py --db <db-path> compare <draft.md>    # metric deltas vs corpus
$RUN <skill>/scripts/style.py freq <paper.md>                      # frequency tables only
$RUN <skill>/scripts/style.py similarity <file> --against <sources> [--baseline <draft>]
```

## voice_anchors.py subcommands

```bash
$RUN <skill>/scripts/voice_anchors.py discover <file>
$RUN <skill>/scripts/voice_anchors.py profile [--voice-dir D | --for file] [--force]
$RUN <skill>/scripts/voice_anchors.py anchors --text <file>|- [--for file] [-k N] [--role R]
```

## venue_profile.py subcommands

```bash
$RUN <skill>/scripts/venue_profile.py discover <file>            # find venues/ via walk-up
$RUN <skill>/scripts/venue_profile.py list --for <file>          # available venue names
$RUN <skill>/scripts/venue_profile.py show --venue N --for <file> # validated profile JSON
$RUN <skill>/scripts/venue_profile.py validate <profile.yaml>
$RUN <skill>/scripts/venue_profile.py bootstrap --voice-dir D --tags a,b [--role R] [--stratum pre-ai]
$RUN <skill>/scripts/venue_profile.py bootstrap --voice-dir D --tags a,b --venue N --write
$RUN <skill>/scripts/venue_profile.py set-anchors --venue N --voice-dir D --arm "tags~clipped" [--composite X]
```

Python consumers import `venue_profile.resolve(start_path=..., venue=...)`,
which raises on schema errors — a broken profile is refused, never partially
applied.

`bootstrap` (GH-339) measures a corpus slice — a manifest query
(role/tags/stratum) or an explicit `--files` list — with the same metric
engine as `style.py corpus`, and emits the profile's
`targets`/`targets_std`/`targets_provenance` block; `--write` merges it into
an existing `venues/<name>.yaml` (author the profile first). Profiles are
measured, never hand-written. `set-anchors` records an anchor query into a
profile with provenance — from tune-anchors arm expressions (repeatable
`--arm`, parsed by tune-anchors' own parser so the syntax cannot drift) or
from explicit `--role/--tags/--stratum/--author` flags.

## Consumers

- **match-outline** — imports `style` for corpus selection, the similarity
  guard, and the `CITATION_RE` pattern. Uses `gpt-oss:120b-cloud` via
  Ollama for whole-document structural rewriting.
- **match-voice** — imports `style.similarity_report` for the rewrite
  verification gate; imports `voice_anchors` for anchor retrieval.
- **filter-tells** — consumes `voice-profile.json` as a detector input
  (`--voice-profile=<path>`); uses `voice_anchors.py` for anchor retrieval
  and baseline profiling.
- **tighten-style** — imports `style` for nominalization density metrics.
- **tune-anchors** — imports `voice_anchors` for the anchor tuning workflow.

## Dependencies

`style.py` is stdlib-only except PyYAML. `voice_anchors.py` uses PyYAML.
No model calls — this is the deterministic half of the analysis pipeline.