# Maintain these docs with a Hankweave pipeline
This manual maintains itself. The pages you are reading were produced, reviewed and repaired by Hankweave hanks, and the pipeline that did the work is the most complete production example we have. This page turns that history into something you can use: a runnable anchor hank to inspect, the generated machinery that came before it, the fixed programs that replaced it, and the invocation and recovery details you need to run docs-maintenance work yourself.
The path through the page follows the decisions, not the chronology. We start with a small hank you can run today, then look at the older generated pipeline to see why its boundaries exist, then show how to pick the smallest correct job for a page that already exists. The last two sections cover running a hank from the command line and recovering from the failures we actually observed while building this edition.
## Work from a real production run
The workflow changed as we used it. We began with a serial pilot that produced a few briefs, generated larger hanks for page batches, then moved to fixed programs with smaller repair and review paths. The accepted 0.10.0 edition has 70 pages. Getting there required source checks, reader corrections and retained intermediate work; it was not one uninterrupted run.
The table below records the shapes we tried and the boundary each one taught us. Read it as a map of the rest of the page: each row corresponds to machinery you will see in an exhibit later.
| Recorded shape | What we learned to separate |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| September 1, 2026: C1 v0.1.x, C2 v0.2.0, C3 v0.3.0 | Facts before prose; independent review; page-time errata returned to briefs. |
| September 2–3: generated waves | The manifest, compiler and orchestrator selected and launched stage-specific shards. Work within a shard still ran in order. |
| September 4: v2's first four fixed hanks | Grounding, briefs, cross-page checks and page writing became reusable programs with selected work supplied as data. |
| September 7–8: narrower follow-on jobs | A retained draft could receive a bounded repair or finish its interrupted review; editing and figures remained separate candidates until final verification. |
In this example, we borrow the boundaries that made that work manageable. We will inspect a runnable anchor hank, look at the historical generated program, then choose which fixed v2 job a piece of documentation actually needs. The [full production history](/contribute/documentation-pipeline) follows the chronology in more detail. The [patterns gallery](/author/patterns/gallery) owns the broader adapting examples.
The older forge had a below-briefs half – resolve, snapshot, fixture recapture, extraction and impact – followed by compiled brief, cross-pass, page, errata and journey stages and `render.py`. Those names describe the historical machinery excerpts below. Each writing stage used Hankweave hanks; the Python orchestrator did not replace the runtime.
**Check-it:** Compare the compiled polish loop later in this example with the fixed-program diagram under *Choose the next job for an existing page*. The former repeats work over a page list; the latter lets us retain a completed candidate and select its next job.
> **Pitfall:** Do not invoke `bunx hankweave@0.10.0` without arguments when you mean to run a hank. That invocation launches the welcome wizard and exits. Pass explicit positional arguments.
## Use the anchor hank as your model
Let's start with a complete example we can run and inspect: `quote-template-unification`. Its seven codons handle eight quoting suppliers – three digitizer dialects and five native extracts – quarantine the unknown `GRN` intake, reconcile 40 supplier-part rows and publish a cited award brief. Extraction, judgment, checks and human-facing output appear as separate jobs, which is exactly the property we want to study. Its award brief is the final cited output, unlike the docs-forge's per-page planning briefs.
For each boundary, we ask three questions together: does the model tier change, does the failure policy change, or is this an artifact a person may want to inspect? We keep mechanical extraction separate from deduplication, alias resolution and exception routing. Those judgments deserve a named step where we can review them.
The excerpt below shows the first codon of the shipped `hank.json`. Notice that it is deliberately narrow: one dialect, a mechanical prompt, a small budget, and `onFailure: "abort"` because there is nothing to judge.
```json
"id": "normalize-aster",
"name": "Normalize Aster (Datalab dialect)",
"model": "haiku",
"continuationMode": "fresh",
"description": "Mechanical extraction of both Aster submissions (original + rev2) into canonical envelope objects. No judgment: dedup, alias resolution, and validity checks happen downstream.",
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline"
}
},
{
"type": "copy",
"copy": {
"from": "rigs/preflight.ts",
"to": "pipeline/preflight.ts"
}
},
{
"type": "command",
"command": {
"run": "bun pipeline/preflight.ts"
}
}
],
"promptFile": "prompts/normalize-aster.md",
"checkpointedFiles": [
"envelope-aster.json"
],
"outputFiles": [
{
"copy": [
"envelope-aster.json"
]
}
],
"onFailure": "abort",
"budget": {
"maxTimeSeconds": 240,
"maxDollars": 0.5,
"onExceeded": "fail"
}
},
```
We leave the checksum-and-shape preflight to `rigs/preflight.ts`, before the first codon spends tokens. There is no benefit in paying an agent to re-decide a checksum.
The boundary-drill excerpt below is a historical design note explaining why deduplication was kept out of that codon. Its checklist is useful, but its older scope and model names are not the current anchor contract; use the shipped `hank.json` excerpt and README contract for current behavior.
```text
…
**Aster's dedup decision: kept out of `normalize-aster`, on purpose.** `normalize-aster` extracts *both* Aster documents without picking a winner, even though the rev2 envelope's `supersedes` field makes "which one wins" almost mechanical. This is a deliberate application of question (2): dedup-conflict detection is a judgment/policy decision (which one wins, and is the conflict worth surfacing to a human) that belongs with `validate-and-repair`'s other exception-routing logic, not with mechanical extraction. Folding it into `normalize-aster` would have made that codon's failure policy inconsistent with its siblings (`normalize-beacon`/`normalize-cedar` truly can't fail on judgment) and would have hidden the conflict from the one codon whose job is to decide what's exception-worthy.
```
From the anchor-hank directory, we prepare the corpus, validate the hank and start a fresh run:
```sh
python3 ../verify.py prepare-data ../quote-template-unification task-data
bunx hankweave@0.10.0 hank.json task-data --validate
bunx hankweave@0.10.0 hank.json task-data --headless --start-new --execution exec --max-cost 9 --shim-idle-timeout 1800 --overwrite-output -o out
```
```text
## Program and output contracts
Seven codons run in order, without loops:
1. `normalize-aster`, `normalize-beacon`, `normalize-cedar`: `haiku`; preserve the three digitizer dialects in canonical envelopes.
2. `survey-and-extracts`: its `rigs/native-inputs.ts` setup deterministically parses five native exports and initializes an incomplete intake survey. The `haiku` agent inspects unmatched raw intake and completes the quarantine decisions. The step exports five envelopes plus `survey-notes.json`.
3. `validate-and-repair`: `pi/baseten/deepseek-ai/DeepSeek-V4-Pro`; setup requires byte-identical native envelopes and a completed survey before model work. The agent validates all eight suppliers and routes hazards to `exception-ledger.json`.
4. `reconcile`: the same Baseten model; writes 40 supplier-part rows. Its budget uses `onExceeded: "fail"`, so a budget stop cannot certify a truncated table.
5. `award-brief`: setup runs `rigs/render-award.ts` to generate cited financial recommendations from `unified-records.csv`; `haiku` completes only the qualitative assessment. `rigs/render-exceptions.ts` remains the lossless ledger-to-CSV renderer. The output-copy hook runs both source-based checks before exporting.
The codon caps sum to $9.00; this is a configured ceiling, not a predicted bill. The command above also requests a $9 global maximum. Some non-reconcile codons use `onExceeded: "complete"`; a zero process exit is therefore insufficient evidence of complete artifacts. Run the deterministic check.
The `quality-observer` sentinel receives only completion events. Its log can discuss fields present in those events. It cannot inspect files, prove row coverage, or infer missing files from absent `file.updated` events. Artifact checks belong to `verify.py`.
```
The README contract in that block is the part to read carefully. It states the seven-codon order, which steps are deterministic and which use a model, and why a zero process exit is not sufficient evidence of complete artifacts when some codons use `onExceeded: "complete"`.
**Check-it:** Confirm that the validation command in the sequence above reports `GOOD TO RUN!` before any codon starts. Validation is a configuration and path check; it does not prove that credentials or provider health will work.
Afterward, we use the deterministic checker for the embedded output contract. A successful process exit alone does not tell us whether the artifacts are complete.
The September 6, 2026 capture recorded $0.88 in tracked codon cost. Keep that receipt separate from the $9.00 configured ceiling and the older $2.41 Sonnet run (September 2) and $0.64 policy-model run (September 3–4). They describe different attempts, not a fixed price for the example.
For contrast, here is the smallest useful hank – the quickstart fixture:
```json
{
"$schema": "https://unpkg.com/hankweave@0.10.0/schemas/hank.schema.json",
"meta": {
"name": "Minimal single provider",
"version": "1.0.0",
"description": "The smallest useful hank: one codon, one provider key, one output file. The quickstart's fixture."
},
"hank": [
{
"id": "summarize-notes",
"name": "Summarize the notes",
"model": "haiku",
"continuationMode": "fresh",
"promptFile": "./prompts/summarize.md",
"checkpointedFiles": ["summary.md"],
"outputFiles": [ { "copy": ["summary.md"] } ]
}
]
}
```
One codon, one provider key and one output file. We split the anchor because normalization, validation and repair, reconciliation, observation and rendering have different policies and artifacts worth inspecting. We do not need that many steps merely to call a model once.
## Follow the docs-forge pipeline
With the anchor's boundaries in mind, the historical docs-forge is easier to read: it is the same discipline applied at the scale of a whole manual. We built the forge incrementally too: extraction first, a pilot trio next, then concurrent shards. The September 2 snapshot had a 69-page manifest with 39 pages built; the first complete set on September 3 had 70. A compiler generated each stage's codons, models, budgets and sentinels from the selected page list. The old counts are milestones, not the size of the accepted edition today.
We changed model assignments as runs gave us evidence. The historical ladder used `glm-5.3` for vetting, mining and briefs, `deepseek-v4-flash` and `glm` for extraction, `DeepSeek-V4-Pro` for brief shards and ownership passes, and `Kimi-K3` for cross-family review. "Never sonnet" was our forge cost policy, not a Hankweave runtime rule.
We kept fact gaps out of prose by routing them to `checks/brief-errata.md`. The deterministic embed renderer checked directives rather than asking writers to type generated material. Before launch, the orchestrator validated the shards and enforced clean-tree and provider-concurrency rules; afterward, it collected outputs and saved resumable state. The September 2 log says Baseten 2, while the later handoff says 3. These are dated settings, not a current default to copy into your pipeline.
The supplied docs-maintenance fixture was captured on September 4 from that v1 workflow. Its `start_here.md` handoff dates itself September 2, so we use it to inspect machinery rather than infer publication status. The compiled polish hank below is real: a two-iteration loop containing 16 per-page polish codons, followed by an assertion codon. Its rigs copy reader lint and directive guards before work; the final assertion reruns the guards. The accompanying acceptance script has ten deterministic checks and makes no model calls.
The log excerpt below records the day the pipeline became one command. Skim it for the component list – manifest, compiler, orchestrator, renderer, impact gate – rather than for the counts, which describe that day's state.
```text
…
Goal restated by Hrishi: forget publishing; build the repeatable machine: input = a runtime version + the existing docs set, output = a new markdown set (examples, full snippets, schemas, ASCII diagrams). Cheap ladder (glm / Kimi / deepseek-flash) for building. Never sonnet (standing).
What landed (all under `runner/`, every piece run for real today):
- `pages.json` (built by `build-manifest.py`): the single page manifest — 69 pages, each with id/section/quadrant/type, harvest sources, brief hints, **deps** (lock surfaces, schemas, source files, generated tables, fixtures), a **diagram slot**, wave, and on-disk status. 39 done, 30 pending (wave 4).
- `compile.py `: the one compiler (retires gen-wave1/2/3). Stages: `briefs` (per-brief writers + cross-family per-brief reviews + merge + repair, sharded), `xpass` (ownership/consistency vs every precedent brief), `pages` (luna writers + lint rig + embed rig + per-page Kimi reviews + merge + 3-model cold-read panel + repair under the durability rule), `errata` (research + apply to briefs), `journeys` (site-level crosslinks + reachability). Model policy in one dict; sonnet asserted absent.
- `forge.py run --wave N`: the orchestrator. Stages data (swap-atomic), compiles, validates (`--validate` GOOD TO RUN), commits (clean-tree law), launches shards concurrently under a **machine-wide per-provider-family cap** (Baseten 2, zai 1 — learned at 15:57 when four Baseten shards 429'd within two minutes), polls, collects artifacts into `results//`, records `state.json` (resumable; `--recover` rebuilds from run dirs if the orchestrator dies), reports spend per shard.
- `hank/shared/render-embeds.ts`: the deterministic embed renderer/verifier. 237 directives found across the 39 pages: 139 SPEC (writer-rendered generation specs), 22 VERIFIED mechanical, 6 DRIFT (paraphrased captures — real fidelity bugs), 5 MISSING (brief aliases used as paths), 10 PENDING (honest placeholders). Directive contract added to the writing guide; report wired into lint -> review -> repair.
- `render.py` (`forge render`): deterministic assembly into `out//docs//.md` — newest canonical page wins, banners/runtime set from the lock, embeds re-derived, links applied, audit (H1, banner, PENDING blocks, diagram slots). Idempotent: identical digest on repeat runs (`a26292998ab6d33a` for the 39-page set).
- `impact.py` (`forge impact --from A --to B`): the change-impact gate. 0.9.0 -> 0.10.0 on real caches: 41 MUST / 22 REGEN / 6 CARRY with per-dependency evidence (help sha, flag sets, init fixture, schema hashes, 21 changed server files).
- `capture-fixtures.sh ` + `forge ground --version V --prev P`: resolve -> snapshot -> fixture re-capture (real runs, oracle for the anchor) -> extraction sandwich -> impact. The below-briefs half of the pipeline as one command (fixture/extract steps untested today beyond dry plumbing).
- `hank/shared/apply-links.ts`: journeys rig — validates every link against the manifest, writes related/next front matter, reports unreachable/orphan pages.
Schema fact learned by validation failure: `retryConfig.delayMs` max is 60000 (`maxDelayMs` may be larger).
```
Running the forge also gave us runtime evidence. The dated findings file has 22 numbered entries (1–14 and 18–25); 13 early reports became upstream issues #223–#235. The remaining findings informed the docs. We keep that count attached to its historical record.
The failures were useful input for [observe and debug](/operate/observe-and-debug): execution reuse, quota stops, budget outcomes and sentinel behavior were things we had actually encountered while producing the manual.
**Check-it:** In the compiler excerpt, find the stage boundaries. In the full compiled hank below, find the `polish` loop and `polish-assert`. The program is long because the compiler emitted a codon for each selected page; it is not the current fixed v2 program.
The two excerpts below are the fixture's own description of the pipeline and one full compiled hank it produced. The hank is included at length on purpose: it shows what "the compiler emits a codon per page" actually looks like, including the repeated rig setup that copies lint and guard scripts before each page's work.
```text
The pipeline is now **manifest -> compiler -> orchestrator -> renderer**, with a change-impact gate for incremental re-runs. Everything below the briefs (resolve, snapshot, fixture captures, extraction) is `forge ground`.
- **Manifest** `pages.json` (built by `runner/build-manifest.py`): 69 pages; per page: `id`, `section`, `quadrant`, `ptype` (authored|generated), `old` (harvest sources), `hints` (brief direction), **`deps`** (what it depends on: `help`, `cli-flags`, `init-fixture`, `schema:`, `source:`, `source-server`, `generated:events|errors`, `fixtures:`, `changelog`, `lock`, `review`, `forge-record`, `why-corpus`), `diagram` (ASCII diagram slot or null), `wave`, and on-disk status. Add a page = add a line to the builder and re-run it.
- **Compiler** `runner/compile.py --wave N [--pages a,b] [--shards k] [--tag t]` emits hank files + codon prompts under `hank/`. Stages: `briefs` (per-brief writer, cross-family per-brief reviewer, merge, repair; sharded), `xpass` (ownership/consistency vs every precedent brief in `data/briefs-done`), `pages` (luna writers, lint rig + embed rig, per-page Kimi reviews, merge, 3-model cold-read panel, repair under the durability rule), `errata` (research facts the pages needed -> apply to briefs), `journeys` (site-level crosslinks + reachability). Model policy is one dict (`MODELS`); sonnet asserted absent; Baseten codons get the long 429 backoff.
```
```json
{
"$schema": "https://unpkg.com/hankweave@0.10.0/schemas/hank.schema.json",
"meta": {
"name": "polish5 polish",
"version": "1.0.0",
"author": "docs-forge compiler",
"description": "Reader-facing polish loop over 16 flagged pages. [families: other]"
},
"globalSystemPromptFile": "./system/system.md",
"overrides": {
"budget": {
"maxDollars": 13.6,
"onExceeded": "fail"
}
},
"hank": [
{
"type": "loop",
"id": "polish",
"name": "Reader-facing polish (up to 2 passes)",
"terminateOn": {
"type": "iterationLimit",
"limit": 2
},
"budget": {
"maxDollars": 9.0,
"maxTimeSeconds": 19200,
"onExceeded": "complete"
},
"codons": [
{
"id": "polish-start-quickstart",
"name": "Polish: start/quickstart",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-start-quickstart/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/start-quickstart.md",
"pages/start-quickstart.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/start-quickstart.md read_only_data_source/pages-wave/start-quickstart.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/start-quickstart.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/start-quickstart.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only start-quickstart >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-start-how-a-run-works",
"name": "Polish: start/how-a-run-works",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-start-how-a-run-works/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/start-how-a-run-works.md",
"pages/start-how-a-run-works.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/start-how-a-run-works.md read_only_data_source/pages-wave/start-how-a-run-works.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/start-how-a-run-works.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/start-how-a-run-works.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only start-how-a-run-works >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-reference-sentinel-config",
"name": "Polish: reference/sentinel-config",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-reference-sentinel-config/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/reference-sentinel-config.md",
"pages/reference-sentinel-config.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/reference-sentinel-config.md read_only_data_source/pages-wave/reference-sentinel-config.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/reference-sentinel-config.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/reference-sentinel-config.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only reference-sentinel-config >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-reference-hankweave-json",
"name": "Polish: reference/hankweave-json",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-reference-hankweave-json/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/reference-hankweave-json.md",
"pages/reference-hankweave-json.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/reference-hankweave-json.md read_only_data_source/pages-wave/reference-hankweave-json.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/reference-hankweave-json.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/reference-hankweave-json.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only reference-hankweave-json >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-concepts-hanks",
"name": "Polish: concepts/hanks",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-concepts-hanks/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/concepts-hanks.md",
"pages/concepts-hanks.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/concepts-hanks.md read_only_data_source/pages-wave/concepts-hanks.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/concepts-hanks.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/concepts-hanks.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only concepts-hanks >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-operate-observability",
"name": "Polish: operate/observability",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-operate-observability/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/operate-observability.md",
"pages/operate-observability.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/operate-observability.md read_only_data_source/pages-wave/operate-observability.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/operate-observability.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/operate-observability.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only operate-observability >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-author-designing-codons-and-handoffs",
"name": "Polish: author/designing-codons-and-handoffs",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-author-designing-codons-and-handoffs/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/author-designing-codons-and-handoffs.md",
"pages/author-designing-codons-and-handoffs.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/author-designing-codons-and-handoffs.md read_only_data_source/pages-wave/author-designing-codons-and-handoffs.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/author-designing-codons-and-handoffs.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/author-designing-codons-and-handoffs.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only author-designing-codons-and-handoffs >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-author-patterns-reliability",
"name": "Polish: author/patterns/reliability",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-author-patterns-reliability/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/author-patterns-reliability.md",
"pages/author-patterns-reliability.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/author-patterns-reliability.md read_only_data_source/pages-wave/author-patterns-reliability.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/author-patterns-reliability.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/author-patterns-reliability.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only author-patterns-reliability >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-author-patterns-completion",
"name": "Polish: author/patterns/completion",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-author-patterns-completion/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/author-patterns-completion.md",
"pages/author-patterns-completion.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/author-patterns-completion.md read_only_data_source/pages-wave/author-patterns-completion.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/author-patterns-completion.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/author-patterns-completion.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only author-patterns-completion >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-author-patterns-composition",
"name": "Polish: author/patterns/composition",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-author-patterns-composition/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/author-patterns-composition.md",
"pages/author-patterns-composition.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/author-patterns-composition.md read_only_data_source/pages-wave/author-patterns-composition.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/author-patterns-composition.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/author-patterns-composition.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only author-patterns-composition >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-author-patterns-gallery",
"name": "Polish: author/patterns/gallery",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-author-patterns-gallery/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/author-patterns-gallery.md",
"pages/author-patterns-gallery.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/author-patterns-gallery.md read_only_data_source/pages-wave/author-patterns-gallery.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/author-patterns-gallery.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/author-patterns-gallery.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only author-patterns-gallery >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-integrate-websocket-quickstart",
"name": "Polish: integrate/websocket-quickstart",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-integrate-websocket-quickstart/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/integrate-websocket-quickstart.md",
"pages/integrate-websocket-quickstart.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/integrate-websocket-quickstart.md read_only_data_source/pages-wave/integrate-websocket-quickstart.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/integrate-websocket-quickstart.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/integrate-websocket-quickstart.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only integrate-websocket-quickstart >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-integrate-protocol",
"name": "Polish: integrate/protocol",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-integrate-protocol/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/integrate-protocol.md",
"pages/integrate-protocol.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/integrate-protocol.md read_only_data_source/pages-wave/integrate-protocol.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/integrate-protocol.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/integrate-protocol.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only integrate-protocol >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-integrate-event-journal",
"name": "Polish: integrate/event-journal",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-integrate-event-journal/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/integrate-event-journal.md",
"pages/integrate-event-journal.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/integrate-event-journal.md read_only_data_source/pages-wave/integrate-event-journal.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/integrate-event-journal.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/integrate-event-journal.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only integrate-event-journal >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-integrate-client-and-exported-types",
"name": "Polish: integrate/client-and-exported-types",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-integrate-client-and-exported-types/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/integrate-client-and-exported-types.md",
"pages/integrate-client-and-exported-types.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/integrate-client-and-exported-types.md read_only_data_source/pages-wave/integrate-client-and-exported-types.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/integrate-client-and-exported-types.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/integrate-client-and-exported-types.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only integrate-client-and-exported-types >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
},
{
"id": "polish-examples-connector-build-test",
"name": "Polish: examples/connector-build-test",
"model": "gpt-5.6-luna",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-examples-connector-build-test/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.6,
"maxTimeSeconds": 1200,
"onExceeded": "complete"
},
"checkpointedFiles": [
"pages/examples-connector-build-test.md",
"pages/examples-connector-build-test.trace.md"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages pages-before pages-best briefs lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/writing-guide.md",
"to": "pipeline/writing-guide.md"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "for d in pages pages-before; do cp -n read_only_data_source/pages-wave/examples-connector-build-test.md read_only_data_source/pages-wave/examples-connector-build-test.trace.md $d/ 2>/dev/null; done; cp -n read_only_data_source/briefs-final/examples-connector-build-test.md briefs/ 2>/dev/null; cp -n read_only_data_source/pages-best/examples-connector-build-test.md pages-best/ 2>/dev/null; true"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --restore --only examples-connector-build-test >> lint/guard.log"
},
"allowFailure": true
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages > lint/reader-report.md || true"
},
"allowFailure": true
}
]
}
]
},
{
"id": "polish-assert",
"name": "Assert reader lint clean",
"model": "deepseek-v4-flash",
"continuationMode": "fresh",
"promptFile": "./codons/polish5-polish-assert/prompt.md",
"onFailure": "retry",
"retryConfig": {
"maxAttempts": 3,
"delayMs": 20000,
"maxDelayMs": 120000
},
"budget": {
"maxDollars": 0.2,
"maxTimeSeconds": 600,
"onExceeded": "complete"
},
"checkpointedFiles": [
"lint/reader-final.md",
"pages/**"
],
"rigSetup": [
{
"type": "command",
"command": {
"run": "mkdir -p pipeline pages lint"
}
},
{
"type": "copy",
"copy": {
"from": "shared/lint-reader.ts",
"to": "pipeline/lint-reader.ts"
}
},
{
"type": "copy",
"copy": {
"from": "shared/guard-directives.ts",
"to": "pipeline/guard-directives.ts"
}
},
{
"type": "command",
"command": {
"run": "bun pipeline/guard-directives.ts pages pages-before --assert > lint/guard-final.md"
}
},
{
"type": "command",
"command": {
"run": "bun pipeline/lint-reader.ts pages --assert > lint/reader-final.md"
},
"allowFailure": true
}
],
"outputFiles": [
{
"copy": [
"pages",
"lint"
]
}
]
}
]
}
```
## Choose the next job for an existing page
By September 4, v2 no longer needed to generate a new hank for every page group. We kept four fixed programs – `10-ground`, `20-briefs`, `30-xpass` and `40-pages` – and put the selected work in each launch's data. The later programs let us keep a finished draft when only a smaller part of its work remained.
The diagram below shows the fixed programs as they stood in September 2026. Each line is a separate hank, not another codon inside `40-pages`. Codons on a line run in the order shown; separate launches can serve different pages. Cross-page work can send supported corrections to page repair, followed by another collection-wide check.
```text
current fixed page programs (September 2026)
20-briefs: revise -> review -> repair -> assert
25-verify-brief: assert
40-pages: write -> errata -> review
-> cold-a -> cold-b -> cold-c
-> repair -> review-repair -> repair-final
-> final-review -> assert
30-xpass: xcheck -> xrepair -> assert
| supported page corrections
v
45-repair-page: repair -> final-review -> assert
60-verify: final-review -> assert
55-readability: rewrite -> candidate (not approval)
50-diagrams: draw -> verify -> repair -> assert
```
Given a piece of documentation in front of you, the table maps what you have to the smallest job that can lawfully advance it, and the assumption that would invalidate the choice.
| What we have | The next job | What we must not assume |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| A brief requiring revision | `20-briefs`; `25-verify-brief` provides a separate brief-assertion path when selected | A receipt's existence alone proves the sentence. |
| A page that needs authoring | The full `40-pages` program | A cold reader's report substitutes for independent final approval. |
| A retained authored draft with a supported correction | `45-repair-page`, if its provenance and input checks admit it | A prior REPAIR report approves the changed page. |
| An unchanged, sealed candidate whose author finished before review stopped | A verification-only finish with the completed author journal and candidate binding | Any partial draft may skip authorship. |
| Integrated page, brief, editorial and figure changes | Fresh `60-verify`, then set acceptance | Old approval transfers to new bytes. |
On September 7, we used bounded repair for a missing Bedrock qualifier in the environment-variable reference. One table row changed, while the brief and trace stayed byte-identical. The three-codon receipt records 664 seconds and $0.1572 tracked cost. On September 8, the fixture guide and state-file reference finished interrupted reviews without another author codon or a subject change. These are specific proofs of reuse, not a claim that all release work is incremental.
We also learned to separate making a page easier to read from approving its facts. The one-codon `55-readability` program uses the Vue guide and source evidence to return an edited candidate. Figures came from a separate `docs-figures` workflow: a text twin and brief, image-or-Mermaid routing, a paper rig and fidelity checks. After integrating the selected edits and figures, we reviewed the whole edition again. The September 8 record reports 70 final page passes, 9/9 acceptance checks and a 70-page edition with 21 figures on `docs-0.10.0-final`.
That branch was served locally for review, not pushed or deployed. The image workflow was not yet a fixed hank inside the default coordinator, and general no-change/new-version scheduling still had reproduced problems. Automated GitHub regeneration and deployment remain future work. For now, we can inspect the run, keep its valid work and choose the smallest next job whose evidence actually qualifies.
## Run a docs-maintenance hank
Use Node `>=22.19.0` for the documented package entry point. `bunx` is the package launcher in the examples below; if you use npm, the equivalent launcher is `npx hankweave@0.10.0`.
Before invoking Hankweave, we choose where the data lives. Init-style hanks keep it in their own directory. The anchor and pipeline examples pass a separate corpus directory as the second positional argument; the execution sees it read-only.
From the directory containing `hank.json`, use the explicit positional form. The first argument is the hank and the second is the data directory. There is no `run` subcommand:
```sh
bunx hankweave@0.10.0 hank.json /path/to/corpus/
```
If you omit the second positional argument, the data source defaults to the current working directory. That is the hank's own directory only when you invoke the command from there. For a new or edited hank, validate before spending tokens:
```sh
bunx hankweave@0.10.0 hank.json /path/to/corpus/ --validate
```
`--validate` catches schema errors and model-catalog misses before any token is spent. The anchor's preparation recipe first copies task inputs into a separate `task-data/` directory, then validates and runs against that directory. Follow the [quote-template-unification example](/examples/quote-template-unification) for the complete corpus preparation and deterministic oracle commands.
**Check-it:** Run validation after editing `hank.json` and look for the captured `GOOD TO RUN!` result. A real validation failure in the forge record also identifies `retryConfig.delayMs`'s maximum as 60000; `maxDelayMs` may be larger.
For a fresh headless execution during iteration, concurrent work or a CI setup you build yourself, use:
```sh
bunx hankweave@0.10.0 hank.json /path/to/corpus/ --headless --start-new -o ./results
```
`--start-new` (`-n`) prevents silent resumption of a completed execution. `--headless` runs without the interface. Without `-o`, artifacts stay in the execution directory's `agentRoot/`; `-o ./results` copies them to the path you choose. Inspect `state.json` for per-codon `claudeLogPath` values; use [observe and debug](/operate/observe-and-debug) for log naming and inspection.
We use per-codon `budget.maxDollars` and `onExceeded` for individual jobs, and `--max-cost` for the run-level cap. At 0.10.0, `--max-cost` is parsed but absent from `--help`; that omission does not mean the flag is unavailable. We also keep ceilings separate from measured cost: the historical wave-three record tracked $128.87 of a $205 campaign envelope, while the anchor capture above measured $0.88 for its own run.
**Check-it:** Before the run, confirm that you validated the edited hank, supplied a second positional data path when the corpus is separate, and selected `--start-new` for a fresh attempt. Afterward, inspect `state.json` and the copied `./results` artifacts.
## Recover from the failures you can observe
Each failure below is one we hit while producing this manual. The pattern is the same throughout: the observable symptom tells you which mechanism fired, and the right response depends on the mechanism rather than on retrying the same command.
**If a run completes without doing new work, inspect the newest execution.** When its data signature already has a `RunCompleted` execution, the server can log "all codons completed" and exit 0 without naming the reused execution or saying that no new work ran. A fresh completed run also has `status: "completed"`, so distinguish the trap by the already-completed newest execution, exit 0, and absence of new codon work. Use `--start-new` for the next attempt.
**If a quota fails after a checkpoint, separate the artifact from the run result.** Since 0.7.3, a provider quota 429 (zai code 1308) during an exhaust-with-prompt follow-up extension can fail the run after the codon has sealed its checkpoint. The artifact exists, but the run returns 1 and resume wants to run that codon again. Treat provider quota as a separate budget axis; use the [runbook](/operate/runbook) and [resume, rollback, and retry](/operate/resume-rollback-and-retry) procedures.
**If a cost cap trips mid-codon, inspect the outcome before accepting its files.** The historical forge lost review outputs after mid-codon `onExceeded: fail` stops, even after `codon.completed`. Its response was a larger allowance and `onExceeded: "complete"` for expensive readers. That policy selects the recorded outcome; it does not promise that a model finishes its reasoning or writes a complete report. We still need the artifact and review checks.
**If a headless resume sees a changed hank, accept or create a fresh execution deliberately.** It can print "Non-interactive mode, skipping confirmation" and then fail with "Operation cancelled by user"; `-y` accepts the changed hash. After a failed codon, resume uses the persisted model and plan. Changing that codon's model therefore requires `--start-new` or rollback.
**If a time cap appears late, keep the incident separate from the mechanism.** One historical codon ran 24,923 seconds against a 2,400-second cap, with the budget error surfacing only when another failure did. That is a reason not to assume prompt teardown, not evidence that periodic budget checks are absent. Use [budgets](/concepts/budgets) for the current mechanism.
**Check-it:** Compare `state.json`'s `status` with the observed strings "all codons completed", "Non-interactive mode, skipping confirmation", and "Operation cancelled by user". A completed status alone does not prove that the latest command did new work.