pactkit 2.11.0__tar.gz → 2.13.0__tar.gz

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

@@ -72,6 +72,14 @@ rules:
   - 09-sectional-write
   - 11-pdca-nudge
   - 12-solution-design
+  - 05-principles
+  - 01-workflow-conventions
+  - 02-mcp-integration
+  - 03-shared-protocols
+  - 04-architecture-principles
+  - 05-sectional-write
+  - 06-solution-design
+  - pactkit
 
 # CI/CD — set provider to github or gitlab to generate pipeline config
 ci:
@@ -85,12 +93,6 @@ ci:
 issue_tracker:
   provider: github
 
-# Hooks — safe, report-only hook templates (command-type only)
-hooks:
-  post_test_coverage: false
-  pre_commit_lint: false
-  pre_push_check: false
-
 # Lint — configure lint behavior in /project-done
 lint_blocking: false
 auto_fix: false
@@ -163,3 +165,7 @@ e2e:
   env_file: .env.test
   test_dir: tests/e2e
   type: none
+hooks:
+  post_test_coverage: false
+  pre_commit_lint: false
+  pre_push_check: false

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

@@ -4,6 +4,23 @@ 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
+- **Rules architecture refactor** (STORY-slim-112) — Merged 6 global core rules into single `pactkit.md`; on-demand rules renumbered 01-06 and moved to `~/.claude/skills/_rules/`. Reduces context window usage by ~60% per conversation.
+- **Auto-deploy on version mismatch** — After `pipx upgrade pactkit`, the next CLI command auto-syncs deployed files without requiring explicit `pactkit init`.
+
+### Fixed
+- **Hardcoded paths in deployer** — `_build_command_rules_header()` now uses `FormatProfile.rules_dir` / `skills_dir` instead of hardcoded `~/.claude/` paths.
+- **Stale filename references** — Updated cross-references in visualize.py, commands.py, lazy_visualize.py, and test files to match new rule filenames.
+
 ## [2.11.0] - 2026-04-25
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.11.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
@@ -369,7 +369,6 @@ docs/
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `stack` | string | auto-detected | Project stack (`python`, `node`, `go`, `java`) |
-| `version` | string | current | PactKit version that generated the config |
 | `developer` | string | `""` | Developer prefix for Story IDs (multi-developer collaboration) |
 | `agents` | list | all 9 | Agent definitions to deploy |
 | `commands` | list | all 11 | Command playbooks to deploy |

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

@@ -327,7 +327,6 @@ docs/
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `stack` | string | auto-detected | Project stack (`python`, `node`, `go`, `java`) |
-| `version` | string | current | PactKit version that generated the config |
 | `developer` | string | `""` | Developer prefix for Story IDs (multi-developer collaboration) |
 | `agents` | list | all 9 | Agent definitions to deploy |
 | `commands` | list | all 11 | Command playbooks to deploy |

{pactkit-2.11.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.11.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 |
@@ -53,3 +45,6 @@
 | 2026-04-23 | Rule files deploy from src/pactkit/prompts/rules.py via pactkit deploy — never edit ~/.claude/rules/ directly | src/pactkit/prompts/rules.py:RULES_MODULES |
 | 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.11.0 → pactkit-2.13.0}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 3796+ 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.13.0/docs/e2e/journey.md

