spec-kitty-cli 3.2.0rc38__tar.gz → 3.2.0rc40__tar.gz

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/CHANGELOG.md

@@ -9,6 +9,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0rc40] - 2026-06-07
+
+### ✨ Added
+
+- Introduced `Lane.GENESIS` pseudo-state and a canonical `WPState` State-pattern FSM in
+  `specify_cli.status.wp_state`, making the FSM the single source of truth for WP lanes,
+  edges, and transitions (mission `wp-lane-state-machine-fsm-01KTGZAZ`).
+- Added ADR `2026-06-07-1-wp-lane-fsm-genesis-and-finalize-clobber.md` documenting the
+  genesis-lane bootstrap and the finalize event-log clobber fix.
+
+### 🔧 Changed
+
+- Routed all WP lane validation and mutation through the single FSM transition primitive;
+  callers no longer reconstruct transition authority from derived constants (#1666).
+
+### 🐛 Fixed
+
+- `implement` and `finalize` no longer overwrite the coordination branch's canonical
+  status event log (`status.events.jsonl`/`status.json`) with the primary checkout's
+  stale copies, preserving seeded lane state on coordination-topology missions (#1589).
+- Reconciled the genesis gate and `spec_kitty_events` 6.0.0 expectations for CI.
+
+## [3.2.0rc39] - 2026-06-07
+
+### ✨ Added
+
+- Added `session_presence` package with `SessionPresenceManager`, `InstallResult`,
+  `ClaudeCodeWriter`, `MarkdownRulesWriter`, `ClaudeCodeHookRegistrar`, `UpgradeChecker`,
+  `SessionPresenceContent`, and supporting writer/hook infrastructure.
+- Added `spec-kitty session-start` CLI command (invoked by the Claude Code `SessionStart`
+  hook) that emits an orientation block to stdout when run inside a spec-kitty project.
+  The command always exits 0 and never blocks a Claude Code session start.
+- `spec-kitty init` now calls `SessionPresenceManager.install()` after saving agent
+  configuration, writing the orientation block and registering the `SessionStart` hook for
+  Claude Code projects automatically.
+- Added Phase 1 upgrade migration (`3_3_0_session_presence_claude_code`) that detects
+  existing Claude Code projects missing the orientation section or `SessionStart` hook and
+  backfills both artefacts on `spec-kitty upgrade`.
+
+### 🐛 Fixed
+
+- Work packages can now declare `scope: codebase-wide` so cross-cutting/refactor
+  WPs are exempt from `owned_files` overlap validation, end-to-end through
+  `finalize-tasks` (#1753). Two coupled defects were fixed: (1) the strict
+  (`extra="forbid"`) `WPMetadata` parser rejected the `scope` key at parse time,
+  and (2) `OwnershipManifest.from_frontmatter` hard-coded `scope = None` on its
+  `WPMetadata` branch — the exact path `finalize-tasks` uses — silently dropping
+  the exemption even when the key parsed. The adapter now propagates `scope`, and
+  acceptance tests assert that narrow WPs claiming the same files still fail
+  regardless of lane/dependency structure, while a codebase-wide WP is exempt.
+  Also removed redundant `@overload` stubs on `from_frontmatter` that tripped
+  strict mypy (`overload-cannot-match`).
+
+### 📝 Docs
+
+- AGENTS.md: added "Use Canonical Sources, Never Improvise" guidance and a
+  ruff/mypy-clean (no disabled checks) code-style rule.
+- `tasks-finalize` doctrine prompt: documented ownership-overlap handling for
+  domain/refactor missions (linearize shared surfaces; declare codebase-wide).
+
 ## [3.2.0rc38] - 2026-06-06
 
 ### ✨ Added

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0rc38
+Version: 3.2.0rc40
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
@@ -67,7 +67,7 @@ Requires-Dist: readchar>=4.2.1
 Requires-Dist: requests>=2.33.0
 Requires-Dist: rich>=14.3.3
 Requires-Dist: ruamel-yaml>=0.18.0
-Requires-Dist: spec-kitty-events<6.0.0,>=5.2.0
+Requires-Dist: spec-kitty-events<7.0.0,>=6.0.0
 Requires-Dist: spec-kitty-tracker<0.5,>=0.4
 Requires-Dist: toml>=0.10.2
 Requires-Dist: transitions>=0.9.2

spec_kitty_cli-3.2.0rc40/kitty-specs/session-presence-multi-harness-01KTH57W/tasks/README.md

@@ -0,0 +1,64 @@
+# Tasks Directory
+
+This directory contains work package (WP) prompt files.
+
+## Directory Structure (v0.9.0+)
+
+```
+tasks/
+├── WP01-setup-infrastructure.md
+├── WP02-user-authentication.md
+├── WP03-api-endpoints.md
+└── README.md
+```
+
+All WP files are stored flat in `tasks/`. Status is tracked in `status.events.jsonl`, not in WP frontmatter.
+
+## Work Package File Format
+
+Each WP file **MUST** use YAML frontmatter:
+
+```yaml
+---
+work_package_id: "WP01"
+title: "Work Package Title"
+dependencies: []
+planning_base_branch: "pr/session-presence-multi-harness"
+merge_target_branch: "pr/session-presence-multi-harness"
+branch_strategy: "Planning artifacts were generated on pr/session-presence-multi-harness; completed changes must merge back into pr/session-presence-multi-harness."
+subtasks:
+  - "T001"
+  - "T002"
+phase: "Phase 1 - Setup"
+assignee: ""
+agent: ""
+shell_pid: ""
+history:
+  - timestamp: "2025-01-01T00:00:00Z"
+    agent: "system"
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+
+# Work Package Prompt: WP01 – Work Package Title
+
+[Content follows...]
+```
+
+## Status Tracking
+
+Status is tracked via the canonical event log (`status.events.jsonl`), not in WP frontmatter.
+Use `spec-kitty agent tasks move-task` to change WP status:
+
+```bash
+spec-kitty agent tasks move-task <WPID> --to <lane>
+```
+
+Example:
+```bash
+spec-kitty agent tasks move-task WP01 --to doing
+```
+
+## File Naming
+
+- Format: `WP01-kebab-case-slug.md`
+- Examples: `WP01-setup-infrastructure.md`, `WP02-user-auth.md`

spec_kitty_cli-3.2.0rc40/kitty-specs/wp-lane-state-machine-fsm-01KTGZAZ/tasks/README.md

@@ -0,0 +1,64 @@
+# Tasks Directory
+
+This directory contains work package (WP) prompt files.
+
+## Directory Structure (v0.9.0+)
+
+```
+tasks/
+├── WP01-setup-infrastructure.md
+├── WP02-user-authentication.md
+├── WP03-api-endpoints.md
+└── README.md
+```
+
+All WP files are stored flat in `tasks/`. Status is tracked in `status.events.jsonl`, not in WP frontmatter.
+
+## Work Package File Format
+
+Each WP file **MUST** use YAML frontmatter:
+
+```yaml
+---
+work_package_id: "WP01"
+title: "Work Package Title"
+dependencies: []
+planning_base_branch: "mission/wp-lane-state-machine-fsm"
+merge_target_branch: "mission/wp-lane-state-machine-fsm"
+branch_strategy: "Planning artifacts were generated on mission/wp-lane-state-machine-fsm; completed changes must merge back into mission/wp-lane-state-machine-fsm."
+subtasks:
+  - "T001"
+  - "T002"
+phase: "Phase 1 - Setup"
+assignee: ""
+agent: ""
+shell_pid: ""
+history:
+  - timestamp: "2025-01-01T00:00:00Z"
+    agent: "system"
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+
+# Work Package Prompt: WP01 – Work Package Title
+
+[Content follows...]
+```
+
+## Status Tracking
+
+Status is tracked via the canonical event log (`status.events.jsonl`), not in WP frontmatter.
+Use `spec-kitty agent tasks move-task` to change WP status:
+
+```bash
+spec-kitty agent tasks move-task <WPID> --to <lane>
+```
+
+Example:
+```bash
+spec-kitty agent tasks move-task WP01 --to doing
+```
+
+## File Naming
+
+- Format: `WP01-kebab-case-slug.md`
+- Examples: `WP01-setup-infrastructure.md`, `WP02-user-auth.md`

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0rc38"
+version = "3.2.0rc40"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -72,8 +72,12 @@ dependencies = [
     # src/runtime/next/ (see WP01 of mission
     # shared-package-boundary-cutover-01KQ22DS), and absence is enforced by
     # tests/architectural/test_pyproject_shape.py.
-    # TeamSpace dry-run and legacy-envelope normalization require the 5.2.0 event contract.
-    "spec-kitty-events>=5.2.0,<6.0.0",
+    # spec-kitty-events 6.0.0 adds the canonical `genesis` lane (major bump per
+    # the events lane-vocabulary contract). The CLI emits `from_lane="genesis"`
+    # seeds, so it requires the genesis-aware contract. The capability gate in
+    # src/specify_cli/status/emit.py (_EVENTS_SUPPORTS_GENESIS) still degrades
+    # gracefully if an older events package is somehow present at runtime.
+    "spec-kitty-events>=6.0.0,<7.0.0",
     "spec-kitty-tracker>=0.4,<0.5",
     "websockets>=12.0",  # WebSocket client for sync protocol
     "toml>=0.10.2",  # Config file parsing

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/agent_profiles/built-in/python-pedro.agent.yaml

@@ -27,6 +27,8 @@ context-sources:
     - "024"
     - "025"
     - "030"
+  tactics:
+    - test-scaffolding-as-design-smell
   additional:
     - coding-standards
     - test-strategy
@@ -165,3 +167,10 @@ directive-references:
   - code: "034"
     name: Test-First Development
     rationale: Tests define the contract before production code — TDD red-green-refactor is the default implementation rhythm
+
+tactic-references:
+  - id: test-scaffolding-as-design-smell
+    rationale: >
+      Write code whose behavior is testable without infrastructure. If a unit test
+      would need real files, git, or several mocks to run, invert the dependency and
+      extract a pure seam before adding the test, rather than expanding the mock setup.

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/agent_profiles/built-in/randy-reducer.agent.yaml

@@ -33,6 +33,7 @@ context-sources:
     - semantic-compression-dead-weight-elimination
     - semantic-compression-semantic-consolidation
     - semantic-compression-equivalence-verification
+    - test-scaffolding-as-design-smell
   additional:
     - semantic-compression-paradigm
     - characterization-tests
@@ -154,3 +155,5 @@ tactic-references:
     rationale: Collapse split business-rule paths into one canonical owner
   - id: semantic-compression-equivalence-verification
     rationale: Prove the smaller implementation still preserves the behavioral envelope
+  - id: test-scaffolding-as-design-smell
+    rationale: Heavy test setup signals duplicated, IO-coupled code paths and a missing seam — extract one pure boundary and collapse the variants.

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/agent_profiles/built-in/reviewer-renata.agent.yaml

@@ -29,6 +29,7 @@ context-sources:
     - code-review-incremental
     - language-driven-design
     - reverse-speccing
+    - test-scaffolding-as-design-smell
   additional:
     - behaviour-driven-development-paradigm
     - review-checklist
@@ -161,3 +162,7 @@ tactic-references:
     rationale: >
       Verify that every behavior covered in scope has a passing executable scenario
       before approving the WP. Scenarios not yet wired to step definitions block approval.
+  - id: test-scaffolding-as-design-smell
+    rationale: >
+      Treat heavy test setup or many infrastructure mocks in a diff as a design
+      smell to flag, not accept — request a pure boundary/seam instead of more doubles.

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/graph.yaml

@@ -277,6 +277,9 @@ nodes:
 - urn: styleguide:reasons-canvas-writing
   kind: styleguide
   label: REASONS Canvas Writing Styleguide
+- urn: styleguide:test-desiderata-and-boundaries
+  kind: styleguide
+  label: Test Desiderata and Clear Test Boundaries
 - urn: styleguide:testing-principles
   kind: styleguide
   label: Testing Principles Styleguide
@@ -586,6 +589,9 @@ nodes:
 - urn: tactic:test-readability-clarity-check
   kind: tactic
   label: Test Readability and Clarity Check
+- urn: tactic:test-scaffolding-as-design-smell
+  kind: tactic
+  label: Test Setup Scaffolding as a Design Smell
 - urn: tactic:test-to-system-reconstruction
   kind: tactic
   label: Test-to-System Reconstruction
@@ -1298,6 +1304,10 @@ edges:
 - source: agent_profile:python-pedro
   target: directive:DIRECTIVE_030
   relation: requires
+- source: agent_profile:python-pedro
+  target: tactic:test-scaffolding-as-design-smell
+  relation: requires
+  reason: Write code whose behavior is testable without infrastructure. If a unit test would need real files, git, or several mocks to run, invert the dependency and extract a pure seam before adding the test, rather than expanding the mock setup.
 - source: agent_profile:randy-reducer
   target: directive:DIRECTIVE_001
   relation: requires
@@ -1334,6 +1344,10 @@ edges:
   target: tactic:semantic-compression-semantic-consolidation
   relation: requires
   reason: Collapse split business-rule paths into one canonical owner
+- source: agent_profile:randy-reducer
+  target: tactic:test-scaffolding-as-design-smell
+  relation: requires
+  reason: Heavy test setup signals duplicated, IO-coupled code paths and a missing seam — extract one pure boundary and collapse the variants.
 - source: agent_profile:researcher-robbie
   target: directive:DIRECTIVE_003
   relation: requires
@@ -1378,6 +1392,10 @@ edges:
   target: tactic:test-readability-clarity-check
   relation: requires
   reason: 'Apply the dual-perspective reconstruction check during review: read only the test suite and attempt to reconstruct system behavior, then compare against the specification. Tests that fail reconstruction are documentation gaps.'
+- source: agent_profile:reviewer-renata
+  target: tactic:test-scaffolding-as-design-smell
+  relation: requires
+  reason: Treat heavy test setup or many infrastructure mocks in a diff as a design smell to flag, not accept — request a pure boundary/seam instead of more doubles.
 - source: directive:DIRECTIVE_001
   target: tactic:paula-patterns-architecture-scout-review
   relation: requires
@@ -2466,6 +2484,18 @@ edges:
   target: tactic:test-boundaries-by-responsibility
   relation: suggests
   when: After identifying coverage gaps, use this tactic to determine the correct level at which to add missing tests
+- source: tactic:test-scaffolding-as-design-smell
+  target: styleguide:test-desiderata-and-boundaries
+  relation: suggests
+  when: The styleguide this tactic operationalizes — desiderata as trade-offs and infrastructure-as-shared-state as the anti-pattern this tactic detects
+- source: tactic:test-scaffolding-as-design-smell
+  target: tactic:function-over-form-testing
+  relation: suggests
+  when: Use to keep the extracted seam's tests asserting behavior, not structure, so they stay structure-insensitive
+- source: tactic:test-scaffolding-as-design-smell
+  target: tactic:test-boundaries-by-responsibility
+  relation: suggests
+  when: Use to decide what belongs inside the extracted seam versus what is stubbed at the boundary
 - source: tactic:test-to-system-reconstruction
   target: directive:DIRECTIVE_034
   relation: suggests

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/missions/mission-steps/software-dev/implement/prompt.md

@@ -39,8 +39,13 @@ guardrails for bulk operations.
 ## Working Directory
 
 **IMPORTANT**: This step works inside the execution workspace (worktree)
-allocated by `spec-kitty agent action implement WPxx --agent <name>`. Do NOT modify files outside
-your `owned_files` boundaries.
+allocated by `spec-kitty agent action implement WPxx --agent <name>`. Prefer to stay within
+your `owned_files` boundaries. If a small, well-justified change to a file outside the map is
+genuinely needed to deliver the WP (e.g. a one-line prerequisite or a stale assertion that
+pins a now-deleted internal), make it and record a one-line rationale in the commit message —
+that is better than a convoluted in-bounds workaround or a duplicated local re-implementation.
+The finalize ownership-overlap gate remains the guard against *parallel* WPs colliding on the
+same file.
 
 **In repos with multiple missions, always pass `--mission <handle>` to every spec-kitty command.** The `<handle>` can be the mission's `mission_id` (ULID), `mid8` (first 8 chars of the ULID), or `mission_slug`. The resolver disambiguates by `mission_id` and returns a structured `MISSION_AMBIGUOUS_SELECTOR` error on ambiguity — there is no silent fallback.
 
@@ -123,7 +128,7 @@ guaranteed to carry.
 
 Read the WP prompt file from `feature_dir/tasks/WPxx-slug.md`.
 Parse frontmatter for:
-- `owned_files` -- only modify files matching these globs
+- `owned_files` -- prefer to modify files matching these globs; out-of-map edits are allowed when small and well-justified (record a one-line rationale)
 - `authoritative_surface` -- primary directory for this WP
 - `execution_mode` -- `code_change` or `planning_artifact`
 - `subtasks` -- ordered list of subtask IDs
@@ -157,7 +162,7 @@ Work through each subtask in order:
 
 After all subtasks are complete:
 - All tests pass
-- No files outside `owned_files` were modified
+- Any files modified outside `owned_files` are small, justified, and have a one-line rationale in the commit message
 - Code follows project conventions (run linter if configured)
 - **Diff-scoped ruff sweep (MANDATORY before moving to `for_review`)** —
   catches lint regressions before they reach the cycle-1 reviewer. The WP06

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/missions/mission-steps/software-dev/review/prompt.md

@@ -16,8 +16,9 @@ compliance with any applicable guardrails (e.g., bulk edit occurrence maps).
 ## Working Directory
 
 **IMPORTANT**: This step works inside the execution workspace (worktree)
-allocated by `spec-kitty agent action review WPxx --agent <name>`. Do NOT modify files outside
-your `owned_files` boundaries.
+allocated by `spec-kitty agent action review WPxx --agent <name>`. Prefer to stay within
+your `owned_files` boundaries; any out-of-map change must be small, justified, and carry a
+one-line rationale in the commit message.
 
 **In repos with multiple missions, always pass `--mission <handle>` to every spec-kitty command.** The `<handle>` can be the mission's `mission_id` (ULID), `mid8` (first 8 chars of the ULID), or `mission_slug`. The resolver disambiguates by `mission_id` and returns a structured `MISSION_AMBIGUOUS_SELECTOR` error on ambiguity — there is no silent fallback.
 
@@ -105,7 +106,7 @@ above documents what the prompt is guaranteed to carry.
 
 Read the WP prompt file from `feature_dir/tasks/WPxx-slug.md`.
 Parse frontmatter for:
-- `owned_files` -- only these globs should have been modified
+- `owned_files` -- the expected modification surface; out-of-map edits are acceptable when small and accompanied by a one-line rationale
 - `authoritative_surface` -- primary directory for this WP
 - `execution_mode` -- `code_change` or `planning_artifact`
 - `subtasks` -- ordered list of subtask IDs
@@ -169,7 +170,7 @@ in the review summary so downstream automation can route the WP correctly.
 For each subtask:
 1. Confirm the subtask has been implemented as specified
 2. Check that tests exist and pass (for code_change subtasks)
-3. Verify no files outside `owned_files` were modified
+3. Verify any files modified outside `owned_files` are small, justified, and carry a one-line rationale (do not reject a well-justified, rationale-logged crossing)
 
 ### 4. Check Quality
 

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/missions/mission-steps/software-dev/tasks/prompt.md

@@ -215,7 +215,7 @@ Prompts do not rediscover feature context. Commands do.
    **Ownership rules**:
    - No two WPs may have overlapping `owned_files`.
    - Use specific paths, not broad globs like `src/**`.
-   - Agents working on a WP must not modify files outside their `owned_files` list.
+   - Agents working on a WP should prefer to stay within their `owned_files` list; a small, well-justified out-of-map edit is acceptable when recorded with a one-line rationale (the no-overlap rule above is the real guard against parallel-WP collisions).
    - Run `spec-kitty agent mission finalize-tasks --validate-only --mission <mission-slug> --json` to check ownership before committing.
 
 8. **Finalize tasks with dependency parsing and commit**:

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/missions/mission-steps/software-dev/tasks-finalize/prompt.md

@@ -51,6 +51,39 @@ do **not** run finalization. Report the blocking fields
 `spec-kitty agent tasks map-requirements --mission <mission-slug> --json` or by
 updating WP `requirement_refs`.
 
+### 1b. Ownership Overlap — domain-focused / refactor missions
+
+If validate-only fails with `"error": "Ownership validation failed"` and
+`ownership_errors` listing overlapping `owned_files`:
+
+**Ownership collisions are EXPECTED for domain-focused and refactor-oriented
+missions** (cross-cutting strangler work, repo-wide migrations, boundary
+enforcement) where many work packages legitimately edit the same files. This is
+not a defect in the slicing. Handle it as follows:
+
+1. **Linearize shared surfaces (execution safety).** Work packages that touch the
+   same files MUST be made dependent/linear (via `Depends on WPxx`) so they
+   execute sequentially in one lane and **share a single worktree** (or run
+   direct-to-branch). Limited parallelism is acceptable and expected for these
+   missions — do not force artificial parallelism. Note: linearization protects
+   the *worktree* from concurrent edits; it does **not** by itself satisfy
+   ownership validation (see step 3).
+2. **Declare cross-cutting WPs codebase-wide (the exemption).** A WP that is
+   expected to overlap broadly should carry `scope: codebase-wide` in its
+   frontmatter; the ownership validator exempts codebase-wide WPs from overlap
+   and authoritative-surface checks. Keep the genuinely-targeted WPs (single test
+   file, single module) narrow and mutually disjoint.
+3. **`codebase-wide` is the ONLY exemption.** Two *narrow* WPs that claim the same
+   files **always** fail ownership validation — regardless of whether they sit in
+   different lanes or are linked in a dependency hierarchy. Dependency/lane
+   structure never bypasses the overlap check. If WPs legitimately share a
+   surface, mark the broadly-overlapping one `scope: codebase-wide`; otherwise
+   re-slice so the narrow WPs are disjoint.
+
+Do **not** fabricate disjoint `owned_files` that misrepresent which WP edits
+which files solely to pass validation — linearize and/or declare codebase-wide
+instead.
+
 ### 2. Run Finalization Command
 
 Only after validate-only exits successfully, run the mutating finalization

{spec_kitty_cli-3.2.0rc38 → spec_kitty_cli-3.2.0rc40}/src/doctrine/missions/mission-steps/software-dev/tasks-packages/prompt.md

@@ -220,7 +220,7 @@ Include the correct implementation command:
 - `owned_files`: List of glob patterns for files this WP touches — no two WPs may overlap.
 - `authoritative_surface`: Path prefix that must be a prefix of at least one `owned_files` entry.
 - `execution_mode`: `"code_change"` for source code changes, `"planning_artifact"` for kitty-specs docs.
-- Agents working on a WP must not modify files outside their `owned_files` list.
+- Agents working on a WP should prefer to stay within their `owned_files` list; a small, well-justified out-of-map edit is acceptable when recorded with a one-line rationale (the no-overlap rule above is the real guard against parallel-WP collisions).
 
 ### 4a. Assign Agent Profiles
 

spec_kitty_cli-3.2.0rc40/src/doctrine/styleguides/built-in/test-desiderata-and-boundaries.styleguide.yaml

@@ -0,0 +1,134 @@
+schema_version: "1.0"
+id: test-desiderata-and-boundaries
+title: Test Desiderata and Clear Test Boundaries
+scope: testing
+applies_to_languages: []
+
+# Sources (traceable adoption):
+#   - Kent Beck, "Test Desiderata" — https://testdesiderata.com/
+#   - Stijn Dejongh, "Define Test Boundaries" —
+#     https://patterns.sddevelopment.be/practices/define_test_boundaries/
+# Complements the broader `testing-principles` styleguide; this artifact focuses
+# on (a) the desiderata as properties to trade off deliberately and (b) drawing
+# the test boundary by functional responsibility so infrastructure is stubbed at
+# a real seam rather than mocked ad hoc.
+
+principles:
+  # — Kent Beck's twelve test desiderata: properties to OPTIMIZE via deliberate
+  #   trade-offs, not to maximize all at once. Conflicts are often a design smell
+  #   resolvable by better boundaries/composability, not an inherent limit.
+  - "Desiderata are trade-offs: choose which properties a given test optimizes; do not pretend one test maximizes all twelve at once."
+  - "Isolated: a test returns the same result regardless of the order tests run in — no shared mutable state, no order dependence."
+  - "Composable: dimensions of variability can be tested separately and combined, so coverage grows without combinatorial test counts."
+  - "Deterministic: if nothing changes, the result does not change — no reliance on clocks, randomness, network, or ambient filesystem state."
+  - "Fast: a test runs quickly enough to run after every small change without friction."
+  - "Writable: a test is cheap to write relative to the code it covers; expensive setup is a signal the boundary is wrong."
+  - "Readable: a test communicates the motivation and scenario to a future reader without spelunking the production code."
+  - "Behavioral: a test is sensitive to changes in the behavior of the code under test."
+  - "Structure-insensitive: a test does not change its result when internal structure is refactored without behavior change."
+  - "Automated: a test runs without human intervention."
+  - "Specific: when a test fails, the cause is obvious from the failure alone."
+  - "Predictive: when all tests pass, the code is fit for production."
+  - "Inspiring: passing the suite inspires confidence to ship."
+  # — Clear Test Boundaries (Define Test Boundaries):
+  - "Boundary by responsibility, not by layer: include exactly the components responsible for the behavior under test; everything else is outside the boundary."
+  - "Stub infrastructure at the boundary: external services, data access, and IO (filesystem, database, clock, network, randomness, git) live OUTSIDE the boundary and are replaced by test doubles or pure inputs."
+  - "Assert observable outcomes, not mechanisms: test the behavior crossing the boundary, not internal call counts or field values, to stay structure-insensitive."
+  - "If a unit test needs heavy infrastructure scaffolding to run, the boundary is wrong: extract a pure seam that takes domain inputs so the behavior is testable without IO."
+
+patterns:
+  - name: Draw the boundary by functional responsibility
+    description: >
+      Pick the behavior to validate, identify the components responsible for it,
+      and place the test boundary around exactly those. Replace infrastructure
+      (IO, data access, external services) with simple inputs or doubles at the
+      boundary. This keeps tests Fast, Isolated, Writable, and
+      Structure-insensitive (Define Test Boundaries; Beck's desiderata).
+    bad_example: |
+      # The unit reaches the filesystem + git directly, so the "unit" test must
+      # build a real mission on disk and mock every infrastructure seam.
+      def test_overlap_rejected(tmp_path):
+          _write_mission_dir(tmp_path)                  # real files
+          with patch("...locate_project_root"), \
+               patch("...safe_commit"), patch("...run_command"), \
+               patch("...bootstrap_canonical_state"):    # infra scaffolding
+              finalize_tasks(feature="m", validate_only=True)
+          # assertion buried behind subprocess/JSON parsing
+    good_example: |
+      # A pure seam takes domain inputs; the behavior is validated with plain
+      # stubs — no files, no git, no command mocking. The IO stays outside.
+      def test_overlap_rejected():
+          manifests = build_wp_manifests({
+              "WP01": wp(owned=["src/foo/**"]),
+              "WP02": wp(owned=["src/foo/**"]),   # overlapping, narrow
+          })
+          assert not validate_ownership(manifests).passed
+
+  - name: Resolve desiderata tension by design, not by accepting brittleness
+    description: >
+      When two desiderata appear to conflict (e.g. Predictive vs Fast,
+      Behavioral vs Structure-insensitive), prefer a design change — a clearer
+      boundary, a pure function, composition — over a brittle test. A pure seam
+      at the boundary usually recovers Fast + Isolated + Specific simultaneously.
+    good_example: |
+      # Behavioral AND structure-insensitive: assert the outcome that crosses the
+      # boundary, regardless of which internal helper produced it.
+      assert resolve_action_context(repo, "m", "WP01").target_branch == expected
+
+anti_patterns:
+  - name: Infrastructure as untyped shared mutable state
+    description: >
+      When production code reads and writes infrastructure (the filesystem,
+      database, git) DIRECTLY from many surfaces instead of through an owning
+      application boundary, that infrastructure becomes un-owned shared mutable
+      state. Two consequences follow: (1) surfaces can disagree about the same
+      on-disk state (read/write forks, staleness); (2) tests cannot exercise the
+      logic without standing up the infrastructure or mocking many seams. The
+      mock/stub scaffolding in tests is a symptom, not the disease — the cure is an
+      owning boundary (a port / aggregate / pure resolver) the logic routes
+      through, which the test then drives with simple inputs.
+    bad_example: |
+      # Direct, scattered filesystem access — every caller re-reads/re-writes
+      # mission state, and every test must reconstruct that state on disk.
+      feature_dir = main_repo_root / "kitty-specs" / mission_slug
+      events = (feature_dir / "status.events.jsonl").read_text()
+      ...
+      (feature_dir / "status.events.jsonl").write_text(updated)   # another surface
+    good_example: |
+      # One owning boundary mediates the state; logic and tests depend on it,
+      # not on the filesystem. The IO lives in one place behind the seam.
+      status = MissionStatus.load(repo_root, mission_slug)   # owns read+write
+      status.transition(wp_id="WP01", to_lane="in_progress")
+      # tests drive MissionStatus / build_wp_manifests with stub inputs — no files
+
+  - name: Over-mocking to compensate for a missing boundary
+    description: >
+      Patching five infrastructure functions to test one behavior means the test
+      is fighting the absence of a seam. Mock only at true system boundaries; if
+      you must mock more, extract the boundary instead. Heavy mocking also makes
+      tests pass when the real integration is broken (loss of Predictive).
+    bad_example: |
+      with patch("a.locate_project_root"), patch("a.safe_commit"), \
+           patch("a.run_command"), patch("a.bootstrap_canonical_state"), \
+           patch("a.validate_ownership"):
+          run_command_under_test()   # nothing real is exercised
+    good_example: |
+      # Extract the decision into a pure function; mock nothing.
+      result = decide(domain_inputs)
+      assert result == expected
+
+quality_test: >
+  Can the behavior under test be validated with plain in-memory inputs and at
+  most one mock at a true system boundary? If the test needs real files, a git
+  repo, or several patched infrastructure functions, the boundary is in the
+  wrong place — extract a pure seam before adding the test.
+
+references:
+  - "https://testdesiderata.com/"
+  - "https://patterns.sddevelopment.be/practices/define_test_boundaries/"
+  - "src/doctrine/styleguides/built-in/testing-principles.styleguide.yaml"
+  - "src/doctrine/styleguides/built-in/mutation-aware-test-design.styleguide.yaml"
+  - "src/doctrine/tactics/built-in/testing/test-boundaries-by-responsibility.tactic.yaml"
+  - "src/doctrine/tactics/built-in/testing/function-over-form-testing.tactic.yaml"
+  - "src/doctrine/directives/built-in/030-test-and-typecheck-quality-gate.directive.yaml"
+  - "src/doctrine/directives/built-in/034-test-first-development.directive.yaml"