T-N19Y-fix-stale-body-schema-doc-claims

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

Goal

After the markdown-contract adoption, the entity body artifact is the contract(...) in each <type>/schema.ts, and the bespoke validator and the 11 body-schema.yaml manifests are deleted. But prose docs still cite those deleted artifacts as live, which misleads anyone reading the entity definitions or the plugin README. This task corrects the stale claims to point at schema.ts / the contract.

The stale citations the audit surfaced:

Location	Stale claim
`plugin/.../entities/task/definition.md` (lines 68, 72)	names `body-schema.yaml` as the authoritative body spec
`plugin/.../entities/backlog/definition.md` (line 50)	names `body-schema.yaml`
`plugin/.../entities/capability/definition.md` (line 70)	names `body-schema.yaml`
`plugin/.../entities/decision/definition.md` (line 72)	names `body-schema.yaml`
`plugin/.../entities/driver/definition.md` (line 63)	names `body-schema.yaml`
`plugin/.../entities/milestone/definition.md` (line 80)	names `body-schema.yaml`
`plugin/.../entities/principle/definition.md` (line 75)	names `body-schema.yaml`
`plugin/.../entities/product/definition.md` (line 63)	names `body-schema.yaml`
`plugin/.../entities/reference/definition.md` (line 61)	names `body-schema.yaml`
`plugin/.../entities/standard/definition.md` (line 70)	names `body-schema.yaml`
`plugin/.../entities/term/definition.md` (line 63)	names `body-schema.yaml`
`README.md` (lines 42-46)	claims each entity dir holds `schema.json` + `body-template.md` and that enforcement is via `plugin/validators/validate_frontmatter.ts` (all deleted; templates are `.eta`)
`plugin/cli/backlog_cli/README.md` (line 47)	cites the deleted `validate_frontmatter.ts`
`plugin/conventions/schema-bump-checklist.md` (line 61)	cites the deleted `validate_frontmatter.ts`

Today

Location	Role today
`plugin/lib/model/entities/*/definition.md`	11 files name `body-schema.yaml` as the body spec; the live artifact is the `contract(...)` in `<type>/schema.ts`
`README.md`	Claims entity dirs hold `schema.json` + `body-template.md` and that enforcement is via `plugin/validators/validate_frontmatter.ts` (~40-47) — all deleted; templates are `.eta`
`plugin/cli/backlog_cli/README.md`	Cites the deleted `validate_frontmatter.ts` (line 47)
`plugin/conventions/schema-bump-checklist.md`	Cites the deleted `validate_frontmatter.ts` (line 61)

Approach

Correct the stale prose to point at the contract in <type>/schema.ts. No code changes.

Rewrite the body-spec line in all 11 entity definition.md files to name the contract(...) in schema.ts instead of body-schema.yaml.
Fix README.md (~40-47): drop the per-dir schema.json / body-template.md claim and the validate_frontmatter.ts enforcement line; state the .eta templates and the contract-based validation path.
Fix the two checklist citations off validate_frontmatter.ts (backlog_cli/README.md:47, schema-bump-checklist.md:61).
Grep body-schema.yaml and validate_frontmatter across plugin/ and README.md to catch references beyond this list. The grep also surfaces plugin/lib/model/entities/_contracts.ts and product/body-template.eta — confirm whether those are live claims (fix) or historical notes (leave).
Re-run sdlc docs generate if an edited file is a generator source.

Files to touch

Location	Kind	Change
`plugin/lib/model/entities/*/definition.md`	modify	11 files: repoint the body-spec line from `body-schema.yaml` to the `contract(...)` in `schema.ts`
`README.md`	modify	Drop the `schema.json` / `body-template.md` / `validate_frontmatter.ts` claims (~40-47); name the `.eta` templates and contract validation
`plugin/cli/backlog_cli/README.md`	modify	Drop the `validate_frontmatter.ts` citation (line 47)
`plugin/conventions/schema-bump-checklist.md`	modify	Drop the `validate_frontmatter.ts` citation (line 61)

Acceptance criteria

AC-1: Each of the 11 entity definition.md files no longer names body-schema.yaml as the body spec; the claim points at the contract in <type>/schema.ts.
AC-2: README.md:42-46 is corrected — it no longer claims schema.json + body-template.md per dir or enforcement via plugin/validators/validate_frontmatter.ts; it reflects the .eta templates and the contract-based validation path.
AC-3: plugin/cli/backlog_cli/README.md:47 and plugin/conventions/schema-bump-checklist.md:61 no longer cite the deleted validate_frontmatter.ts.
AC-4: If any corrected file is a generator source, sdlc docs generate is re-run so the generated docs stay in sync.

Out of scope

Historical decision records under docs/planning/decisions/ that mention body-schema.yaml — D-0004 reconciliation is covered by its own cleanup task.

← Back to Tasks