pactkit 2.18.0__tar.gz → 2.20.0__tar.gz

{pactkit-2.18.0 → pactkit-2.20.0}/.gitignore

@@ -58,6 +58,7 @@ pactkit-plugin/
 # Backup
 *.bak
 .mcp.json
+.pactkit/
 coder/
 docker/
 docs/slides/

{pactkit-2.18.0 → pactkit-2.20.0}/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.20.0] - 2026-08-22
+
+### Added
+- **Verified resumable Act checkpoints** (STORY-slim-146) — PactKit now persists Story-scoped continuation state with validated Spec, Board, test, regression, and lint evidence. `pactkit continuation status/verify/resume/checkpoint` supports safe cross-process recovery, stale-state detection, terminal completion, fresh-cycle archival, secret/path sanitization, and Story-level locking. All 13 runtime skills and the Classic, OpenCode, Codex, and Copilot deployments share the recovery contract.
+
+### Fixed
+- **Adapter-safe command rendering and deployment gates** (STORY-slim-145) — operation-aware prompt rendering preserves PactKit CLI semantics across adapters, rejects lossy command transformations, checks generated prompt integrity before writing, and blocks incompatible Core/adapter versions unless skew is explicitly acknowledged.
+
+## [2.19.0] - 2026-08-17
+
+### Added
+- **Spec Dependency Surface** (STORY-slim-143) — every scaffolded Spec now carries a machine-readable `## Dependency Surface` table (`Depends on` / `Provides` / `Touches` / `Conflict risk`). Story dependencies and file-level conflict surface are no longer implicit in the architect's head — they're data.
+- **`pactkit spec-graph`** (STORY-slim-143) — deterministic story dependency DAG from all Specs: topological **execution waves** (wave N depends only on waves < N; same-wave stories are parallelizable), a **file-overlap conflict matrix** (same-wave overlaps flagged unsafe-parallel), cycle detection with non-zero exit, and Mermaid output to `docs/architecture/graphs/story_graph.mmd`. Stdlib only (`graphlib`, `fnmatch`), zero new dependencies.
+- **Spec linter rules E010/W011** (STORY-slim-143) — dangling `Depends on` references (story ID with no Spec file) are now an Act-blocking ERROR; missing Dependency Surface is a WARNING. Reuses spec_linter's section-parsing helpers (newly public: `strip_code_blocks` / `section_text`).
+- **Sprint Wave Mode** (STORY-slim-144) — `/project-sprint` with empty arguments scans the backlog, consumes `pactkit spec-graph --json` (new flag), and runs conflict-free same-wave stories as parallel worktree subagents (cap `sprint.max_parallel`, default 3). Stories with same-wave conflicts or undeclared Touches are serialized safe-by-default. Wave gate: wave N+1 starts only after wave N is fully merged green; fail-fast with no auto-retry; resume by re-running (idempotent). Single-story mode with arguments is byte-for-byte unchanged.
+- **Plan playbook Dependency Surface step** (STORY-slim-143) — `/project-plan` Phase 3.2a now fills the table from Phase 1 trace findings, so every new Spec ships scheduling data.
+
 ## [2.18.0] - 2026-08-17
 
 ### Added

