UNOFFICIAL/EXPERIMENTAL
Use this when a verifier fails or the repo looks stale. Prefer the narrowest repair that matches the failure.
General Pattern
- Read the first failure, not the last one.
- Identify the owner: manual Markdown, generated data, generated site, proof receipt, command-surface lint, or live evidence.
- Regenerate only the owned surface.
- Re-run the matching verifier.
- Run
git diff --check.
Common Failures
| Failure | Meaning | Recovery |
|---|---|---|
Markdown file is in an unexpected location | docs:verify does not know the directory. | Add the directory pattern to scripts/verify-doc-map.mjs only if the location is intentional; then assign every new doc a role in docs/README.md. |
docs/README.md does not assign a role | A top-level manual doc is not in the doc map. | Add a row for the file in docs/README.md, then run npm run docs:verify. |
Broken markdown link | A Markdown link target does not exist from that file's directory. | Fix the link target or move the file intentionally; then run npm run docs:verify. |
tests/npm-script-catalog.* is stale | package.json scripts changed. | Run npm run npm-scripts:catalog, then npm run npm-scripts:catalog:verify. |
site/... is stale | Generated public site output does not match the generator and data. | Only if website work was requested: run HELM_EXPT_SITE_GENERATED_AT="$(cat site/generated-at.txt)" npm run site:generate, then npm run site:verify and npm run site:ux:verify. |
data/README.md is stale or CSV index stale | Generated data index does not match data/. | Run npm run data:index, then npm run data:index:verify. |
helm-render-intents output is stale | Render-intent YAML/CSV/JSON no longer matches matrix or lifecycle data. | Run npm run helm-render-intents, then npm run helm-render-intents:verify. |
| Matrix output is stale | The master matrix no longer matches source data. | Run npm run master-matrix, then npm run master-matrix:verify. |
| Command-surface verifier rejects an example | A doc uses stale cub syntax or planned syntax without saying it is planned. | Fix the example or mark planned/future syntax clearly; re-run the command-surface verifier. |
git diff --check reports trailing whitespace | A generated or manual file has whitespace errors. | Fix the source generator if many generated files are affected; fix the manual file directly if only manual docs changed. |
When Not To Regenerate
Do not regenerate a broad surface just because it is nearby. Examples:
- Do not run
npm run site:generateduring an agent-doc-only change. - Do not regenerate catalog maps during a Markdown audit.
- Do not run live parity while fixing broken docs.
- Do not run
npm run verifyas the first debugging step for a narrow stale file.
Live-Lane Recovery
If a live run fails:
- Preserve logs and receipts under the run directory.
- Check whether the failure is a target prerequisite, remote image, runtime health, controller health, model gap, or infrastructure block.
- Use the generated rerun/action surfaces before retrying:
data/live-parity-rerun-plan/summary.mddata/target-prerequisite-actions/summary.mddata/model-prereq-resolution/summary.mddata/live-run-blocks/summary.md
- Do not edit prose to turn a row green.
Escalate To The Broad Gate
Run npm run verify after focused checks pass when:
- the change touches shared proof logic;
- the change updates many generated surfaces;
- the user asks for a full verification pass;
- a broad publish or release gate is needed.