Contracts
characterization-envelope-contract.md
Contract: Characterization envelope (FR-008 / FR-006 / NFR-001)
Purpose: pin the trio's observable behaviour BEFORE refactor; every decomposition WP depends on this suite being green on pre-refactor code.
Three assertion layers: 1. Pure-core in→out — deterministic fixtures for each helper about to move; exact-value assertions. 2. CLI JSON envelope — drive agent action implement/review, spec-kitty implement, spec-kitty accept in --json mode via CliRunner; assert the envelope (_json_safe_output) after normalizing non-deterministic fields: git SHAs, at/timestamp ISO fields, absolute paths, worktree ids. Guarded alongside tests/integration/test_json_envelope_strict.py. 3. State-transition — assert lane/state transitions via the deterministic status-event reducer given event inputs (NOT wall-clock fields), covering rejection/rewind/resume.
Normalization rule: a field that varies by environment (SHA, timestamp, path, pid) is normalized to a stable token before comparison — never asserted raw.
Gate: an implement WP## for any decomposition WP is blocked until the characterization suite is committed green against the pre-refactor tree (tasks encode this as a hard dependency on the IC-CHAR WP).
seam-consumption-contract.md
Contract: Trio seam-only consumption (FR-004 / SC-002 / #2465)
Rule: workflow.py, implement.py, acceptance/__init__.py (and their extracted cores/executors) resolve mission read paths ONLY through the mission_runtime.resolution seam wrappers — never by importing leaf resolver primitives.
Allowed (seam wrappers): placement_seam(...).read_dir(kind) (a); resolve_handle_to_read_path(..., require_exists=True) (b); primary_feature_dir_for_mission(...) (c).
Forbidden in the trio: direct import/call of leaf primitives that bypass the kind-aware projection (the six-entry-point sprawl this consolidates).
Enforcement: extend tests/architectural/test_single_mission_surface_resolver.py with a trio-scoped assertion (AST import scan) that the three modules import only the allowed wrappers. Non-trio callers are OUT of scope (C-004) — the ratchet is trio-scoped.
Preservation: the three contracts (a/b/c) remain distinct; a refactor that routes a fail-closed (b) or topology-blind (c) site through the lenient (a) projection is a CONTRACT VIOLATION (data-loss / coord-follow regression), even if tests are green.