@@ -0,0 +1,243 @@
+# User Journey Format Specification
+
+> This document defines the canonical format for `docs/e2e/journey.md` in PactKit-managed projects.
+> It is a **format specification template** -- projects copy and fill this structure with their own journeys.
+
+## Purpose
+
+A user journey describes an end-to-end flow that spans multiple stories. While individual stories
+have their own acceptance criteria (in `docs/test_cases/`), journeys capture the cross-story
+integration path that a real user follows.
+
+**Relationship to other artifacts:**
+- `docs/test_cases/{ID}_case.md` -- single-story acceptance (Gherkin scenarios)
+- `docs/e2e/journey.md` -- cross-story user flows (this document)
+- `tests/e2e/` -- executable E2E test code implementing journey segments
+
+---
+
+## Journey Structure
+
+Each journey follows this format:
+
+```markdown
+## Journey: {Journey Name}
+
+> {One-line description of the user goal}
+
+### Pre-conditions (Fixtures)
+
+| Fixture | Description | Setup Method |
+|---------|-------------|--------------|
+| {name} | {what it provides} | {seed script / API call / fixture function} |
+
+### Steps
+
+#### Step 1: {Step Title} [client]
+
+**Action**: {What the user does}
+
+**Assertions**:
+- STRUCTURE: {element/component} exists on page
+- STRUCTURE: {data container} is non-empty
+- BEHAVIOR: {interaction} triggers {expected response}
+
+#### Step 2: {Step Title} [server]
+
+**Action**: {What the system processes}
+
+**Assertions**:
+- STRUCTURE: {database record / API response} contains expected fields
+- STRUCTURE: {response payload} is non-empty
+- BEHAVIOR: {side effect} is observable (log entry, event emitted, etc.)
+
+#### Step 3: {Step Title} [server+client]
+
+**Action**: {Full-stack interaction}
+
+**Assertions**:
+- STRUCTURE: {UI element} renders with data from server
+- STRUCTURE: {response} matches expected schema shape
+- BEHAVIOR: {round-trip} completes within timeout
+```
+
+---
+
+## Execution Layer Annotations
+
+Each step MUST be annotated with its execution layer:
+
+| Annotation | Meaning | Test Tooling |
+|------------|---------|--------------|
+| `[client]` | Browser/UI interaction only | Playwright, Cypress |
+| `[server]` | Backend/API processing only | pytest + httpx, curl |
+| `[server+client]` | Full-stack round-trip | Playwright + API assertions |
+
+---
+
+## Assertion Types
+
+Assertions are classified into two categories with different enforcement rules:
+
+### Structure Assertions (MUST)
+
+Structure assertions verify that the expected elements, fields, or components **exist** and are
+**non-empty**. These are deterministic and safe to assert in any context.
+
+Examples:
+- "SQL code block element exists on page"
+- "Chart component is rendered"
+- "API response contains `data` field"
+- "Answer container has text content (length > 0)"
+
+### Content Assertions (MUST NOT for AI-generated content)
+
+Content assertions verify specific text values, numbers, or exact strings. These are appropriate
+for deterministic outputs but MUST NOT be used for AI-generated content.
+
+**When content is deterministic** (e.g., user profile display, static labels):
+- Exact text matching is acceptable
+- Numeric value assertions are acceptable
+
+**When content is AI-generated** (e.g., chatbot responses, generated analysis):
+- MUST NOT assert specific text content
+- MUST NOT assert exact numeric values in generated output
+- MUST NOT assert specific word choices or phrasing
+
+---
+
+## AI Content Assertion Strategy
+
+> This section provides guidance for projects that include AI-generated content in their user journeys
+> (e.g., chatbots, AI assistants, generated reports, analysis tools).
+
+### What to Assert (MUST)
+
+| Category | Example Assertion |
+|----------|------------------|
+| Structure exists | "SQL code block element is present in the response area" |
+| Non-empty | "Response container has text content with length > 0" |
+| Component renders | "Chart component is mounted and visible" |
+| Schema shape | "API response has `answer` field of type string" |
+| Timing | "Response arrives within N seconds" |
+| State transition | "Loading spinner disappears after response" |
+
+### What NOT to Assert (MUST NOT)
+
+| Anti-Pattern | Why It Fails |
+|--------------|--------------|
+| `assert response.text == "The answer is 42"` | AI output is non-deterministic |
+| `assert chart.data_points == [1.5, 2.3, 4.1]` | Generated values vary per run |
+| `assert sql_block.contains("SELECT * FROM users")` | AI may generate equivalent but different SQL |
+| `assert summary.word_count == 150` | Length varies with model/prompt |
+
+### Correct Pattern
+
+```python
+# STRUCTURE: verify element exists
+assert page.locator(".sql-code-block").is_visible()
+
+# NON-EMPTY: verify content was generated
+sql_content = page.locator(".sql-code-block").text_content()
+assert len(sql_content.strip()) > 0
+
+# SCHEMA: verify response shape, not content
+response = api_client.get("/chat/answer")
+assert "answer" in response.json()
+assert isinstance(response.json()["answer"], str)
+assert len(response.json()["answer"]) > 0
+
+# BEHAVIOR: verify state transition occurred
+assert page.locator(".loading-spinner").is_hidden()
+assert page.locator(".answer-area").is_visible()
+```
+
+---
+
+## Pre-condition Fixtures
+
+Each journey MUST declare its pre-conditions as named fixtures:
+
+```markdown
+### Pre-conditions (Fixtures)
+
+| Fixture | Description | Setup Method |
+|---------|-------------|--------------|
+| authenticated_user | Logged-in user session | `conftest.py::auth_fixture` |
+| sample_dataset | Pre-loaded test data | `scripts/seed_test_data.py` |
+| clean_state | Empty database with schema | `pytest fixture: db_reset` |
+```
+
+Fixtures are referenced by name in step pre-conditions, enabling:
+- Test isolation (each journey starts from a known state)
+- Parallelization (independent journeys can run concurrently)
+- Debugging (reproduce failures by loading specific fixtures)
+
+---
+
+## Example: Complete Journey
+
+```markdown
+## Journey: First Question to Answer
+
+> New user asks their first question and receives an AI-generated answer.
+
+### Pre-conditions (Fixtures)
+
+| Fixture | Description | Setup Method |
+|---------|-------------|--------------|
+| authenticated_user | Logged-in user with valid session | `conftest.py::auth_user` |
+| connected_datasource | At least one data source configured | `seed/datasource.sql` |
+
+### Steps
+
+#### Step 1: Navigate to Chat [client]
+
+**Action**: User opens the chat interface from dashboard.
+
+**Assertions**:
+- STRUCTURE: Chat input field is visible
+- STRUCTURE: Message history area exists (may be empty)
+- BEHAVIOR: Input field accepts text input
+
+#### Step 2: Submit Question [server+client]
+
+**Action**: User types a question and presses Enter.
+
+**Assertions**:
+- STRUCTURE: Loading indicator appears
+- STRUCTURE: User message appears in history
+- BEHAVIOR: API call to `/api/chat` is triggered
+
+#### Step 3: Receive Answer [server+client]
+
+**Action**: Server processes the question and streams response.
+
+**Assertions**:
+- STRUCTURE: Answer area becomes visible
+- STRUCTURE: Answer text content is non-empty
+- STRUCTURE: SQL code block is present (if query was data-related)
+- BEHAVIOR: Loading indicator disappears
+- MUST NOT: Assert specific answer text content (AI-generated)
+- MUST NOT: Assert exact SQL query string (AI-generated)
+
+#### Step 4: View Generated Visualization [client]
+
+**Action**: User clicks on the chart tab to see generated visualization.
+
+**Assertions**:
+- STRUCTURE: Chart component is rendered
+- STRUCTURE: Chart has at least one data series
+- BEHAVIOR: Chart responds to hover interaction
+- MUST NOT: Assert specific chart data values (AI-generated)
+```
+
+---
+
+## Usage in Check Phase 4
+
+When `/project-check` Phase 4 (E2E Execution) runs:
+
+1. If `docs/e2e/journey.md` exists, read it to identify journey segments affected by the current story
+2. E2E tests SHOULD cover the affected segments (not the full journey)
+3. Journey definitions inform test scope; `docs/test_cases/` informs acceptance criteria

