pactkit 2.12.0__tar.gz → 2.13.0__tar.gz

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

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

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

@@ -4,6 +4,13 @@ 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
+
+### Added
+- **`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.
+
 ## [2.12.0] - 2026-05-06
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.12.0
+Version: 2.13.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

{pactkit-2.12.0 → pactkit-2.13.0}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -54,3 +54,11 @@
 | 2026-03-24 | _scan_hooks() only accepts files with 'use' prefix in hook dirs (src/hooks/, composables/) to prevent utility files from becoming hook nodes | visualize.py:_scan_hooks |
 | 2026-03-24 | regression_workflow_impact hook/store matching uses node.id substring of changed file path, not reverse — e.g. 'useAuth' in 'src/hooks/useAuth.ts' | visualize.py:regression_workflow_impact |
 | 2026-03-25 | export_focus_graphs() in visualize.py uses forward_reach() (not reverse_reach()) because entry points (command/service/page) are graph roots that invoke downward — forward BFS shows their dependency tree | src/pactkit/skills/visualize.py:export_focus_graphs |
+| 2026-03-26 | board.py update_task: added 3-tier fuzzy fallback (single-task auto-mark, substring match, numeric index) to handle real-world callers that don't know exact task names on the board | src/pactkit/skills/board.py:update_task |
+| 2026-03-26 | Position-based block removal (start, end tuples) is safer than str.find() for board operations — prevents substring false matches on similar story IDs | board.py:_parse_story_blocks |
+| 2026-03-26 | Fixing _parse_story_blocks to return adjusted_end (len match) inherently fixed fix_board offset compensation — root cause fix in board.py:_parse_story_blocks eliminated downstream R2 symptom in board.py:fix_board | board.py:_parse_story_blocks,board.py:fix_board |
+| 2026-03-26 | Helpers added to visualize.py standalone header get stripped by load_script(); always place new functions below the SCRIPT BODY marker | visualize.py:_mermaid_escape |
+| 2026-03-26 | dict.pop() in shared config references causes caller mutation; use .get() for read-only access to avoid breaking multi-call scenarios | deployer.py:_deploy_ci |
+| 2026-03-26 | _atomic_mmd_write() in visualize.py prevents truncated .mmd on crash via tmp+rename; all 4 write sites converted | visualize.py:_atomic_mmd_write |
+| 2026-03-26 | test_story_slim056.py _init_project() helper creates realistic pactkit project fixture for subprocess E2E tests; 60 tests cover all 25 subcommands | test_story_slim056.py:_init_project |
+| 2026-03-26 | entry_points auto-discovery with _load_entry_point_deployers() enables pip install pactkit-opencode to self-register; pre-existing tests referencing extracted functions must be updated to import from adapter package | deployer.py:_load_entry_point_deployers |

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

@@ -2,14 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 2026-03-26 | board.py update_task: added 3-tier fuzzy fallback (single-task auto-mark, substring match, numeric index) to handle real-world callers that don't know exact task names on the board | src/pactkit/skills/board.py:update_task |
-| 2026-03-26 | Position-based block removal (start, end tuples) is safer than str.find() for board operations — prevents substring false matches on similar story IDs | board.py:_parse_story_blocks |
-| 2026-03-26 | Fixing _parse_story_blocks to return adjusted_end (len match) inherently fixed fix_board offset compensation — root cause fix in board.py:_parse_story_blocks eliminated downstream R2 symptom in board.py:fix_board | board.py:_parse_story_blocks,board.py:fix_board |
-| 2026-03-26 | Helpers added to visualize.py standalone header get stripped by load_script(); always place new functions below the SCRIPT BODY marker | visualize.py:_mermaid_escape |
-| 2026-03-26 | dict.pop() in shared config references causes caller mutation; use .get() for read-only access to avoid breaking multi-call scenarios | deployer.py:_deploy_ci |
-| 2026-03-26 | _atomic_mmd_write() in visualize.py prevents truncated .mmd on crash via tmp+rename; all 4 write sites converted | visualize.py:_atomic_mmd_write |
-| 2026-03-26 | test_story_slim056.py _init_project() helper creates realistic pactkit project fixture for subprocess E2E tests; 60 tests cover all 25 subcommands | test_story_slim056.py:_init_project |
-| 2026-03-26 | entry_points auto-discovery with _load_entry_point_deployers() enables pip install pactkit-opencode to self-register; pre-existing tests referencing extracted functions must be updated to import from adapter package | deployer.py:_load_entry_point_deployers |
 | 2026-03-26 | VALID_FORMATS auto-derives from FORMAT_PROFILES.keys() — removing a profile cascades to config, CLI, and deployer with zero manual sync | profiles.py:FORMAT_PROFILES |
 | 2026-03-26 | DeployerBase static methods use lazy imports to avoid circular dependencies between deploy_base.py and deployer.py | deploy_base.py:DeployerBase.render_prompt |
 | 2026-03-26 | Thin adapter conversion: pactkit-codex reduced from 15,356 lines (full fork) to 668 lines (thin adapter) by importing core via DeployerBase. Key: deploy_codex_playbooks needs explicit path replacement for ALL format prefixes (~/.claude/, ~/.config/opencode/ → ~/.codex/) | pactkit_codex/deployer.py:deploy_codex_playbooks |
@@ -54,3 +46,5 @@
 | 2026-04-24 | Plan Phase横向扫描(Lateral Scan)比纵向trace更重要——PactSearch的10个技术债中60%源于缺少水平重复检测。修复方向是改Plan playbook引导Architect用已有工具(LSP/visualize/grep)做横向扫描，而非新建CLI | commands.py:Plan_Phase_1 |
 | 2026-04-24 | When migrating functionality (e.g., version checking from pactkit.yaml to global marker), grep all references across source, prompts, tests, and CLI help text — partial migration leaves ghost behavior | board.py:update_version |
 | 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 |

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

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

@@ -1,19 +1,20 @@
-# Sprint Board
 
-## 📋 Backlog
+### [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
 
-- [ ] 拆分 RULES_CORE/ONDEMAND + 新建 05-principles
-- [ ] 更新 deployer 双目录部署
-- [ ] 更新所有 skill @import 路径
-- [ ] 更新测试断言
-
-## 🔄 In Progress
-
-## ✅ Done
+- [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
@@ -37,3 +38,10 @@
 
 - [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] 单元测试

{pactkit-2.12.0 → pactkit-2.13.0}/docs/product/context.md

@@ -1,16 +1,14 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-05-06T14:08:28+08:00 by pactkit context
+> Last updated: 2026-05-07T10:33:00+08:00 by pactkit context
 
 ## Sprint Status
-Backlog: 1 | In Progress: 0 | Done: 4 stories
+Backlog: 0 | In Progress: 0 | Done: 0 stories
 
 ## Current Stories
 None
 
 ## Recent Completions
-- STORY-slim-110: project-design 集成 User Journey 生成
-- STORY-slim-109: E2E journey.md 规范定义与 File Atlas 集成
-- STORY-slim-108: pactkit-trace --summary 模式：接口摘要输出
+None
 
 ## Active Branches
 + claude/naughty-euclid-e6a787
@@ -18,14 +16,14 @@ None
 * main
 
 ## Key Decisions
-- Signal Strength L3 SHOULD semantics in rules.py:RULES_MODULES['core'] must use RFC 2119 wording — 'warning, non-blocking' caused AI to systematically defer all SHOULD tasks during Act
-- Rule files deploy from src/pactkit/prompts/rules.py via pactkit deploy — never edit ~/.claude/rules/ directly
 - Plan Phase横向扫描(Lateral Scan)比纵向trace更重要——PactSearch的10个技术债中60%源于缺少水平重复检测。修复方向是改Plan playbook引导Architect用已有工具(LSP/visualize/grep)做横向扫描，而非新建CLI
 - When migrating functionality (e.g., version checking from pactkit.yaml to global marker), grep all references across source, prompts, tests, and CLI help text — partial migration leaves ghost behavior
 - 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
+- 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)
+- 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']
 
 ## Next Recommended Action
-`/project-plan`
+`/project-design`
 
 ## Agent Continuation
 No active work session.

pactkit-2.13.0/docs/product/sprint_board.md

@@ -0,0 +1,8 @@
+# Sprint Board
+
+## 📋 Backlog
+
+## 🔄 In Progress
+
+## ✅ Done
+

pactkit-2.13.0/docs/specs/STORY-slim-113.md

@@ -0,0 +1,175 @@
+# STORY-slim-113: pactkit interface-summary CLI — Code Enforce 接口摘要
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-113 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.13.0 |
+
+## Background
+
+### 问题
+
+STORY-slim-108 引入了"接口摘要"概念——Act Phase 1 对 trace 发现的非目标模块只读签名+docstring。但当前实现**完全依赖 Prompt 指导**（pactkit-trace SKILL.md 的 "Layered Output" 表格 + Act Phase 1.2 的一句 "Layered Loading"），AI 实际执行时仍然直接 Read 完整文件，因为：
+
+1. 没有工具约束——AI 调用 Read 工具时没有 `--summary-only` 限制
+2. 一句文字指导不足以改变 AI 的默认行为
+3. 违反了 PactKit 自己的 "Code Enforces, Prompt Instructs" 原则（架构原则 §10）
+
+### 方案
+
+新增 `pactkit interface-summary <file>` CLI 命令：
+- 基于现有 `python_analyzer.py` 的 AST 能力（已有 `extract_classes`、`extract_functions_and_calls`）
+- 输出经代码裁剪的接口摘要，AI 拿到的物理上就是精简内容
+- Act Phase 1 改为**显式步骤**：对非目标模块调用此 CLI 而非 Read
+
+### 为什么不用 hook
+
+用户明确要求不使用 hook。本方案通过 CLI 输出 + playbook 步骤变更来实现 Code Enforce，无需 harness 层面的文件拦截。
+
+## Requirements
+
+### R1: 新增 `pactkit interface-summary` CLI 命令 (MUST)
+
+新增子命令接受一个或多个文件路径，输出接口摘要：
+
+```
+pactkit interface-summary src/pactkit/generators/deployer.py
+```
+
+输出格式（per file）：
+```
+# deployer.py — Interface Summary
+
+class ClassicDeployer(BaseDeployer):
+    """Deploy PactKit to ~/.claude/ (Classic format)."""
+    +deploy(target, config) -> DeployResult
+    +_deploy_rules(claude_root, enabled_rules) -> None
+    +_deploy_skills(claude_root, enabled_skills) -> None
+    -_cleanup_legacy(target) -> None
+
+def atomic_write(path: Path, content: str) -> None:
+    """Write content atomically via tempfile + rename."""
+
+def _render_prompt(template: str, profile: FormatProfile) -> str:
+    """Replace placeholders with profile-specific values."""
+```
+
+提取规则：
+- **Class**: class name + bases + docstring 第一行 + public/private methods with signature
+- **Function**: def name + params with type hints + return type + docstring 第一行
+- **Skip**: 函数体、局部变量、内部逻辑
+- **Constants/Enums**: 顶层 `UPPER_CASE` 赋值保留名称和类型
+
+### R2: 多语言支持通过 LANG_PROFILES 分派 (SHOULD)
+
+使用已有的 `LANG_PROFILES` + analyzer 架构：
+- Python: `ast` 模块提取（已有基础设施）
+- TypeScript: `tree_sitter_typescript` 提取 exported declarations
+- Go: `tree_sitter_go` 提取 exported (大写) func/struct
+
+初始版本 MUST 支持 Python。TS/Go 为 SHOULD。
+
+### R3: Act Phase 1 增加显式步骤 (MUST)
+
+修改 `project-act/SKILL.md` Phase 1.2，从当前的一句指导：
+> "Layered Loading: For non-target modules discovered by trace, read interface summary..."
+
+改为显式步骤：
+```
+2b. **Interface Summary** (for non-target modules):
+    - For each module discovered by trace that is NOT the modification target:
+      `pactkit interface-summary <file>`
+    - Only escalate to `Read <file>` when you confirm the module needs modification.
+```
+
+### R4: pactkit-trace SKILL.md 更新输出格式指引 (MUST)
+
+修改 pactkit-trace SKILL.md Phase 3 "Layered Output" 部分，从"建议 AI 自行精简"改为"调用 CLI 获取"：
+
+> For related (non-target) modules, run `pactkit interface-summary <file>` instead of reading full source.
+
+### R5: 不修改 Read 工具行为 (MUST NOT)
+
+本 story 不修改 Claude Code harness 的 Read 工具、不添加 hook、不拦截文件访问。通过提供更好的替代工具来引导行为，而非限制现有工具。
+
+## Acceptance Criteria
+
+### AC1: CLI 输出接口摘要 (R1)
+
+- **Given** 一个 Python 文件 `src/pactkit/generators/deployer.py`（含多个 class 和函数）
+- **When** 运行 `pactkit interface-summary src/pactkit/generators/deployer.py`
+- **Then** 输出包含所有 class（带 bases 和 methods 签名）和顶层函数（带参数和返回类型），不包含函数体
+
+### AC2: 输出行数显著小于原文件 (R1)
+
+- **Given** `deployer.py` 约 600+ 行
+- **When** 运行 `pactkit interface-summary` 对其生成摘要
+- **Then** 输出行数 ≤ 原文件行数的 25%（即 ≤ 150 行）
+
+### AC3: 多文件支持 (R1)
+
+- **Given** 两个 Python 文件 A.py 和 B.py
+- **When** 运行 `pactkit interface-summary A.py B.py`
+- **Then** 输出两个文件的摘要，以 `# filename — Interface Summary` 分隔
+
+### AC4: Act Phase 1 步骤可验证 (R3)
+
+- **Given** 修改后的 project-act SKILL.md
+- **When** 读取 Phase 1 内容
+- **Then** 存在显式编号步骤 "2b" 包含 `pactkit interface-summary` 命令
+
+### AC5: 非 Python 文件 graceful fallback (R2)
+
+- **Given** 一个 .go 文件但 tree-sitter-go 未安装
+- **When** 运行 `pactkit interface-summary file.go`
+- **Then** 输出警告 "Unsupported or unavailable analyzer for .go" 并退出 0（不阻塞）
+
+## Target Call Chain
+
+```
+pactkit interface-summary <files>
+  → cli.py: main() → parse args → _interface_summary_command(args)
+  → interface_summary.py: generate_summary(file_paths)
+    → detect language from extension
+    → LANG_PROFILES dispatch → python_analyzer / ts_analyzer / go_analyzer
+    → For Python:
+      → ast.parse(source)
+      → Extract: class defs (name, bases, docstring, method signatures)
+      → Extract: top-level functions (name, params, return type, docstring)
+      → Extract: top-level constants (UPPER_CASE assignments)
+    → Format output as structured text
+    → Print to stdout
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/skills/interface_summary.py` | 新建：接口摘要提取逻辑，复用 python_analyzer AST 能力 | None | Medium |
+| 2 | `src/pactkit/cli.py` | 注册 `interface-summary` 子命令 | Step 1 | Low |
+| 3 | `~/.claude/skills/project-act/SKILL.md` (source: `src/pactkit/prompts/commands.py`) | Phase 1.2 → 1.2a + 1.2b 显式步骤 | Step 1-2 | Low |
+| 4 | `~/.claude/skills/pactkit-trace/SKILL.md` (source: `src/pactkit/prompts/skills.py`) | Phase 3 Layered Output 改为 CLI 调用指引 | Step 1-2 | Low |
+| 5 | `tests/unit/test_interface_summary.py` | 新建：单元测试覆盖 Python 文件摘要输出 | Step 1 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | No | 无秘钥变更 |
+| SEC-2 | No | 输入为本地文件路径，已有 file_path.stat() 大小检查 |
+| SEC-3 | No | 无数据库 |
+| SEC-4 | No | 无 UI |
+| SEC-5 | No | 无认证 |
+| SEC-6 | No | 无接口暴露 |
+| SEC-7 | No | CLI 输出，无敏感信息 |
+| SEC-8 | No | 无新依赖（复用现有 ast + tree_sitter） |
+
+## Out of Scope
+
+- 修改 Claude Code Read 工具行为
+- Hook 机制
+- 自动拦截 AI 的 Read 调用
+- Java analyzer 支持（已有但不在本 story 优先级内）
+- `pactkit trace` CLI 命令（本 story 只做 interface-summary，trace 仍是 skill）

