0039: Keep Project Maps Out Of The Verification Ledger

Status: Accepted

Date: 2026-07-22

Context

The Lanternworks dogfood map copied exact Unity test counts and source revisions into STAGE.md, .stage/project.yaml, and docs/verification.md. Ordinary product commits then made the orientation artifacts appear stale even when their architecture, ownership, operation contracts, and evidence boundaries had not changed.

The duplication did not improve verification. A reader could not tell which copy was authoritative, and an agent refreshing the map had to spend attention on bookkeeping unrelated to project orientation. It repeated the same class of mistake seen in retired evidence infrastructure: preserving data because STAGE could represent it, not because the map's consumer needed another copy.

Decision

• Treat adopted project maps as durable orientation surfaces.
• Record operation capability, readiness, effects, claim scope, and the canonical route to verification.
• Keep exact counts, revisions, timestamps, artifact hashes, and individual run outcomes in one canonical verification history, release record, or revision-bound external trial.
• Use available for a durable runnable operation. Use passed only when an artifact intentionally records a specific invocation and its provenance.
• Label retained last-known results as historical checkpoint evidence, never as proof of an unverified newer source state.
• Refresh maps when durable direction, language, ownership, architecture, operation contracts, evidence boundaries, risks, or decision rights change. An ordinary passing rerun or unrelated product commit does not require map churn.
• Preserve exact source metadata in external audits and release records because reproducible source identity is part of those artifacts' purpose.

Consequences

• Project maps remain useful after routine product commits.
• Verification results have one obvious authority instead of several drifting summaries.
• Agents spend less time refreshing numbers that do not change how work should be performed.
• A map can still expose a revision-bound checkpoint when its consumer needs one, but the choice and historical limitation must be explicit.
• Existing schemas remain compatible; this changes authoring guidance, not the supported artifact shape.

Evidence Boundary

This decision is based on one same-owner Unity dogfood project and the observed maintenance drift in its adopted map. It does not establish that every project needs a separate verification document. Small projects may keep canonical verification guidance in STAGE.md when that is genuinely the single source; they should still avoid duplicating volatile results elsewhere.