pactkit 2.14.2__tar.gz → 2.15.1__tar.gz

{pactkit-2.14.2 → pactkit-2.15.1}/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [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
+- **`lint` optional dependency group** — `pip install pactkit[lint]` now includes `ruff>=0.4`. The `all` extra also includes `lint`. Users no longer need to install ruff separately for the lint gate to work.
+- **External tools documentation** — README and pactkit.dev installation pages now document recommended external tools (gh, codegraph) with install commands and fallback behavior.
+
+### Fixed
+- **CI: tree-sitter tests skip when not installed** — `test_story_slim032`, `test_story_slim033`, `test_story_slim034` now use `pytest.importorskip("tree_sitter")` so they skip gracefully in CI environments without the `visualize` extra.
+
 ## [2.14.2] - 2026-06-01
 
 ### Added

{pactkit-2.14.2 → pactkit-2.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.14.2
+Version: 2.15.1
 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
@@ -25,12 +25,15 @@ Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
 Requires-Dist: pactkit-codex>=2.9.0; extra == 'all'
 Requires-Dist: pactkit-opencode>=2.9.0; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
 Requires-Dist: tree-sitter-go>=0.25; extra == 'all'
 Requires-Dist: tree-sitter-java>=0.23; extra == 'all'
 Requires-Dist: tree-sitter-typescript>=0.23; extra == 'all'
 Requires-Dist: tree-sitter>=0.25; extra == 'all'
 Provides-Extra: codex
 Requires-Dist: pactkit-codex>=2.9.0; extra == 'codex'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.4; extra == 'lint'
 Provides-Extra: opencode
 Requires-Dist: pactkit-opencode>=2.9.0; extra == 'opencode'
 Provides-Extra: visualize
@@ -117,6 +120,23 @@ Requires Python 3.10+ and one of:
 
 > `pip install pactkit` automatically installs adapters for all 3 IDEs.
 
+### Optional Extras
+
+```bash
+pip install pactkit[lint]        # Includes ruff for lint gate
+pip install pactkit[visualize]   # Includes tree-sitter for AST analysis
+pip install pactkit[all]         # Everything above + IDE adapters
+```
+
+### Recommended External Tools
+
+These tools enhance PactKit but cannot be distributed via pip:
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| [gh](https://cli.github.com) | GitHub CLI (issue sync, release, PR) | `brew install gh` |
+| [codegraph](https://www.npmjs.com/package/codegraph) | Code symbol index & call chain analysis | `npm install -g codegraph` |
+
 ## Quick Start
 
 ```bash

{pactkit-2.14.2 → pactkit-2.15.1}/README.md

@@ -75,6 +75,23 @@ Requires Python 3.10+ and one of:
 
 > `pip install pactkit` automatically installs adapters for all 3 IDEs.
 
+### Optional Extras
+
+```bash
+pip install pactkit[lint]        # Includes ruff for lint gate
+pip install pactkit[visualize]   # Includes tree-sitter for AST analysis
+pip install pactkit[all]         # Everything above + IDE adapters
+```
+
+### Recommended External Tools
+
+These tools enhance PactKit but cannot be distributed via pip:
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| [gh](https://cli.github.com) | GitHub CLI (issue sync, release, PR) | `brew install gh` |
+| [codegraph](https://www.npmjs.com/package/codegraph) | Code symbol index & call chain analysis | `npm install -g codegraph` |
+
 ## Quick Start
 
 ```bash

{pactkit-2.14.2 → pactkit-2.15.1}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -63,3 +63,4 @@
 | 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 |

{pactkit-2.14.2 → pactkit-2.15.1}/docs/architecture/governance/lessons.md

@@ -2,7 +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 |
@@ -53,3 +52,4 @@
 | 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 |

{pactkit-2.14.2 → pactkit-2.15.1}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4009+ tests must pass before any commit to `main`.
+1. All 4023+ 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.1/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.14.2 → pactkit-2.15.1}/docs/product/context.md

@@ -1,5 +1,5 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-06-01T11:05:34+08:00 by pactkit context
+> Last updated: 2026-06-10T11:17:05+08:00 by pactkit context
 
 ## Sprint Status
 Backlog: 3 | In Progress: 0 | Done: 0 stories
@@ -16,11 +16,11 @@ None
 * main
 
 ## Key Decisions
-- 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
 - 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.
 
 ## Next Recommended Action
 `/project-plan`

pactkit-2.15.1/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.1/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)

{pactkit-2.14.2 → pactkit-2.15.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pactkit"
-version = "2.14.2"
+version = "2.15.1"
 description = "Spec-driven agentic DevOps toolkit for AI coding assistants"
 readme = "README.md"
 license = "MIT"
@@ -62,8 +62,11 @@ visualize = [
     "tree-sitter-java>=0.23",
     "tree-sitter-typescript>=0.23",
 ]
+lint = [
+    "ruff>=0.4",
+]
 all = [
-    "pactkit[opencode,codex,visualize]",
+    "pactkit[opencode,codex,visualize,lint]",
 ]
 
 [tool.hatch.build.targets.wheel]

{pactkit-2.14.2 → pactkit-2.15.1}/src/pactkit/__init__.py

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

{pactkit-2.14.2 → pactkit-2.15.1}/src/pactkit/config.py

@@ -85,6 +85,7 @@ VALID_RULES = frozenset(
         "04-architecture-principles",
         "05-sectional-write",
         "06-solution-design",
+        "07-engineering-concerns",
     }
 )
 

{pactkit-2.14.2 → pactkit-2.15.1}/src/pactkit/generators/deploy_base.py

@@ -153,6 +153,12 @@ class DeployerBase:
             config=config, _legacy_prefix=_legacy_prefix,
         )
 
+    @staticmethod
+    def deploy_guides(claude_root, profile=None):
+        from pactkit.generators.deployer import _deploy_guides
+
+        return _deploy_guides(claude_root, profile=profile)
+
     @staticmethod
     def deploy_ci(provider, project_root, config):
         from pactkit.generators.deployer import _deploy_ci

{pactkit-2.14.2 → pactkit-2.15.1}/src/pactkit/generators/deployer.py

@@ -84,6 +84,8 @@ def _render_prompt(template: str, profile: FormatProfile) -> str:
         "SCAFFOLD_CMD": f"python3 {skills_root}/pactkit-scaffold/scripts/scaffold.py",
         "REPORT_CMD": f"python3 {skills_root}/pactkit-report/scripts/report.py",
         "GLOBAL_INSTRUCTIONS": f"{profile.global_config_dir}/{profile.global_instructions_file}",
+        # Engineering guides path (STORY-slim-128)
+        "GUIDES_PATH": f"{skills_root}/_rules/guides",
         # Document schema variables (STORY-slim-007)
         "CONTEXT_SECTIONS": CONTEXT_SECTIONS_TEXT,
         "LESSONS_ROW_FORMAT": LESSONS_ROW_FORMAT,
@@ -357,6 +359,7 @@ def _deploy_classic(config=None, target=None):
     _cleanup_legacy(skills_dir)
     rule_scopes = config.get("rule_scopes", {})
     n_rules = _deploy_rules(claude_root, enabled_rules, rule_scopes=rule_scopes, profile=classic_profile)
+    _deploy_guides(claude_root, profile=classic_profile)
     _deploy_claude_md(claude_root, enabled_rules)
     agent_models = config.get("agent_models", {})
     n_agents = _deploy_agents(agents_dir, enabled_agents, profile=classic_profile, agent_models=agent_models)
@@ -676,6 +679,32 @@ def _deploy_rules(claude_root, enabled_rules, rule_scopes=None, profile=None):
     return deployed
 
 
+def _deploy_guides(claude_root, profile=None):
+    """Deploy engineering guide files to skills/_rules/guides/ (STORY-slim-128).
+
+    Guides are on-demand reference files loaded by Act Phase 1.5 based on
+    Spec's engineering concerns. Not loaded into context unless explicitly read.
+    """
+    from pactkit.prompts.guides import GUIDES_DIR, GUIDES_FILES
+
+    guides_dir = claude_root / "skills" / prompts.RULES_ONDEMAND_DIR / GUIDES_DIR
+    guides_dir.mkdir(parents=True, exist_ok=True)
+
+    # Clean existing managed guide files (upgrade path)
+    for f in guides_dir.glob("*.md"):
+        if f.name in GUIDES_FILES:
+            f.unlink()
+
+    deployed = 0
+    for filename, content in GUIDES_FILES.items():
+        if profile is not None:
+            content = _render_prompt(content, profile)
+        atomic_write(guides_dir / filename, content)
+        deployed += 1
+
+    return deployed
+
+
 def _is_pactkit_managed_global_md(content):
     """Detect if CLAUDE.md content is a PactKit-managed template (BUG-slim-089).
 

{pactkit-2.14.2 → pactkit-2.15.1}/src/pactkit/prompts/commands.py

@@ -104,7 +104,12 @@ model: opus
 ## 🎬 Phase 2: Design & Impact
 1.  **Diff**: Compare User Request vs Current Reality (from Phase 1).
 2.  **Duplication Audit**: Run the Duplication Audit from system-architect protocol — if this is the Nth same-kind implementation, grep existing implementations and assess shared abstraction needs before writing Spec.
-3.  **Update HLD**: Modify `docs/architecture/graphs/system_design.mmd`.
+3.  **Engineering Concerns Assessment** — scan the requirement for NFR keywords:
+    - Reference the Engineering Concerns trigger index (`07-engineering-concerns.md`) keyword table.
+    - For each matched concern, the Spec's Technical Design MUST include a decision (e.g., concurrency model, timeout strategy, caching policy).
+    - Unmatched concerns → do not add (avoid noise).
+    - **Output checkpoint**: `"Engineering concerns identified: {list}. Decisions will be included in Technical Design."`
+4.  **Update HLD**: Modify `docs/architecture/graphs/system_design.mmd`.
     - *Rule*: Keep the `code_graph.mmd` as is (it updates automatically).
 
 ## 🎬 Phase 3.1: Story ID Generation
@@ -217,7 +222,18 @@ model: sonnet
     - For **agent**: Check AgentParser output for orchestration edges so new code doesn't break agent flow.
 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.
+    - Output brief capability assessment before proceeding to Phase 1.5.
+
+## 🔧 Phase 1.5: Engineering Concerns Loading (Conditional)
+> **PURPOSE**: Load only the NFR guides relevant to this Story — keeps context minimal while ensuring engineering rigor.
+1.  **Read Spec Technical Design**: Check if the Spec contains engineering concern decisions (from Plan Phase 2).
+2.  **Identify concerns**: Extract the concern keywords mentioned (e.g., database, api-integration, resilience).
+3.  **Load guides**: For each identified concern, read the corresponding guide file from `{GUIDES_PATH}/`:
+    - MUST load only 1-3 relevant guides (those matching the Spec's concerns).
+    - NEVER load all 13 guides.
+    - If Spec has no engineering concerns section, skip this phase silently.
+4.  **Apply constraints**: Use the loaded guides' MUST/NEVER rules as implementation constraints in Phase 3.
+5.  **Output checkpoint**: `"Engineering guides loaded: {list}. Applying as implementation constraints."`
 
 ## 🎬 Phase 2: Test Scaffolding (TDD)
 1.  **Constraint**: NEVER write source code in this phase — doing so breaks TDD causality: tests must exist before the code they verify.