pactkit-2.13.0/docs/specs/STORY-slim-114.md

@@ -0,0 +1,158 @@
+# STORY-slim-114: Act Phase 4 Journey Sync — journey.md 维护闭环
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-114 |
+| Status | Done |
+| Priority | P2 |
+| Release | 2.13.0 |
+
+## Background
+
+### 问题
+
+STORY-slim-109 定义了 `docs/e2e/journey.md` 格式规范，STORY-slim-110 让 `/project-design` 自动生成 journey.md，STORY-slim-111 让 `/project-check` 消费 journey.md 来确定 E2E 范围。
+
+但**没有任何命令负责更新 journey.md**。当 `/project-act` 完成一个 story 并改变了用户流中的某个步骤时：
+- journey.md 的步骤描述可能已过时
+- 断言可能不再准确（新加了 UI 元素、改了 API schema）
+- Check Phase 4 会基于 stale 的 journey 定义来确定 E2E 范围
+
+这是一个 **create → consume without update** 的生命周期缺口。
+
+### 方案
+
+在 Act Phase 4 增加条件步骤 "Journey Sync"：
+- 触发条件明确（journey.md 存在 + story 涉及旅程步骤）
+- 行为轻量（读 + 判断 + 按需 Edit，不是全文重写）
+- 无 hook，纯 playbook 步骤
+
+### 同时修复：Design 阶段 Journey Annotation
+
+STORY-slim-110 的 Design Phase 2 已要求"annotate each Story's Spec with the journey segment it relates to"，但这个标注没有标准格式。定义 annotation 格式使 Act Phase 4 能自动判断"当前 story 是否涉及 journey 步骤"。
+
+## Requirements
+
+### R1: Act Phase 4 新增 Journey Sync 步骤 (MUST)
+
+在 Act Phase 4 的 "Sync & Document" 中增加步骤（位于 visualize 之后、board update 之前）：
+
+```markdown
+1b. **Journey Sync (Conditional)**:
+    - **Skip if**: `docs/e2e/journey.md` does not exist in the project
+    - **Skip if**: Current Story's Spec has no `## Journey Segment` section
+    - **If triggered**:
+      1. Read `docs/e2e/journey.md`
+      2. Locate the journey step(s) referenced in the Spec's `## Journey Segment`
+      3. Review: do the step assertions still hold after this Story's code changes?
+      4. If outdated: Edit the affected step(s) — update assertions, add new structure assertions, or adjust step description
+      5. If still accurate: skip with log "Journey steps verified — no update needed"
+```
+
+### R2: Spec 标注格式定义 (MUST)
+
+定义 Spec 中标注 journey segment 的标准格式：
+
+```markdown
+## Journey Segment
+
+- Journey: {Journey Name}
+- Steps: {step numbers, e.g., "2-3" or "4"}
+- Impact: {brief description of how this story affects the journey}
+```
+
+此 section 由 `/project-plan` Phase 3.2a 生成（如果 journey.md 存在），或由 `/project-design` Phase 2 自动添加。
+
+### R3: Plan Phase 3.2a 条件生成 Journey Segment section (SHOULD)
+
+修改 project-plan playbook 的 Phase 3.2a：
+- **条件**: 如果项目有 `docs/e2e/journey.md`
+- **行为**: 读 journey.md，判断当前 story 是否涉及某个 journey 的步骤，如果是则在 Spec 中添加 `## Journey Segment` section
+- **不阻塞**: 如果不涉及任何 journey，不添加此 section（Act Phase 4 的 skip 条件自动生效）
+
+### R4: 不引入新的 CLI 命令 (MUST NOT)
+
+Journey Sync 是 playbook 行为指导，不需要新的 CLI 工具。AI 通过 Read + Edit 操作 journey.md 即可。理由：journey.md 内容是自由格式的 markdown，不适合结构化工具处理。
+
+### R5: Merge over Replace 策略 (MUST)
+
+Journey Sync 更新 journey.md 时 MUST 使用 Edit（增量修改），MUST NOT 使用 Write（全文覆盖）。journey.md 可能包含多个 journey，只改当前 story 涉及的步骤。
+
+## Acceptance Criteria
+
+### AC1: Journey Sync 在 Act Phase 4 存在 (R1)
+
+- **Given** 修改后的 project-act SKILL.md
+- **When** 读取 Phase 4 内容
+- **Then** 存在步骤 "1b" 或 "Journey Sync" 标题，包含 skip 条件和触发行为
+
+### AC2: 无 journey.md 时静默跳过 (R1)
+
+- **Given** 项目没有 `docs/e2e/journey.md`
+- **When** Act Phase 4 执行到 Journey Sync
+- **Then** 静默跳过，无报错
+
+### AC3: Spec 无 Journey Segment section 时跳过 (R1)
+
+- **Given** 项目有 journey.md，但当前 Story 的 Spec 没有 `## Journey Segment`
+- **When** Act Phase 4 执行到 Journey Sync
+- **Then** 跳过，无更新
+
+### AC4: Story 涉及 journey 步骤时触发更新 (R1)
+
+- **Given** 项目有 journey.md，Story Spec 有 `## Journey Segment` 标注 "Journey: First Login, Steps: 2-3"
+- **When** Act Phase 4 执行 Journey Sync
+- **Then** 读取 journey.md 中 "First Login" journey 的 Step 2-3，检查断言是否需更新
+
+### AC5: Spec scaffold 生成 Journey Segment (R2, R3)
+
+- **Given** 项目有 `docs/e2e/journey.md` 定义了 3 个 journey
+- **When** `/project-plan` 生成新 Spec
+- **Then** Spec 中包含 `## Journey Segment` section（如果 story 涉及某个 journey）
+
+## Target Call Chain
+
+```
+/project-act Phase 4:
+  → 1. pactkit visualize --lazy (existing)
+  → 1b. Journey Sync:
+       → Check: does docs/e2e/journey.md exist? (Bash: test -f)
+       → Check: does docs/specs/{ID}.md contain "## Journey Segment"? (grep)
+       → If both: Read journey.md → locate affected steps → Edit if outdated
+  → 2. Board update (existing)
+  → 3. Context update (existing)
+
+/project-plan Phase 3.2a (conditional):
+  → Check: does docs/e2e/journey.md exist?
+  → If yes: Read journey.md → match story scope to journey steps → add ## Journey Segment to Spec
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/commands.py` (act section) | Phase 4 新增 1b Journey Sync 步骤 | None | Low |
+| 2 | `src/pactkit/prompts/commands.py` (plan section) | Phase 3.2a 增加条件 Journey Segment 生成 | None | Low |
+| 3 | `src/pactkit/prompts/skills.py` (trace section) | 无变更（确认不冲突） | None | None |
+| 4 | `tests/unit/test_story_slim114_journey_sync.py` | 验证 Act playbook 包含 Journey Sync 步骤文本 | Step 1 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | No | 无秘钥变更 |
+| SEC-2 | No | 无外部输入处理 |
+| SEC-3 | No | 无数据库 |
+| SEC-4 | No | 无 UI |
+| SEC-5 | No | 无认证 |
+| SEC-6 | No | 无接口 |
+| SEC-7 | No | 无错误输出 |
+| SEC-8 | No | 无依赖变更 |
+
+## Out of Scope
+
+- 新增 CLI 命令（journey.md 由 AI 通过 Read+Edit 操作）
+- journey.md 的结构化 linter（内容是自由格式 markdown）
+- Check Phase 4 修改（已由 STORY-slim-111 处理）
+- Design Phase 1.5.5 修改（已由 STORY-slim-110 处理）
+- 自动检测 journey 影响（需要 AI 判断力，不适合 Code Enforce）

