pactkit 2.10.1__tar.gz → 2.10.2__tar.gz

{pactkit-2.10.1 → pactkit-2.10.2}/.github/workflows/pactkit.yml

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

{pactkit-2.10.1 → pactkit-2.10.2}/.opencode/pactkit.yaml

@@ -2,7 +2,7 @@
 # Edit this file to customize which components are deployed.
 # Remove items from a list to disable them. Default: all enabled.
 
-version: "2.10.1"
+version: "2.10.2"
 stack: python
 root: .
 developer: "slim"
@@ -71,6 +71,7 @@ rules:
   - 07-shared-protocols
   - 08-architecture-principles
   - 09-sectional-write
+  - 11-pdca-nudge
 
 # CI/CD — set provider to github or gitlab to generate pipeline config
 ci:

{pactkit-2.10.1 → pactkit-2.10.2}/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.10.2] - 2026-04-20
+
+### Added
+- **PDCA Nudge Protocol** (STORY-slim-098) — AI proactively recommends PDCA commands when free conversation yields actionable conclusions. Trigger matrix maps signals to commands; suppression rules prevent noise.
+
+### Fixed
+- **Shared Protocols Context.md reference** (STORY-slim-099) — Added missing `Act Phase 4` to the Context.md Canonical Format "Referenced by" line. Ensures context.md reflects Act progress for session continuity.
+- **Semantic version comparison** (HOTFIX-slim-099) — Version mismatch warning now uses tuple comparison instead of string equality, giving correct upgrade/downgrade direction.
+
 ## [2.10.1] - 2026-04-16
 
 ### Added

{pactkit-2.10.1 → pactkit-2.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.10.1
+Version: 2.10.2
 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.10.1 → pactkit-2.10.2}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -43,3 +43,6 @@
 | 2026-03-23 | code-explorer maxTurns reduced from 50 to 15 in agents.py; Plan Phase 1 now requires bounded Explore prompts with target/scope/limit/output via Delegation Template in commands.py | src/pactkit/prompts/agents.py:code-explorer.maxTurns,src/pactkit/prompts/commands.py:Phase1.DelegationTemplate |
 | 2026-03-23 | Added 09-sectional-write as core rule in src/pactkit/prompts/rules.py RULES_MODULES. Threshold 300 lines based on P75-P90 analysis of specs/source/tests. Applies to any file type. | src/pactkit/prompts/rules.py:RULES_MODULES |
 | 2026-03-23 | When adding a new pactkit.yaml config section, 4 touch points needed: get_default_config, DEEP_MERGE_KEYS, validate_config, generate_default_yaml. Table format in prompts saves chars vs individual sections. | config.py:get_default_config |
+| 2026-03-24 | Plan Phase 3.2a scaffold-first: replaced AI freeform Write with {SCAFFOLD_CMD} create_spec + Read + Edit in src/pactkit/prompts/commands.py. Removed 3 inline format examples (~240 chars). Pre-existing tests (test_bug034, test_story055_commands, test_story_slim019) needed updates for new checkpoint wording. | src/pactkit/prompts/commands.py:Phase3.2a |
+| 2026-03-24 | spec_linter.py _check_acceptance_criteria: per-subsection GWT check must use raw_text (with code blocks) not stripped text, because specs legitimately wrap Gherkin in fenced blocks | spec_linter.py:_check_acceptance_criteria |
+| 2026-03-24 | Standalone scripts (visualize.py) need try/except ImportError guards for yaml.safe_load when reading pactkit.yaml — they cannot import from pactkit library | visualize.py:_load_scan_excludes |

{pactkit-2.10.1 → pactkit-2.10.2}/docs/architecture/governance/lessons.md

