Root cause: docs/evidence-contract-v1.md fenced planned invocations (guard --scope working-tree --json, judge --ephemeral --json, report --json) while their flags were deferred to EVID-002/EVID-003. scripts/checkcliexamples.py extracts every fenced line starting with gitreins and replays it through the real argparse, which rejects the unknown flags (exit 2), so the checker exits 1 → CI red. The defect is the doc, not the checker.
I've written the complete, self-contained solution to ~/solution.md. Summary of its contents:
docs-publish-a-planned-cli-surface-as-fenced-runnable-examplesRoot cause: docs/evidence-contract-v1.md fenced planned invocations (guard --scope working-tree --json, judge --ephemeral --json, report --json) while their flags were deferred to EVID-002/EVID-003. scripts/check_cli_examples.py extracts every fenced line starting with gitreins and replays it through the real argparse, which rejects the unknown flags (exit 2), so the checker exits 1 → CI red. The defect is the doc, not the checker.
Exact fix (doc-only): Move the three invocations out of the bash fence into a status'd bullet list naming each flag's landing row, so the checker no longer replays them but readers still see the contract:
- **Planned (EVID-002):** `gitreins guard --scope working-tree --json`
- **Planned (EVID-003):** `gitreins judge --ephemeral`
- **Planned (EVID-002):** `gitreins report --json`
Verification: python scripts/check_cli_examples.py must exit 0 (106 examples, 18 docs) across 3.10/3.11/3.12; the HEAD~1 falsification control must still exit 2 on all three lines, proving the checker was not weakened. Plus a general prevention rule: unbuilt CLI surface is documented as prose/bullets, never as fenced runnable commands.
The file also includes the apply/scan snippets (a Python fence-scanner to list every replayed gitreins line) and the CI verification matrix.
# Evidence - Problem class: docs-publish-a-planned-cli-surface-as-fenced-runnable-examples-check-cli-examples-style-docs-verification-fails-ci - Model: openrouter/deepseek/deepseek-v4.1-flash - Solved: 2026-09-23T00:14:20.898Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "EVID-001 published the evidence contract (JSON Schema + doc) while the CLI emitters were deferred to follow-up rows (EVID-002: --json/--scope on guard/judge/report; EVID-003: judge --ephemeral). The doc fenced the PLANNED invocations as runnable commands; check_cli_examples.py by design replays every fenced gitreins line through the real argparse, so a doc promising unbuilt flags is a CI red, not a docs nit. General rule: a doc that promises unbuilt CLI surface must present it as a contract (prose/bullets), never as a fenced command, in any repo whose CI replays doc examples through the real parser. Do not weaken the checker to accommodate aspirational docs.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "docs-publish-a-planned-cli-surface-as-fenced-runnable-examples-check-cli-examples-style-docs-verification-fails-ci", "provider": "openrouter", "solved_at": "2026-09-23T00:14:20.898Z", "version": ""}I've written the complete, self-contained solution to ~/solution.md. Summary of its contents:
docs-publish-a-planned-cli-surface-as-fenced-runnable-examplesRoot cause: docs/evidence-contract-v1.md fenced planned invocations (guard --scope working-tree --json, judge --ephemeral --json, report --json) while their flags were deferred to EVID-002/EVID-003. scripts/check_cli_examples.py extracts every fenced line starting with gitreins and replays it through the real argparse, which rejects the unknown flags (exit 2), so the checker exits 1 → CI red. The defect is the doc, not the checker.
Exact fix (doc-only): Move the three invocations out of the bash fence into a status'd bullet list naming each flag's landing row, so the checker no longer replays them but readers still see the contract:
- **Planned (EVID-002):** `gitreins guard --scope working-tree --json`
- **Planned (EVID-003):** `gitreins judge --ephemeral`
- **Planned (EVID-002):** `gitreins report --json`
Verification: python scripts/check_cli_examples.py must exit 0 (106 examples, 18 docs) across 3.10/3.11/3.12; the HEAD~1 falsification control must still exit 2 on all three lines, proving the checker was not weakened. Plus a general prevention rule: unbuilt CLI surface is documented as prose/bullets, never as fenced runnable commands.
The file also includes the apply/scan snippets (a Python fence-scanner to list every replayed gitreins line) and the CI verification matrix.
# Evidence - Problem class: docs-publish-a-planned-cli-surface-as-fenced-runnable-examples-check-cli-examples-style-docs-verification-fails-ci - Model: openrouter/deepseek/deepseek-v4.1-flash - Solved: 2026-09-23T00:14:20.898Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "EVID-001 published the evidence contract (JSON Schema + doc) while the CLI emitters were deferred to follow-up rows (EVID-002: --json/--scope on guard/judge/report; EVID-003: judge --ephemeral). The doc fenced the PLANNED invocations as runnable commands; check_cli_examples.py by design replays every fenced gitreins line through the real argparse, so a doc promising unbuilt flags is a CI red, not a docs nit. General rule: a doc that promises unbuilt CLI surface must present it as a contract (prose/bullets), never as a fenced command, in any repo whose CI replays doc examples through the real parser. Do not weaken the checker to accommodate aspirational docs.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "docs-publish-a-planned-cli-surface-as-fenced-runnable-examples-check-cli-examples-style-docs-verification-fails-ci", "provider": "openrouter", "solved_at": "2026-09-23T00:14:20.898Z", "version": ""}