Spec Kitty

Contracts

commit-path-contract.md

Contract: coord-commit correctness (FR-001/002/003/004, NFR-001/002)

Behavioral contract

#	Given	When	Then
1	a coord-routed mission, complete identity triple	a bookkeeping write commits	routes to _commit_via_coordination_transaction; commits to the coord worktree; git show <coord_ref>:<path> exists; no primary residue
2	a coord-routed mission, INCOMPLETE identity triple (_load_coord_branch_meta returns a None)	the commit path runs	it FAILS LOUD (misroute guard) — it must NOT reach the legacy leaf and commit coord paths from repo_root
3	the legacy leaf is legitimately reached (coord-less path)	its porcelain pre-check runs	the pre-check runs against the resolved worktree root (not repo_root); no phantom "already committed" for gitignored coord files
4	a deliberately mis-placed write (worktree_root ≠ destination_ref)	safe_commit runs	raises SafeCommitHeadMismatch — the write is unrepresentable at commit (NFR-001 negative case)
5	a review-cycle (WORK_PACKAGE_TASK, PRIMARY) artifact	authored	lands in its PRIMARY home (tasks/<wp>/), never the coord husk
6	ANALYSIS_REPORT (re-homed PRIMARY)	authored	lands PRIMARY (target branch); NO coord copy is made
7	a status event on a COORD-topology mission	emitted	commits to the coord worktree (not primary-uncommitted)
8	a status event on a coord-LESS topology (SINGLE_BRANCH/LANES/flat)	emitted	the non-transactional primary write path is PRESERVED (no regression)

Invariants (must hold after this mission)

• assert_partition_invariant green (disjoint-and-total) after the ANALYSIS_REPORT re-home.
• safe_commit unchanged: HEAD==destination_ref guard + .worktrees/ path-policy intact (git/ is read-only here).
• No second, independently-writable copy of any COORD artifact (residue factory removed for coord kinds).
• The modern transaction path is unchanged in behavior — proven by an added regression, not a code edit.

Test contract (NFR-001/002)

CoordinationWorkspace.resolve), CliRunner on agent action implement/review; assert placement via git show <ref>:<path>. Reuse tests/regression/test_issue_2508.py + tests/integration/coord_topology_fixture.py.

with no --invocation-id; assert the failure mode (record whether the block is SafeCommitHeadMismatch = FR-002 seam, or the actor warning = FR-006 seam). The verdict gates the FR-005/006 claim on US2 AC-3.

• Real-repo e2e (no stubbed safe_commit): real git init + real git worktree add (via production
• Live #2861 causation repro (runs FIRST): agent action review WP## --agent tool:model:profile:role

gate-and-doctor-contracts.md

Contract: gate exemption (FR-007) + coord staleness (FR-008/009) + actor (FR-005/006)

Runtime-state gate exemption (FR-007, C-004)

#	Given	When	Then
1	a diff touching the running mission's OWN status.events.jsonl	the diff-compliance gate runs	that file is exempt (source="runtime-state", no violation); NO occurrence_map entry needed
2	a diff renaming ANOTHER mission's runtime files	the gate runs	those are NOT exempt (feature_dir mismatch)
3	a spec.md/plan.md/tasks.md change under the same feature_dir	the gate runs	still classifies (reviewable surface not exempt)
4	a non-runtime file under the mission's feature_dir	the gate runs	still classifies/violates per the normal rules

exemptions). check_review_diff_compliance threads the mission's own feature_dir + the named allowlist into assess_file/classify_path.

• The exemption branch fires BEFORE the path-heuristic classifier (mirroring the existing move/exception

Coord staleness (FR-008/009, C-003/C-005)

#	Given	When	Then
1	coord tip is a strict ancestor of target_branch	doctor coordination --check-staleness	reports stale (non-blocking); finalize-tasks prints a non-blocking WARN + recovery command
2	strict-ancestor + coord worktree clean	doctor coordination --fix	fast-forwards the coord branch to include target's new commits
3	coord diverged (not strict-ancestor) OR coord worktree dirty	doctor coordination --fix	FAILS LOUD with a unified diff; mutates nothing

"repair arbitrary drifted content" command. The reconciliation gate (review_artifact_consistency, now in merge/) is preserved as a fail-loud net, not deleted (NFR-003).

• --fix stays MINIMIZED (C-003): it does the Gap-1 fast-forward only. It does NOT grow into a general

Actor identity (FR-005/006, C-002/C-007)

#	Given	When	Then
1	compact --agent tool:model:profile:role, no dispatch Op	claim runs	actor = {role, tool, profile, model} parsed; tool is the bare token, not the whole string
2	partial --agent tool:: (missing segments)	claim runs	absent segments stay None on the actor — NO synthetic unknown-model/{tool}-default
3	--model without --invocation-id	claim runs	still RAISES (unchanged — C-002/C-007 provenance)
4	a correctly-parsed dict actor	emitted to the SaaS fanout	accepted (Union[str,Dict]), not rejected as non-string
5	(US2 AC-3) manual review claim succeeds	after the FR-002 fix	no --force needed; merge shows no false "hollow reviews" — NOTE: satisfied by FR-002, confirmed by the NFR-002 repro, not by FR-005/006 alone