T-FPSR-references-artifact-and-index-appendix

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

Goal

The references roster becomes the fourth generated artifact (docs/references.md), and index.md’s Appendix gains generated Glossary and References sections — terms and references render in the front door per D-0009-reference-entity-and-docs-appendix §3–4.

Today

Location	Role today
plugin/lib/services/docs/generate.ts	ARTIFACT_NAMES = ["index","glossary","site"]; buildGlossaryData is the catalog-section model
plugin/lib/services/docs/index_template.eta	# Appendix holds Conventions only; IndexData has no glossary/references sections
plugin/lib/services/docs/ops/generate.ts	Artifact enum lacks references
plugin/skills/docs/SKILL.md	Names three artifacts (per-skill doc docs/skills/docs.md mirrors it)
plugin/lib/services/docs/tests/fixtures/mini/	Fixture terms exist; no fixture references

Proposed

sdlc docs generate references writes docs/references.md (Reference | Summary | Link | Cited by, host-labelled links, bucketFor bucketing, alphabetical by title); the index Appendix carries Glossary and References sections plus pointer lines; Start here gains a references row; an empty corpus renders preamble-only without error.

Approach

1. buildReferencesData(planningDir): loadEntities("references"), title sort (case-insensitive), cells [refCell, summaryCell, linkCell, citedByCell] — linkCell renders [<host>](<url>), blank when no url.
2. references_template.eta with the fixed preamble; ARTIFACT_NAMES/artifactPath/renderArtifact gain references.
3. IndexData gains glossary + references; index_template.eta Appendix sections + pointer lines; Start-here row.
4. Op input enum widens; docs-help golden re-snapshot.
5. Tests: assembly units, empty-corpus tolerance, byte-stable idempotency, op positional selection; fixture references under fixtures/mini/docs/planning/references/.
6. docs skill + per-skill doc widen to four artifacts.

Files to touch

Location	Kind	Change
plugin/lib/services/docs/generate.ts	modify	buildReferencesData, artifact registry growth, IndexData sections
plugin/lib/services/docs/references_template.eta	new	Roster layout + preamble
plugin/lib/services/docs/index_template.eta	modify	Appendix Glossary/References sections; Start-here row
plugin/lib/services/docs/ops/generate.ts	modify	Artifact enum gains references
plugin/lib/services/docs/tests/generate_references.test.ts	new	Assembly + idempotency + op selection
plugin/lib/services/docs/tests/fixtures/mini/docs/planning/references/	new	Fixture instances (active/draft/retired/no-url)
plugin/cli/tests/goldens/docs-help.txt	modify	Artifact list re-snapshot
plugin/skills/docs/SKILL.md	modify	Four artifacts
docs/skills/docs.md	modify	Mirror
docs/references.md	new	Born generated (preamble-only until T-XUTL)
docs/index.md	modify	Regenerated with the Appendix sections

Acceptance criteria

• AC-1: sdlc docs generate references writes docs/references.md; a second run is byte-identical.
• AC-2: docs/index.md’s Appendix shows generated Glossary and References sections (fixtures and live corpus).
• AC-3: Bare sdlc docs generate emits all four artifacts in canonical order index glossary references site.
• AC-4: An empty docs/planning/references/ renders a preamble-only references.md without error.

Out of scope

• Site pages (T-8YB9, T-E2B1); the seed corpus (T-XUTL).

Dependencies

• T-UE7T — the reference package and references/ dir must exist.

Discovery context

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

Depends on

T-UE7T

---

← Back to Tasks