pactkit 2.18.0__tar.gz → 2.19.0__tar.gz

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

@@ -4,6 +4,15 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [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.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.18.0
+Version: 2.19.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
@@ -289,7 +289,7 @@ 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 doctor` | Diagnose project health (HLD drift, board, config, deployment content parity, adapter skew) |
 | `pactkit spec-lint` | Validate spec structure (14 rules: E001-E008, W001-W006) |
 | `pactkit spec-status` | Update spec Status field (Draft/In Progress/Done) |
 | `pactkit guard` | Check project init markers |

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

@@ -244,7 +244,7 @@ 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 doctor` | Diagnose project health (HLD drift, board, config, deployment content parity, adapter skew) |
 | `pactkit spec-lint` | Validate spec structure (14 rules: E001-E008, W001-W006) |
 | `pactkit spec-status` | Update spec Status field (Draft/In Progress/Done) |
 | `pactkit guard` | Check project init markers |

{pactkit-2.18.0 → pactkit-2.19.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.19.0/docs/architecture/governance/archive/lessons_archive_202604.md

@@ -0,0 +1,5 @@
+# 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 |

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

@@ -2,8 +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 |
@@ -53,3 +51,5 @@
 | 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 |

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

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4120+ tests must pass before any commit to `main`.
+1. All 4183+ 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.19.0}/docs/product/archive/archive_202608.md

@@ -65,3 +65,22 @@
 - [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

{pactkit-2.18.0 → pactkit-2.19.0}/docs/product/context.md

@@ -1,5 +1,5 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-08-17T14:59:59+08:00 by pactkit context
+> Last updated: 2026-08-17T17:57:13+08:00 by pactkit context
 
 ## Sprint Status
 Backlog: 5 | In Progress: 0 | Done: 0 stories
@@ -16,11 +16,11 @@ None
 * main
 
 ## Key Decisions
-- guardrail 测试（行数/字符数上限）触线时，优先把组装逻辑上移到 CLI 组合层而不是抬阈值——deployer 保持精简，init/update 的副作用归 cli 编排
-- 配置副本同步 canonical 不能用键数启发式（默认值墙副本键数多但意图少，会覆盖手工配置），必须用显式优先级——见 config.py:sync_config_copies 的 CANONICAL_PREFERENCE
 - 门禁词表扫描须先剥离 code fence/inline code span（done_verify.py:_strip_code_spans），否则词表元讨论自身误报
 - 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)
 
 ## Next Recommended Action
 `/project-plan`

pactkit-2.19.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.19.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

pactkit-2.19.0/docs/test_cases/STORY-slim-143_case.md

@@ -0,0 +1,43 @@
+# Test Cases: STORY-slim-143 — Spec Dependency Surface & Story DAG (spec-graph)
+
+## TC-1: Scaffolded spec carries Dependency Surface (AC1)
+
+- **Given** pactkit 项目已初始化且新 schema 已部署
+- **When** 运行 `scaffold.py create_spec "STORY-x-999" "demo"`
+- **Then** 生成的 Spec 含 `## Dependency Surface` 及全部四个字段（Depends on / Provides / Touches / Conflict risk），且 `pactkit spec-lint` 无 E010/W011
+
+## TC-2: Dangling dependency rejected (AC2)
+
+- **Given** 某 Spec 的 Depends on 引用不存在的 `STORY-slim-999`
+- **When** 运行 `pactkit spec-lint`
+- **Then** 报告 E010（含该 ID）并以非零码退出
+
+## TC-3: Missing section is a warning (AC3)
+
+- **Given** 一个无 `## Dependency Surface` 的旧 Spec（其余部分合法）
+- **When** 运行 `pactkit spec-lint`
+- **Then** 报告 W011 但整体 PASS，既有规则不受影响
+
+## TC-4: Waves and conflict matrix (AC4)
+
+- **Given** 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`
+- **Then** wave 1 = {A, C}、wave 2 = {B}，且 A↔C 被标记为同 wave 文件冲突（unsafe-parallel）
+
+## TC-5: Cycle detection (AC5)
+
+- **Given** 两个互相依赖的 Spec
+- **When** 运行 `pactkit spec-graph`
+- **Then** 以非零码退出并输出 cycle 路径
+
+## TC-6: Deterministic output (AC6)
+
+- **Given** 任意固定 Spec 集合
+- **When** `pactkit spec-graph` 连续运行两次
+- **Then** wave 列表与冲突矩阵字节一致
+
+## TC-7: Plan playbook documents the step (AC7)
+
+- **Given** 更新后的 project-plan 命令内容
+- **When** 阅读 Phase 3.2a
+- **Then** 存在 Dependency Surface 填写指引，且包含 E010 与 `pactkit spec-graph` 引用

pactkit-2.19.0/docs/test_cases/STORY-slim-144_case.md

@@ -0,0 +1,37 @@
+# Test Cases: STORY-slim-144 — Sprint Wave Mode: conflict-aware parallel orchestration
+
+## TC-1: JSON output shape (AC1)
+
+- **Given** 两个 wave + 一个同 wave 冲突的 Spec 集合
+- **When** 运行 `pactkit spec-graph --json`
+- **Then** 输出合法 JSON 含 `waves`（排序的 ID 列表的列表）与 `conflicts`（含 story_a/story_b/shared/same_wave），两次运行字节一致
+
+## TC-2: Cycle under --json (AC2)
+
+- **Given** 两个互相依赖的 Spec
+- **When** 运行 `pactkit spec-graph --json`
+- **Then** 以非零码退出且 stderr 含 cycle 路径
+
+## TC-3: Mode detection (AC3)
+
+- **Given** 更新后的 SPRINT_PROMPT / project-sprint.md
+- **When** 阅读入口 Phase
+- **Then** 非空 `$ARGUMENTS` → 单 story 模式（行为不变）；空 → wave 模式（board 扫描 + `spec-graph --json` + 无可并行 story 时回退建议）
+
+## TC-4: Scheduling policy (AC4)
+
+- **Given** 更新后的 playbook
+- **When** 阅读 Wave Mode section
+- **Then** 编码全部策略：声明 Touches 且两两无冲突才并行 / `sprint.max_parallel` 默认 3 / 冲突或未声明者串行 / 按引用复用 Stage A-C（不复制定义）
+
+## TC-5: Wave gate & failure policy (AC5)
+
+- **Given** 更新后的 playbook
+- **When** 阅读 Wave Mode section
+- **Then** 编码：wave N+1 阻塞至 N 全部 merge 绿 / fail-fast 且 NEVER auto-retry / merge 冲突提示 `git merge --abort` / dispatch 前打印 wave plan 并等用户确认
+
+## TC-6: Prompt hygiene (AC6)
+
+- **Given** 实现完成
+- **When** 运行全量测试
+- **Then** 全部通过（prompt 基线 bump 均带 justification 注释）

{pactkit-2.18.0 → pactkit-2.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pactkit"
-version = "2.18.0"
+version = "2.19.0"
 description = "Spec-driven agentic DevOps toolkit for AI coding assistants"
 readme = "README.md"
 license = "MIT"

{pactkit-2.18.0 → pactkit-2.19.0}/src/pactkit/__init__.py

@@ -1,3 +1,3 @@
 """PactKit - Spec-driven agentic DevOps toolkit."""
 
-__version__ = "2.18.0"
+__version__ = "2.19.0"

{pactkit-2.18.0 → pactkit-2.19.0}/src/pactkit/cli.py

@@ -249,6 +249,23 @@ def main():
     sec_scope_parser = subparsers.add_parser("sec-scope", help="Auto-detect security scope")
     sec_scope_parser.add_argument("files", nargs="*", help="Changed file paths")
 
+    # pactkit spec-graph (STORY-slim-143)
+    spec_graph_parser = subparsers.add_parser(
+        "spec-graph", help="Story dependency graph: execution waves + conflict matrix"
+    )
+    spec_graph_parser.add_argument(
+        "--specs-dir", default="docs/specs", help="Directory containing spec files"
+    )
+    spec_graph_parser.add_argument(
+        "--write-graph", action="store_true", help="Write Mermaid graph to --graph-path"
+    )
+    spec_graph_parser.add_argument(
+        "--graph-path", default="docs/architecture/graphs/story_graph.mmd", help="Mermaid output path"
+    )
+    spec_graph_parser.add_argument(
+        "--json", action="store_true", help="Emit machine-readable JSON (waves + conflicts)"
+    )
+
     # pactkit lint-context (STORY-slim-014 R2)
     lint_ctx_parser = subparsers.add_parser("lint-context", help="Validate context.md structure")
     lint_ctx_parser.add_argument("path", nargs="?", default="docs/product/context.md", help="Path to context.md")
@@ -574,6 +591,16 @@ def main():
         ctx_path.write_text(content, encoding="utf-8")
         print(f"Generated {ctx_path}")
 
+    elif args.command == "spec-graph":
+        from pactkit.spec_graph import main as spec_graph_main
+
+        argv = ["--specs-dir", args.specs_dir, "--graph-path", args.graph_path]
+        if args.write_graph:
+            argv.append("--write-graph")
+        if args.json:
+            argv.append("--json")
+        raise SystemExit(spec_graph_main(argv))
+
     elif args.command == "sec-scope":
         from pathlib import Path
 

{pactkit-2.18.0 → pactkit-2.19.0}/src/pactkit/prompts/commands.py

@@ -124,6 +124,7 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
     - Edit `(Description of the problem or feature)` → actual Background content from your Trace findings
     - Edit `## Target Call Chain` placeholder → actual call chain from Phase 1
     - Edit `### R1: (Requirement Name) (MUST)` → actual requirements using RFC 2119 keywords (MUST/SHOULD/MAY). Add more R{N} sections as needed.
+    - Edit `## Dependency Surface` fields (dangling ID = E010; feeds `pactkit spec-graph`)
 4.  **Journey Segment (Conditional)**: If `docs/e2e/journey.md` exists in the project:
     - Read `docs/e2e/journey.md` to identify defined journeys and their steps.
     - Assess whether this Story's scope touches any journey step (e.g., modifies a UI flow, changes an API endpoint used in a journey).