pactkit 2.13.0__tar.gz → 2.14.0__tar.gz

pactkit-2.14.0/.codegraph/.gitignore

@@ -0,0 +1,16 @@
+# CodeGraph data files
+# These are local to each machine and should not be committed
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Cache
+cache/
+
+# Logs
+*.log
+
+# Hook markers
+.dirty

{pactkit-2.13.0 → pactkit-2.14.0}/.github/workflows/pactkit.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[visualize]"
+          pip install -e .
           pip install pytest ruff
           pactkit init
 

{pactkit-2.13.0 → pactkit-2.14.0}/.gitignore

@@ -62,3 +62,6 @@ coder/
 docker/
 docs/slides/
 
+
+# Call graph SQLite output (STORY-slim-121)
+docs/architecture/graphs/*.db

{pactkit-2.13.0 → pactkit-2.14.0}/.opencode/pactkit.yaml

@@ -143,6 +143,7 @@ agent_models:
 
 # Visualize — configure directory scan exclusions
 visualize:
+  graph_provider: codegraph
   scan_excludes:
     - venv
     - _venv

{pactkit-2.13.0 → pactkit-2.14.0}/CHANGELOG.md

@@ -4,9 +4,29 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
-## [2.13.0] - 2026-05-07
+## [2.14.0] - 2026-05-26
 
 ### Added
+- **Codegraph integration** (STORY-slim-124) — `pactkit query` now reads from `.codegraph/codegraph.db` (generated by `@colbymchenry/codegraph`) when `visualize.graph_provider: codegraph` is configured. Provides 2.6x more edges than pactkit's own suffix-match resolution (6580 vs 2483 in real projects), with qualified names, line numbers, and type-aware resolution.
+- **Auto-init codegraph** — When `graph_provider: codegraph` is set and `.codegraph/codegraph.db` is missing, `pactkit query` auto-runs `codegraph init -i` if the CLI is on PATH. Plan/Act phases also auto-setup codegraph when detected.
+- **Graph Query Protocol dual-mode** — PDCA commands now support two modes: Codegraph Mode (`pactkit query` + codegraph CLI + MCP tools) and Grep Mode (default fallback on `.mmd` files).
+
+### Removed
+- **`_write_sqlite_db()`** — Pactkit no longer generates its own `call_graph.db`. The upstream codegraph tool produces a superior graph with tree-sitter + import-aware resolution.
+- **`visualize.sqlite_output` config** — Replaced by `visualize.graph_provider: codegraph`. Existing configs should migrate.
+
+### Changed
+- **`pactkit query`** — Now reads `.codegraph/codegraph.db` (codegraph schema with hash IDs, JOIN edges+nodes) instead of pactkit's own `call_graph.db`.
+- **PDCA prompts updated** — All references to `call_graph.db` / "SQLite Mode" removed from Plan, Act, Check, Done, Hotfix, and Trace skills. Impact analysis uses `pactkit query --callers` (codegraph) or grep `.mmd` (default).
+
+## [2.13.0] - 2026-05-25
+
+### Added
+- **Call graph SQLite output** (STORY-slim-121) — `pactkit visualize --mode call` now optionally writes `call_graph.db` alongside the existing `.mmd` file. Enable via `visualize.sqlite_output: true` in `pactkit.yaml`. Atomic write (tmp+rename), zero new dependencies (`sqlite3` stdlib).
+- **`pactkit query` CLI** (STORY-slim-121) — New subcommand for structured call graph queries: `--callers <func>` (fan-in), `--callees <func>` (fan-out), `--chain <func> [--down]` (transitive upstream/downstream via recursive CTE). Reads from `call_graph.db`; exits with helpful message when db is missing.
+- **Graph Query Protocol upgrade** (STORY-slim-121) — `SKILL_VISUALIZE_MD` now routes to `pactkit query` as primary path when `call_graph.db` exists, with grep as fallback for mmd-only projects.
+- **Enhanced Python call graph coverage** (STORY-slim-119) — `_extract_calls` now captures non-self attribute calls (`engine.run()`), function references in list/tuple/keyword/assign contexts, and nested functions via `ast.walk` + parent map. Edge count on medium-large projects: 1,360 → 3,764 (+177%).
+- **Test and script scanning in call graph** (STORY-slim-120) — `visualize --mode call` now scans `tests/`, `scripts/`, and `alembic/` directories in addition to `src/`. Locality-based `_resolve_callee` prefers same-file/same-package candidates when multiple matches exist.
 - **`pactkit interface-summary` CLI** (STORY-slim-113) — AST-based interface extraction that physically outputs only signatures, types, and docstrings. Enforces "Code Enforces, Prompt Instructs" for Act Phase 1 layered loading — AI receives truncated content by design.
 - **Journey Sync in Act Phase 4** (STORY-slim-114) — Conditional step that updates `docs/e2e/journey.md` when a Story modifies journey-relevant steps. Closes the create→consume→update lifecycle gap.
 - **Journey Segment in Plan Phase 3.2a** (STORY-slim-114) — Conditional Spec annotation that links Stories to journey steps, enabling Act Phase 4 auto-detection.

{pactkit-2.13.0 → pactkit-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.13.0
+Version: 2.14.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
@@ -55,7 +55,7 @@ Description-Content-Type: text/markdown
 
 > **PactKit** (Pact 契约 + Kit) is a governance framework that enforces the **P.A.C.T.** contract between humans and AI agents. Deterministic operations run as code, not prompts. Decisions are grounded in data, not memory. AI does what it's best at — creativity and language — while code handles everything that must be repeatable and correct.
 >
-> 25 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` deploys to all 3 supported IDEs.
+> 26 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` deploys to all 3 supported IDEs.
 
 ### Supported AI Tools
 
@@ -247,7 +247,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 | Skill | Type | Purpose |
 |-------|------|---------|
-| **pactkit-visualize** | Scripted | Code dependency graph (Mermaid): file-level, class-level, call-level |
+| **pactkit-visualize** | Scripted | Code dependency graph (Mermaid .mmd): file-level, class-level, call-level |
 | **pactkit-board** | Scripted | Sprint board operations: add story, update task, archive |
 | **pactkit-scaffold** | Scripted | File scaffolding: create spec, test files, git branches, skills |
 | **pactkit-trace** | Prompt-only | Deep code tracing and execution flow analysis |
@@ -260,7 +260,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 ## CLI Subcommands
 
-PactKit ships 25 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+PactKit ships 26 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
 
 | Command | Purpose |
 |---------|---------|
@@ -281,6 +281,7 @@ PactKit ships 25 deterministic CLI subcommands — operations that were previous
 | `pactkit test-map` | Map source files to test files |
 | `pactkit coverage-gate` | Enforce 3-tier coverage thresholds (80/50/block) |
 | `pactkit visualize` | Conditional graph regeneration (lazy mode) |
+| `pactkit query` | Query call graph via codegraph: `--callers`, `--callees`, `--chain [--down]` (requires `graph_provider: codegraph`) |
 | `pactkit lesson-append` | Append lesson with specificity check and dedup |
 | `pactkit invariants-refresh` | Update test count invariant in rules.md |
 | `pactkit sec-scope` | Detect security scope for changed files |
@@ -375,6 +376,7 @@ docs/
 | `skills` | list | all 10 | Skills to deploy |
 | `rules` | list | all 8 | Constitution rule modules to deploy |
 | `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
+| `visualize.graph_provider` | string | (absent) | Graph query backend. Set `codegraph` to use `.codegraph/codegraph.db` for `pactkit query`. Absent = grep `.mmd` |
 | `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`). Sub-fields: `runner` (default: `ubuntu-latest`), `language_version` (default: auto per stack), `github_host` (GHE server address), `actions_ref` (GHE actions prefix) |
 | `issue_tracker` | object | `provider: none` | External issue tracker (`github`, `none`) |
 | `hooks` | object | disabled | Opt-in hook templates (pre-commit, post-test, pre-push) |

{pactkit-2.13.0 → pactkit-2.14.0}/README.md

@@ -13,7 +13,7 @@
 
 > **PactKit** (Pact 契约 + Kit) is a governance framework that enforces the **P.A.C.T.** contract between humans and AI agents. Deterministic operations run as code, not prompts. Decisions are grounded in data, not memory. AI does what it's best at — creativity and language — while code handles everything that must be repeatable and correct.
 >
-> 25 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` deploys to all 3 supported IDEs.
+> 26 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` deploys to all 3 supported IDEs.
 
 ### Supported AI Tools
 
@@ -205,7 +205,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 | Skill | Type | Purpose |
 |-------|------|---------|
-| **pactkit-visualize** | Scripted | Code dependency graph (Mermaid): file-level, class-level, call-level |
+| **pactkit-visualize** | Scripted | Code dependency graph (Mermaid .mmd): file-level, class-level, call-level |
 | **pactkit-board** | Scripted | Sprint board operations: add story, update task, archive |
 | **pactkit-scaffold** | Scripted | File scaffolding: create spec, test files, git branches, skills |
 | **pactkit-trace** | Prompt-only | Deep code tracing and execution flow analysis |
@@ -218,7 +218,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 ## CLI Subcommands
 
-PactKit ships 25 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+PactKit ships 26 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
 
 | Command | Purpose |
 |---------|---------|
@@ -239,6 +239,7 @@ PactKit ships 25 deterministic CLI subcommands — operations that were previous
 | `pactkit test-map` | Map source files to test files |
 | `pactkit coverage-gate` | Enforce 3-tier coverage thresholds (80/50/block) |
 | `pactkit visualize` | Conditional graph regeneration (lazy mode) |
+| `pactkit query` | Query call graph via codegraph: `--callers`, `--callees`, `--chain [--down]` (requires `graph_provider: codegraph`) |
 | `pactkit lesson-append` | Append lesson with specificity check and dedup |
 | `pactkit invariants-refresh` | Update test count invariant in rules.md |
 | `pactkit sec-scope` | Detect security scope for changed files |
@@ -333,6 +334,7 @@ docs/
 | `skills` | list | all 10 | Skills to deploy |
 | `rules` | list | all 8 | Constitution rule modules to deploy |
 | `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
+| `visualize.graph_provider` | string | (absent) | Graph query backend. Set `codegraph` to use `.codegraph/codegraph.db` for `pactkit query`. Absent = grep `.mmd` |
 | `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`). Sub-fields: `runner` (default: `ubuntu-latest`), `language_version` (default: auto per stack), `github_host` (GHE server address), `actions_ref` (GHE actions prefix) |
 | `issue_tracker` | object | `provider: none` | External issue tracker (`github`, `none`) |
 | `hooks` | object | disabled | Opt-in hook templates (pre-commit, post-test, pre-push) |

{pactkit-2.13.0 → pactkit-2.14.0}/docs/architecture/governance/lessons.md

@@ -48,3 +48,7 @@
 | 2026-04-27 | When extracting project-specific rules into a framework, generalize by removing project names, library references, and spec IDs — keep only the anti-pattern/fix-pattern structure that applies to any codebase | rules.py:RULES_MODULES |
 | 2026-05-07 | Code Enforces implementation: pactkit interface-summary uses ast.parse() to physically output only signatures—AI receives truncated content, not a prompt instruction to self-truncate. Pattern: CLI tool as enforcement layer (interface_summary.py:generate_summary) | src/pactkit/skills/interface_summary.py:generate_summary |
 | 2026-05-07 | Lifecycle gap pattern: when artifact has create+consume but no update mechanism, add conditional sync in the modifying command. Applied: Act Phase 4 Journey Sync step in commands.py COMMANDS_CONTENT['project-act.md'] | src/pactkit/prompts/commands.py:COMMANDS_CONTENT |
+| 2026-05-25 | code_graph.mmd uses sanitized node IDs (src_pactkit_generators_deployer_py), not bare filenames — grep patterns for fan-in/fan-out must use .* wildcard or they silently never match | src/pactkit/prompts/skills.py:SKILL_VISUALIZE_MD |
+| 2026-05-25 | When SCAN_EXCLUDES is a module-level constant shared across graph modes, add mode-specific exclusion logic at the call site rather than modifying the constant — pass call_extra_excludes = SCAN_EXCLUDES - {'tests'} only for call mode to avoid affecting file/class modes | visualize.py:_build_call_graph |
+| 2026-05-25 | _write_sqlite_db reuses func_registry and rel_edges already in memory from _build_call_graph — no second AST scan; pactkit query reads db directly without touching pactkit.yaml | visualize.py:_build_call_graph |
+| 2026-05-26 | SKILL.md model: frontmatter is passed through by deployer without transformation — source prompts in commands.py/workflows.py are the single source of truth for deployed skill metadata | commands.py:COMMANDS_CONTENT |

{pactkit-2.13.0 → pactkit-2.14.0}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 3937+ tests must pass before any commit to `main`.
+1. All 3986+ 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.14.0/docs/product/archive/archive_202605.md

@@ -0,0 +1,109 @@
+
+### [STORY-slim-113] pactkit interface-summary CLI — Code Enforce 接口摘要
+> Spec: docs/specs/STORY-slim-113.md
+
+- [x] 新建 interface_summary.py 提取逻辑
+- [x] CLI 注册 interface-summary 命令
+- [x] Act Phase 1 改为显式步骤
+- [x] pactkit-trace 更新输出指引
+- [x] 单元测试
+
+### [STORY-slim-112] Rules 架构重构：全局原则 vs 按需操作规程
+> Spec: docs/specs/STORY-slim-112.md
+
+- [x] 拆分 RULES_CORE/ONDEMAND + 新建 05-principles
+- [x] 更新 deployer 双目录部署
+- [x] 更新所有 skill @import 路径
+- [x] 更新测试断言
+
+### [STORY-slim-111] Check Phase 4 Playwright 断言策略指南
+> Spec: docs/specs/STORY-slim-111.md
+
+- [x] 修改 project-check SKILL.md Phase 4 增加断言策略
+
+### [STORY-slim-110] project-design 集成 User Journey 生成
+> Spec: docs/specs/STORY-slim-110.md
+
+- [x] 修改 project-design SKILL.md Phase 1 Group B
+
+### [STORY-slim-109] E2E journey.md 规范定义与 File Atlas 集成
+> Spec: docs/specs/STORY-slim-109.md
+
+- [x] 注册 File Atlas
+- [x] 创建 journey.md 格式规范
+- [x] 修改 project-check Phase 4
+
+### [STORY-slim-108] pactkit-trace --summary 模式：接口摘要输出
+> Spec: docs/specs/STORY-slim-108.md
+
+- [x] 修改 pactkit-trace SKILL.md Phase 3
+- [x] 修改 project-act SKILL.md Phase 1
+
+### [STORY-slim-114] Act Phase 4 Journey Sync — journey.md 维护闭环
+> Spec: docs/specs/STORY-slim-114.md
+
+- [x] Act Phase 4 新增 Journey Sync 步骤
+- [x] Plan Phase 3.2a 条件 Journey Segment
+- [x] 单元测试
+
+### [HOTFIX-slim-117] Fix Graph Query Protocol grep patterns
+> Spec: docs/specs/HOTFIX-slim-117.md
+
+- [x] Fix fan-in/fan-out grep patterns in SKILL_VISUALIZE_MD
+- [x] Fix importer-count grep in project-act.md Phase 3
+
+### [STORY-slim-116] Skill Model Precision and Graph Query Optimization
+> Spec: docs/specs/STORY-slim-116.md
+
+- [x] Add graph query protocol to project-act and project-plan
+- [x] Add model field to pactkit-visualize SKILL.md
+- [x] Add model fields to 28 skills missing model assignment
+- [x] Update project-plan and project-sprint to opus
+- [x] Add haiku to pure I/O skills (scaffold, board, doctor, status, report, draw, arch-diagram, profile, find-skills, docx, pdf, pptx, xlsx)
+
+### [STORY-slim-120] Improve Call Graph Coverage: Test Files, Scripts, Locality Resolution
+> Spec: docs/specs/STORY-slim-120.md
+
+- [x] Write TDD tests for AC1-AC4
+- [x] R1: scan tests/ in call mode
+- [x] R2: scan scripts/ and alembic/
+- [x] R3: locality-based _resolve_callee
+- [x] Run pactkit update
+
+### [STORY-slim-121] call graph SQLite output with pactkit query CLI
+> Spec: docs/specs/STORY-slim-121.md
+
+- [x] Add visualize.sqlite_output config toggle
+- [x] Add _load_sqlite_config() helper
+- [x] Add _write_sqlite_db() with atomic write
+- [x] Wire into _build_call_graph()
+- [x] Add pactkit query subcommand (fan-in/fan-out/chain)
+- [x] Update SKILL_VISUALIZE_MD with pactkit query examples
+- [x] Add *.db to .gitignore
+
+### [STORY-slim-124] codegraph integration — read .codegraph/codegraph.db as graph provider
+> Spec: docs/specs/STORY-slim-124.md
+
+- [x] Add graph_provider config to pactkit.yaml
+- [x] Guard _write_sqlite_db when codegraph
+- [x] Implement codegraph SQL in pactkit query
+- [x] Update Graph Query Protocol in skills.py
+- [x] Update PDCA prompts to prefer pactkit query
+
+### [HOTFIX-slim-123] Fix: call_graph.db duplicate edges and orphan nodes
+> Spec: docs/specs/HOTFIX-slim-123.md
+
+- [x] Dedup rel_edges before insert
+- [x] Filter edges to only reference existing nodes
+
+### [HOTFIX-slim-122] Fix: focus/entry overwrites call_graph.db
+> Spec: docs/specs/HOTFIX-slim-122.md
+
+- [x] Guard sqlite write against focus/entry mode
+
+### [STORY-slim-125] Add model frontmatter to all PDCA command/skill prompts
+> Spec: docs/specs/STORY-slim-125.md
+
+- [x] Add model to commands.py
+- [x] Add model to workflows.py
+- [x] Add regression test

pactkit-2.14.0/docs/product/context.md

@@ -0,0 +1,29 @@
+# Project Context (Auto-generated)
+> Last updated: 2026-05-26T17:29:18+08:00 by pactkit context
+
+## Sprint Status
+Backlog: 2 | In Progress: 0 | Done: 0 stories
+
+## Current Stories
+None
+
+## Recent Completions
+None
+
+## Active Branches
++ claude/naughty-euclid-e6a787
+  develop
+* main
+
+## Key Decisions
+- Lifecycle gap pattern: when artifact has create+consume but no update mechanism, add conditional sync in the modifying command. Applied: Act Phase 4 Journey Sync step in commands.py COMMANDS_CONTENT['project-act.md']
+- code_graph.mmd uses sanitized node IDs (src_pactkit_generators_deployer_py), not bare filenames — grep patterns for fan-in/fan-out must use .* wildcard or they silently never match
+- When SCAN_EXCLUDES is a module-level constant shared across graph modes, add mode-specific exclusion logic at the call site rather than modifying the constant — pass call_extra_excludes = SCAN_EXCLUDES - {'tests'} only for call mode to avoid affecting file/class modes
+- _write_sqlite_db reuses func_registry and rel_edges already in memory from _build_call_graph — no second AST scan; pactkit query reads db directly without touching pactkit.yaml
+- SKILL.md model: frontmatter is passed through by deployer without transformation — source prompts in commands.py/workflows.py are the single source of truth for deployed skill metadata
+
+## Next Recommended Action
+`/project-plan`
+
+## Agent Continuation
+No active work session.

pactkit-2.14.0/docs/product/sprint_board.md

@@ -0,0 +1,24 @@
+# Sprint Board
+
+## 📋 Backlog
+
+### [STORY-slim-118] codegraph MCP Integration for Semantic Code Queries
+> Spec: docs/specs/STORY-slim-118.md
+
+- [ ] Document replacement vs augmentation decision
+- [ ] Add codegraph MCP conditional note to SKILL_VISUALIZE_MD Graph Query Protocol
+- [ ] Run pactkit update to redeploy
+
+### [STORY-slim-119] Improve Python Call Graph Coverage
+> Spec: docs/specs/STORY-slim-119.md
+
+- [ ] Extend _extract_calls to capture non-self attribute method calls (R1)
+- [ ] Capture function references in list/assignment contexts (R2)
+- [ ] Use ast.walk to scan nested functions (R3)
+- [ ] Write TDD tests for AC1-AC4
+- [ ] Run pactkit update to redeploy
+
+## 🔄 In Progress
+
+## ✅ Done
+

pactkit-2.14.0/docs/specs/HOTFIX-slim-117.md

@@ -0,0 +1,18 @@
+# HOTFIX-slim-117: Fix Graph Query Protocol grep patterns for code_graph.mmd
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-117 |
+| Status | Done |
+| Release | 2.14.0 |
+
+## Background
+
+Graph Query Protocol (added in STORY-slim-116) uses `grep " --> deployer"` and `grep "deployer --> "` to filter edges in `code_graph.mmd`. However, nodes in `code_graph.mmd` are sanitized IDs (`src_pactkit_generators_deployer_py`), not bare filenames. These patterns never match — silent no-op. Correct patterns require `.*` wildcard: `grep " --> .*deployer"` (fan-in) and `grep "deployer.* --> "` (fan-out).
+
+Same issue in `project-act.md` Phase 3 importer-count: `grep " --> <file>"` → `grep " --> .*<file>"`.
+
+## Target Files
+
+- `src/pactkit/prompts/skills.py` — SKILL_VISUALIZE_MD lines 93, 96, 99
+- `src/pactkit/prompts/commands.py` — project-act.md Phase 3 line 237

pactkit-2.14.0/docs/specs/HOTFIX-slim-122.md

@@ -0,0 +1,20 @@
+# HOTFIX-slim-122: prevent focus/entry mode from overwriting full call_graph.db
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-122 |
+| Status | In Progress |
+| Priority | P2 |
+| Release | 2.13.0 |
+
+## Background
+
+`_build_call_graph()` writes `call_graph.db` unconditionally when `sqlite_output: true`, including when running in `--focus` or `--entry` mode. These modes produce a subgraph (not the full call graph), so writing them to `call_graph.db` overwrites the complete dataset with a partial one.
+
+## Fix
+
+Only write `call_graph.db` when both `focus` and `entry` are falsy (i.e., full graph mode).
+
+- **Target**: `src/pactkit/skills/visualize.py`
+- **Line 855**: Add `and not focus` guard (BFS/entry path)
+- **Line 891**: Add `and not focus` guard (full graph path with focus filter)

pactkit-2.14.0/docs/specs/HOTFIX-slim-123.md

@@ -0,0 +1,17 @@
+# HOTFIX-slim-123: call_graph.db dedup edges and filter orphan nodes
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-123 |
+| Status | Done |
+| Priority | P1 |
+
+## Background
+
+`_write_sqlite_db()` had two data quality issues: (1) duplicate edges (35.8% in pactsearch) because `rel_edges` was inserted without dedup, and (2) orphan edges referencing nodes not in `func_registry` (e.g., `__module__` synthetic callers).
+
+## Fix
+
+- Target: `src/pactkit/skills/visualize.py:_write_sqlite_db()`
+- Dedup `rel_edges` via set conversion before INSERT
+- Filter edges to only include caller/callee pairs where both exist in `func_registry`

pactkit-2.14.0/docs/specs/STORY-slim-115.md

@@ -0,0 +1,141 @@
+# STORY-slim-115: Worktree/Parallel Session Artifact Drift Prevention
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-115 |
+| Title | Worktree/Parallel Session Artifact Drift Prevention |
+| Status | Draft |
+| Release | TBD |
+
+## Background
+
+### The Problem
+
+PactKit 的多个共享 artifact 文件在 worktree 或并行 session 场景下会发生 **drift（漂移）**——一个 session 的正确状态被另一个 session 的旧版本覆盖。
+
+**真实案例（koi 项目，2026-05-07）**：
+1. Session A 在 `59a043b` 完成 STORY-026/028，board 正确显示它们在 Done 区
+2. Session B（`/dev` worktree）基于更早的 board 版本工作
+3. Session B 完成 STORY-029，commit 时用自己的旧 board 覆盖了 Session A 的正确状态
+4. 结果：已完成的 STORY-026/028 被"移回" Backlog，archive 中已有记录但 board 与之矛盾
+
+### Hot Files 分析
+
+以下文件被多个 PDCA 命令读写，是并行冲突的高危区：
+
+| File | Written By | Conflict Risk |
+|------|------------|---------------|
+| `docs/product/sprint_board.md` | Plan (add), Act (move to In Progress), Done (move to Done, archive) | **HIGH** — 整个文件被覆盖 |
+| `docs/product/context.md` | Plan, Act, Done, Hotfix (context update) | **MEDIUM** — 最后写入者覆盖 |
+| `docs/architecture/governance/lessons.md` | Done (append lessons) | **LOW** — append-only 但仍可能丢行 |
+| `docs/architecture/governance/rules.md` | Done (update test count invariant) | **LOW** — 单行更新 |
+| `docs/product/archive/archive_YYYYMM.md` | Done (append archived stories) | **LOW** — append-only |
+
+### Root Cause
+
+1. **Worktree 隔离不完整**：worktree 创建时 fork 了主分支的状态，但返回时没有 merge 主分支的 board 变更
+2. **Board 是 mutable 的单一文件**：状态转移（Backlog→In Progress→Done）是覆盖式操作，不是增量操作
+3. **没有 conflict detection**：commit 时如果 board 被其他 session 修改过，git 不会自动冲突（不同位置的修改会 auto-merge，导致逻辑不一致）
+
+## Target Call Chain
+
+```
+/project-act → Phase 0.6 → move story to In Progress → sprint_board.md
+/project-done → Phase 3.5 → archive story → sprint_board.md + archive_YYYYMM.md
+/dev worktree → ... → commit → merge back → potential board drift
+```
+
+## Requirements
+
+### R1: Derived Board View (MUST)
+Board 不再是手动维护的 mutable 文件，而是从 specs + archive 推导的 **view**：
+- Story 存在于 `docs/specs/{ID}.md` 且 `status: backlog` → Backlog
+- Story 存在于 `docs/specs/{ID}.md` 且 `status: in_progress` → In Progress  
+- Story 存在于 archive 或 spec `status: done` → Done（显示在 archive，不在 board）
+
+状态存储在 spec 文件的 frontmatter 或 metadata table 中，单 story 单文件，并行修改不同 story 不冲突。
+
+### R2: Board Generation Command (MUST)
+`pactkit board` 命令动态生成 board 视图：
+```bash
+pactkit board           # 输出 markdown 格式的当前 board
+pactkit board --write   # 可选：写入 sprint_board.md（用于兼容现有工具）
+```
+
+### R3: Playbook Migration (MUST)
+修改 PDCA 命令的 board 操作：
+- `/project-plan`：`pactkit spec-status {ID} backlog` 设置 spec 状态
+- `/project-act`：`pactkit spec-status {ID} in_progress` 设置 spec 状态
+- `/project-done`：`pactkit spec-status {ID} done` 设置 spec 状态 + archive 追加
+
+不再直接编辑 `sprint_board.md`。
+
+### R4: Worktree Merge Protocol (SHOULD)
+Worktree 返回主分支前，自动检查 board 相关文件是否有冲突：
+- 如果 spec 文件被主分支修改过，提示用户 merge
+- 如果 archive 文件被主分支追加过，auto-merge（append-only 安全）
+
+### R5: Conflict Detection Hook (SHOULD)
+Pre-commit hook 检测 board drift：
+- 如果 `sprint_board.md` 的 base 版本与当前 HEAD 不同，警告用户
+- 建议运行 `pactkit board --write` 重新生成
+
+### R6: Backward Compatibility (MUST)
+- 现有 `sprint_board.md` 格式保持不变（generated file 或 view）
+- 不使用 `pactkit` CLI 的用户仍可手动编辑 board（但建议迁移）
+- Migration path：运行 `pactkit board-migrate` 从现有 board 反推 spec status
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 User Input | N/A | Internal tooling, no user input |
+| SEC-2 Secrets | N/A | No secrets involved |
+| SEC-3 File Access | N/A | Only project-local files |
+| SEC-4 Network | N/A | No network access |
+| SEC-5 Auth | N/A | No auth changes |
+| SEC-6 Data Validation | N/A | No external data |
+| SEC-7 Crypto | N/A | No crypto |
+| SEC-8 Logging | N/A | No sensitive data logging |
+
+## Acceptance Criteria
+
+### AC1: Derived Board Correctness (R1, R2)
+- **Given** a project with 3 specs: A (status: backlog), B (status: in_progress), C (status: done)
+- **When** `pactkit board` is run
+- **Then** output shows A in Backlog, B in In Progress, Done section is empty (done stories go to archive)
+
+### AC2: Spec Status Transition (R3)
+- **Given** a spec STORY-001 with `status: backlog`
+- **When** `pactkit spec-status STORY-001 in_progress` is run
+- **Then** the spec file's status field is updated to `in_progress`
+- **And** `pactkit board` shows STORY-001 in In Progress section
+
+### AC3: Parallel Session Safety (R1)
+- **Given** two parallel sessions working on different stories (STORY-A and STORY-B)
+- **When** both sessions complete and commit
+- **Then** both stories' spec status are correctly updated (no overwrite)
+- **And** `pactkit board` shows correct state for both
+
+### AC4: Migration from Existing Board (R6)
+- **Given** an existing `sprint_board.md` with stories in various sections
+- **When** `pactkit board-migrate` is run
+- **Then** each story's spec file is updated with the correct status
+- **And** `pactkit board` reproduces the original board structure
+
+## Implementation Steps
+
+| Step | File | Change |
+|------|------|--------|
+| 1 | `src/pactkit/board.py` | New module: `generate_board()`, `get_spec_status()`, `set_spec_status()` |
+| 2 | `src/pactkit/cli.py` | Add `board`, `spec-status`, `board-migrate` commands |
+| 3 | `pactkit-plugin/commands/project-plan.md` | Replace board edit with `pactkit spec-status` |
+| 4 | `pactkit-plugin/commands/project-act.md` | Replace board edit with `pactkit spec-status` |
+| 5 | `pactkit-plugin/commands/project-done.md` | Replace board edit with `pactkit spec-status` |
+| 6 | `tests/unit/test_board.py` | Unit tests for board generation and status transitions |
+
+## Notes
+
+- 这个改动是 **breaking change**，需要在 release notes 中说明 migration path
+- 考虑添加 `pactkit.yaml` 配置项 `board.mode: derived | legacy` 支持渐进迁移
+- Context.md 的 drift 问题较轻（信息类文件，不影响工作流状态），可以后续处理