pactkit 2.15.0__tar.gz → 2.15.2__tar.gz

pactkit-2.15.2/.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

{pactkit-2.15.0 → pactkit-2.15.2}/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.15.2] - 2026-07-02
+
+### Changed
+- **Codegraph commands decoupled from prompts** (STORY-slim-132) — Replaced hardcoded codegraph CLI command lists with runtime `codegraph --help` discovery. PactKit no longer needs updates when codegraph changes its command signatures.
+
+### Fixed
+- **Act Phase 0.6 board move command** (HOTFIX-slim-132) — Added explicit `board.py move_story` command template to prevent AI from guessing wrong subcommand syntax.
+- **Prompt deployer** (HOTFIX-slim-131) — Insert @ references after YAML frontmatter so model: field is parsed correctly.
+- **Skill frontmatter** (HOTFIX-slim-130) — Move @ references below YAML frontmatter in project-* skills.
+
+### Refactored
+- **Prompt rules** — Moved large rules from @inject to on-demand Read to reduce initial context size.
+
+## [2.15.1] - 2026-06-10
+
+### Added
+- **Engineering Concerns guide system** (STORY-slim-128) — On-demand NFR guide loading via trigger index. Plan Phase 2 scans requirement keywords and includes NFR decisions in Spec; Act Phase 1.5 loads matched guides (1-3 max). Initial 13 concerns: concurrency, async, configuration, observability, module-design, database, caching, api-integration, event-driven, resilience, memory-management, code-review-first, component-reuse.
+- **6 additional engineering guides** (STORY-slim-129) — error-recovery (retry/backoff/idempotency), data-consistency (transactions/saga/optimistic lock), backwards-compatibility (API versioning/non-breaking migration), performance-antipatterns (N+1/unbounded queries/indexing), graceful-shutdown (SIGTERM/drain/cleanup order), testing-strategy (boundary/mock vs real/isolation). Total: 19 guides.
+
+### Fixed
+- **Spec linter** — Accept heading format for Security Scope `SEC-*` entries.
+- **CI** — Remove obsolete `.opencode/pactkit.yaml` test.
+
 ## [2.15.0] - 2026-06-04
 
 ### Added

{pactkit-2.15.0 → pactkit-2.15.2}/PKG-INFO

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

@@ -63,3 +63,6 @@
 | 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 |