@@ -2,9 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 2026-03-24 | Plan Phase 3.2a scaffold-first: replaced AI freeform Write with {SCAFFOLD_CMD} create_spec + Read + Edit in src/pactkit/prompts/commands.py. Removed 3 inline format examples (~240 chars). Pre-existing tests (test_bug034, test_story055_commands, test_story_slim019) needed updates for new checkpoint wording. | src/pactkit/prompts/commands.py:Phase3.2a |
-| 2026-03-24 | spec_linter.py _check_acceptance_criteria: per-subsection GWT check must use raw_text (with code blocks) not stripped text, because specs legitimately wrap Gherkin in fenced blocks | spec_linter.py:_check_acceptance_criteria |
-| 2026-03-24 | Standalone scripts (visualize.py) need try/except ImportError guards for yaml.safe_load when reading pactkit.yaml — they cannot import from pactkit library | visualize.py:_load_scan_excludes |
 | 2026-03-24 | Inline data in standalone scripts must have canonical-source comments pointing to the library module (e.g. _STACK_MARKERS → cleaners.py, _LANG_FILE_EXT → workflows.py) per Architecture Principle 1 | visualize.py:_STACK_MARKERS |
 | 2026-03-24 | Worktree isolation diverges from working-tree: verify visualize.py _scan_files() signature is preserved across stories to avoid breaking callers | visualize.py:_scan_files |
 | 2026-03-24 | Extracting _detect_stack() from _detect_file_ext() enables both file discovery and test mapping to share stack detection — DRY refactoring | visualize.py:_detect_stack |
@@ -53,3 +50,6 @@
 | 2026-04-16 | File-level hotspot aggregation (complexity_avg × blast_pct × fan_in) reduces 141 per-function findings to ~10 actionable items; _suggest_action() maps dominant signal to Split/Stabilize/Isolate/Decompose verb | src/pactkit/audit.py:_compute_hotspots,_suggest_action |
 | 2026-04-16 | Weighted hotspot formula (complexity 25% + docstring 15% + smells 15% + layers 10% + test 20% + blast 15%) gives meaningful scores across different project profiles; _generate_suggested_tasks auto-scaffolds BUG/HOTFIX specs with Done-completed filter for idempotency | src/pactkit/audit.py:_compute_hotspots,_generate_suggested_tasks |
 | 2026-04-16 | Dual-dimension audit (config+code 50/50) gives accurate project health picture; scanning ~/.claude/ global config catches harness setup invisible at project level | audit.py:_all_config_dirs |
+| 2026-04-17 | Dual-anchor pattern: declare principle in RULES_MODULES['core'] (01-core-protocol.md), detail in dedicated module (11-pdca-nudge.md). Prevents attention dilution when rules/ has 10+ files — Core Protocol acts as behavioral constitution anchor. | src/pactkit/prompts/rules.py:RULES_MODULES |
+| 2026-04-18 | Version comparison guards must use semantic (tuple) comparison, not string equality — string != treats 2.10.1 != 2.5.0 without direction, giving wrong upgrade advice | guards.py:check_version_mismatch |
+| 2026-04-20 | Plugin deployer (_deploy_commands in deployer.py:952-954) uses _rewrite_skills_prefix instead of _render_prompt, keeping raw placeholders like {BOARD_CMD} — not a deploy drift bug but by-design template behavior | src/pactkit/generators/deployer.py:_deploy_commands |

{pactkit-2.10.1 → pactkit-2.10.2}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 3734+ tests must pass before any commit to `main`.
+1. All 3752+ 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.10.1 → pactkit-2.10.2}/docs/product/archive/archive_202604.md

@@ -185,3 +185,23 @@
 - [x] R1: Fix focus filter in _build_call_graph
 - [x] R2: Report empty Tab placeholder
 - [x] R3: Skip empty .mmd in unified report
+
+### [STORY-slim-098] PDCA Nudge Protocol — AI主动推荐PDCA命令
+> Spec: docs/specs/STORY-slim-098.md
+
+- [x] 创建11-pdca-nudge.md规则模板
+- [x] 在VALID_RULES注册新规则
+- [x] 添加部署测试
+- [x] 运行deploy验证
+
+### [HOTFIX-slim-099] Fix version mismatch guard semantic comparison
+> Spec: docs/specs/HOTFIX-slim-099.md
+
+- [x] Use packaging.version for directional version comparison in guards.py
+
+### [STORY-slim-099] Add Act Phase reference to Shared Protocols Context.md section
+> Spec: docs/specs/STORY-slim-099.md
+
+- [x] Update Shared Protocols Referenced-by line
+- [x] Redeploy via pactkit update
+- [x] Verify deployed plugin sync

{pactkit-2.10.1 → pactkit-2.10.2}/docs/product/context.md

@@ -1,5 +1,5 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-04-16T19:13:31+08:00 by pactkit context
+> Last updated: 2026-04-20T10:21:11+08:00 by pactkit context
 
 ## Sprint Status
 Backlog: 0 | In Progress: 0 | Done: 0 stories