{pactkit-2.12.0 → pactkit-2.13.0}/pyproject.toml

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

{pactkit-2.12.0 → pactkit-2.13.0}/src/pactkit/__init__.py

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

{pactkit-2.12.0 → pactkit-2.13.0}/src/pactkit/cli.py

@@ -341,6 +341,10 @@ def main():
     spec_status_parser.add_argument("spec", help="Path to spec file")
     spec_status_parser.add_argument("status", choices=["Draft", "In Progress", "Done"], help="New status value")
 
+    # pactkit interface-summary (STORY-slim-113)
+    iface_parser = subparsers.add_parser("interface-summary", help="Output interface summary (signatures only)")
+    iface_parser.add_argument("files", nargs="+", help="Source file(s) to summarize")
+
     # pactkit redetect-stack (STORY-slim-077)
     subparsers.add_parser("redetect-stack", help="Re-detect project stacks and update pactkit.yaml")
 
@@ -738,6 +742,14 @@ def main():
         if result["action"] == "error":
             raise SystemExit(1)
 
+    elif args.command == "interface-summary":
+        from pathlib import Path
+
+        from pactkit.skills.interface_summary import generate_summary
+
+        paths = [Path(f) for f in args.files]
+        print(generate_summary(paths))
+
     elif args.command == "redetect-stack":
         from pathlib import Path
 

