v1
2Layer 2 · Reference Approach

Reference.

Every kind is a Markdown document with YAML frontmatter and required sections. The canonical schema and audit criteria ship inside the docassert package, and your repo can override them; this page is the map.

All document kinds share kind, id, project, title, and status. The remaining fields vary by kind and are listed below.

The shared shape.

Frontmatter is typed metadata (validated against a JSON Schema); sections carry the content (checked for presence and completeness).

any-document.md
---kind: <one of the 21 below>project: PRJ-001-AUR   # the owning project's idid: AUR-brd        # <CODE>-<slug>, globally uniquetitle: Human-readable titlestatus: draft       # draft | proposed | approved | baselined---## A Required SectionContent, plus traceable items where the kind defines them.

Project identity.

Documents live in per-project folders. Each project is anchored by a project.md (the 21st kind, project) whose id is the canonical PRJ-NNN-CODE. The CODE namespaces every document id (AUR-brd) and item id (AUR-BR-001).

documents/PRJ-001-AUR/project.md
---kind: projectid: PRJ-001-AUR    # PRJ-<NNN>-<CODE>, unique across all projectscode: AUR            # 2–6 letters; namespaces this project's idsname: Aurora — Customer Onboarding Overhaulsponsor: jordan.leestatus: active         # proposed | active | on-hold | closed---

An optional repo: OWNER/NAME on the anchor maps the project to its code repository for the execution bridge. docassert projects generates projects.yaml from these anchors, and a CI check fails if it drifts or an id/code is duplicated. Checks: project-id-format.

Item & link syntax.

Traceable rows are bullets with a bold ID and optional typed links. Broken links always block; coverage of approved items is enforced.

convention
- **AUR-PR-014** (traces: AUR-BR-001, AUR-BR-003): The product shall provide a self-serve flow.
relationmeaningexample
traceschild requirement → the parent it refinesPR→BR · FR/NFR→PR · US→PR
verifiesacceptance criterion → the requirement it checksAC→PR/FR
teststest case → the acceptance criterion it exercisesTC→AC
threatensrisk → the item it endangersRISK→BR/PR
affectsdecision → the requirement it changesADR→FR/NFR

The twenty-one document kinds.

projectThe identity anchor: one per project folder, declaring the canonical id (PRJ-NNN-CODE), code, sponsor, lifecycle status, delivery profile, and the repo its execution bridges to.
frontmatterkind, id, project, title, status, code, name, sponsor, profile, repo
sectionsOverview · Scope
checksproject-id-format
charterThe contract for a piece of work.
frontmatterkind, id, project, title, status, sponsor, budget, dates
sectionsObjective · Success Criteria · Scope · Milestones (dated bullets draw the timeline; the target date is an implicit milestone) · Risks · Approval
checksmilestones-dated · measurable-success-criteria · risks-have-owner-and-mitigation · dates-consistent
business-caseThe justification, upstream of the BRD.
frontmatterkind, id, project, title, status, sponsor
sectionsProblem Statement · Options Considered · Recommendation · Costs · Benefits
checksrequired-sections
brdBusiness requirements.
frontmatterkind, id, project, title, status, owner
sectionsPurpose · Business Requirements · Out of Scope
itemsBR
checksitems-well-formed
prdProduct requirements and acceptance criteria.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Product Requirements · Acceptance Criteria
itemsPR (traces BR, optionally after another PR for sequencing) · AC (verifies PR)
checksitems-well-formed
frnfrFunctional & non-functional requirements.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Functional Requirements · Non-Functional Requirements
itemsFR · NFR (trace PR)
checksitems-well-formed
user-storyUser stories.
frontmatterkind, id, project, title, status, owner
sectionsOverview · User Stories
itemsUS (traces PR)
checksstory-format
test-casesTest cases.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Test Cases
itemsTC (tests AC)
checksitems-well-formed
adrArchitecture decision log.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Decisions
itemsADR (affects FR/NFR)
checksadr-items-have-status
risk-registerThe risk register. Risks carry a disposition (open, mitigated, accepted, closed); open risks hold derived status at amber only at or above the configurable risk appetite (probability × impact ≥ 6 by default), so writing a risk down does not cost the project its green.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Risks
itemsRISK (threatens BR/PR)
checksrisk-items-complete · risk-disposition-valid
raci-stakeholderRoles and responsibilities.
frontmatterkind, id, project, title, status, owner
sectionsStakeholders · RACI Matrix
checksraci-one-accountable
qa-test-planTest strategy and gates.
frontmatterkind, id, project, title, status, owner
sectionsScope · Test Approach · Environments · Entry Criteria · Exit Criteria
checksmeasurable-exit-criteria
data-migration-planHow data moves and is verified.
frontmatterkind, id, project, title, status, owner
sectionsScope · Source Systems · Field Mapping · Validation · Cutover · Rollback
checksmapping-table
release-cutover-planThe go-live switch.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Pre-Cutover Checklist · Cutover Steps · Verification · Rollback Trigger
checksnumbered-steps (Cutover Steps)
rollback-planThe abort path.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Trigger Conditions · Rollback Steps · Verification
checksnumbered-steps (Rollback Steps)
hypercare-planHeightened post-go-live support.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Support Window · Severity Levels · Escalation · Exit Criteria
checksmeasurable-exit-criteria
runbookOperational procedures.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Prerequisites · Procedures · Monitoring · Escalation
checksnumbered-steps (Procedures)
operationsA governed service catalog for ongoing work, chartered per period.
frontmatterkind, id, project, title, status, owner, review_by
sectionsOverview · Services
itemsSVC
checkssvc-items-complete · ops-review-fresh (advisory; a stale review turns derived status amber)
status-reportA point-in-time status.
frontmatterkind, id, project, title, status, owner, period, rag
sectionsSummary · Progress · Risks & Issues · Next Steps
checksreferences-risk
post-implementation-reviewClosure and lessons.
frontmatterkind, id, project, title, status, owner
sectionsSummary · Outcomes vs Objectives · What Went Well · What Could Improve · Lessons Learned · Follow-up Actions
checksrequired-sections
benefits-realizationBenefits vs the business case.
frontmatterkind, id, project, title, status, owner
sectionsOverview · Benefits · Measurement · Realized Value
checksmeasurable-items (Benefits)

The full JSON Schema, audit criteria, and a runnable sample for every kind live in the pipeline repo. Fork them; add your own.

schema/ · criteria/ · templates/ →