# Spec: the spec system

```
Status: READY
Stage: Process
Constitution: "The constitution rule" (spec-driven work), "The player
  contract" (spec-and-code pair), "Ticks and the defense rule"
Depends on: none
```

## Behavior

The `spec/` layer is the agent-targetable contract surface. A spec is not a
brainstorm, a devlog, or a wishlist. It is a scoped work order that an agent
can implement or audit without rehydrating the whole conversation.

Each spec must state:

- **Status** — where it is in the implementation lifecycle.
- **Status note** — optional prose explaining why that status is not final.
  The `Status:` value itself stays an exact enum.
- **Stage** — the milestone/scope it belongs to (`B1`, `B2`, `B3`,
  `Deferred`, `Release`, or `Process`).
- **Constitution** — the constitutional clauses it serves.
- **Depends on** — other specs that must exist or be implemented first.
- **Acceptance criteria** — observable tests/surfaces that prove the spec is
  implemented.

## Status semantics

`Status:` must be one of the exact values below. Do not append parenthetical
notes to it; use `Status note:` instead. Exact status values let agents and
scripts audit the spec surface without natural-language parsing.

- **DRAFT** — design is still forming; do not implement except exploratory
  scaffolding called out as such.
- **READY** — scoped tightly enough for an agent to implement.
- **IN PROGRESS** — implementation has started and criteria may be partial.
  The implementing commit or devlog should say which criteria are done and
  which remain.
- **BLOCKED** — implementation/audit is blocked by an open contradiction,
  missing decision, or external tool/auth issue. Link the Tangled issue or
  explicit blocker.
- **IMPLEMENTED** — every acceptance criterion holds in the sim core with
  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.

- A `Stage: B1` spec's acceptance criteria must be achievable during B1.
- Later-stage behavior belongs in a `Future / deferred` section or a
  separate later-stage spec.
- If implementation reveals that a criterion is actually later-stage, that
  is a meta-spec tick finding: move or split it rather than silently
  half-implementing it.
- If a spec serves multiple stages, split it unless the shared substrate is
  genuinely inseparable.

The common failure is writing a correct future rule into the wrong current
acceptance set. That makes agents think the current milestone is blocked by
work the constitution explicitly deferred.

## Acceptance criteria rules

Acceptance criteria should be:

- **Observable** — a player surface, sim state, log line, save field, or test
  can see it.
- **Testable** — a future agent knows what to assert.
- **Scoped** — no hidden later-milestone obligation.
- **Self-contained** — no requirement depends on local scratch files,
  `~/Downloads`, expired URLs, or another agent's private filesystem. If a
  reference is required to implement or audit the spec, commit it in the repo
  and link it by relative path.
- **Contract-linked** — if a bug violates it, the bug can be named against
  that criterion or the constitutional clause behind it.

Every bug found by a tick should be classified against either a
constitutional/player contract clause or a spec acceptance criterion. If no
criterion exists for the violated behavior, clarify the spec or file a
Tangled issue; do not let the bug float as vibes.

## Spec-change rule

Changing the spec system is itself spec work.

- Meta-spec changes should update this file.
- Behavior-affecting spec changes still need the normal same-commit
  constitution amendment and `Defense:` paragraph.
- Pure clarification that narrows agent interpretation without changing game
  behavior can live in `spec/` / `knowledge/` with a defense in the commit
  message, but does not need a `DESIGN.md` amendment unless it changes what
  the game promises.

## Acceptance criteria

1. `spec/README.md` points here and defines the same required header fields.
2. Current B1 specs declare `Stage: B1 — The Basement`.
3. `Status:` values are exact enum values; status prose lives in `Status note:`.
4. Spec-required reference assets are repo-relative and self-contained, not
   local-machine paths.
5. Future-stage requirements are not placed in B1 acceptance criteria unless
   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).