{pactkit-2.12.0 → pactkit-2.13.0}/src/pactkit/prompts/commands.py

@@ -116,7 +116,19 @@ 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.
-4.  **Output checkpoint**: Print "Spec skeleton filled. Adding acceptance criteria."
+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).
+    - If yes: add a `## Journey Segment` section to the Spec with the format:
+      ```
+      ## Journey Segment
+
+      - Journey: {Journey Name}
+      - Steps: {step numbers, e.g., "2-3" or "4"}
+      - Impact: {brief description of how this story affects the journey}
+      ```
+    - If the Story does not affect any journey: do NOT add this section (Act Phase 4 Journey Sync will auto-skip).
+5.  **Output checkpoint**: Print "Spec skeleton filled. Adding acceptance criteria."
 
 ## 🎬 Phase 3.2b: Acceptance Criteria & Implementation Steps
 1.  **Edit AC** (use Edit tool): Replace `### AC1: (Scenario Name) (R1)` and its Given/When/Then placeholders with actual scenarios. The template already provides the `- **Given**` / `- **When**` / `- **Then**` structure — fill in the content. Add more AC{N} sections as needed.
@@ -190,11 +202,15 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 1.  **Targeted Visual Scan**: Run `visualize --focus <module>` only (single targeted mode). For large codebases, add `--depth 2`. Do NOT run full 3-mode visualize here — that is handled by Phase 4 Lazy Visualize after implementation.
 2.  **Trace Verification** — use pactkit-trace skill:
     - Before touching any code, confirm the call site and ensure you don't break existing callers.
