T-OQDE-complete-retired-mechanism-doc-sweep

Status: closed/done · Impact: low · Complexity: medium

Goal

The markdown-contract adoption retired the per-entity body-schema.yaml body manifests and the per-entity schema.json mirrors; neither exists on disk anymore (find plugin/lib/model/entities -name 'body-schema.yaml' -o -name 'schema.json' returns nothing). The live artifact is the per-type contract(...) in each <type>/schema.ts (e.g. DriverContract, ProductContract), validated by sdlc entities validate. T-N19Y fixed a first wave of stale doc claims and T-MDJC took the backlog/milestone/task definition.md residue, but the same retired-mechanism boilerplate is templated across the remaining entity definition.md files and a batch of skill docs, where it still names those deleted files as the current authority. This docs-only task completes the sweep: it repoints that remaining set at the live contract(...) / schema.ts mechanism so no reader is sent to a file that no longer exists.

Today

Location	Role today
plugin/lib/model/entities/driver/definition.md	~line 63: “Authoritative spec is body-schema.yaml” — the named file is deleted
plugin/lib/model/entities/term/definition.md	~line 63: same body-schema.yaml boilerplate line
plugin/lib/model/entities/capability/definition.md	~line 70: same body-schema.yaml boilerplate line
plugin/lib/model/entities/principle/definition.md	~line 75: same body-schema.yaml boilerplate line
plugin/lib/model/entities/product/definition.md	~line 63: same body-schema.yaml boilerplate line
plugin/lib/model/entities/standard/definition.md	~line 70: same body-schema.yaml boilerplate line
plugin/lib/model/entities/reference/definition.md	~line 61: same body-schema.yaml boilerplate line
plugin/lib/model/entities/decision/definition.md	~line 72: same body-schema.yaml boilerplate line
plugin/lib/model/entities/product/body-template.eta	~line 5: “sections are pinned (body-schema.yaml has allow_unknown: true)” — names the retired file as live
plugin/skills/README.md	~line 123 (“discovers types from .../schema.json”) and ~line 177 (lists .../schema.json as a live “schema / contract file”) — both name a deleted path
plugin/skills/setup/SKILL.md	~line 44 (${CLAUDE_PLUGIN_ROOT}schemas/<type>.schema.json, e.g. task.schema.json) and ~line 178 (“discovers artifact types from entities/<type>/schema.json”) — neither plugin/schemas/ nor the per-entity schema.json exists
plugin/skills/entities-audit/SKILL.md	~line 27: “The plugin keeps one schema per entity type at entities/<type>/schema.json” — deleted path
plugin/skills/task-work/SKILL.md	~lines 49/52: “resolves the right schema (entities/task/schema.json)” / “Schema lives at .../entities/task/schema.json” — deleted path
plugin/skills/standard-new/SKILL.md	~line 67: cites entities/standard/schema.json — deleted path
plugin/skills/task-new/SKILL.md	~line 24: cites entities/task/schema.json — deleted path
plugin/skills/task-review/SKILL.md	~line 47: cites entities/task/schema.json — deleted path
plugin/skills/milestones-from-file/SKILL.md	~line 111: cites entities/milestone/schema.json — deleted path
plugin/skills/backlog-triage/SKILL.md	~line 29: cites entities/backlog/schema.json — deleted path
plugin/lib/model/entities/driver/schema.ts	The live mechanism the docs should point at — DriverContract = contract({...}); each other entity dir has its <Type>Contract counterpart

Proposed

Every LIVE claim in the enumerated files that names body-schema.yaml or a per-entity schema.json (including the schemas/<type>.schema.json variant) as the current body/section spec or authoritative contract is repointed to the live one: the entity’s contract(...) in its <type>/schema.ts, discovered and validated by sdlc entities validate. Concretely: the eight remaining entity definition.md boilerplate lines name the contract(...) instead of body-schema.yaml; product/body-template.eta stops citing body-schema.yaml as the live pinning mechanism; and the skill docs stop pointing readers at entities/<type>/schema.json / schemas/<type>.schema.json, naming <type>/schema.ts and the sdlc entities validate path instead. After the edits, the generated docs are regenerated if any edited narrative feeds them, and the docs-drift and site-build hooks pass. No historical/migration prose and no test fixtures are touched.

