T-UE7T-reference-entity-package

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

Goal

Ship the substrate for D-0009-reference-entity-and-docs-appendix’s reference type: the entity package, the RF identifier row, and the registry amendments — so external sources can be minted as first-class entities. Pure addition; unblocks every later phase.

Today

Location	Role today
plugin/lib/model/entities/term/	The model package this one mirrors — schema, S-0005 definition, body manifest, template, create op
plugin/lib/model/identifier.ts	PREFIXES registry — no RF row, so the identifier gate skips docs/planning/references/
docs/planning/decisions/D-0002-entity-identifier-shape.md	Prefix table reserves R for Requirement; no Reference row
docs/planning/decisions/D-ORMG-data-model.md	Roster carries Evidence as deferred; no Reference row

Proposed

sdlc reference create <slug> --title <name> [--url <url>] mints validating RF-NNNN instances under docs/planning/references/; audit/validate/migrate/setup cover the type with zero wiring; D-0002 and D-ORMG carry the row. Frontmatter and body shape per D-0009 §2: optional url (format: uri), Summary required with ^summary, Material/Notes optional.

Approach

1. Mirror the term package into plugin/lib/model/entities/reference/: schema.json (RF id pattern, status enum open/draft|open/active|closed/retired default open/active, optional url with format: uri, related as cited-by), body-schema.yaml (Summary required with ^summary guidance; Material, Notes optional), body-template.eta, definition.md per S-0005.
2. ops/create.ts — defineOp({ path: ["reference", "create"] }), positional slug, flags title/-t, url, related repeatable; delegate to runCreate.
3. PREFIXES row { RF, Reference, references, incrementing } after Term.
4. Amend D-0002’s prefix table and D-ORMG’s roster (Reference row in the Planning-meta layer; Evidence row notes the curated-catalog slice is now Reference’s).
5. Re-snapshot help goldens; update the unknown-noun choice list, setup dir count, and ops_create tests.

Files to touch

Location	Kind	Change
plugin/lib/model/entities/reference/schema.json	new	RF frontmatter contract
plugin/lib/model/entities/reference/definition.md	new	S-0005 companion definition
plugin/lib/model/entities/reference/body-schema.yaml	new	Summary/Material/Notes manifest
plugin/lib/model/entities/reference/body-template.eta	new	Instance skeleton
plugin/lib/model/entities/reference/ops/create.ts	new	sdlc reference create
plugin/lib/model/identifier.ts	modify	PREFIXES gains the RF row
docs/planning/decisions/D-0002-entity-identifier-shape.md	modify	Prefix table gains the Reference row
docs/planning/decisions/D-ORMG-data-model.md	modify	Roster row + Evidence note
plugin/cli/tests/goldens/	modify	Help goldens re-snapshot (reference noun)
plugin/lib/tests/ops_create.test.ts	modify	Reference create coverage
plugin/lib/services/project/tests/ops.test.ts	modify	Setup dir count 10 → 11

Acceptance criteria

• AC-1: sdlc reference create obsidian-bases --title "Obsidian Bases" --url https://help.obsidian.md/bases writes an instance that passes sdlc entities validate.
• AC-2: sdlc project setup creates docs/planning/references/; sdlc entities audit discovers the type.
• AC-3: The commit-time identifier gate flags a misnamed file under docs/planning/references/.
• AC-4: Full test battery green (bun test incl. goldens).

Out of scope

• The references artifact and index Appendix (T-FPSR).
• Site work (T-8YB9, T-E2B1) and the seed corpus (T-XUTL).

Dependencies

• D-0009-reference-entity-and-docs-appendix accepted (or accepted-in-principle via its PR).

Discovery context

• Extracted from D-0009-reference-entity-and-docs-appendix Migration Phase 1.

---

← Back to Tasks