@@ -15,11 +15,11 @@ develop
 * main
 
 ## Key Decisions
-- D3 force graph selectNode() computes blast radius via in-browser BFS — no backend needed; folder-based coloring via d3.scaleOrdinal on path prefix gives CodeFlow-quality visuals
-- H1-H7 harness audit aggregator pattern: each _check_hN() function is self-contained with its own L0-L3 criteria, making it easy to add new checks per layer without touching scoring logic
-- File-level hotspot aggregation (complexity_avg × blast_pct × fan_in) reduces 141 per-function findings to ~10 actionable items; _suggest_action() maps dominant signal to Split/Stabilize/Isolate/Decompose verb
 - Weighted hotspot formula (complexity 25% + docstring 15% + smells 15% + layers 10% + test 20% + blast 15%) gives meaningful scores across different project profiles; _generate_suggested_tasks auto-scaffolds BUG/HOTFIX specs with Done-completed filter for idempotency
 - Dual-dimension audit (config+code 50/50) gives accurate project health picture; scanning ~/.claude/ global config catches harness setup invisible at project level
+- Dual-anchor pattern: declare principle in RULES_MODULES['core'] (01-core-protocol.md), detail in dedicated module (11-pdca-nudge.md). Prevents attention dilution when rules/ has 10+ files — Core Protocol acts as behavioral constitution anchor.
+- Version comparison guards must use semantic (tuple) comparison, not string equality — string != treats 2.10.1 != 2.5.0 without direction, giving wrong upgrade advice
+- Plugin deployer (_deploy_commands in deployer.py:952-954) uses _rewrite_skills_prefix instead of _render_prompt, keeping raw placeholders like {BOARD_CMD} — not a deploy drift bug but by-design template behavior
 
 ## Next Recommended Action
 `/project-design`

pactkit-2.10.2/docs/specs/HOTFIX-slim-099.md

@@ -0,0 +1,14 @@
+# HOTFIX-slim-099: Fix version mismatch guard to use semantic comparison
+
+## Background
+`check_version_mismatch()` in `guards.py` uses string `!=` to compare yaml version vs installed version. This gives a misleading "Run `pactkit update` to sync" message even when yaml version is **newer** than installed — in which case the user should upgrade pactkit, not downgrade the yaml.
+
+## Target
+- **File**: `src/pactkit/guards.py`
+- **Function**: `check_version_mismatch()` (line 71-85)
+
+## Fix
+- Use `packaging.version.Version` for semantic comparison
+- yaml > installed → suggest `pipx upgrade pactkit`
+- yaml < installed → suggest `pactkit update`
+- equal → no warning (existing behavior)

pactkit-2.10.2/docs/specs/STORY-slim-098.md