-    - **Layered Loading**: For non-target modules discovered by trace, read interface summary (signature + types + docstring) first. Only escalate to full source when modification is confirmed needed.
-3.  **Topology-Aware Trace (Conditional)** — if `detect_topology(root)` includes `api_call` or `agent`:
+3.  **Interface Summary (Code Enforce)** — for non-target modules discovered by trace:
+    - Run `pactkit interface-summary <file>` for each related module you do NOT plan to modify.
+    - This outputs signatures + types + docstrings only (function bodies excluded by code).
+    - Only escalate to full `Read <file>` when you confirm the module needs modification.
+    - If `pactkit` is not on `$PATH`, use `python3 -m pactkit interface-summary <file>`.
+4.  **Topology-Aware Trace (Conditional)** — if `detect_topology(root)` includes `api_call` or `agent`:
     - For **api_call**: Run `api_convention_summary(root)` to check API path prefixes and fetch function conventions. Use these conventions when writing new API calls to maintain consistency.
     - For **agent**: Check AgentParser output for orchestration edges so new code doesn't break agent flow.
-4.  **Solution Design Protocol (Conditional)** — if the implementation involves frameworks already used by the project:
+5.  **Solution Design Protocol (Conditional)** — if the implementation involves frameworks already used by the project:
     - Execute the **Solution Design Protocol** from `06-solution-design.md` to evaluate capability delta before writing code.
     - Output brief capability assessment before proceeding to Phase 2.
 
