T-MDJC-fix-residual-stale-pre-markdown-contract-doc-claims

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

Goal

The markdown-contract adoption retired the bespoke validator, its schema.json mirrors, the body-schema.yaml body manifests, and plugin/validators/validate_frontmatter.ts — none of those files exist on disk anymore. T-N19Y fixed the first wave of doc claims that still named that retired mechanism, but a residual set of live claims survived and now misdirects readers to files that are gone. This docs-only follow-on repoints that residual set at the current mechanism: the per-type markdown-contract contract(...) in each entity’s schema.ts, validated via sdlc entities validate.

Today

Location	Role today
plugin/lib/services/docs/site_data_model_template.eta	The entity-dir file listing names body-schema.yaml (“Structure of the prose body”) as a real dir file (~line 52) — the file no longer exists
plugin/conventions/sdlc-yaml.md	A quality_checks: example invokes bun run plugin/validators/validate_frontmatter.ts ... (~line 100) — that script is deleted
plugin/lib/model/entities/backlog/definition.md	Asserts “schema.json is the authoritative contract” (~line 35) and “body-schema.yaml declares no sections” (~line 50) — both retired
plugin/lib/model/entities/milestone/definition.md	Asserts “The authoritative machine-readable contract is schema.json” (~line 65) and “…contract is body-schema.yaml” (~line 80) — both retired
plugin/lib/model/entities/task/definition.md	Asserts “schema.json is the authoritative contract” (~line 36) and “Authoritative spec is body-schema.yaml” (~line 68) — both retired. Lines ~87/133/155 also say “authoritative” but about the lease/status cache — those are correct and OUT OF SCOPE
plugin/lib/model/entities/task/schema.ts#TaskContract	The current mechanism the docs should point at — the per-type contract(...)
plugin/lib/model/entities/backlog/schema.ts#BacklogContract	Current mechanism for backlog
plugin/lib/model/entities/milestone/schema.ts#MilestoneContract	Current mechanism for milestone

Proposed

Every claim in the enumerated files that names schema.json, body-schema.yaml, or validate_frontmatter.ts as the current validation mechanism is repointed to the live one: the entity’s contract(...) in its schema.ts (frontmatter + body sections in one declarative contract), validated by sdlc entities validate. The .eta dir-file listing no longer names a body-schema.yaml file. The sdlc-yaml.md example runs sdlc entities validate instead of the deleted validator script. The lease/status-cache “authoritative” mentions in task/definition.md (~87/133/155) are left untouched. After the edits, the generated docs are regenerated and the docs-drift and site-build hooks pass.

Approach

1. plugin/lib/services/docs/site_data_model_template.eta: drop the body-schema.yaml row from the entity-dir file listing (or replace it with a note that schema.ts now carries the body-section contract) so the listing matches what is actually on disk.
2. plugin/conventions/sdlc-yaml.md: replace the plugin/validators/validate_frontmatter.ts example command in the quality_checks: block with bun run plugin/cli/sdlc.ts entities validate docs/planning/tasks/some.md.
3. plugin/lib/model/entities/backlog/definition.md: repoint the “schema.json is the authoritative contract” claim (~35) and the “body-schema.yaml declares no sections” claim (~50) to BacklogContract in backlog/schema.ts, validated via sdlc entities validate.
4. plugin/lib/model/entities/milestone/definition.md: repoint the two claims (~65 schema.json, ~80 body-schema.yaml) to MilestoneContract in milestone/schema.ts.
5. plugin/lib/model/entities/task/definition.md: repoint the schema.json claim (~36) and the body-schema.yaml claim (~68) to TaskContract / TaskReadyContract in task/schema.ts. Do NOT edit the lease/status-cache “authoritative” lines (~87/133/155) — they are correct.
6. 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.

Files to touch

Location	Kind	Change
plugin/lib/services/docs/site_data_model_template.eta	modify	Remove the body-schema.yaml dir-file row; the body contract now lives in schema.ts
plugin/conventions/sdlc-yaml.md	modify	Swap the validate_frontmatter.ts example command for sdlc entities validate
plugin/lib/model/entities/backlog/definition.md	modify	Repoint the schema.json (~35) and body-schema.yaml (~50) claims to BacklogContract / sdlc entities validate
plugin/lib/model/entities/milestone/definition.md	modify	Repoint the schema.json (~65) and body-schema.yaml (~80) claims to MilestoneContract / sdlc entities validate
plugin/lib/model/entities/task/definition.md	modify	Repoint the schema.json (~36) and body-schema.yaml (~68) claims to TaskContract / sdlc entities validate; leave the lease/status lines ~87/133/155 untouched

Acceptance criteria

• AC-1: None of the five touched files contains a live claim asserting body-schema.yaml, validate_frontmatter.ts, or schema.json as the current validation mechanism — each now names the entity’s contract(...) in its schema.ts, validated via sdlc entities validate.
• AC-2: The lease/status-cache “authoritative” mentions in plugin/lib/model/entities/task/definition.md (~lines 87/133/155) are byte-unchanged.
• AC-3: The body-schema.yaml row is gone from the site_data_model_template.eta dir-file listing, and the sdlc-yaml.md quality_checks: example no longer invokes validate_frontmatter.ts.
• AC-4: The docs-drift (project-check-docs-drift) and site-build (project-check-site-build) lefthook gates pass after the edits (generated docs regenerated if affected).

Out of scope

• The identical “Authoritative spec is body-schema.yaml” boilerplate line in the OTHER entity definition.md files (driver, term, capability, principle, product, standard, reference, decision) and product/body-template.eta — a grep sweep shows the retired token is templated across most entity types; fixing that whole boilerplate set is a separate, larger consistency task, not this targeted T-N19Y follow-on.
• The validate_frontmatter.ts mentions in skill docs (skills/README.md, skills/CLAUDE.md, task-define/SKILL.md, schema-bump-checklist.md, backlog_cli/README.md) — those are pipe-safety/incident narrative, not current-mechanism assertions; out of scope here.
• Any code change — this is docs-only; the 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 mechanism it replaced is already gone. This is the docs follow-on to T-N19Y, which fixed the first wave of the same stale claims and is itself still open/ready under milestone M-0009.

Discovery context

• Surfaced by a read-side audit after the markdown-contract adoption (milestone M-0009): a grep for body-schema.yaml / validate_frontmatter.ts / schema.json found live current-mechanism claims that T-N19Y’s first wave did not reach.

---

← Back to Tasks