From fda0e107c6cf46686e93aee532a1499add06629c Mon Sep 17 00:00:00 2001 From: Cameron Date: Mon, 6 Jul 2026 14:13:22 -0700 Subject: [PATCH] Meta-spec: cross-spec contracts, as-built specs, Depends-on as audit scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three process learnings from parallel B1 work, rolled into meta.md: - Cross-spec contracts: shared identifiers/interfaces between systems must be stated as an explicit contract in one spec and referenced via Depends-on, not left as unwritten assumptions. Earned by the observer-id vs person-id drift that schedules.md surfaced (recruit/LookAway hit the wrong observer) — found independently by two parallel sessions. - Depends-on is the audit scope: implementing/changing a spec includes re-verifying the contracts of everything it depends on. - Specs must not silently contradict siblings; a modeling choice touching a depended-on spec's model is recorded (e.g. located witnessing as eyewitnessing vs detection's pooled signals), not made silently. - As-built specs: a spec documenting already-shipped code may start at IMPLEMENTED as the acceptance record (aggregate-observer.md). - Two new meta acceptance criteria + one for the check.sh completeness gate. Defense: meta-spec's own spec-change rule — 'meta-spec changes update this file'; these are process clarifications that narrow agent interpretation without changing game behavior, so they live in spec/ with this defense and need no DESIGN.md amendment. --- spec/meta.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/spec/meta.md b/spec/meta.md index 3fe19e5c..90a5f4c9 100644 --- a/spec/meta.md +++ b/spec/meta.md @@ -45,6 +45,41 @@ scripts audit the spec surface without natural-language parsing. tests, both frontends surface the behavior where applicable, save/load round-trips relevant state, and `knowledge/` reflects current reality. +**As-built specs.** In parallel work a spec is sometimes written *after* the +code it describes (a system shipped in one session before its spec landed in +another). Such a spec may be born at IMPLEMENTED, serving as the retroactive +**acceptance record** rather than a work order. Its acceptance criteria must +still be real and checked against the shipped code, and any criterion not yet +met is called out in the `Status note:` — an as-built spec is documentation +of what *is*, verified, not a rubber stamp. (Seen with aggregate-observer.md, +shipped in parallel and documented at IMPLEMENTED.) + +## Cross-spec contracts + +A spec owns one system, but systems share **interfaces and identifiers** — +and a shared contract that no spec states is a latent bug that only surfaces +when a second system relies on it. + +- **State shared contracts explicitly.** When two systems key off the same + identifier or interface (e.g. an observer's id *is* a person's id; a + machine's signature feeds a detection channel), the owning spec states the + contract and the relying spec references it via `Depends on`. Do not leave + it as an unwritten assumption that happens to be true. +- **`Depends on` is the audit scope.** Implementing or changing a spec + includes re-verifying the contracts of everything it depends on — and that + those dependencies' cross-references back into this system still hold. + Implementing schedules.md surfaced that observer ids had silently drifted + from person ids (recruit/LookAway hit the wrong observer); a stated + contract + dependency audit is what catches that before shipping. +- **Specs must not silently contradict each other.** The "never contradict + the constitution" rule extends to sibling specs. When an implementation + makes a modeling choice that touches a depended-on spec's model (e.g. + schedules.md modeling located witnessing as immediate eyewitnessing rather + than detection.md's pooled-signature flow), record the choice and its + relationship to that spec in the `Status note:` or a `Design note:`. If it + genuinely conflicts, that is a tick finding, not an implementer's silent + call. + ## Stage discipline Stage prevents future work from masquerading as present work. @@ -105,3 +140,10 @@ Changing the spec system is itself spec work. the constitution explicitly says the substrate must land in B1. 6. Ticks that find bugs or contradictions can name the contract/criterion they violate, or file an issue to clarify the missing criterion. +7. A spec's `Depends on` names the specs whose contracts it relies on; + shared identifiers/interfaces between systems are stated as a contract in + one spec, not left as unwritten assumptions. +8. An as-built spec (documenting shipped code) may start at IMPLEMENTED, but + its criteria are verified against the code and any unmet one is noted. +9. A spec has no truncated or empty required sections (enforced by + `tools/check.sh`: every spec carries acceptance criteria). -- 2.51.2