amadan
spec: gate the CLI page against main.go's dispatch switch, not its usage text
Reading the usage prose would only prove the docs match a second copy of the docs. The switch statement is the CLI — rastrillo's docsite makes the same argument and reads the AST. Flags stay ungated here: CARLOS declares them across forty files in the root package, where rastrillo has one small cmd package. Also corrects which script does what on the website side: check-docs.mjs carries the rendered-output and slugify-agreement checks together.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 file changed,
+12
−5
docs/superpowers/specs/2026-08-24-docs-sites-design.md+12 −5
diff --git a/docs/superpowers/specs/2026-08-24-docs-sites-design.md b/docs/superpowers/specs/2026-08-24-docs-sites-design.md| index 4b26b263b..1544d4d66 100644 |
| --- a/docs/superpowers/specs/2026-08-24-docs-sites-design.md |
| +++ b/docs/superpowers/specs/2026-08-24-docs-sites-design.md |
| @@ -118,16 +118,23 @@ Go, in `internal/docsite`, over the platform corpus: |
| on each side. |
| - **Fence languages are declared.** No bare triple-backticks. |
| - **Every top-level command is documented.** The list comes from `main.go`'s |
| - usage text; each command must appear in the CLI reference page. |
| + dispatch switch, read as a Go AST — not from its usage text. Gating against |
| + the usage prose would only prove the docs match a second copy of the docs; |
| + the switch statement is the CLI. Each case must appear in the CLI reference |
| + page. Flags are deliberately not gated: rastrillo can, because its CLI is one |
| + small package, but CARLOS declares flags across forty files in the root |
| + package and the list would be hundreds long. |
| - **Every `carlos` invocation in a fence names a real command.** This is the |
| gate rastrillo does not have and CARLOS needs: a renamed verb currently |
| breaks nothing until a reader types it. |
| JavaScript, in both site repos, run by `npm run check`: Eleventy builds, then |
| -`check-anchors.mjs` compares the slug rule to the fixture and `check-docs.mjs` |
| -re-runs the link and nav checks against the corpus present in that repo. For |
| -carloku this is the only gate, so it has to carry the link and nav checks on |
| -its own. |
| +`check-docs.mjs` checks what the Go gate cannot — that rendering actually |
| +produced the pages and the ids those links point at, and that the renderer's |
| +`slugify` agrees with `docsite.Anchor` on the shared fixture. A link can be |
| +correct in the source and still 404 in a browser if the two disagree about how |
| +a heading becomes an anchor. For carloku this is the only gate, so it carries |
| +the nav and link checks on its own as well. |
| Neither site repo has CI today and Actions minutes have been tight, so |
| `npm run check` is a local step in the ship runbook. Adding a five-line |