@@ -225,6 +241,15 @@ allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
 
 ## 🎬 Phase 4: Sync & Document
 1.  Run `pactkit clean` and `pactkit visualize --lazy` (runs file, `--mode class`, `--mode call` if source changed).
+1b. **Journey Sync (Conditional)**:
+    - **Skip if**: `docs/e2e/journey.md` does not exist in the project.
+    - **Skip if**: Current Story's Spec has no `## Journey Segment` section.
+    - **If triggered**:
+      1. Read `docs/e2e/journey.md`
+      2. Locate the journey step(s) referenced in the Spec's `## Journey Segment` (format: `- Journey: {Name}` / `- Steps: {N}` / `- Impact: {desc}`)
+      3. Review: do the step assertions still hold after this Story's code changes?
+      4. If outdated: Edit the affected step(s) in journey.md — update assertions, add new structure assertions, or adjust step description. MUST use Edit (incremental), MUST NOT use Write (full replace).
+      5. If still accurate: skip with log "Journey steps verified — no update needed"
 2.  **Update Board (CRITICAL)**: Run `{BOARD_CMD} update_task {STORY_ID} "Task Name"` for each completed task to mark it as `[x]`.
 3.  **Update Continuation State**: Run `pactkit context --continuation --last-command "/project-act {STORY_ID}" --phase "Phase 4: complete"` to record the agent's stopping point for session handoff.
 4.  **Coverage Table Output (STORY-slim-105)**: Output a coverage table listing each R{N} from the Spec:

{pactkit-2.12.0 → pactkit-2.13.0}/src/pactkit/prompts/skills.py

@@ -256,18 +256,14 @@ Deep code analysis and execution path tracing via static analysis.
 
 #### Layered Output: Interface Summary vs Full Implementation
 
-| Module Role | Output Level | Content |
-|-------------|-------------|---------|
-| Target (to be modified) | Full implementation | Complete function bodies |
-| Related (dependency, not modified) | Interface summary | Signature + types + docstring only |
+| Module Role | Output Level | How |
+|-------------|-------------|-----|
+| Target (to be modified) | Full implementation | `Read <file>` |
+| Related (dependency, not modified) | Interface summary | `pactkit interface-summary <file>` |
 
-**Interface Summary Extraction by Language:**
+For related (non-target) modules, run `pactkit interface-summary <file>` instead of reading full source. This CLI command uses AST parsing to output only signatures + types + docstrings — function bodies are excluded by code, not by prompt instruction.
 
-- **Python**: `def name(params) -> ReturnType:` + docstring + `@decorator` annotations
-- **TypeScript**: `export function/interface/type` declarations + JSDoc comments
-- **Go**: Exported `func Name(params) ReturnType` + struct definitions + godoc comment
-
-Interface summary is produced on-the-fly during trace output — no separate files are generated (DRY: avoid stale pre-generated artifacts).
+If `pactkit` is not on `$PATH`, use `python3 -m pactkit interface-summary <file>`.
 
 ### 4. Visual Synthesis
 Output a **Mermaid Sequence Diagram** to visualize the flow.