Approach

1. Entity definition.md boilerplate (driver, term, capability, principle, product, standard, reference, decision): rewrite the templated “Authoritative spec is body-schema.yaml.” line in each to name the entity’s contract(...) in <type>/schema.ts (e.g. DriverContract in driver/schema.ts), validated via sdlc entities validate. The order:/allow_unknown: prose that precedes it stays — only the retired-file citation changes.
2. plugin/lib/model/entities/product/body-template.eta (~line 5): drop the body-schema.yaml citation from the pinned-sections note; describe the allow_unknown behavior as carried by ProductContract in product/schema.ts.
3. Skill docs: in each enumerated SKILL.md / README.md, replace the entities/<type>/schema.json (and schemas/<type>.schema.json) citation with the live entities/<type>/schema.ts contract path and, where the sentence describes validation, the sdlc entities validate command. Fix the type-discovery sentences (skills/README.md ~123, setup/SKILL.md ~178, entities-audit/SKILL.md ~27) to say types are discovered from <type>/schema.ts.
4. Regenerate the committed generated docs (sdlc docs generate) if any edited narrative feeds them, then run the docs-drift and site-build project-check hooks and confirm both pass.
5. Run the verifying greps in the ACs to confirm no LIVE retired-mechanism citation remains in the enumerated files and that the excluded historical / test-fixture trees are byte-unchanged.

Files to touch

Location	Kind	Change
plugin/lib/model/entities/driver/definition.md	modify	Repoint the body-schema.yaml boilerplate line to DriverContract in driver/schema.ts
plugin/lib/model/entities/term/definition.md	modify	Repoint the body-schema.yaml boilerplate line to TermContract in term/schema.ts
plugin/lib/model/entities/capability/definition.md	modify	Repoint the body-schema.yaml boilerplate line to CapabilityContract in capability/schema.ts
plugin/lib/model/entities/principle/definition.md	modify	Repoint the body-schema.yaml boilerplate line to PrincipleContract in principle/schema.ts
plugin/lib/model/entities/product/definition.md	modify	Repoint the body-schema.yaml boilerplate line to ProductContract in product/schema.ts
plugin/lib/model/entities/standard/definition.md	modify	Repoint the body-schema.yaml boilerplate line to StandardContract in standard/schema.ts
plugin/lib/model/entities/reference/definition.md	modify	Repoint the body-schema.yaml boilerplate line to ReferenceContract in reference/schema.ts
plugin/lib/model/entities/decision/definition.md	modify	Repoint the body-schema.yaml boilerplate line to DecisionContract in decision/schema.ts
plugin/lib/model/entities/product/body-template.eta	modify	Drop the body-schema.yaml citation from the pinned-sections note; attribute allow_unknown to ProductContract
plugin/skills/README.md	modify	Repoint the type-discovery (~123) and schema-file (~177) schema.json citations to <type>/schema.ts
plugin/skills/setup/SKILL.md	modify	Repoint the schemas/<type>.schema.json (~44) and entities/<type>/schema.json (~178) citations to <type>/schema.ts
plugin/skills/entities-audit/SKILL.md	modify	Repoint the “one schema per type at entities/<type>/schema.json” line (~27) to <type>/schema.ts
plugin/skills/task-work/SKILL.md	modify	Repoint the two entities/task/schema.json citations (~49/52) to task/schema.ts
plugin/skills/standard-new/SKILL.md	modify	Repoint the entities/standard/schema.json citation (~67) to standard/schema.ts
plugin/skills/task-new/SKILL.md	modify	Repoint the entities/task/schema.json citation (~24) to task/schema.ts
plugin/skills/task-review/SKILL.md	modify	Repoint the entities/task/schema.json citation (~47) to task/schema.ts
plugin/skills/milestones-from-file/SKILL.md	modify	Repoint the entities/milestone/schema.json citation (~111) to milestone/schema.ts
plugin/skills/backlog-triage/SKILL.md	modify	Repoint the entities/backlog/schema.json citation (~29) to backlog/schema.ts

Acceptance criteria

