Records And Control Surfaces¶

Purpose¶

This page maps the non-canon surfaces that still matter operationally:

records/ for governed history and proposal continuity
specs/ for versioned contracts
templates/ for reusable governed artifact shapes
governance/ for repo rules
meta/ for machine-readable routing and lifecycle truth
evidence/ for execution proof

These are not interchangeable with docs/.

Control Surface Map¶

flowchart TD
    A["Ledger control surfaces"] --> B["Records"]
    A --> C["Specs"]
    A --> D["Templates"]
    A --> E["Governance"]
    A --> F["Metadata"]
    A --> G["Evidence"]

    B --> B1["Proposals"]
    B --> B2["Decisions"]
    F --> F1["Routing"]
    F --> F2["Issue governance"]
    F --> F3["Launch and lifecycle"]

Records¶

Surface	Start here	Why it matters
records root	records/README.md	rule for proposal and decision history
proposals	records/proposals/README.md	RFC and proposal continuity
decisions	records/decisions/README.md	active decisions and ADR-backed history
active decision log	records/decisions/ACTIVE_DECISION_LOG.md	current working decision memory
ADR index	records/decisions/adr/README.md	durable architecture decision surface

Use records when:

you need historical traceability
you need to understand why a boundary exists
you need proposal continuity rather than current doctrine

Specs¶

Start here	Why it matters	High-signal documents
specs/ORB-REGISTRY.md	index of active ORB and governance specs	ORB-PROJ-001.md, ORB-REVIEW-001.md, ORB-EXEC-001.md

Use specs when:

a task depends on a contract baseline
a route requires contract or schema awareness
you need versioned technical truth rather than narrative canon

Templates¶

Start here	Why it matters	High-signal documents
templates/README.md	repo-level template inventory	EXECUTION-STATE-ISSUE-COMMENT-TEMPLATE.md, ISSUE-NORMALIZATION-COMMENT-TEMPLATE.md, ADR-TEMPLATE.md, RFC-DESIGN-TEMPLATE.md

Use templates when:

the shape of the artifact matters as much as the content
you need a governed issue comment, RFC, ADR, spec, or evidence record
you want to avoid inventing ad hoc task artifacts

Governance¶

Start here	Why it matters	High-signal documents
governance/GOVERNANCE-INDEX.md	layered map of repo governance	DOC-STRUCTURE-CONVENTION.md, README-SECTION-STANDARD.md, lifecycle/DEFINITION-OF-DONE.md, lifecycle/ADR-WORKFLOW.md

Use governance when:

you need a repo rule or lifecycle requirement
you need naming, structure, or closeout obligations
you need enforceable behavior rather than strategy guidance

Metadata¶

Start here	Why it matters	High-signal documents
meta/task-routing.yaml	route, mode, and obligation truth	meta/issue-governance.yaml, meta/project-lifecycle.yaml, meta/agent-launch-contract.yaml, meta/standards-registry.yaml

Use metadata when:

GitHub issue or project workflow must be interpreted deterministically
the task route, closeout obligations, or launch contract matters
machine-readable control truth is more important than prose summary

Evidence¶

Start here	Why it matters	High-signal documents
evidence/SPRINT-1/INDEX.md	example index into structured proof sets	evidence/phase-1-project-spine/P1-011/phase-1-spine-end-to-end-validation.md, evidence/SPRINT-1/PHASE-0-BOOTSTRAP/INDEX.md, evidence/LOCAL-DEV/v0.2/axiom-pack.md

Use evidence when:

you need execution proof instead of task intent
you need validation artifacts for a governed closeout
you need to inspect how a prior wave proved a claim

Evidence is proof, not canon. It should support closure and auditability, not replace current doctrine.

If you need a validation-first path across standards, specs, CI, and proof, continue to this site's Validation, Standards, And Evidence page.

Working Rule¶

Choose the surface that matches the kind of truth you need:

records/ for continuity and history
specs/ for versioned contracts
templates/ for artifact shape
governance/ for repo rules
meta/ for machine-readable control
evidence/ for proof

If you need approved human guidance, go back to docs/.