{pactkit-2.11.0 → pactkit-2.13.0}/docs/product/archive/archive_202604.md

@@ -269,3 +269,21 @@
 - [x] Update CLI help text
 - [x] Clean prompt references
 - [x] Update agent docs
+
+### [STORY-slim-107] Integrate tech debt prevention patterns into framework rules
+> Spec: docs/specs/STORY-slim-107.md
+
+- [x] Expand architecture §1 DRY with dual-write
+- [x] Expand architecture §6 Security (deny-by-default, input validation, timing)
+- [x] Add architecture §10 Code Enforces / LLM≠Calculator
+- [x] Add architecture §11 Concurrency & Async Safety
+- [x] Add architecture §12 Cache Lifecycle
+- [x] Add architecture §13 Dead Code Hygiene
+- [x] Add String→Enum to solution module
+- [x] Run test suite
+
+### [BUG-slim-107] Fix scan_excludes replacing defaults and hidden root module
+> Spec: docs/specs/BUG-slim-107.md
+
+- [x] Merge custom excludes with defaults
+- [x] Show root module in available list

pactkit-2.13.0/docs/product/archive/archive_202605.md

@@ -0,0 +1,47 @@
+
+### [STORY-slim-113] pactkit interface-summary CLI — Code Enforce 接口摘要
+> Spec: docs/specs/STORY-slim-113.md
+
+- [x] 新建 interface_summary.py 提取逻辑
+- [x] CLI 注册 interface-summary 命令
+- [x] Act Phase 1 改为显式步骤
+- [x] pactkit-trace 更新输出指引
+- [x] 单元测试
+
+### [STORY-slim-112] Rules 架构重构：全局原则 vs 按需操作规程
+> Spec: docs/specs/STORY-slim-112.md
+
+- [x] 拆分 RULES_CORE/ONDEMAND + 新建 05-principles
+- [x] 更新 deployer 双目录部署
+- [x] 更新所有 skill @import 路径
+- [x] 更新测试断言
+
+### [STORY-slim-111] Check Phase 4 Playwright 断言策略指南
+> Spec: docs/specs/STORY-slim-111.md
+
+- [x] 修改 project-check SKILL.md Phase 4 增加断言策略
+
+### [STORY-slim-110] project-design 集成 User Journey 生成
+> Spec: docs/specs/STORY-slim-110.md
+
+- [x] 修改 project-design SKILL.md Phase 1 Group B
+
+### [STORY-slim-109] E2E journey.md 规范定义与 File Atlas 集成
+> Spec: docs/specs/STORY-slim-109.md
+
+- [x] 注册 File Atlas
+- [x] 创建 journey.md 格式规范
+- [x] 修改 project-check Phase 4
+
+### [STORY-slim-108] pactkit-trace --summary 模式：接口摘要输出
+> Spec: docs/specs/STORY-slim-108.md
+
+- [x] 修改 pactkit-trace SKILL.md Phase 3
+- [x] 修改 project-act SKILL.md Phase 1
+
+### [STORY-slim-114] Act Phase 4 Journey Sync — journey.md 维护闭环
+> Spec: docs/specs/STORY-slim-114.md
+
+- [x] Act Phase 4 新增 Journey Sync 步骤
+- [x] Plan Phase 3.2a 条件 Journey Segment
+- [x] 单元测试