@@ -0,0 +1,143 @@
+# STORY-slim-098: PDCA Nudge Protocol — AI主动推荐PDCA命令
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-098 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.11.0 |
+
+## Background
+
+当用户与 AI 进行自由对话（非 PDCA 命令上下文）时，AI 经常分析出 bug、架构改进点、新功能需求等结论，但不会主动提示用户使用对应的 PDCA 命令来跟踪和实现这些结论。用户聊着聊着就忘了 PDCA 的存在，导致有价值的分析结果停留在对话中，没有进入 Spec → Act → Check → Done 的可追溯流程。
+
+**现状**:
+- `context.md` 的 `Next Recommended Action` 仅在用户主动查看时可见（被动）
+- Routing Table (`04-routing-table.md`) 只描述"When NOT to use"，没有正向触发逻辑
+- Core Protocol 仅在 Session Context 中建议 `/project-init`，对话中无 nudge 机制
+
+**目标**: 新增 `11-pdca-nudge.md` 规则文件，定义 AI 在自由对话中检测到可行动结论时主动推荐 PDCA 命令的协议。
+
+## Requirements
+
+### R0: Core Protocol 锚定 (MUST)
+
+在 `01-core-protocol.md` 中新增 `## PDCA Nudge` 小节（紧随 `## Session Context` 之后），声明原则：
+
+```markdown
+## PDCA Nudge
+When AI analysis in free conversation (outside PDCA command context) yields actionable conclusions — bugs, architecture improvements, new feature needs — SHOULD recommend the appropriate PDCA command at the end of the reply. See `11-pdca-nudge.md` for trigger matrix and suppression rules.
+```
+
+**Why**: Core Protocol 是 AI 行为的"宪法"，是 system prompt 中最早被阅读的锚点。仅放 rules/ 会被 12+ 个规则平铺稀释；在 Core Protocol 中声明原则确保 nudge 被视为核心行为而非可选建议。
+
+### R1: PDCA Nudge 触发矩阵 (MUST)
+
+AI 在自由对话中（非 PDCA 命令执行上下文）检测到以下信号时，MUST 在回复末尾附加 PDCA 推荐提示：
+
+| 信号类型 | 推荐命令 | 判断条件 |
+|----------|----------|----------|
+| 发现 bug / 错误行为 | `/project-hotfix` | 单文件修复，无设计决策 |
+| 发现 bug + 涉及设计变更 | `/project-plan` | 多文件或需求不明确 |
+| 识别出架构改进 | `/project-plan` | 涉及 2+ 文件修改 |
+| 识别出新功能需求 | `/project-plan` | 单功能 |
+| 识别出新产品/多功能需求 | `/project-design` | 3+ 个独立 story 的绿地项目 |
+| 已有 Spec 的待实现需求 | `/project-act STORY-XXX` | Board 上有对应 story |
+| 3+ 个独立改进项 | `/project-sprint` | 多个 story 可并行 |
+| 代码质量问题（可快速修复） | `/project-hotfix` | 不涉及行为变更 |
+
+### R2: Nudge 格式 (MUST)
+
+推荐提示 MUST 使用以下固定格式，置于回复末尾（分析内容之后）：
+
+```
+💡 这个分析结果可以通过 `{command}` 来跟踪实现：
+> {一句话说明为什么推荐这个命令}
+```
+
+### R3: 抑制条件 (MUST)
+
+以下场景 MUST NOT 触发 nudge：
+- 当前已在 PDCA 命令执行上下文中（Plan/Act/Check/Done/Sprint 等）
+- 用户明确表示只想聊天、不想走流程
+- 分析结论是对现有实现的确认（没有发现问题）
+- 用户在同一对话中已经收到过相同命令的 nudge（去重）
+
+### R4: 非阻塞 (SHOULD)
+
+Nudge SHOULD 是非阻塞的建议，不改变 AI 当前回复的内容结构。AI 完整回答用户问题后，在末尾附加 nudge。用户可以忽略 nudge 继续对话。
+
+## Acceptance Criteria
+
+### AC1: Bug 分析触发 hotfix 推荐 (R1, R2)
+
+- **Given** 用户在自由对话中请求分析某段代码
+- **When** AI 发现一个单文件 bug（如逻辑错误、边界条件缺失）
+- **Then** AI 回复完整分析后，末尾附加 `/project-hotfix` nudge
+
+### AC2: 架构建议触发 plan 推荐 (R1, R2)
+
+- **Given** 用户在自由对话中讨论代码结构
+- **When** AI 识别出涉及 2+ 文件的架构改进建议
+- **Then** AI 回复完整分析后，末尾附加 `/project-plan` nudge
+
+### AC3: PDCA 上下文内不触发 (R3)
+
+- **Given** 用户正在执行 `/project-act STORY-XXX`
+- **When** AI 在实现过程中发现额外的改进点
+- **Then** AI 不附加 nudge（当前已在 PDCA 上下文中）
+
+### AC4: 去重抑制 (R3)
+
+- **Given** AI 在同一对话中已推荐过 `/project-plan`
+- **When** AI 再次发现可以走 `/project-plan` 的结论
+- **Then** AI 不重复推荐相同命令
+
+### AC5: 非阻塞体验 (R4)
+
+- **Given** 用户提问 "这段代码有什么问题？"
+- **When** AI 分析完成并附加 nudge
+- **Then** nudge 在回复末尾，不打断分析内容的完整性；用户可直接继续下一个问题而无需回应 nudge
+
+### AC6: 双层锚定部署验证 (R0)
+
+- **Given** 运行 `pactkit deploy`
+- **When** 检查部署产物 `~/.claude/rules/01-core-protocol.md`
+- **Then** 文件包含 `## PDCA Nudge` 小节，且内容引用 `11-pdca-nudge.md`
+
+## Target Call Chain
+
+无代码调用链。本 Story 变更的是 prompt 规则文件（`~/.claude/rules/11-pdca-nudge.md`），属于 PactKit 部署产物。
+- 规则文件通过 `pactkit deploy` 部署到 `~/.claude/rules/` 目录
+- 规则文件被 Claude Code 在 session 启动时自动加载
+- 规则内容直接影响 AI 行为，无代码执行路径
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/templates/rules/01-core-protocol.md` | 在 `## Session Context` 之后新增 `## PDCA Nudge` 小节（3-4 行原则声明 + 指向 11-pdca-nudge.md） | None | Low |
+| 2 | `src/pactkit/templates/rules/11-pdca-nudge.md` | 新建规则模板，定义完整触发矩阵、格式模板、抑制条件 | None | Low |
+| 3 | `src/pactkit/config.py` | 在 `VALID_RULES` 列表中添加 `11-pdca-nudge` | Step 2 | Low |
+| 4 | `tests/unit/test_deploy_rules.py` | 添加测试：验证新规则被 deploy 包含 | Step 2-3 | Low |
+| 5 | `pactkit deploy` (验证) | 运行 deploy，确认 01-core-protocol.md 含 PDCA Nudge 节 + 11-pdca-nudge.md 出现在 `~/.claude/rules/` | Step 1-4 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | 变更仅为 prompt 规则文本，不涉及可执行代码逻辑 |
+| SEC-2 | N/A | 无用户输入处理 |
+| SEC-3 | N/A | 无数据库操作 |
+| SEC-4 | N/A | 无前端文件 |
+| SEC-5 | N/A | 无认证逻辑 |
+| SEC-6 | N/A | 无 API/路由 |
+| SEC-7 | N/A | 无错误处理变更（config.py 仅增加列表项） |
+| SEC-8 | N/A | 无依赖变更 |
+
+## Out of Scope
+
+- 不修改任何 PDCA 命令的 playbook（Plan/Act/Check/Done 等）
+- 不修改 Routing Table (`04-routing-table.md`)  — nudge 是补充，不改变现有路由逻辑
+- 不实现自动执行 PDCA 命令 — nudge 仅推荐，由用户决定是否执行
+- 不修改 `context.md` 的 `Next Recommended Action` 机制 — 两者互补（context.md 是 session 级，nudge 是对话级）