{pactkit-2.18.0 → pactkit-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.18.0
+Version: 2.20.0
 Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
 Project-URL: Homepage, https://pactkit.dev
 Project-URL: Repository, https://github.com/pactkit/pactkit-public
@@ -194,7 +194,7 @@ Or run the full cycle in one command:
 | **Done** | `/project-done` | Repo Maintainer | Regression gate -> Archive -> Conventional commit |
 | **Release** | `/project-release` | Repo Maintainer | Version bump -> Snapshot -> Git tag -> GitHub Release |
 | **PR** | `/project-pr` | Repo Maintainer | Push branch -> Create pull request via gh CLI |
-| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration |
+| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration; empty args = Wave Mode (parallel backlog stories via `spec-graph` waves + conflict matrix) |
 | **Hotfix** | `/project-hotfix` | Senior Developer | Fast-track fix bypassing PDCA (with traceability) |
 | **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
 | **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |
@@ -289,8 +289,9 @@ PactKit ships 36 deterministic CLI subcommands — operations that were previous
 | `pactkit upgrade` | Upgrade with format selection |
 | `pactkit version` | Show installed version |
 | `pactkit schema` | Print document schemas |
-| `pactkit doctor` | Diagnose project health (HLD drift, board, config) |
-| `pactkit spec-lint` | Validate spec structure (14 rules: E001-E008, W001-W006) |
+| `pactkit doctor` | Diagnose project health (HLD drift, board, config, deployment content parity, adapter skew) |
+| `pactkit spec-lint` | Validate spec structure (E001-E010, W001-W011; incl. dependency surface checks) |
+| `pactkit spec-graph` | Story dependency DAG: topological execution waves + file-conflict matrix (`--json` for orchestrators, `--write-graph` for Mermaid) |
 | `pactkit spec-status` | Update spec Status field (Draft/In Progress/Done) |
 | `pactkit guard` | Check project init markers |
 | `pactkit next-id` | Generate next Story/Bug ID |

{pactkit-2.18.0 → pactkit-2.20.0}/README.md

@@ -149,7 +149,7 @@ Or run the full cycle in one command:
 | **Done** | `/project-done` | Repo Maintainer | Regression gate -> Archive -> Conventional commit |
 | **Release** | `/project-release` | Repo Maintainer | Version bump -> Snapshot -> Git tag -> GitHub Release |
 | **PR** | `/project-pr` | Repo Maintainer | Push branch -> Create pull request via gh CLI |
-| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration |
+| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration; empty args = Wave Mode (parallel backlog stories via `spec-graph` waves + conflict matrix) |
 | **Hotfix** | `/project-hotfix` | Senior Developer | Fast-track fix bypassing PDCA (with traceability) |
 | **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
 | **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |
@@ -244,8 +244,9 @@ PactKit ships 36 deterministic CLI subcommands — operations that were previous
 | `pactkit upgrade` | Upgrade with format selection |
 | `pactkit version` | Show installed version |
 | `pactkit schema` | Print document schemas |
-| `pactkit doctor` | Diagnose project health (HLD drift, board, config) |
-| `pactkit spec-lint` | Validate spec structure (14 rules: E001-E008, W001-W006) |
+| `pactkit doctor` | Diagnose project health (HLD drift, board, config, deployment content parity, adapter skew) |
+| `pactkit spec-lint` | Validate spec structure (E001-E010, W001-W011; incl. dependency surface checks) |
+| `pactkit spec-graph` | Story dependency DAG: topological execution waves + file-conflict matrix (`--json` for orchestrators, `--write-graph` for Mermaid) |
 | `pactkit spec-status` | Update spec Status field (Draft/In Progress/Done) |
 | `pactkit guard` | Check project init markers |
 | `pactkit next-id` | Generate next Story/Bug ID |

{pactkit-2.18.0 → pactkit-2.20.0}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -73,3 +73,4 @@
 | 2026-03-31 | tree-sitter comment nodes are direct children of function body nodes (block/statement_block), enabling scoped dispatch hint queries without parent traversal. Per-language comment query needed: Go/TS use (comment), Java uses [(line_comment)(block_comment)]. | visualize.py:_extract_calls_from_body |
 | 2026-03-31 | config.py load_config() deep merge was single-level; adding check.pactguard (nested dict inside check) required upgrading to two-level merge to preserve sub-dict defaults like mode and blocking | src/pactkit/config.py:load_config |
 | 2026-03-31 | Adding pactkit-garden to VALID_SKILLS broke 5 hardcoded count assertions in test_config.py, test_pdca_slim.py, test_selective_deploy.py, test_prompt_structural_invariants.py, test_story_slim063.py — grep == 21 and == 10 in tests before releasing a new skill | tests/unit/test_pdca_slim.py:test_valid_skills_count |
+| 2026-03-31 | DETECTED_ENV in commands.py init playbook was unnecessary — _render_prompt(template, profile) already resolves per-format at deploy time. Added FORMAT_NAME to deployer.py var_map to enable pactkit init --format {FORMAT_NAME}. | deployer.py:_render_prompt |

pactkit-2.20.0/docs/architecture/governance/archive/lessons_archive_202604.md

@@ -0,0 +1,6 @@
+# Lessons Archive (2026-04)
+
+| Date | Lesson | Context |
+|------|--------|---------|
+| 2026-04-01 | Graduated safety language: retire MANDATORY keyword across prompts/commands.py, workflows.py, skills.py — use CRITICAL for safety gates (T1) and MUST for required steps (T2). Consistency prevents AI from treating all-caps keywords as equally urgent. | prompts/commands.py:MANDATORY→MUST/CRITICAL |
+| 2026-04-01 | Multi-stack visualize: _detect_stack() returning single str masks Go/TS/Java files in mixed projects; _build_class_graph hardcoded ast.parse() silently skips non-Python via except. Fix: _detect_stacks() returns list, extract_classes() ABC on all 4 analyzers. | visualize.py:_detect_stacks,_build_class_graph |

{pactkit-2.18.0 → pactkit-2.20.0}/docs/architecture/governance/lessons.md

@@ -2,9 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 2026-03-31 | DETECTED_ENV in commands.py init playbook was unnecessary — _render_prompt(template, profile) already resolves per-format at deploy time. Added FORMAT_NAME to deployer.py var_map to enable pactkit init --format {FORMAT_NAME}. | deployer.py:_render_prompt |
-| 2026-04-01 | Graduated safety language: retire MANDATORY keyword across prompts/commands.py, workflows.py, skills.py — use CRITICAL for safety gates (T1) and MUST for required steps (T2). Consistency prevents AI from treating all-caps keywords as equally urgent. | prompts/commands.py:MANDATORY→MUST/CRITICAL |
-| 2026-04-01 | Multi-stack visualize: _detect_stack() returning single str masks Go/TS/Java files in mixed projects; _build_class_graph hardcoded ast.parse() silently skips non-Python via except. Fix: _detect_stacks() returns list, extract_classes() ABC on all 4 analyzers. | visualize.py:_detect_stacks,_build_class_graph |
 | 2026-04-01 | Monorepo stack detection requires depth-1 subdir scan; cleaners.py and visualize.py _STACK_MARKERS must scan root/* not just root | cleaners.py:detect_stacks |
 | 2026-04-01 | When splitting a monolithic file into submodules with deploy-time inlining via load_script(), relative imports (from .foo) in exec() context raise KeyError not ImportError — guard with except (ImportError, KeyError) | skills/__init__.py:load_script |
 | 2026-04-01 | TSAnalyzer._load_tsconfig_paths must search depth-1 subdirs like _detect_stacks does because visualize.py always passes monorepo root as root param, not stack subdir — tsconfig in frontend/ is invisible if only root is searched | src/pactkit/skills/analyzers/ts_analyzer.py:_load_tsconfig_paths |
@@ -53,3 +50,6 @@
 | 2026-08-13 | 门禁词表扫描须先剥离 code fence/inline code span（done_verify.py:_strip_code_spans），否则词表元讨论自身误报 | done_verify.py:_strip_code_spans |
 | 2026-08-17 | check_deploy_parity 新增 hash 路径漏了 SEC-7 降级守卫（PermissionError/AttributeError 穿透 doctor）——Spec Security Scope 逐条自查 + 独立评审实重现能抓作者盲区 | doctor.py:check_deploy_parity |
 | 2026-08-17 | deploy(format=all) 的 adapter 分支无视 target 直写真实 home——跨环境副作用必须显式审查 target/HOME 语义；测试通过 subprocess 调 CLI 时 HOME 未隔离即真实机器 | deployer.py:deploy |
+| 2026-08-17 | Baseline budget tests (test_story063_prompt_slimming.py BASELINE_TOTAL_CHARS) leave <100 chars headroom — new playbook instructions must compress hard or bump baseline with justification comment | pactkit/prompts/commands.py |
+| 2026-08-17 | pactkit update only deploys to ~/.claude — in-repo pactkit-plugin/commands copies need manual sync from prompts/ source (verified by normalized diff) | pactkit/prompts/workflows.py:SPRINT_PROMPT |
+| 2026-08-22 | Continuation completion must validate real Spec/Board/test evidence and keep read-validate-write under a Story-level process lock; prompt-only evidence is insufficient. | src/pactkit/continuation.py:ContinuationStore |

{pactkit-2.18.0 → pactkit-2.20.0}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4120+ tests must pass before any commit to `main`.
+1. All 4271+ tests must pass before any commit to `main`.
 2. Specs (`docs/specs/`) are the source of truth — code conforms to specs, not the reverse.
 3. CLI entry point is `pactkit` via `src/pactkit/cli.py:main`.
 4. No runtime dependencies beyond `pyyaml`.

{pactkit-2.18.0 → pactkit-2.20.0}/docs/product/archive/archive_202608.md

@@ -65,3 +65,31 @@
 - [x] doctor.py: adapter 版本偏斜 warning
 - [x] 运维: 本机 adapter 升级 2.17.0
 - [x] AC3 双跑全量套件验证
+
+### [STORY-slim-143] Spec Dependency Surface & Story DAG (spec-graph)
+> Spec: docs/specs/STORY-slim-143.md
+
+- [x] schemas.py Dependency Surface constants+template
+- [x] spec_linter dangling-ref/missing-section rules
+- [x] spec_graph.py DAG+waves+conflict matrix
+- [x] cli.py spec-graph subcommand
+- [x] TDD tests AC1-AC7
+- [x] plan playbook Phase 3.2 step
+
+### [STORY-slim-144] Sprint Wave Mode: conflict-aware parallel orchestration
+> Spec: docs/specs/STORY-slim-144.md
+
+- [x] spec-graph --json serializer
+- [x] TDD json tests AC1-AC2
+- [x] SPRINT_PROMPT wave mode section R2-R5
+- [x] regenerate deployed sprint playbook
+- [x] prompt content tests AC3-AC6
+
+### [STORY-slim-146] 全 Skill 可恢复执行契约与 Act 断点续作
+> Spec: docs/specs/STORY-slim-146.md
+
+- [x] 建立 13 个 runtime skill 的恢复契约与完整性校验
+- [x] 实现原子 continuation checkpoint、验证与安全 resume CLI
+- [x] 为 project-act 加入逐步 checkpoint 与完成覆盖门禁
+- [x] 接入 doctor/garden/status 诊断并验证 legacy 兼容
+- [x] 验证四种 format 与外部 adapter 的真实 project-act 部署 parity

pactkit-2.20.0/docs/product/context.md

@@ -0,0 +1,29 @@
+# Project Context (Auto-generated)
+> Last updated: 2026-08-22T08:48:25+08:00 by pactkit context
+
+## Sprint Status
+Backlog: 5 | In Progress: 1 | Done: 0 stories
+
+## Current Stories
+- STORY-slim-145: Codex 部署命令语义完整性与 Adapter 兼容门禁
+
+## Recent Completions
+None
+
+## Active Branches
++ claude/naughty-euclid-e6a787
+  develop
+* main
+
+## Key Decisions
+- check_deploy_parity 新增 hash 路径漏了 SEC-7 降级守卫（PermissionError/AttributeError 穿透 doctor）——Spec Security Scope 逐条自查 + 独立评审实重现能抓作者盲区
+- deploy(format=all) 的 adapter 分支无视 target 直写真实 home——跨环境副作用必须显式审查 target/HOME 语义；测试通过 subprocess 调 CLI 时 HOME 未隔离即真实机器
+- Baseline budget tests (test_story063_prompt_slimming.py BASELINE_TOTAL_CHARS) leave <100 chars headroom — new playbook instructions must compress hard or bump baseline with justification comment
+- pactkit update only deploys to ~/.claude — in-repo pactkit-plugin/commands copies need manual sync from prompts/ source (verified by normalized diff)
+- Continuation completion must validate real Spec/Board/test evidence and keep read-validate-write under a Story-level process lock; prompt-only evidence is insufficient.
+
+## Next Recommended Action
+`/project-act` (stories in progress)
+
+## Agent Continuation
+No active work session.

{pactkit-2.18.0 → pactkit-2.20.0}/docs/product/sprint_board.md

@@ -38,5 +38,13 @@
 
 ## 🔄 In Progress
 
-## ✅ Done
+### [STORY-slim-145] Codex 部署命令语义完整性与 Adapter 兼容门禁
+> Spec: docs/specs/STORY-slim-145.md
+
+- [x] 建立 CLI policy 与结构化操作渲染契约
+- [x] 移除 pactkit-codex 有损命令前缀替换
+- [x] 增加 prompt 完整性与 Classic/Codex parity 门禁
+- [x] 阻止不兼容 Core/adapter 组合静默部署
+- [ ] 完成隔离迁移、双仓回归与同版本发布验证
 
+## ✅ Done

pactkit-2.20.0/docs/specs/STORY-slim-143.md

@@ -0,0 +1,178 @@
+# STORY-slim-143: Spec Dependency Surface & Story DAG (spec-graph)
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-143 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.19.0 |
+
+## Background
+
+/project-plan currently writes each Spec in isolation — there is no structured record of *what a story depends on*, *what public surface it provides*, or *which files it will touch*. Plan Phase 3.3 only suggests "record story dependencies if applicable" via Memory MCP (optional, unstructured). Consequences:
+
+1. When multiple stories are implemented in parallel (multiple agents / worktrees), file-level conflicts are only discovered at merge time.
+2. Story execution order （先后顺序） is implicit in the architect's head, not computable — nothing can topologically sort the board.
+3. `/project-sprint` today runs strictly one story at a time; safe parallel scheduling requires machine-readable dependency data.
+
+This story adds a **Dependency Surface** section to the Spec schema, lints it, and introduces `pactkit spec-graph` — a deterministic CLI that parses all Specs and emits a story dependency DAG, topological execution waves, and a file-overlap conflict matrix. Downstream stories (sprint wave orchestration, interface-first contract staging, merge-preflight) consume this data but are out of scope here.
+
+## Requirements
+
+### R1: Dependency Surface Schema (MUST)
+
+`schemas.py` MUST define a new optional Spec section `## Dependency Surface` (added to `SPEC_TEMPLATE` and `SPEC_OPTIONAL_SECTIONS`, registered in `SCHEMA_REGISTRY`) with exactly four pipe-table fields:
+
+| Field | Value |
+|-------|-------|
+| Depends on | comma-separated story IDs this story consumes, each with a `needs:` note (e.g. `STORY-143 (needs: spec-graph CLI)`), or `None` |
+| Provides | public surface this story adds (CLI commands, exported functions, schema constants), or `None` |
+| Touches | glob-level file paths this story expects to modify (e.g. `src/pactkit/cli.py`, `src/pactkit/skills/*.py`) |
+| Conflict risk | `LOW` / `MEDIUM` / `HIGH` + free-text reason |
+
+Schema constants (section name, field names, risk levels) MUST live in `schemas.py` as named constants — no magic strings in parser/linter/CLI.
+
+### R2: Linter Rules for Dependency Surface (MUST)
+
+`spec_linter.py` MUST add checks, invoked from `validate_spec()` following the existing `_check_*` call-sequence pattern:
+
+- **New ERROR rule**: a `Depends on` entry references a story ID that has no corresponding file in the specs dir (dangling dependency) — typo protection, since ordering decisions rely on these edges.
+- **New WARNING rule**: `## Dependency Surface` section is missing or its table lacks any of the four required fields.
+
+Both rules MUST reuse the existing `_find_section` / `_section_text` parsing helpers — no fourth copy of section-parsing regexes.
+
+### R3: `pactkit spec-graph` CLI (MUST)
+
+New module `src/pactkit/spec_graph.py` + `spec-graph` subcommand in `cli.py` (argparse subparser + dispatch chain, same pattern as `spec-lint`). Given `--specs-dir docs/specs` (default), it MUST:
+
+1. Parse every Spec's Dependency Surface table (reusing spec_linter parsing helpers).
+2. Build the story DAG from `Depends on` edges (excluding edges to stories already `Status | Done`, which are satisfied).
+3. Topologically sort into **execution waves**: wave N contains all stories whose remaining dependencies are all in waves < N. Stories in the same wave are parallelizable.
+4. Compute a **conflict matrix**: pairs of stories whose `Touches` globs overlap (same literal path or glob intersection) are flagged; pairs in the same wave with overlap MUST be highlighted as unsafe-parallel.
+5. Detect dependency cycles and MUST report them as an error (non-zero exit) with the cycle path — a cycle means the Specs themselves are contradictory.
+6. Emit a Mermaid graph to `docs/architecture/graphs/story_graph.mmd` (`--write-graph` flag) and print the wave list + conflict matrix to stdout.
+
+### R4: Deterministic Scheduling Semantics (MUST)
+
+Wave assignment, overlap detection, and cycle detection MUST be computed entirely in code (LLM ≠ Calculator). The CLI output MUST be stable for identical Spec inputs — same input, same waves, same matrix ordering (sorted output, no dict-iteration nondeterminism).
+
+### R5: Plan Playbook Integration (SHOULD)
+
+`pactkit-plugin/commands/project-plan.md` Phase 3.2 SHOULD gain a step instructing the architect to fill the Dependency Surface from Phase 1 trace findings (touches = traced files; depends-on = stories whose Provides it consumes). Sprint parallel orchestration itself is explicitly NOT changed by this story.
+
+## Technical Design
+
+### Lateral Scan Results
+
+- Operation: parse Spec metadata/section structure
+- Existing implementations: 3 (`spec_linter.py` `_find_section`/`_section_text`, `done_verify.py` requirement parsing, `audit.py` status check)
+- Assessment: **Reuse existing** — `spec_graph.py` and the new lint rules import spec_linter's helpers; no new regex parser is written.
+
+### Capability Assessment
+
+| Need | Source | Decision |
+|------|--------|----------|
+| Spec section/metadata parsing | `pactkit.skills.spec_linter` (project) | Reuse |
+| Topological sort / cycle detection | stdlib (`graphlib.TopologicalSorter`, Python ≥ 3.9) | Enable — no new dependency |
+| Glob overlap check | stdlib `fnmatch` + path normalization | Enable |
+| CLI registration | `cli.py` subparser chain (project) | Reuse |
+
+### New Implementation Required
+
+- `pactkit/spec_graph.py`: Dependency Surface parsing → DAG → waves → conflict matrix → Mermaid emit. Single responsibility, pure functions over parsed data (testable without filesystem fixtures beyond temp specs).
+
+### Concurrency Decision (Engineering Concern: concurrency)
+
+No runtime concurrency in this story. The *scheduling* semantics are deterministic data: waves are computed by `graphlib`, and any future parallel executor (sprint story) consumes the wave list rather than re-deriving it. This keeps the "can these two stories run in parallel?" judgment in code, not in an LLM prompt.
+
+## Acceptance Criteria
+
+### AC1: Scaffolded Spec carries Dependency Surface (R1)
+
+- **Given** a project with pactkit initialized and the new schema deployed
+- **When** `scaffold.py create_spec "STORY-x-999" "demo"` is run
+- **Then** the generated Spec contains `## Dependency Surface` with all four fields (Depends on / Provides / Touches / Conflict risk) and `pactkit spec-lint` on it reports 0 errors and 0 warnings for the new rules.
+
+### AC2: Dangling dependency is rejected (R2)
+
+- **Given** a Spec whose `Depends on` includes `STORY-slim-999` and no such file exists in the specs dir
+- **When** `pactkit spec-lint` runs on that Spec
+- **Then** it reports the new ERROR rule naming the dangling ID, and exits non-zero.
+
+### AC3: Missing section is a warning (R2)
+
+- **Given** an otherwise-valid Spec with no `## Dependency Surface` section (e.g. all pre-2.19 Specs)
+- **When** `pactkit spec-lint` runs on it
+- **Then** the new WARNING fires but existing rules are unaffected.
+
+### AC4: Waves and conflict matrix from real Specs (R3, R4)
+
+- **Given** three Specs: A (Depends on: None, Touches: `a.py`), B (Depends on: A, Touches: `b.py`), C (Depends on: None, Touches: `a.py`)
+- **When** `pactkit spec-graph` runs
+- **Then** output shows wave 1 = {A, C}, wave 2 = {B}, and flags A↔C as a same-wave file conflict on `a.py` (unsafe-parallel).
+
+### AC5: Cycle detection (R3, R4)
+
+- **Given** two Specs that depend on each other
+- **When** `pactkit spec-graph` runs
+- **Then** it exits non-zero and prints the cycle path (e.g. `A -> B -> A`).
+
+### AC6: Deterministic output (R4)
+
+- **Given** any fixed set of Specs
+- **When** `pactkit spec-graph` runs twice
+- **Then** wave lists and conflict matrix are byte-identical (sorted, stable ordering).
+
+### AC7: Plan playbook documents the step (R5)
+
+- **Given** the updated `project-plan.md` playbook
+- **When** reading Phase 3.2
+- **Then** it contains a step instructing the architect to fill the Dependency Surface (touches from Phase 1 trace, depends-on from consumed Provides), with a pointer to the field semantics in R1.
+
+## Target Call Chain
+
+- CLI: `pactkit spec-graph` → `cli.py` (subparser + dispatch) → `pactkit.spec_graph.main(argv)`
+- Core: `spec_graph.main` → `parse_dependency_surfaces(specs_dir)` (reuses `spec_linter._find_section` / `_section_text`) → `build_dag()` → `graphlib.TopologicalSorter` (waves) → `conflict_matrix()` (fnmatch overlap) → stdout / `story_graph.mmd`
+- Lint: `pactkit spec-lint` → `spec_linter.validate_spec()` → new `_check_dependency_surface()` (dangling-ref ERROR, missing-section WARNING)
+- Scaffold: `scaffold.py create_spec` → `schemas.SPEC_TEMPLATE` (now includes Dependency Surface)
+
+## Dependency Surface
+
+| Field | Value |
+|-------|-------|
+| Depends on | None |
+| Provides | `pactkit spec-graph` CLI; `pactkit.spec_graph` module; `DEP_SURFACE_*` schema constants; 2 new spec-lint rules |
+| Touches | `src/pactkit/schemas.py`, `src/pactkit/skills/spec_linter.py`, `src/pactkit/spec_graph.py` (new), `src/pactkit/cli.py`, `pactkit-plugin/commands/project-plan.md`, `tests/unit/test_story_slim143_spec_graph.py` (new), `tests/unit/test_story042_spec_linter.py` |
+| Conflict risk | LOW — schemas.py and cli.py are frequently touched, but changes are append-only (new section constant, new subparser), minimal overlap with typical feature stories |
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/schemas.py` | Add `DEP_SURFACE_*` constants + section in SPEC_TEMPLATE + SCHEMA_REGISTRY | None | Low |
+| 2 | `src/pactkit/skills/spec_linter.py` | Add `_check_dependency_surface` (dangling-ref ERROR, missing-section WARNING) | Step 1 | Low |
+| 3 | `src/pactkit/spec_graph.py` | New module: parse → DAG → waves (graphlib) → conflict matrix → Mermaid | Step 1 | Medium (glob-overlap edge cases) |
+| 4 | `src/pactkit/cli.py` | Register `spec-graph` subparser + dispatch | Step 3 | Low |
+| 5 | `tests/unit/` | TDD tests for AC1–AC6 | Steps 1–4 | Low |
+| 6 | `pactkit-plugin/commands/project-plan.md` | Phase 3.2 step: fill Dependency Surface from trace findings | Step 1 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | new source module spec_graph.py — code quality standards apply |
+| SEC-2 | Yes | parses user-authored Spec markdown + glob paths — must tolerate malformed tables/globs without crashing |
+| SEC-3 | N/A | no database/ORM (auto-detect false positive: no SQL involved) |
+| SEC-4 | N/A | no frontend files |
+| SEC-5 | N/A | no auth patterns |
+| SEC-6 | N/A | no API/route files |
+| SEC-7 | Yes | cycle detection and dangling refs must fail with clear errors, non-zero exit, no stack traces |
+| SEC-8 | N/A | no new dependencies — stdlib only (graphlib, fnmatch) |
+
+## Out of Scope
+
+- `/project-sprint` wave-based parallel orchestration (depends on this story's Provides; separate story)
+- Interface-first contract staging for depended-upon stories
+- Merge-preflight conflict check (`--check-conflicts`) at agent completion time
+- Auto-fixing file conflicts (spec-graph only *reports* them)
+- Board format changes (board.py untouched)

pactkit-2.20.0/docs/specs/STORY-slim-144.md

@@ -0,0 +1,169 @@
+# STORY-slim-144: Sprint Wave Mode: conflict-aware parallel orchestration
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-144 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.19.0 |
+
+## Background
+
+`/project-sprint` (v1.5.0) orchestrates exactly ONE story per invocation: Plan → Act → Check → Close, strictly sequential in worktrees. STORY-slim-143 delivered the missing data layer — every Spec now declares a Dependency Surface, and `pactkit spec-graph` computes execution waves (topological layers) and a file-overlap conflict matrix. What remains is the **consumer**: a wave mode in sprint that runs multiple backlog stories concurrently when the data proves it safe.
+
+Design constraints from the existing architecture:
+- Backward compatible: `$ARGUMENTS` present → current single-story mode, unchanged.
+- LLM ≠ Calculator: wave membership, parallel/serialize decisions, and conflict checks come from `spec-graph` output, never from orchestrator judgment.
+- Safe by default: stories without a declared `Touches` (legacy/placeholder) MUST NOT be parallelized — unknown conflict surface means serialize.
+
+## Requirements
+
+### R1: `spec-graph --json` Machine-Readable Output (MUST)
+
+`pactkit spec-graph` MUST accept a `--json` flag emitting `{waves: [[ids]], conflicts: [{story_a, story_b, shared, same_wave}]}` with sorted, deterministic ordering. The sprint orchestrator consumes this instead of parsing human output. Cycle errors MUST still exit non-zero (JSON or not).
+
+### R2: Wave Mode Entry (MUST)
+
+`commands/project-sprint.md` (source: `src/pactkit/prompts/workflows.py` SPRINT_PROMPT) MUST gain a wave mode with this entry rule:
+
+- `$ARGUMENTS` non-empty → existing single-story mode, byte-for-byte behavior preserved.
+- `$ARGUMENTS` empty → wave mode:
+  1. `board.py list_stories` → BACKLOG story IDs.
+  2. `pactkit spec-graph --json` → waves + conflicts, filtered to backlog IDs with existing Specs.
+  3. If no parallelizable stories exist (all serialized), log and fall back to single-story suggestion.
+
+### R3: Conflict-Aware Scheduling Policy (MUST)
+
+Within each wave, the orchestrator MUST partition stories into:
+
+- **Parallel batch**: stories whose Touches are all declared (no placeholder/missing) AND pairwise non-conflicting per the matrix. Batch size MUST NOT exceed `sprint.max_parallel` from pactkit.yaml (default 3, named constant — no magic value); excess stories spill to a following sub-batch.
+- **Serialized tail**: stories flagged same-wave-conflict, or with undeclared Touches, run one-at-a-time after the parallel batch.
+
+Each story (parallel or serialized) runs the EXISTING per-story PDCA chain (Plan→Act→Check→Close) in its own worktree, reusing current Stage A/B/C dispatch logic — no duplicated stage definitions (DRY).
+
+### R4: Wave Gate & Failure Policy (MUST)
+
+- Wave N+1 MUST NOT start until every wave-N story is merged green (worktree merged, tests passing per each story's Close stage).
+- Any story failure → STOP the wave immediately (fail-fast, consistent with current single-story semantics), report which stories completed/merged vs pending, and leave remaining stories on the board. NEVER auto-retry a failed story in the same run.
+- Merge conflict on worktree merge → STOP + suggest `git merge --abort` (existing error contract preserved).
+
+### R5: Observability (SHOULD)
+
+The orchestrator SHOULD print a wave plan before dispatching (wave N: parallel=[...], serialized=[...], skipped=[...] with reasons) so the user can abort before any subagent spawns.
+
+## Technical Design
+
+### Lateral Scan Results
+
+- Operation: subagent orchestration with dependency ordering
+- Existing implementations: 1 (`SPRINT_PROMPT` single-story chain) — no existing parallel scheduler
+- Assessment: **New is justified** — wave mode extends the single existing orchestrator; per-story chain is reused verbatim, not copied.
+
+### Capability Assessment
+
+| Need | Source | Decision |
+|------|--------|----------|
+| Waves + conflict matrix | `pactkit spec-graph` (STORY-slim-143) | Reuse — add `--json` consumer interface |
+| Backlog enumeration | `board.py list_stories` | Reuse |
+| Worktree isolation | existing sprint Stage A/B/C pattern | Reuse |
+| Parallel cap config | pactkit.yaml `sprint.max_parallel` (new optional key, default 3) | New config key |
+
+### New Implementation Required
+
+- `spec_graph.py`: `--json` flag + `to_json()` serializer (~30 lines).
+- `SPRINT_PROMPT`: Wave Mode section (Phase 0.5: Mode Detection; Phase 1W: Wave loop). Deployed copy `pactkit-plugin/commands/project-sprint.md` regenerated via `pactkit update`.
+
+### Concurrency Decision (Engineering Concern: concurrency)
+
+Parallelism is at the **subagent/team level** (Claude Code Task agents with worktree isolation), not threads/processes in pactkit code — pactkit itself stays single-threaded. The cap (`sprint.max_parallel`, default 3) bounds concurrent worktrees. Merging is always sequential (one worktree at a time), which is the serialization point that keeps git state sane. Conflict avoidance is precomputed by `spec-graph`, not detected at merge time.
+
+### Error-Recovery Decision (Engineering Concern: error-recovery)
+
+Fail-fast per wave; no auto-retry; partial progress is always safe because every completed story merged through its own green PDCA chain. Resume = re-run `/project-sprint` — remaining backlog stories re-enter wave computation (idempotent, since completed stories are Done and excluded by spec-graph).
+
+### Backwards-Compatibility Decision (Engineering Concern: backwards-compatibility)
+
+Single-story mode is the default when args are present — zero behavior change for existing users. Wave mode is opt-in via empty args. `sprint.max_parallel` absent from pactkit.yaml → default 3, no config migration needed.
+
+## Acceptance Criteria
+
+### AC1: JSON output shape (R1)
+
+- **Given** specs forming 2 waves with one same-wave conflict
+- **When** `pactkit spec-graph --json` runs
+- **Then** stdout parses as JSON with `waves` (list of sorted ID lists) and `conflicts` (list of objects with story_a/story_b/shared/same_wave), and two runs are byte-identical.
+
+### AC2: Cycle still errors under --json (R1)
+
+- **Given** two mutually dependent specs
+- **When** `pactkit spec-graph --json` runs
+- **Then** exit code is non-zero and stderr names the cycle.
+
+### AC3: Mode detection (R2)
+
+- **Given** the updated SPRINT_PROMPT / project-sprint.md
+- **When** reading the entry phase
+- **Then** it specifies: non-empty `$ARGUMENTS` → single-story mode (unchanged path); empty → wave mode with board scan + `spec-graph --json` + fallback when nothing is parallelizable.
+
+### AC4: Scheduling policy documented and deterministic (R3)
+
+- **Given** the updated playbook
+- **When** reading the wave-mode section
+- **Then** it encodes all of: parallel batch requires declared Touches AND pairwise non-conflict; `sprint.max_parallel` cap with default 3; serialized tail for conflicted/undeclared stories; per-story worktree PDCA chain reuse (reference, not copy).
+
+### AC5: Wave gate & failure policy (R4, R5)
+
+- **Given** the updated playbook
+- **When** reading the wave-mode section
+- **Then** it states: wave N+1 blocked until wave N fully merged; fail-fast STOP with completed/pending report; no auto-retry; merge-conflict → STOP + `git merge --abort` suggestion; wave plan printed before dispatch.
+
+### AC6: Prompt hygiene (R2-R5)
+
+- **Given** the implemented changes
+- **When** running `pytest tests/unit/test_prompt_cli_refs.py tests/unit/test_story063_prompt_slimming.py` and full suite
+- **Then** all pass (prompt baselines bumped per project convention if needed, with justification comments).
+
+## Target Call Chain
+
+- Wave mode: `/project-sprint` (empty args) → SPRINT_PROMPT Mode Detection → `board.py list_stories` + `pactkit spec-graph --json` → wave plan → per-story existing Stage A/B/C dispatch (worktree) → sequential merges → wave gate → next wave
+- JSON: `cli.py spec-graph` → `spec_graph.main(["--json"])` → `to_json(graph)` (waves via `compute_waves`, conflicts via `compute_conflicts`)
+
+## Dependency Surface
+
+| Field | Value |
+|-------|-------|
+| Depends on | STORY-slim-143 (needs: `pactkit spec-graph` waves + conflict matrix, `spec_graph.compute_waves`/`compute_conflicts`) |
+| Provides | `pactkit spec-graph --json`; sprint wave mode; `sprint.max_parallel` config key |
+| Touches | `src/pactkit/spec_graph.py`, `src/pactkit/prompts/workflows.py`, `pactkit-plugin/commands/project-sprint.md`, `tests/unit/test_story_slim144_wave_mode.py` (new) |
+| Conflict risk | LOW — workflows.py SPRINT_PROMPT and spec_graph.py append-only changes; no overlap with typical feature stories |
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/spec_graph.py` | Add `--json` + `to_json()` | None | Low |
+| 2 | `tests/unit/test_story_slim144_wave_mode.py` | TDD tests for AC1/AC2 | Step 1 | Low |
+| 3 | `src/pactkit/prompts/workflows.py` | SPRINT_PROMPT wave mode section (R2-R5) | Step 1 | Medium (prompt size budget) |
+| 4 | `pactkit-plugin/commands/project-sprint.md` | Regenerate via `pactkit update` | Step 3 | Low |
+| 5 | `tests/unit/` | Prompt content assertions for AC3-AC5 | Step 3 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | spec_graph.py source change — code quality standards apply |
+| SEC-2 | Yes | --json serializer consumes spec-derived data — output must be valid JSON for any malformed surface input |
+| SEC-3 | N/A | no database |
+| SEC-4 | N/A | no frontend |
+| SEC-5 | N/A | auto-detect false positive: no auth/session code touched (prompt text only) |
+| SEC-6 | N/A | no API endpoints |
+| SEC-7 | Yes | cycle error under --json must stay a clean single-line stderr + non-zero exit |
+| SEC-8 | N/A | no new dependencies (stdlib json) |
+
+## Out of Scope
+
+- Interface-first contract staging (separate downstream story)
+- Merge-preflight conflict check at agent completion time
+- Auto-retry / self-healing of failed stories
+- Parallelism inside pactkit code itself (threads/async) — orchestration-level only
+- Changing single-story mode behavior in any way