+| 2026-03-27 | When migrating commands to skills (subdir/SKILL.md format), all path assertions in pre-existing tests must be updated in the same commit — 17 tests broke because they asserted flat commands/*.md paths | deployer.py:_deploy_commands |

{pactkit-2.15.0 → pactkit-2.15.2}/docs/architecture/governance/lessons.md

@@ -2,9 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 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 |
-| 2026-03-27 | When migrating commands to skills (subdir/SKILL.md format), all path assertions in pre-existing tests must be updated in the same commit — 17 tests broke because they asserted flat commands/*.md paths | deployer.py:_deploy_commands |
 | 2026-03-30 | Frontend API path convention bugs are structurally preventable: ApiCallParser+api_convention_summary in trace phase surfaces prefix/wrapper conventions before implementation, eliminating a class of copy-paste path errors | visualize.py:ApiCallParser |
 | 2026-03-31 | Rendering-only changes to visualize.py can be isolated by extracting a shared render helper (_render_nested_call_graph) that both forward and reverse BFS call — keeps AST parsing untouched | visualize.py:_render_nested_call_graph |
 | 2026-03-31 | dict.update() on call_edges causes last-wins overwrite when scanning same-name functions across files; use extend-merge pattern instead | visualize.py:_build_call_graph |
@@ -53,3 +50,6 @@
 | 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 |
 | 2026-06-01 | codegraph sync must be enforced by code (pactkit visualize/sync), not by prompt instructions — prompt-only enforcement is unreliable for deterministic operations | lazy_visualize.py:codegraph_sync |
 | 2026-06-01 | Managed-block pattern (start/end markers + regex replace) is the canonical way to update mixed-ownership files — same pattern for CLAUDE.md and CLAUDE.local.md | deployer.py:_upsert_claude_md_managed_block |
+| 2026-06-10 | Engineering guides are additive: new GUIDES_FILES entries auto-deploy via _deploy_guides() without deployer changes. Test impact limited to count assertions in test_story_slim128. | src/pactkit/prompts/guides.py:GUIDES_FILES |
+| 2026-06-29 | Large @inject rules (architecture 11KB, solution 8.4KB, engineering 4.3KB) removed from COMMAND_RULES_MAP — loaded on-demand via Read in playbooks. Saves ~12,500 tokens/PDCA session. | src/pactkit/prompts/rules.py:COMMAND_RULES_MAP |
+| 2026-07-02 | Hardcoding external tool CLI commands in SKILL_VISUALIZE_MD and deployer.py creates upgrade coupling — replaced with codegraph --help runtime discovery in _build_claude_md_managed_content() | src/pactkit/generators/deployer.py:_build_claude_md_managed_content |

{pactkit-2.15.0 → pactkit-2.15.2}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4009+ tests must pass before any commit to `main`.
+1. All 4032+ 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.15.2/docs/product/archive/archive_202606.md

@@ -0,0 +1,37 @@
+
+### [STORY-slim-126] codegraph sync code enforcement
+> Spec: docs/specs/STORY-slim-126.md
+
+- [x] Add codegraph_sync() function
+- [x] Integrate into visualize path
+- [x] Add pactkit sync subcommand
+- [x] Remove prompt instructions
+- [x] Unit tests
+
+### [STORY-slim-127] project CLAUDE.md managed-block update
+> Spec: docs/specs/STORY-slim-127.md
+
+- [x] Add marker constants
+- [x] Extract managed content builder
+- [x] Rewrite _generate_project_claude_md with upsert
+- [x] Unit tests
+
+### [STORY-slim-129] Engineering Concerns Guide Expansion — 6 Additional NFR Guides
+> Spec: docs/specs/STORY-slim-129.md
+
+- [x] Add 6 guide files to guides.py
+- [x] Update trigger index in rules.py
+- [x] Update test expectations 13→19
+- [x] Verify deployment
+
+### [STORY-slim-128] Engineering Concerns: Guide-based NFR enforcement
+> Spec: docs/specs/STORY-slim-128.md
+
+- [x] Create guides.py with 13 guide contents
+- [x] Add trigger index to rules.py
+- [x] Extend deployer for guides/ subdirectory
+- [x] Enhance plan Phase 2 with NFR assessment
+- [x] Enhance act Phase 1.5 with guide loading
+- [x] Config registration + COMMAND_RULES_MAP
+- [x] Multi-format parity
+- [x] Unit tests

pactkit-2.15.2/docs/product/archive/archive_202607.md

@@ -0,0 +1,13 @@
+
+### [STORY-slim-132] Decouple codegraph commands from hardcoded prompt
+> Spec: docs/specs/STORY-slim-132.md
+
+- [x] Replace skills.py codegraph block with help fallback
+- [x] Replace deployer.py codegraph section
+- [x] Update global CLAUDE.md
+- [x] Remove MCP tool name list
+
+### [HOTFIX-slim-130] Fix skill frontmatter parsing
+> Spec: docs/specs/HOTFIX-slim-130.md
+
+- [x] Move @ references below YAML frontmatter block in all project-* skills

pactkit-2.15.2/docs/product/context.md

@@ -0,0 +1,29 @@
+# Project Context (Auto-generated)
+> Last updated: 2026-07-02T11:00:51+08:00 by pactkit context
+
+## Sprint Status
+Backlog: 4 | In Progress: 0 | Done: 0 stories
+
+## Current Stories
+None
+
+## Recent Completions
+None
+
+## Active Branches
++ claude/naughty-euclid-e6a787
+  develop
+* main
+
+## Key Decisions
+- codegraph sync must be enforced by code (pactkit visualize/sync), not by prompt instructions — prompt-only enforcement is unreliable for deterministic operations
+- Managed-block pattern (start/end markers + regex replace) is the canonical way to update mixed-ownership files — same pattern for CLAUDE.md and CLAUDE.local.md
+- Engineering guides are additive: new GUIDES_FILES entries auto-deploy via _deploy_guides() without deployer changes. Test impact limited to count assertions in test_story_slim128.
+- Large @inject rules (architecture 11KB, solution 8.4KB, engineering 4.3KB) removed from COMMAND_RULES_MAP — loaded on-demand via Read in playbooks. Saves ~12,500 tokens/PDCA session.
+- Hardcoding external tool CLI commands in SKILL_VISUALIZE_MD and deployer.py creates upgrade coupling — replaced with codegraph --help runtime discovery in _build_claude_md_managed_content()
+
+## Next Recommended Action
+`/project-plan`
+
+## Agent Continuation
+No active work session.

{pactkit-2.15.0 → pactkit-2.15.2}/docs/product/sprint_board.md

@@ -26,6 +26,17 @@
 - [ ] Fix project-done
 - [ ] Fix project-hotfix
 
+### [HOTFIX-slim-131] Fix deployer @ refs before frontmatter
+> Spec: docs/specs/HOTFIX-slim-131.md
+
+- [ ] Fix _deploy_commands prepend order
+
+
+### [HOTFIX-slim-132] Add explicit board.py move_story command to project-act
+> Spec: docs/specs/HOTFIX-slim-132.md
+
+- [ ] Add move_story command template to Phase 0.6
+
 ## 🔄 In Progress
 
 ## ✅ Done

pactkit-2.15.2/docs/specs/HOTFIX-slim-130.md

@@ -0,0 +1,104 @@
+# HOTFIX-slim-130: Fix skill frontmatter parsing — move @ references below YAML block
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-130 |
+| Status | Open |
+| Priority | P1 |
+| Release | 2.15.2 |
+
+## Background
+
+All 11 `project-*` skills have `@` reference lines (file includes) placed **before** the YAML frontmatter block (`---`). Claude Code's skill parser requires frontmatter to start on line 1 of the file. When `@` lines precede `---`, the entire frontmatter is treated as plain text — `model`, `allowed-tools`, and `description` fields are silently ignored.
+
+**Impact**: Every `/project-*` command runs on the session's default model (opus) regardless of the `model:` directive in frontmatter. This wastes tokens (opus for tasks that should use sonnet) and breaks the model routing strategy defined in `pactkit.yaml`.
+
+**Root cause**: Skill files were authored with `@` includes at the top for readability, unaware that this breaks YAML frontmatter detection.
+
+## Affected Files
+
+All skills matching `~/.claude/skills/project-*/SKILL.md` (11 files):
+
+1. `project-act/SKILL.md`
+2. `project-check/SKILL.md`
+3. `project-clarify/SKILL.md`
+4. `project-design/SKILL.md`
+5. `project-done/SKILL.md`
+6. `project-hotfix/SKILL.md`
+7. `project-init/SKILL.md`
+8. `project-plan/SKILL.md`
+9. `project-pr/SKILL.md`
+10. `project-release/SKILL.md`
+11. `project-sprint/SKILL.md`
+
+## Requirements
+
+### R1: Frontmatter MUST be first in file (MUST)
+
+Every `SKILL.md` file MUST start with `---` on line 1. No content (including `@` references) may precede the frontmatter block.
+
+### R2: @ references MUST move below frontmatter (MUST)
+
+All `@` include lines MUST be placed immediately after the closing `---` of the frontmatter block, before the markdown body. Preserve the original set of references — do not add or remove any.
+
+### R3: Existing frontmatter fields preserved (MUST)
+
+All existing frontmatter fields (`description`, `allowed-tools`, `model`) MUST remain unchanged in value. Only their position in the file changes.
+
+## Acceptance Criteria
+
+### AC1: Frontmatter starts on line 1 (R1)
+
+- **Given** any file in `~/.claude/skills/project-*/SKILL.md`
+- **When** I read line 1
+- **Then** it MUST be exactly `---`
+
+### AC2: Model field is parseable (R1, R3)
+
+- **Given** `project-act/SKILL.md` with `model: sonnet` in frontmatter
+- **When** Claude Code loads the skill
+- **Then** the skill executes on sonnet, not the session default
+
+### AC3: @ references still present (R2)
+
+- **Given** any affected skill file
+- **When** I count `@` reference lines
+- **Then** the count matches the original (no references lost or added)
+
+### AC4: No content change (R3)
+
+- **Given** the markdown body of any affected skill
+- **When** compared to pre-fix content (excluding line position)
+- **Then** all instructions, phases, and protocols are identical
+
+## Fix Pattern
+
+Before (broken):
+```markdown
+@~/.claude/skills/_rules/04-architecture-principles.md
+@~/.claude/rules/09-credential-safety.md
+
+---
+description: "Implement code per Spec, strict TDD"
+model: sonnet
+---
+
+# Command: Act
+```
+
+After (correct):
+```markdown
+---
+description: "Implement code per Spec, strict TDD"
+model: sonnet
+---
+
+@~/.claude/skills/_rules/04-architecture-principles.md
+@~/.claude/rules/09-credential-safety.md
+
+# Command: Act
+```
+
+## Security Scope
+
+SEC-1: No credential or secret handling involved. Pure file reformatting.

pactkit-2.15.2/docs/specs/HOTFIX-slim-131.md

@@ -0,0 +1,21 @@
+# HOTFIX-slim-131: Fix deployer prepending @ references before YAML frontmatter
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-131 |
+| Status | In Progress |
+| Priority | P0 |
+| Release | 2.15.2 |
+
+## Background
+
+`_deploy_commands()` in deployer.py prepends `_build_command_rules_header()` output (@ reference lines) before the command content which includes YAML frontmatter. This pushes frontmatter away from line 1, causing Claude Code to not parse `model:`, `description:`, and `allowed-tools:` fields. The `model:` frontmatter (added in STORY-slim-125) never takes effect at runtime.
+
+## Fix
+
+Insert @ references after the closing `---` of frontmatter, not before the opening `---`.
+
+## Target
+
+- File: `src/pactkit/generators/deployer.py`
+- Function: `_deploy_commands()` (line ~1008)

pactkit-2.15.2/docs/specs/HOTFIX-slim-132.md

@@ -0,0 +1,23 @@
+# HOTFIX-slim-132: Add explicit board.py move_story command to project-act playbook
+
+| Field | Value |
+|-------|-------|
+| ID | HOTFIX-slim-132 |
+| Status | Done |
+| Priority | P2 |
+| Release | 2.16.0 |
+
+## Background
+
+AI consistently guesses wrong board.py subcommand syntax (tries `move_to_in_progress`, `"In Progress"`) because project-act Phase 0.6 only says "move it to In Progress" without giving the exact CLI invocation.
+
+## Fix
+
+In `project-act/SKILL.md` Phase 0.6 step 3, replace vague instruction with explicit command template:
+```
+python3 ~/.claude/skills/pactkit-board/scripts/board.py move_story "{STORY_ID}" "in_progress"
+```
+
+## Target
+
+`~/.claude/skills/project-act/SKILL.md:46`

pactkit-2.15.2/docs/specs/STORY-slim-128.md

@@ -0,0 +1,157 @@
+# STORY-slim-128: Engineering Concerns: Guide-based NFR enforcement
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-128 |
+| Status | Draft |
+| Priority | P1 |
+| Release | 2.16.0 |
+
+## Background
+
+LLM 编程时系统性缺失非功能性需求（NFR）考量：并发模型、超时策略、缓存一致性、内存管理等。
+现有 PactKit 规则体系中，`06-solution-design.md` 只覆盖"复用已有组件"，缺乏对其他 12 类工程关注点的引导。
+
+核心矛盾：如果把所有 NFR 规则放入常驻 prompt，context 膨胀导致注意力衰减；如果不放，LLM 就忽略它们。
+
+解决方案：**按需加载的指南系统** — 一个轻量触发索引（常驻，~40行）+ 13 个精炼指南文件（按需加载，每个 <50 行）。
+Plan 阶段：根据需求关键词强制回答 NFR 决策问题（写入 Spec）。
+Act 阶段：根据 Spec 中标注的 concerns，动态加载对应指南作为实现约束。
+
+### 调用链
+```
+rules.py (RULES_MODULES["engineering"]) → deployer._deploy_rules() → ~/.claude/skills/_rules/07-engineering-concerns.md
+rules.py (GUIDES_FILES) → deployer._deploy_guides() → ~/.claude/skills/_rules/guides/*.md
+commands.py (plan Phase 2 扩展) → deployed SKILL.md
+commands.py (act Phase 1.5 扩展) → deployed SKILL.md
+```
+
+## Requirements
+
+### R1: Trigger Index Rule (MUST)
+
+新增 `RULES_MODULES["engineering"]` 和 `RULES_ONDEMAND_FILES["engineering"]`，部署为 `07-engineering-concerns.md`。
+内容为触发索引表（~40行）：列出关键词→concern 映射，以及 concern→guide 文件的路由表。
+此文件通过 `@import` 被 plan/act 命令加载。
+
+### R2: Guides Deployment Mechanism (MUST)
+
+在 `deployer.py` 中新增 `_deploy_guides()` 函数，将 13 个精炼指南文件部署到 `~/.claude/skills/_rules/guides/` 目录。
+所有 format 均需支持：Claude Code（文件部署）、OpenCode（inline 或文件）、Codex（文件）、Copilot（文件）。
+指南文件源定义在新文件 `src/pactkit/prompts/guides.py` 中（避免 `rules.py` 过长）。
+
+### R3: Guides Content — 13 Engineering Guides (MUST)
+
+每个指南文件 < 50 行，格式统一：决策表 + MUST 清单 + NEVER 清单 + 代码模板。
+覆盖：concurrency、async-patterns、configuration、observability、module-design、database、caching、api-integration、event-driven、resilience、memory-management、code-review-first、component-reuse。
+
+### R4: Plan Command Enhancement (MUST)
+
+`project-plan` Phase 2 新增 "Engineering Concerns Assessment" 步骤：
+- 扫描需求关键词（定时/API/数据库/缓存/事件/并发等）
+- 匹配到的 concern → Spec 的 Technical Design 中 MUST 包含对应 NFR 决策
+- 未匹配 → 不强制（避免噪音）
+
+### R5: Act Command Enhancement (MUST)
+
+`project-act` 新增 Phase 1.5 "Engineering Concerns Loading"：
+- 读取 Spec 的 Technical Design → 识别标注的 engineering concerns
+- 加载对应的指南文件（`read` 指令）
+- MUST 只加载相关的 1-3 个，NEVER 全部加载
+
+### R6: Config Integration (SHOULD)
+
+在 `VALID_RULES` 中注册 `"07-engineering-concerns"`。
+在 `COMMAND_RULES_MAP` 中为 `project-plan` 和 `project-act` 添加 `"engineering"` key。
+支持通过 `pactkit.yaml` 的 `rules` 配置项禁用。
+
+### R7: Multi-format Parity (MUST)
+
+OpenCode、Codex、Copilot 格式均需部署 guides 内容：
+- OpenCode/Codex：作为独立文件部署到对应 rules 目录，或 inline 嵌入
+- Copilot：写入对应的 prompt 文件中（copilot 不支持动态文件引用，需 inline）
+- 各格式 plan/act playbook 均需包含 engineering concerns phase
+
+## Acceptance Criteria
+
+### AC1: Trigger Index Deployed (R1, R6)
+
+- **Given** PactKit 已安装，用户运行 `pactkit init`
+- **When** deployer 执行 classic format 部署
+- **Then** `~/.claude/skills/_rules/07-engineering-concerns.md` 文件存在，内容包含关键词→concern 映射表和 concern→guide 路由表
+
+### AC2: All 13 Guides Deployed (R2, R3)
+
+- **Given** 用户运行 `pactkit init` 或 `pactkit update`
+- **When** deployer 执行部署
+- **Then** `~/.claude/skills/_rules/guides/` 目录下存在 13 个 .md 文件，每个文件 < 50 行
+
+### AC3: Plan Phase Triggers NFR Questions (R4)
+
+- **Given** 一个包含 "从第三方 API 拉取数据存入数据库" 的 Story
+- **When** Plan Phase 2 执行 Engineering Concerns Assessment
+- **Then** Spec 的 Technical Design 中包含：并发模型决策、API 超时/重试策略、数据库连接管理策略
+
+### AC4: Act Phase Loads Relevant Guides Only (R5)
+
+- **Given** Spec 的 Technical Design 标注了 `concerns: [database, api-integration]`
+- **When** Act Phase 1.5 执行
+- **Then** 只加载 `guides/database.md` 和 `guides/api-integration.md`，不加载其他 11 个指南
+
+### AC5: OpenCode/Codex/Copilot Parity (R7)
+
+- **Given** 用户运行 `pactkit init --format opencode`
+- **When** deployer 执行 OpenCode 格式部署
+- **Then** 对应目录下存在 engineering concerns trigger index + guides 内容（inline 或文件形式）
+
+## Target Call Chain
+
+```
+# 部署链
+pactkit init/update
+  → deployer._deploy_classic() (deployer.py:302)
+    → _deploy_rules(claude_root, enabled_rules) (deployer.py:584)
+      → atomic_write(ondemand_dir / "07-engineering-concerns.md") — R1
+    → _deploy_guides(claude_root) (NEW) (deployer.py:NEW)
+      → atomic_write(guides_dir / "*.md") x13 — R2
+    → _deploy_commands(skills_dir, ...) (deployer.py:917)
+      → _build_command_rules_header("project-plan") — includes "engineering" — R4
+      → _build_command_rules_header("project-act") — includes "engineering" — R5
+
+# 指南内容源
+src/pactkit/prompts/guides.py (NEW)
+  → GUIDES_FILES: dict[str, str]  — filename → content
+  → Referenced by deployer._deploy_guides()
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/guides.py` | 新建：定义 GUIDES_FILES dict（13 个指南内容） | None | Low |
+| 2 | `src/pactkit/prompts/rules.py` | 新增 RULES_MODULES["engineering"] 触发索引内容 + RULES_ONDEMAND_FILES 注册 | Step 1 | Low |
+| 3 | `src/pactkit/config.py` | VALID_RULES 新增 "07-engineering-concerns" | Step 2 | Low |
+| 4 | `src/pactkit/generators/deployer.py` | 新增 _deploy_guides() + 在 _deploy_classic/opencode/codex/copilot 中调用 | Steps 1-3 | Medium |
+| 5 | `src/pactkit/prompts/commands.py` | plan Phase 2 新增 Engineering Concerns Assessment 段落 | Step 2 | Low |
+| 6 | `src/pactkit/prompts/commands.py` | act 新增 Phase 1.5 Engineering Concerns Loading 段落 | Step 2 | Low |
+| 7 | `src/pactkit/prompts/rules.py` | COMMAND_RULES_MAP 为 plan/act 添加 "engineering" | Step 3 | Low |
+| 8 | `tests/unit/` | 测试：deployer 部署 guides 目录、plan/act 包含新 phase | All | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | No secrets involved — only prompt/doc content |
+| SEC-2 | N/A | No user input processing |
+| SEC-3 | N/A | No database queries |
+| SEC-4 | N/A | No rendering |
+| SEC-5 | N/A | No auth |
+| SEC-6 | N/A | No endpoints |
+| SEC-7 | N/A | No error messages |
+| SEC-8 | N/A | No new dependencies |
+
+## Out of Scope
+
+- CI/lint 自动化检测（semgrep/ruff 自定义规则）— 后续 Story
+- 指南文件的热加载/动态选择 AI 判断 — 本 Story 用关键词匹配，不用 LLM 判断
+- Check 阶段的完整 13 项 checklist 验证 — 可选后续 Story

pactkit-2.15.2/docs/specs/STORY-slim-129.md

@@ -0,0 +1,134 @@
+# STORY-slim-129: Engineering Concerns Guide Expansion — 6 Additional NFR Guides
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-129 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.15.1 |
+
+## Background
+
+STORY-slim-128 established the Engineering Concerns guide system with 13 on-demand guides covering concurrency, async, configuration, observability, module design, database, caching, API integration, event-driven, resilience, memory management, code-review-first, and component-reuse.
+
+Analysis of common LLM-generated code weaknesses identified 6 additional high-frequency gaps:
+1. **Error Recovery & Retry** — LLM try/catch blocks almost always just `log + return None`, missing retry with backoff, idempotency, partial failure handling
+2. **Data Consistency** — multi-table/multi-service writes without transaction strategy, no idempotency key, no compensation
+3. **Backwards Compatibility** — LLM defaults to breaking changes for API/schema modifications
+4. **Performance Anti-patterns** — N+1 queries, unbounded list APIs, missing indices, hot-path serialization
+5. **Graceful Shutdown** — no SIGTERM handler, no in-flight request drain, no resource cleanup ordering
+6. **Testing Strategy** — LLM writes tests without considering boundary testing, mock vs real, or test isolation
+
+## Requirements
+
+### R1: Six New Guide Files (MUST)
+
+Add 6 new guide files to `GUIDES_FILES` in `src/pactkit/prompts/guides.py`:
+- `error-recovery.md` — retry strategies, backoff, idempotency, partial failure
+- `data-consistency.md` — distributed transactions, idempotency keys, optimistic/pessimistic locking, Saga
+- `backwards-compatibility.md` — API versioning, non-breaking DB migrations, protocol evolution
+- `performance-antipatterns.md` — N+1 queries, unbounded queries, missing indexes, hot-path costs
+- `graceful-shutdown.md` — SIGTERM handling, request drain, resource cleanup order
+- `testing-strategy.md` — boundary testing, mock vs real, test isolation, deterministic tests
+
+Each guide MUST follow existing format: Decision Table + MUST + NEVER + Template, ≤ 50 lines.
+
+### R2: Trigger Index Update (MUST)
+
+Add 6 new rows to the keyword→concern table in `RULES_MODULES["engineering"]` in `src/pactkit/prompts/rules.py`:
+- error-recovery: retry/重试/backoff/幂等/idempoten/partial failure
+- data-consistency: 一致性/consistency/saga/补偿/idempotency key/分布式事务
+- backwards-compatibility: 兼容/backward/breaking change/deprecat/migration/版本
+- performance-antipatterns: N+1/unbounded/分页/pagina/index/索引/热路径/hot path
+- graceful-shutdown: shutdown/优雅关闭/SIGTERM/drain/信号处理
+- testing-strategy: 测试策略/test strategy/mock/stub/boundary/隔离/isolation
+
+### R3: Guide Loading Table Update (MUST)
+
+Add 6 new rows to the Act Phase Guide Loading Table in the same `engineering` module content, mapping concern→guide file path.
+
+### R4: Pre-existing Test Update (MUST)
+
+Update hardcoded counts in tests:
+- `test_story_slim128_engineering_concerns.py`: 13→19 guide count
+- `test_story_slim026.py`: plan prompt char baseline if exceeded
+- `test_story063_prompt_slimming.py`: BASELINE_TOTAL_CHARS if exceeded
+- Trigger index "NEVER load all 13" → "NEVER load all 19"
+
+### R5: Token Budget Control (SHOULD)
+
+Total trigger index growth SHOULD be ≤ 8 lines (6 keyword rows + 6 guide path rows = 12 table rows, but table rows are short). The trigger index must remain under ~60 lines total.
+
+### R6: Guide Loading Cap (MUST)
+
+Maintain the "MUST load only 1-3 relevant guides" instruction. Do NOT increase the cap — more guides available does not mean more should be loaded simultaneously.
+
+## Acceptance Criteria
+
+### AC1: Guide Files Registered (R1)
+
+- **Given** `GUIDES_FILES` dict in `src/pactkit/prompts/guides.py`
+- **When** the module is loaded
+- **Then** it contains exactly 19 entries (13 original + 6 new), each ≤ 50 lines with MUST and NEVER sections
+
+### AC2: Trigger Index Extended (R2, R3)
+
+- **Given** `RULES_MODULES["engineering"]` in rules.py
+- **When** the content is inspected
+- **Then** the keyword table has 19 rows and the guide loading table has 19 rows
+
+### AC3: Deployment Creates 19 Guide Files (R1)
+
+- **Given** `_deploy_guides()` is called
+- **When** deployment completes
+- **Then** 19 `.md` files exist in `skills/_rules/guides/` directory
+
+### AC4: Guide Loading Cap Unchanged (R6)
+
+- **Given** trigger index content
+- **When** inspected for loading instruction
+- **Then** still says "MUST load only 1-3 relevant guides" (not 4+)
+
+### AC5: All Tests Pass (R4)
+
+- **Given** updated test expectations (19 guides)
+- **When** full test suite runs
+- **Then** all tests pass including pre-existing count assertions
+
+## Target Call Chain
+
+```
+guides.py::GUIDES_FILES (add 6 entries)
+  → rules.py::RULES_MODULES["engineering"] (extend keyword table + guide table)
+    → deployer.py::_deploy_guides() (already handles any GUIDES_FILES count)
+      → tests/ (update count assertions 13→19)
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/guides.py` | Add 6 new guide entries to GUIDES_FILES | None | Low |
+| 2 | `src/pactkit/prompts/rules.py` | Add 6 keyword rows + 6 guide loading rows to engineering module | Step 1 | Low |
+| 3 | `tests/unit/test_story_slim128_engineering_concerns.py` | Update count 13→19, update EXPECTED_GUIDES set | Steps 1-2 | Low |
+| 4 | Other test files | Update baselines if char counts exceeded | Steps 1-2 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 Input Validation | N/A | docs/tests only |
+| SEC-2 Auth/AuthZ | N/A | docs/tests only |
+| SEC-3 Data Exposure | N/A | docs/tests only |
+| SEC-4 Cryptography | N/A | docs/tests only |
+| SEC-5 Error Handling | N/A | docs/tests only |
+| SEC-6 Dependencies | N/A | docs/tests only |
+| SEC-7 Logging | N/A | docs/tests only |
+| SEC-8 Config/Secrets | N/A | docs/tests only |
+
+## Out of Scope
+
+- No changes to deployer logic (already handles dynamic GUIDES_FILES count)
+- No changes to command prompts (plan/act phases already reference the trigger index)
+- No new RULES_ONDEMAND_FILES entry needed (engineering key already exists)
+- No config.py changes (VALID_RULES already includes 07-engineering-concerns)