pactkit-2.10.2/docs/specs/STORY-slim-099.md

@@ -0,0 +1,87 @@
+# STORY-slim-099: Add Act Phase reference to Shared Protocols Context.md section
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-099 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.10.2 |
+
+## Background
+
+The Shared Protocols rule `07-shared-protocols.md` defines the Context.md Canonical Format and lists which PDCA phases reference it: `Init Phase 6, Plan Phase 3, Done Phase 4.5`. However, `/project-act` Phase 4 also updates context.md via `pactkit context --continuation` (source template in `commands.py:202`), but this reference is missing from the Shared Protocols listing.
+
+Additionally, the deployed plugin version (`pactkit-plugin/commands/project-act.md`) is missing Act Phase 4 step 3 (`pactkit context --continuation`), which exists in the source template. This causes context.md to not reflect Act progress when a session is interrupted before `/project-done`.
+
+**Impact**: When a user runs `/project-plan` → `/project-act` and exits without running `/project-done`, context.md remains frozen at the Plan snapshot. New sessions cold-start with stale state.
+
+## Requirements
+
+### R1: Shared Protocols Reference Update (MUST)
+
+The `Context.md Canonical Format` section in `07-shared-protocols.md` MUST include `Act Phase 4` in its "Referenced by" line, alongside the existing `Init Phase 6, Plan Phase 3, Done Phase 4.5`.
+
+### R2: Deployed Plugin Sync (MUST)
+
+The deployed `pactkit-plugin/commands/project-act.md` MUST include Act Phase 4 step 3 (`pactkit context --continuation`) matching the source template in `commands.py`. This is achieved by running `pactkit update` (redeploy).
+
+## Acceptance Criteria
+
+### AC1: Shared Protocols includes Act Phase 4 (R1)
+
+- **Given** the file `~/.claude/rules/07-shared-protocols.md` exists
+- **When** reading the `Context.md Canonical Format` section's "Referenced by" line
+- **Then** it contains `Act Phase 4` alongside `Init Phase 6, Plan Phase 3, Done Phase 4.5`
+
+### AC2: Deployed Act playbook includes context update step (R2)
+
+- **Given** `pactkit update` has been run after this change
+- **When** reading `pactkit-plugin/commands/project-act.md` Phase 4
+- **Then** step 3 contains `pactkit context --continuation --last-command "/project-act {STORY_ID}" --phase "Phase 4: complete"`
+
+### AC3: Source template consistency (R2)
+
+- **Given** the source template in `src/pactkit/prompts/commands.py`
+- **When** comparing Act Phase 4 steps between source and deployed
+- **Then** the deployed version matches the source template (no drift)
+
+## Target Call Chain
+
+```
+User runs /project-act STORY-XXX
+  → Act Phase 4 (Sync & Document)
+    → pactkit context --continuation --last-command "/project-act STORY-XXX" --phase "Phase 4: complete"
+      → context_gen.generate_context(continuation_args={...})
+        → writes docs/product/context.md (full regeneration + Agent Continuation section)
+```
+
+Source template: `src/pactkit/prompts/commands.py:199-202`
+Shared Protocols: `~/.claude/rules/07-shared-protocols.md:14` (referenced by list)
+Deployed plugin: `pactkit-plugin/commands/project-act.md:68-70`
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/rules.py` | Add `Act Phase 4` to Context.md Canonical Format "Referenced by" line | None | Low |
+| 2 | Run `pactkit update` | Redeploy to sync `pactkit-plugin/commands/project-act.md` | Step 1 | Low |
+| 3 | Verify deployed file | Confirm Act Phase 4 step 3 present in deployed playbook | Step 2 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | docs/prompt-only change, no user input handling |
+| SEC-2 | N/A | docs/prompt-only change, no input validation |
+| SEC-3 | N/A | no database interaction |
+| SEC-4 | N/A | no frontend files |
+| SEC-5 | N/A | no auth/session changes |
+| SEC-6 | N/A | no API endpoints |
+| SEC-7 | N/A | no error handling changes |
+| SEC-8 | N/A | no dependency changes |
+
+## Out of Scope
+
+- Changing the `pactkit context` CLI behavior or `context_gen.py` logic
+- Adding new context.md sections or changing the canonical format
+- Modifying other PDCA commands' context update behavior

{pactkit-2.10.1 → pactkit-2.10.2}/pyproject.toml

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

{pactkit-2.10.1 → pactkit-2.10.2}/src/pactkit/__init__.py

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

{pactkit-2.10.1 → pactkit-2.10.2}/src/pactkit/cli.py

@@ -407,7 +407,6 @@ def main():
             version_warn = check_version_mismatch(project_root)
             if version_warn:
                 print(f"  ⚠️  {version_warn}")
-                print("     Run `pactkit update` to sync")
         else:
             for m in missing:
                 print(f"  ✗ {m}")

{pactkit-2.10.1 → pactkit-2.10.2}/src/pactkit/config.py

@@ -87,6 +87,7 @@ VALID_RULES = frozenset(
         "07-shared-protocols",
         "08-architecture-principles",
         "09-sectional-write",
+        "11-pdca-nudge",
     }
 )
 

{pactkit-2.10.1 → pactkit-2.10.2}/src/pactkit/guards.py

@@ -68,6 +68,14 @@ def check_config_completeness(project_root: Path) -> list[str]:
     return warnings
 
 
+def _parse_version(v: str) -> tuple[int, ...]:
+    """Parse dotted version string into comparable tuple."""
+    try:
+        return tuple(int(x) for x in v.split("."))
+    except (ValueError, AttributeError):
+        return ()
+
+
 def check_version_mismatch(project_root: Path) -> str | None:
     """Check if pactkit.yaml version differs from installed __version__.
 
@@ -80,6 +88,21 @@ def check_version_mismatch(project_root: Path) -> str | None:
 
     cfg = load_config(yaml_path)
     yaml_version = cfg.get("version", "")
-    if yaml_version and yaml_version != __version__:
+    if not yaml_version or yaml_version == __version__:
+        return None
+
+    yaml_v = _parse_version(yaml_version)
+    installed_v = _parse_version(__version__)
+
+    if not yaml_v or not installed_v:
         return f"Version mismatch: pactkit.yaml {yaml_version} vs installed {__version__}"
-    return None
+
+    if yaml_v > installed_v:
+        return (
+            f"Version mismatch: pactkit.yaml {yaml_version} > installed {__version__}\n"
+            f"         Run `pipx upgrade pactkit` to update the CLI"
+        )
+    return (
+        f"Version mismatch: pactkit.yaml {yaml_version} < installed {__version__}\n"
+        f"         Run `pactkit update` to sync"
+    )

{pactkit-2.10.1 → pactkit-2.10.2}/src/pactkit/prompts/rules.py

@@ -10,6 +10,9 @@ Then read `docs/product/context.md` to understand project state before taking ac
 If the file is missing, suggest `/project-init` to bootstrap the project.
 If "Last updated" date is before today, suggest running `$daily-retro`.
 
+## PDCA Nudge
+When AI analysis in free conversation (outside PDCA command context) yields actionable conclusions — bugs, architecture improvements, new feature needs — SHOULD recommend the appropriate PDCA command at the end of the reply. See `11-pdca-nudge.md` for trigger matrix and suppression rules.
+
 ## Visual First
 Before modifying code:
 - Run `visualize` to view file dependency graph
@@ -274,7 +277,7 @@ If source files changed (per `LANG_PROFILES[stack].source_dirs`) OR `code_graph.
 Map changed source files to test files via `LANG_PROFILES[stack].test_map_pattern`. If no mapping can be determined, fall back to the full test suite.
 
 ## Context.md Canonical Format
