T-YXM5-site-docs-long-tail
Status: closed/done · Impact: medium · Complexity: medium
The site’s script-reference generator scans only .py files — and
plugin/scripts/ has none, so that reference section is already stale.
After the sweep the deterministic surface IS the registry. Rewrite regen
to project /reference/ops/ from the registry, refresh the per-skill
docs whose flowcharts name old scripts, and sweep the remaining doc/site
prose.
| Location | Role today |
|---|---|
site/scripts/regen.mjs | regenScripts() walks plugin/scripts/*.py + plugin/skills/<skill>/*.py — zero matches today |
docs/skills/ | per-skill docs with Mermaid flowcharts citing old script names |
plugin/cli/README.md | pre-sweep CLI description |
docs/planning/decisions/D-0007-deterministic-op-substrate.md | needs a consequences note once the migration completes (forward amendment note already landed with D-H7FS) |
docs/planning/standards/S-0001-co-locate-first-promote-when-shared.md | same |
| D-K9PX (system architecture) — since deleted into D-VSLI-distributed-work-runner-architecture | §sdlc <noun> <verb> surface describes the pre-path[] shape |
docs/planning/decisions/D-0004-entity-definition-architecture.md | §ops-modules line states the {noun, verb} descriptor |
docs/planning/standards/S-0004-sdlc-cli-llm-head-deterministic-tail.md | sdlc <noun> <verb> shape language predates path[] |
Proposed
Section titled “Proposed”regen.mjs emits one reference page per registered path (sourced from
the registry / sdlc --help --advanced), with the index copy fixed;
docs/skills/*.md refreshed via the dev-update-docs/update-skill-doc
flow so the check_skill_docs lefthook gate stays green; the ~138-file
docs/site naming long tail swept (historical task post-mortems stay
as-is); CLI README updated; D-0007/S-0001 carry completion notes.
Approach
Section titled “Approach”- Rewrite
regenScripts()→regenOps(): enumerate registered paths, one page per op/service leaf; fix the reference index copy. - Run the site build; fix breakage.
- Refresh
docs/skills/*.mdagainst the codemodded SKILL.md files (dev-update-docs flow);check_skill_docsgreen. - Sweep docs/site for old script names — update live references, leave historical post-mortems.
- Add consequences notes to D-0007 and S-0001; update
plugin/cli/README.md. - Descriptive-doc sweep per D-H7FS §Consequences timing rule (they stay truthful until the new
shape is shipped reality): update the architecture map — now
D-VSLI-distributed-work-runner-architecture, which absorbed D-K9PX — plus D-0004 §ops
modules and S-0004, to the path[] shape and
--outputcontract.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
site/scripts/regen.mjs | modify | regenScripts → registry-driven regenOps |
docs/skills/ | modify | flowchart refresh per codemodded skill |
plugin/cli/README.md | modify | path[] surface description |
docs/planning/decisions/D-0007-deterministic-op-substrate.md | modify | consequences note |
docs/planning/standards/S-0001-co-locate-first-promote-when-shared.md | modify | consequences note |
docs/planning/decisions/D-VSLI-distributed-work-runner-architecture.md (successor to the deleted D-K9PX) | modify | sdlc surface prose → path[] + —output |
docs/planning/decisions/D-0004-entity-definition-architecture.md | modify | ops-module descriptor line → path[] |
docs/planning/standards/S-0004-sdlc-cli-llm-head-deterministic-tail.md | modify | command-shape language → path[] |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: site build green;
/reference/ops/contains one page per registered path, none for deleted scripts. - AC-2:
check_skill_docslefthook gate green across all skills. - AC-3: grep for the old script filenames across docs/ and site/ hits only historical task/post-mortem files.
- AC-4: D-0007 and S-0001 note the completed migration; CLI README describes the path[] surface.
- AC-5: D-VSLI-distributed-work-runner-architecture (which absorbed D-K9PX), D-0004, and
S-0004 describe the path[] descriptor and
--outputcontract —grep -rn 'sdlc <noun> <verb>' docs/planning/returns no stale shape language outside historical post-mortems.
Out of scope
Section titled “Out of scope”- New documentation content beyond refresh.
- MCP/HTTP adapter docs (those adapters don’t exist yet).
Dependencies
Section titled “Dependencies”- T-YBKU-shim-deletion-guard — paths must be dead before the sweep finalizes (drafting may start earlier).
Discovery context
Section titled “Discovery context”- Refutation finding: regen.mjs is .py-only and already stale; T-5PLQ’s co-located-script regen support predates the TS migration. docs/plans/op-substrate-full-sweep.md T16.