v1
2Layer 2 · Reference Approach

Core Concepts.

Everything is a Markdown document with YAML frontmatter and defined sections. Requirements are authored as linked items, which is what makes the whole set testable and traceable.

One shape for every document.

Every kind shares one shape: frontmatter (typed metadata a JSON Schema checks) and required sections (the audit checks they're present and complete). Plain Markdown a person can read and a diff can review. Examples use Aurora, the fictional sample project; its people are invented.

documents/PRJ-001-AUR/charter.md
---kind: charterproject: PRJ-001-AURid: AUR-chartersponsor: jordan.leestatus: approved---## ObjectiveCut median onboarding time from 14 days to under 2 days.## Success Criteria- Median onboarding time drops below 48 hours. - Manual setup tickets fall by at least 80%.

Every document belongs to a project.

Documents are organized project-first, and each project has a self-identifying id such as PRJ-001-AUR, which pairs a unique sequence with a short code. A project.md anchors each folder.

documents/PRJ-001-AUR/
project.md       # id: PRJ-001-AUR · code: AUR · sponsorcharter.md       # id: AUR-charterbrd.md           # items: AUR-BR-001, AUR-BR-002prd.md           # items: AUR-PR-014 (traces: AUR-BR-001)…

The AUR- code namespaces every id, so AUR-BR-001 and ATL-BR-001 are different requirements in different projects, each globally unique and each declaring its own project. A generated projects.yaml registers them all.

Requirements are linked items.

The unit of traceability is the item: a bullet with a stable ID and typed links to what it depends on. That turns a pile of documents into a queryable graph.

the chain, across four documents
**AUR-BR-001**: The business shall reduce onboarding time to under 2 days.**AUR-PR-014** (traces: AUR-BR-001): The product shall provide a self-serve flow.**AUR-AC-001** (verifies: AUR-PR-014): Given a new customer…, then an active account exists.**AUR-TC-001** (tests: AUR-AC-001): Complete the wizard → account active, zero tickets.

BR → PR → FR/NFR → AC → TC. Every hop is a typed link the pipeline checks: broken references block, and the matrix is generated from them.

Two tiers of checks.

The same split runs on every document and across the whole graph.

Structural: deterministic and blocking
Required fields and sections present, success criteria measurable, risks have owners, references resolve. Plain code, reliable enough to gate a merge. Integrity errors block at any status; completeness gaps are advisory for drafts and gate once a document is proposed. Open risks move the derived status only when they score at or above a configurable appetite. The CLI itself is covered by a published stability policy, and the policy's command reference is regenerated from the parser so it cannot drift.
Semantic: AI-graded and advisory
Is the objective specific? Does AUR-PR-014 actually fulfil AUR-BR-001? Each link is scored via the Anthropic API against a rubric chosen for its relation, since a mechanism contributing to a KPI deserves a different judgment than a story implementing a requirement. Grades are cached by content hash, so unchanged links are never re-billed and the per-run budget goes to new work. Results post to the PR. They never block.

Twenty-one kinds, one pattern.

Each kind is a template + schema + criteria trio. Adding a kind means adding a trio, with no new code for the common cases.

project
The project anchor, with unique id, code, sponsor, and status.
charter
Objective, measurable success criteria, sponsor, budget.
business-case
Problem, options, recommendation, costs, benefits.
brd
Business requirements as BR items.
prd
Product requirements (PR) + acceptance criteria (AC).
frnfr
Functional (FR) & non-functional (NFR) requirements.
user-story
Stories (US) in "As a… I want…" form.
test-cases
Test cases (TC) that verify acceptance criteria.
adr
Architecture decisions with a recorded status.
risk-register
Risks with probability, impact, owner, response.
raci-stakeholder
Roles matrix with one Accountable per activity.
qa-test-plan
Scope, environments, measurable exit criteria.
data-migration-plan
Sources, field mapping, validation, cutover.
release-cutover-plan
Ordered cutover steps and a rollback trigger.
rollback-plan
Trigger conditions and ordered rollback steps.
hypercare-plan
Support window, severities, measurable exit.
runbook
Operational procedures, monitoring, escalation.
operations
Service catalog with levels, measures, review freshness.
status-report
Period, RAG, cites risks from the register.
post-implementation-review
Outcomes vs objectives, lessons, actions.
benefits-realization
Measurable benefits vs the business case.