-> Referenced by: Init Phase 6, Plan Phase 3, Done Phase 4.5
+> Referenced by: Init Phase 6, Plan Phase 3, Act Phase 4, Done Phase 4.5
 
 Write `docs/product/context.md` using this format:
 ```markdown
@@ -402,6 +405,50 @@ Compose entire file in head → one Write call at the end
 ```
 Write skeleton → Edit block 1 → checkpoint → Edit block 2 → checkpoint → ...
 ```
+""",
+    "nudge": """# PDCA Nudge Protocol
+
+> **Signal Level**: L3 Recommended (SHOULD) — non-blocking suggestion.
+
+## When to Nudge
+
+When AI analysis in **free conversation** (outside any PDCA command context) produces actionable conclusions, SHOULD append a PDCA command recommendation at the end of the reply.
+
+## Trigger Matrix
+
+| Signal | Command | Condition |
+|--------|---------|-----------|
+| Bug / error found (single file) | `/project-hotfix` | Single-file fix, no design decision needed |
+| Bug + design change needed | `/project-plan` | Multi-file or unclear requirements |
+| Architecture improvement identified | `/project-plan` | Involves 2+ file changes |
+| New feature need identified | `/project-plan` | Single feature |
+| New product / multi-feature need | `/project-design` | 3+ independent stories, greenfield |
+| Existing Spec ready to implement | `/project-act STORY-XXX` | Story is on the Board |
+| 3+ independent improvement items | `/project-sprint` | Multiple stories can run in parallel |
+| Code quality issue (quick fix) | `/project-hotfix` | No behavior change |
+
+## Nudge Format
+
+Place at the **end** of the reply, after all analysis content:
+
+```
+💡 This analysis can be tracked via `{command}`:
+> {one-sentence reason why this command fits}
+```
+
+When replying in Chinese, use:
+
+```
+💡 这个分析结果可以通过 `{command}` 来跟踪实现：
+> {一句话说明为什么推荐这个命令}
+```
+
+## Suppression Rules (MUST NOT nudge when)
+
+- **In PDCA context**: A PDCA command is already active (Plan/Act/Check/Done/Sprint/Hotfix/Design)
+- **User opted out**: User explicitly said they just want to chat, not follow a workflow
+- **No issue found**: Analysis confirms the current implementation is correct
+- **Dedup**: The same command was already nudged earlier in this conversation
 """,
 }
 
@@ -427,6 +474,7 @@ RULES_ONDEMAND_FILES = {
     "mcp": "06-mcp-integration.md",
     "shared": "07-shared-protocols.md",
     "architecture": "08-architecture-principles.md",
+    "nudge": "11-pdca-nudge.md",
 }
 
 # Full set of PactKit-MANAGED rules (used for deployment + CLAUDE_MD_TEMPLATE)
@@ -469,7 +517,7 @@ COMMAND_RULES_MAP = {
 }
 
 # Managed file prefixes (deployer will clean these, leave user files intact)
-RULES_MANAGED_PREFIXES = ["01-", "02-", "03-", "04-", "05-", "06-", "07-", "08-", "09-"]
+RULES_MANAGED_PREFIXES = ["01-", "02-", "03-", "04-", "05-", "06-", "07-", "08-", "09-", "11-"]
 
 # CLAUDE_MD_TEMPLATE: auto-generated from RULES_FILES (STORY-slim-007: DRY principle)
 # Classic mode uses @import syntax — all rules included (Claude Code @import is lazy-loaded natively)

{pactkit-2.10.1 → pactkit-2.10.2}/tests/unit/test_config.py

@@ -49,9 +49,9 @@ class TestGetDefaultConfig:
         assert len(cfg["skills"]) == 24
 
     def test_default_rules_count(self):
-        """9 rule modules (added 09-sectional-write)."""
+        """10 rule modules (added 11-pdca-nudge)."""
         cfg = _config().get_default_config()
-        assert len(cfg["rules"]) == 9
+        assert len(cfg["rules"]) == 10
 
     def test_default_stack_is_auto(self):
         cfg = _config().get_default_config()

{pactkit-2.10.1 → pactkit-2.10.2}/tests/unit/test_constitution_sharpening.py

@@ -113,8 +113,8 @@ class TestTokenReduction:
 
     # Baseline updated: 400 words (post-STORY-008 reduction + subagent section).
     # 30% headroom → max words. Increase baseline if adding valuable content.
-    # Raised from 400 to 600 for STORY-slim-086: Signal Strength Convention table added.
-    BASELINE_WORD_COUNT = 600
+    # Raised from 600 to 660 for STORY-slim-098: PDCA Nudge anchor section added.
+    BASELINE_WORD_COUNT = 660
 
     def test_core_protocol_within_limit(self):
         p = _prompts()

{pactkit-2.10.1 → pactkit-2.10.2}/tests/unit/test_prompt_structural_invariants.py

@@ -114,8 +114,8 @@ class TestPromptModuleCounts:
     """Verify expected counts of prompt modules."""
 
     def test_rule_count(self):
-        """9 rule modules (added 09-sectional-write)."""
-        assert len(prompts.RULES_MODULES) == 9
+        """10 rule modules (added 11-pdca-nudge)."""
+        assert len(prompts.RULES_MODULES) == 10
 
     def test_command_count(self):
         """STORY-051: Should have 11 command playbooks (added project-release, project-pr)."""

{pactkit-2.10.1 → pactkit-2.10.2}/tests/unit/test_selective_deploy.py

@@ -247,7 +247,7 @@ class TestDeploymentSummary:
         assert "24/24 Skills" in output
         assert "13 embedded" in output
         assert "11 commands" in output
-        assert "8/8 Rules" in output or "9/9 Rules" in output  # 9 rules after 09-sectional-write
+        assert "10/10 Rules" in output
 
     def test_summary_printed_partial(self, tmp_path, capsys):
         # +pactkit-audit, +pactkit-report = 24 total (13 embedded + 11 commands)

{pactkit-2.10.1 → pactkit-2.10.2}/tests/unit/test_story_slim011_command_rules.py

@@ -85,6 +85,9 @@ class TestAC8AllRulesMapped:
         # credential is special (not in RULES_FILES) — exclude from check
         mapped_keys.discard("credential")
 
+        # nudge is conversation-scoped (suppressed inside PDCA context) — not command-mapped
+        all_rule_keys.discard("nudge")
+
         unmapped = all_rule_keys - mapped_keys
         assert not unmapped, f"Rules not mapped to any command: {unmapped}"
 

{pactkit-2.10.1 → pactkit-2.10.2}/tests/unit/test_story_slim021.py

@@ -25,8 +25,8 @@ class TestR6RuleExists:
     def test_valid_rules_contains_sectional_write(self):
         assert "09-sectional-write" in VALID_RULES
 
-    def test_valid_rules_count_is_9(self):
-        assert len(VALID_RULES) == 9
+    def test_valid_rules_count_is_10(self):
+        assert len(VALID_RULES) == 10
 
     def test_rules_modules_contains_sectional(self):
         assert "sectional" in RULES_MODULES