• AC-1: None of the eight enumerated entity definition.md files (driver, term, capability, principle, product, standard, reference, decision) contains a live claim naming body-schema.yaml as the current body/section spec — each names the entity’s contract(...) in <type>/schema.ts, validated via sdlc entities validate.
• AC-2: plugin/lib/model/entities/product/body-template.eta no longer cites body-schema.yaml as the live pinning mechanism.
• AC-3: None of the enumerated skill docs (skills/README.md, setup/SKILL.md, entities-audit/SKILL.md, task-work/SKILL.md, standard-new/SKILL.md, task-new/SKILL.md, task-review/SKILL.md, milestones-from-file/SKILL.md, backlog-triage/SKILL.md) cites entities/<type>/schema.json or schemas/<type>.schema.json as a current plugin file — each names <type>/schema.ts / sdlc entities validate.
• AC-4: The verifying grep grep -rn "body-schema.yaml" plugin/lib/model/entities/*/definition.md plugin/lib/model/entities/product/body-template.eta returns no LIVE match, and a schema.json grep over the enumerated skill docs returns none — while the excluded historical/test-fixture trees (plugin/skills/entities-migrate/tests/**, plugin/skills/entities-audit/tests/fixtures/**, plugin/skills/task-ensure-ready/tests/ensure_ready.test.ts) are byte-unchanged.
• AC-5: sdlc entities validate on the touched entity docs stays green, and the docs-drift (project-check-docs-drift) and site-build (project-check-site-build) lefthook gates pass after the edits (generated docs regenerated if any edited narrative feeds them).

Out of scope

• The files owned by T-MDJC (this same PR): the schema.json / body-schema.yaml claims in backlog/definition.md, milestone/definition.md, and task/definition.md, plus plugin/lib/services/docs/site_data_model_template.eta and plugin/conventions/sdlc-yaml.md. Not touched here.
• The files owned by T-N19Y (PR #623): the root README.md schema.json / body-template.md / validate_frontmatter.ts claims, and the validate_frontmatter.ts citations in plugin/cli/backlog_cli/README.md and plugin/conventions/schema-bump-checklist.md. Note: T-N19Y’s written scope also nominally enumerates the eight entity definition.md boilerplate lines; per T-MDJC’s explicit deferral of “that whole boilerplate set” to a separate, larger consistency task, THIS task is the concrete owner of that remaining set — the same first-wave / follow-on relationship T-MDJC already has to T-N19Y. If T-N19Y lands first and happens to fix any of these lines, treat the already-fixed lines as satisfied (the edits are idempotent).
• HISTORICAL / migration context, left untouched: the synthetic schema.json fixtures the test harness itself creates under plugin/skills/entities-migrate/tests/** and plugin/skills/entities-audit/tests/fixtures/** (accurate about the fixtures, not claims about the live plugin); the “schema.json is gone” note in plugin/skills/task-ensure-ready/tests/ensure_ready.test.ts (~383); D-0004 and other decision records under docs/planning/decisions/; and any “schema.json/body-schema.yaml was retired” completed-migration prose.
• Lease/status-cache “authoritative” mentions (e.g. in task/definition.md ~87/133/155) — that is the unrelated lease/status sense, not a body-contract claim, and is already T-MDJC’s stated carve-out.
• Any code change — this is docs-only; the <type>/schema.ts contracts already exist.

Dependencies

• none — enabled by the already-vendored markdown-contract 0.2.0 (vendor/markdown-contract-0.2.0.tgz); the retired body-schema.yaml / schema.json mechanism it replaced is already deleted from disk. This complements T-N19Y (PR #623, the first wave) and T-MDJC (this PR, the backlog/milestone/task residue); the three partition the stale-doc set with no file overlap. All three sit under milestone M-0009.

Discovery context

• Surfaced by the same read-side audit after the markdown-contract adoption (milestone M-0009) that produced T-N19Y and T-MDJC. A grep for body-schema.yaml / schema.json over plugin/lib/model/entities/*/definition.md and plugin/skills found the templated boilerplate had been left behind on the entity types and skill docs those two tasks did not enumerate. T-MDJC’s own “Out of scope” explicitly names this remaining boilerplate set as “a separate, larger consistency task” — this is that task.

---

← Back to Tasks