pactkit-2.13.0/docs/product/context.md

@@ -0,0 +1,29 @@
+# Project Context (Auto-generated)
+> Last updated: 2026-05-07T10:33:00+08:00 by pactkit context
+
+## Sprint Status
+Backlog: 0 | In Progress: 0 | Done: 0 stories
+
+## Current Stories
+None
+
+## Recent Completions
+None
+
+## Active Branches
++ claude/naughty-euclid-e6a787
+  develop
+* main
+
+## Key Decisions
+- 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-design`
+
+## Agent Continuation
+No active work session.

pactkit-2.13.0/docs/specs/BUG-slim-107.md

@@ -0,0 +1,12 @@
+# BUG-slim-107: Custom scan_excludes replaces defaults, leaking .next as modules
+
+## Background
+When a project's `pactkit.yaml` defines custom `visualize.scan_excludes`, it completely replaces the built-in `SCAN_EXCLUDES` set. Projects lose critical exclusions like `.next`, causing build artifacts to be detected as modules. Combined with the root module `.` being hidden from the "Available modules" error message, this misleads AI into concluding "visual scan not applicable to Python projects".
+
+## Target
+- `src/pactkit/skills/visualize.py:280` — merge custom excludes with defaults instead of replacing
+- `src/pactkit/skills/visualize.py:1180` — include root module in available list with descriptive label
+
+## Fix
+1. `_detect_modules`: union custom scan_excludes with SCAN_EXCLUDES
+2. Available modules list: show root module as `"." (project root)` instead of filtering it out

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

@@ -0,0 +1,134 @@
+# STORY-slim-107: Integrate tech debt prevention patterns into framework rules
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-107 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.12.0 |
+
+## Background
+
+A tech debt cleanup across the pactsearch project (BUG-172~191, STORY-182~209) yielded 12 recurring anti-patterns. These were captured in a personal rules file (`13-tech-debt-patterns.md`) but are not yet available to PactKit framework users. The valuable, language-agnostic patterns should be integrated into the existing deployed rule modules (`architecture` and `solution`) so all PactKit users benefit from these lessons.
+
+**Source material**: `~/.claude/rules/13-tech-debt-patterns.md` (12 rules derived from real tech debt specs)
+
+**Integration targets** (no new rule files — enrich existing ones):
+- `architecture` module (`08-architecture-principles.md`): expand §1 DRY, expand §6 Security, add §10–§13
+- `solution` module (`12-solution-design.md`): add String→Enum pattern to Implementation Constraints
+
+## Requirements
+
+### R1: Expand Architecture §1 DRY with Dual-Write Prevention (MUST)
+
+Add a "No Dual-Write" sub-section to §1 Single Source of Truth (DRY) with:
+- Anti-pattern table (Memory+DB, Cache+Source, Frontend+Backend enums, File+DB)
+- Fix pattern (choose ONE truth source; others become read-cache or projection)
+- Keep language-agnostic (no owlready2/rdflib references)
+
+### R2: Expand Architecture §6 Security with Deny-by-Default, Input Validation, and Timing Consistency (MUST)
+
+Extend §6 Defense-in-Depth with three new sub-sections:
+- **Deny-by-Default**: Sensitive endpoints MUST require auth by default; empty config = denied
+- **Input Validation**: User input entering URLs, commands, SQL, file paths MUST be validated/escaped (table by destination type)
+- **Timing Consistency**: Security-sensitive branches MUST have consistent timing to prevent side-channel attacks
+
+### R3: Add Architecture §10 Code Enforces, Prompt Instructs (MUST)
+
+New principle with litmus test: "If the LLM ignores the prompt instruction, does the constraint still hold?" Includes anti-pattern table (SQL limit, input length, output format, date freshness) and LLM≠Calculator decision matrix.
+
+### R4: Add Architecture §11 Concurrency & Async Safety (SHOULD)
+
+New principle covering:
+- Fire-and-forget tasks MUST NOT silently fail (error visibility, backpressure, shutdown awareness)
+- Request-scoped state (ContextVar or equivalent) MUST be cleaned up in finally blocks
+- Shared mutable state MUST be protected (lock, semaphore lazy-init)
+
+### R5: Add Architecture §12 Cache Lifecycle (SHOULD)
+
+New principle: every cache MUST be registered in a central invalidation function. Write operations MUST declare which caches they affect.
+
+### R6: Add Architecture §13 Dead Code Hygiene (SHOULD)
+
+New principle: unused functions, empty middleware, unwired components MUST be deleted or activated. Categories table (dead function, empty middleware, unwired component, commented code).
+
+### R7: Add String→Enum Pattern to Solution Design (SHOULD)
+
+In `solution` module under Implementation Constraints (after No Magic Values), add a `String Literal → Enum` sub-section:
+- Rule: any string value appearing in 3+ places SHOULD be promoted to a typed enum
+- Language-agnostic pattern (Python `str, Enum`; TypeScript `as const`; etc.)
+- Migration checklist (define enum, replace literals, verify with grep)
+
+## Acceptance Criteria
+
+### AC1: Architecture module deploys with new principles (R1, R2, R3, R4, R5, R6)
+
+- **Given** PactKit v2.12.0 is deployed via `pactkit deploy`
+- **When** the `08-architecture-principles.md` file is generated
+- **Then** it contains §1 with dual-write sub-section, §6 with 3 security sub-sections, §10 Code Enforces, §11 Concurrency Safety, §12 Cache Lifecycle, §13 Dead Code Hygiene
+
+### AC2: Solution module deploys with String→Enum pattern (R7)
+
+- **Given** PactKit v2.12.0 is deployed via `pactkit deploy`
+- **When** the `12-solution-design.md` file is generated
+- **Then** it contains a "String Literal → Enum" sub-section under Implementation Constraints
+
+### AC3: All rules are language-agnostic (R1-R7)
+
+- **Given** the new rule content in `rules.py`
+- **When** reviewed for project-specific references
+- **Then** no pactsearch-specific terms (owlready2, rdflib, pactsearch, BUG-172, STORY-182, etc.) appear — only generic patterns
+
+### AC4: Existing tests pass (R1-R7)
+
+- **Given** the modified `rules.py`
+- **When** `pytest tests/ -v` is run
+- **Then** all existing tests pass with 0 failures
+
+### AC5: RULES_MANAGED_PREFIXES unchanged (R1-R7)
+
+- **Given** no new rule files are created
+- **When** `RULES_MANAGED_PREFIXES` is inspected
+- **Then** it is identical to the pre-change value (no new prefix added)
+
+## Target Call Chain
+
+```
+rules.py:RULES_MODULES["architecture"]  → deployer._deploy_rules() → atomic_write(08-architecture-principles.md)
+rules.py:RULES_MODULES["solution"]      → deployer._deploy_rules() → atomic_write(12-solution-design.md)
+```
+No new modules, no new files, no new keys — only content changes within existing string values.
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/rules.py` | Expand `architecture` §1 with dual-write sub-section | None | Low |
+| 2 | `src/pactkit/prompts/rules.py` | Expand `architecture` §6 with deny-by-default, input validation, timing consistency | Step 1 | Low |
+| 3 | `src/pactkit/prompts/rules.py` | Add `architecture` §10 Code Enforces / LLM≠Calculator | Step 2 | Low |
+| 4 | `src/pactkit/prompts/rules.py` | Add `architecture` §11 Concurrency & Async Safety | Step 3 | Low |
+| 5 | `src/pactkit/prompts/rules.py` | Add `architecture` §12 Cache Lifecycle | Step 4 | Low |
+| 6 | `src/pactkit/prompts/rules.py` | Add `architecture` §13 Dead Code Hygiene | Step 5 | Low |
+| 7 | `src/pactkit/prompts/rules.py` | Add String→Enum pattern to `solution` Implementation Constraints | None | Low |
+| 8 | `tests/` | Run full test suite, verify 0 failures | Steps 1-7 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | Prompt content only, no credentials |
+| SEC-2 | N/A | No file path handling changes |
+| SEC-3 | N/A | No user input processing |
+| SEC-4 | N/A | No network calls |
+| SEC-5 | N/A | No shell commands |
+| SEC-6 | N/A | No config file writes |
+| SEC-7 | N/A | No dependency changes |
+| SEC-8 | N/A | No API endpoints |
+
+## Out of Scope
+
+- Creating new rule files (no `13-*.md` or `14-*.md` in PactKit framework)
+- `pactkit audit` CLI integration (future story)
+- Modifying `RULES_MANAGED_PREFIXES`, `RULES_FILES`, or `COMMAND_RULES_MAP`
+- P.A.C.T. philosophy rules (personal, not framework-level)
+- Project-specific examples (pactsearch owlready2, rdflib, etc.)