Step 6 - Run a campaign

Goal: establish the corpus - document every unit your config declares, each doc validated and stamped, in one orchestrated run.

You have a config and an empty corpus. A campaign fills it: it derives the worklist from the CLI, documents each unit through the full loop, and verifies the result mechanically. You kick it off with one utterance; the agent does the rest.

What one unit's loop is

Every unit goes through the same five steps - this is the loop the campaign runs per unit, and the same loop that runs when you document a single unit directly:

alloy generate <kind>/<name>   →  context bundle          (deterministic)
agent writes the doc           →  markdown                (probabilistic)
alloy validate <doc home>      →  8 gates pass or it goes back
you review & merge             →  the only path into the corpus
alloy stamp <kind>/<name>      →  provenance written, only now

Two guards inside that loop are worth knowing, because they are what stop a hollow doc:

• The context bundle must carry at least two code input files. Fewer means a rule pack is not reaching the unit's source, so the agent stops and reports rather than authoring over nothing.
• alloy stamp re-runs the gate and refuses to write provenance if it fails. Provenance asserts a doc was verified against its source; a doc that does not pass the gate has not been.

Run the campaign

First, sanity-check the denominator:

alloy discover               # every documentable unit your config declares

Then hand off to the alloy-campaign skill. In your agent:

run the corpus campaign

The skill orchestrates:

1. Derives the worklist from alloy status --json and alloy discover - undocumented units to author, drifted units to re-author. It never hardcodes a unit list; the CLI is authoritative.
2. Asks you the scope if you did not name one - everything remaining (resumable), one wave (one kind), or a sample of one unit per kind as a trial. It prints the resolved unit list and count and confirms before spending tokens.
3. Fans out one worker per unit, at most six at a time, each running the per-unit loop above on its one target.
4. Verifies from stamps, never from a worker's self-report. A unit is done only if its docs carry source_ref: frontmatter - written solely by alloy stamp. A unit that authored but failed to stamp is caught by a dedicated sweep and re-dispatched once.
5. Finalizes the maps - alloy finalize <source> regenerates each category's navigational map from the router frontmatter the docs carry. It is LLM-free and byte-stable.

Because stamps are the state and there is no separate state file, resume is just running the campaign again: it re-derives the worklist and skips everything already stamped.

Scope it the first time

For a first run, a sample (one unit of each kind) is a good trial - it surfaces a bad rule pack or a hollow-bundle problem cheaply, before you spend the whole run. Then go to everything remaining once the sample looks right.

When the wave finishes

The skill reports units stamped (grouped by kind), every validator warning (each is a mandatory read), gap-marker counts per unit, and any unit that tripped the two-files guard. Then it hands you the residue - the judgment steps it never runs:

alloy validate .alloy/corpus     # 0 failed over the whole corpus, including map integrity

Review the docs, then commit them (the campaign never commits). Repeat per wave until alloy status shows every unit documented and fresh.

Next: step 7 - Add curated docs.