pactkit 2.2.0__tar.gz → 2.3.0__tar.gz

{pactkit-2.2.0 → pactkit-2.3.0}/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.3.0] - 2026-03-22
+
+### Added
+- **Deterministic CLI Subcommands** (STORY-slim-014) — Migrated 7 Done-phase operations from prompt-delegated to Python CLI: `clean`, `regression`, `context`, `sec-scope`, `guard`, `next-id`, `visualize --lazy`.
+- **Doctor, Backfill-Release, Issue-Sync CLI** (STORY-slim-015) — `pactkit doctor` diagnoses project health (HLD drift, board structure, config completeness). `pactkit backfill-release` replaces `Release: TBD` in completed specs. `pactkit issue-sync` handles GitHub issue lifecycle for BUG/HOTFIX items.
+- **Test-Map and Lint CLI** (STORY-slim-016) — `pactkit test-map` maps changed source files to test files via `LANG_PROFILES.test_map_pattern`. `pactkit lint` runs stack-aware lint with auto-fix and blocking modes from `pactkit.yaml`.
+- **Lesson-Append, Invariants-Refresh, Coverage-Gate CLI** (STORY-slim-017) — `pactkit lesson-append` checks specificity (file/function reference) and dedup (Jaccard < 0.5) before appending. `pactkit invariants-refresh` updates test count invariant. `pactkit coverage-gate` enforces 3-tier coverage thresholds (80/50/block).
+- **Systemic Cross-Flow Guards** (STORY-slim-018) — 4 guard test suites: R1 prompt-CLI cross-reference validation, R2 canonical `LANG_PROFILE_REQUIRED_KEYS` SSoT in `schemas.py`, R3 Spec Status lifecycle (`spec-status` CLI + W006 lint rule), R4 declarative cross-flow coverage matrix (12 subcommands × prompt keys).
+- **Spec Status CLI** — `pactkit spec-status <spec> <status>` programmatically updates `| Status |` field in spec files. W006 lint rule flags invalid status values.
+
+### Fixed
+- **Cross-Flow Integrity** (BUG-slim-003 through BUG-slim-006) — 4 rounds of systematic audits fixed 25+ gaps: dead CLI subcommands with zero prompt references, argparser flags without `deploy()` parity, `visualize --lazy` not calling actual function, double `python3` prefix in HOTFIX_PROMPT, unused LANG_PROFILES keys removed.
+- **SSoT Violations** — `backfill.py` imports `BOARD_SECTION_DONE` from schemas (was hardcoded regex). `lessons.py` uses `LESSONS_ROW_FORMAT` from schemas. 5 test files import `LANG_PROFILE_REQUIRED_KEYS` instead of hardcoding key sets.
+- **Prompt Cognitive Overload** (STORY-slim-013) — Reduced redundancy across PDCA command prompts.
+- **Rules-Commands Collision** (BUG-slim-002) — Resolved instruction conflicts between rules and command playbooks.
+- **Draw Skill Stuck** — Added concrete templates to `pactkit-draw` to prevent empty-output behavior.
+
+### Changed
+- `SPEC_VALID_STATUSES` and `LANG_PROFILE_REQUIRED_KEYS` canonicalized in `schemas.py` as single source of truth.
+- Sprint board required sections enforced: `## 📋 Backlog`, `## 🔄 In Progress`, `## ✅ Done`.
+- BUG-017/BUG-029 spec Status fields corrected to valid values per `SPEC_VALID_STATUSES`.
+
 ## [2.2.0] - 2026-03-20
 
 ### Added

{pactkit-2.2.0 → pactkit-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.2.0
+Version: 2.3.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
@@ -35,9 +35,11 @@ Description-Content-Type: text/markdown
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
 </p>
 
-<p align="center"><strong>Ship features with AI agents that follow specs, not vibes.</strong></p>
+<p align="center"><strong>CODE is the Law. Data is the Truth. Prompt is ONLY instruction. AI is ONLY creativity.</strong></p>
 
-> PactKit gives AI coding assistants a structured operating system — 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` and your AI assistant writes specs before code, runs TDD, and never commits without passing tests.
+> **PactKit** (Pact 契约 + Kit) is a governance framework that enforces the **P.A.C.T.** contract between humans and AI agents. Deterministic operations run as code, not prompts. Decisions are grounded in data, not memory. AI does what it's best at — creativity and language — while code handles everything that must be repeatable and correct.
+>
+> 25 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` and your AI assistant follows the contract.
 
 ### Supported AI Tools
 
@@ -57,15 +59,31 @@ You:  /project-sprint "Add OAuth2 login"
  Done   Repo Maintainer gates regression, archives story, commits
 ```
 
-## Why PactKit?
+## The P.A.C.T. Governance Contract
+
+The name says it all — **Pact** means covenant. These four principles define the boundary between human intent and AI execution:
+
+```
+P   Prompt   is ONLY instruction   Tells AI how to act — defines process, never state
+A   AI       is ONLY creativity    Formatting, summarization, language — never deterministic logic
+C   Code     is the Law            Sole executor of deterministic operations — no bypass, no approximation
+T   Truth    Data is the Truth     Factual basis for all judgment — no memory, no inference, no fabrication
+```
 
-AI coding assistants are powerful but unpredictable without structure. PactKit adds a **spec-driven governance layer**:
+- If a script exists → **use it**. Never reimplement in natural language. (C)
+- If data is available → **read it**. Never guess or recall from memory. (T)
+- Prompts define HOW, never WHAT. Current state comes from data, not docs. (P)
+- AI formats, summarizes, and creates. AI does not parse, compute, or fabricate. (A)
 
-- **Spec is the Law** — Specifications are the single source of truth (Spec > Tests > Code)
-- **Multi-Agent Ensemble** — 9 specialized agents collaborate, each with defined roles
+> Read the full philosophy: [docs/architecture/governance/philosophy.md](docs/architecture/governance/philosophy.md)
+
+## Why PactKit?
+
+- **P.A.C.T. Governance** — A contract between humans and AI agents, with clear boundaries
+- **Multi-Agent Ensemble** — 9 specialized agents collaborate, each with constrained tools
 - **Full PDCA Lifecycle** — Plan -> Act -> Check -> Done, with quality gates at every stage
-- **Safe by Design** — TDD-first development, safe regression testing, pre-existing test protection
-- **Multi-Tool Support** — Works with Claude Code and OpenCode (with model routing)
+- **Safe by Design** — TDD-first, safe regression, pre-existing test protection
+- **Multi-Tool Support** — Works with Claude Code and OpenCode
 
 ## Installation
 
@@ -206,6 +224,38 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 | **pactkit-review** | Prompt-only | PR code review with SOLID/Security/Quality checklists |
 | **pactkit-release** | Prompt-only | Version bump, architecture snapshot, git tag |
 
+## CLI Subcommands
+
+PactKit ships 25 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+
+| Command | Purpose |
+|---------|---------|
+| `pactkit init` | Deploy toolkit to AI coding assistant |
+| `pactkit update` | Update playbooks (preserves config) |
+| `pactkit upgrade` | Upgrade with format selection |
+| `pactkit version` | Show installed version |
+| `pactkit schema` | Print document schemas |
+| `pactkit doctor` | Diagnose project health (HLD drift, board, config) |
+| `pactkit spec-lint` | Validate spec structure (14 rules: E001-E008, W001-W006) |
+| `pactkit spec-status` | Update spec Status field (Draft/In Progress/Done) |
+| `pactkit guard` | Check project init markers |
+| `pactkit next-id` | Generate next Story/Bug ID |
+| `pactkit context` | Generate `context.md` from project state |
+| `pactkit clean` | Remove stack-specific temp artifacts |
+| `pactkit lint` | Stack-aware lint with auto-fix and blocking modes |
+| `pactkit regression` | Classify changes (SKIP/FULL/IMPACT) |
+| `pactkit test-map` | Map source files to test files |
+| `pactkit coverage-gate` | Enforce 3-tier coverage thresholds (80/50/block) |
+| `pactkit visualize` | Conditional graph regeneration (lazy mode) |
+| `pactkit lesson-append` | Append lesson with specificity check and dedup |
+| `pactkit invariants-refresh` | Update test count invariant in rules.md |
+| `pactkit sec-scope` | Detect security scope for changed files |
+| `pactkit backfill-release` | Replace Release: TBD in completed specs |
+| `pactkit issue-sync` | GitHub issue lifecycle for BUG/HOTFIX items |
+| `pactkit lint-context` | Validate context.md structure |
+| `pactkit lint-lessons` | Validate lessons.md structure |
+| `pactkit lint-testcase` | Validate test case structure |
+
 ## Deployment Architecture
 
 PactKit supports two deployment formats:
@@ -299,15 +349,15 @@ PactKit's safe regression system prevents agents from blindly modifying pre-exis
 - **Regression Check** — Read-only gate; pre-existing test failure = STOP and report
 - **Done Gate** — Full regression by default; incremental only when ALL safety conditions are met
 
-## Hierarchy of Truth
+## Hierarchy of Truth (the "T" in P.A.C.T.)
 
 ```
-Tier 1: Specs & Test Cases           <- The Law
-Tier 2: Tests                        <- The Verification
+Tier 1: Specs & Test Cases           <- The Law (CODE is the Law)
+Tier 2: Tests                        <- The Verification (DATA is the Truth)
 Tier 3: Implementation               <- The Mutable Reality
 ```
 
-When conflicts arise: Spec wins. Always.
+When conflicts arise: Spec wins. Always. The agent modifies code, never the spec.
 
 ## MCP Integration
 

{pactkit-2.2.0 → pactkit-2.3.0}/README.md

@@ -9,9 +9,11 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
 </p>
 
-<p align="center"><strong>Ship features with AI agents that follow specs, not vibes.</strong></p>
+<p align="center"><strong>CODE is the Law. Data is the Truth. Prompt is ONLY instruction. AI is ONLY creativity.</strong></p>
 
-> PactKit gives AI coding assistants a structured operating system — 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` and your AI assistant writes specs before code, runs TDD, and never commits without passing tests.
+> **PactKit** (Pact 契约 + Kit) is a governance framework that enforces the **P.A.C.T.** contract between humans and AI agents. Deterministic operations run as code, not prompts. Decisions are grounded in data, not memory. AI does what it's best at — creativity and language — while code handles everything that must be repeatable and correct.
+>
+> 25 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` and your AI assistant follows the contract.
 
 ### Supported AI Tools
 
@@ -31,15 +33,31 @@ You:  /project-sprint "Add OAuth2 login"
  Done   Repo Maintainer gates regression, archives story, commits
 ```
 
-## Why PactKit?
+## The P.A.C.T. Governance Contract
+
+The name says it all — **Pact** means covenant. These four principles define the boundary between human intent and AI execution:
+
+```
+P   Prompt   is ONLY instruction   Tells AI how to act — defines process, never state
+A   AI       is ONLY creativity    Formatting, summarization, language — never deterministic logic
+C   Code     is the Law            Sole executor of deterministic operations — no bypass, no approximation
+T   Truth    Data is the Truth     Factual basis for all judgment — no memory, no inference, no fabrication
+```
 
-AI coding assistants are powerful but unpredictable without structure. PactKit adds a **spec-driven governance layer**:
+- If a script exists → **use it**. Never reimplement in natural language. (C)
+- If data is available → **read it**. Never guess or recall from memory. (T)
+- Prompts define HOW, never WHAT. Current state comes from data, not docs. (P)
+- AI formats, summarizes, and creates. AI does not parse, compute, or fabricate. (A)
 
-- **Spec is the Law** — Specifications are the single source of truth (Spec > Tests > Code)
-- **Multi-Agent Ensemble** — 9 specialized agents collaborate, each with defined roles
+> Read the full philosophy: [docs/architecture/governance/philosophy.md](docs/architecture/governance/philosophy.md)
+
+## Why PactKit?
+
+- **P.A.C.T. Governance** — A contract between humans and AI agents, with clear boundaries
+- **Multi-Agent Ensemble** — 9 specialized agents collaborate, each with constrained tools
 - **Full PDCA Lifecycle** — Plan -> Act -> Check -> Done, with quality gates at every stage
-- **Safe by Design** — TDD-first development, safe regression testing, pre-existing test protection
-- **Multi-Tool Support** — Works with Claude Code and OpenCode (with model routing)
+- **Safe by Design** — TDD-first, safe regression, pre-existing test protection
+- **Multi-Tool Support** — Works with Claude Code and OpenCode
 
 ## Installation
 
@@ -180,6 +198,38 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 | **pactkit-review** | Prompt-only | PR code review with SOLID/Security/Quality checklists |
 | **pactkit-release** | Prompt-only | Version bump, architecture snapshot, git tag |
 
+## CLI Subcommands
+
+PactKit ships 25 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+
+| Command | Purpose |
+|---------|---------|
+| `pactkit init` | Deploy toolkit to AI coding assistant |
+| `pactkit update` | Update playbooks (preserves config) |
+| `pactkit upgrade` | Upgrade with format selection |
+| `pactkit version` | Show installed version |
+| `pactkit schema` | Print document schemas |
+| `pactkit doctor` | Diagnose project health (HLD drift, board, config) |
+| `pactkit spec-lint` | Validate spec structure (14 rules: E001-E008, W001-W006) |
+| `pactkit spec-status` | Update spec Status field (Draft/In Progress/Done) |
+| `pactkit guard` | Check project init markers |
+| `pactkit next-id` | Generate next Story/Bug ID |
+| `pactkit context` | Generate `context.md` from project state |
+| `pactkit clean` | Remove stack-specific temp artifacts |
+| `pactkit lint` | Stack-aware lint with auto-fix and blocking modes |
+| `pactkit regression` | Classify changes (SKIP/FULL/IMPACT) |
+| `pactkit test-map` | Map source files to test files |
+| `pactkit coverage-gate` | Enforce 3-tier coverage thresholds (80/50/block) |
+| `pactkit visualize` | Conditional graph regeneration (lazy mode) |
+| `pactkit lesson-append` | Append lesson with specificity check and dedup |
+| `pactkit invariants-refresh` | Update test count invariant in rules.md |
+| `pactkit sec-scope` | Detect security scope for changed files |
+| `pactkit backfill-release` | Replace Release: TBD in completed specs |
+| `pactkit issue-sync` | GitHub issue lifecycle for BUG/HOTFIX items |
+| `pactkit lint-context` | Validate context.md structure |
+| `pactkit lint-lessons` | Validate lessons.md structure |
+| `pactkit lint-testcase` | Validate test case structure |
+
 ## Deployment Architecture
 
 PactKit supports two deployment formats:
@@ -273,15 +323,15 @@ PactKit's safe regression system prevents agents from blindly modifying pre-exis
 - **Regression Check** — Read-only gate; pre-existing test failure = STOP and report
 - **Done Gate** — Full regression by default; incremental only when ALL safety conditions are met
 
-## Hierarchy of Truth
+## Hierarchy of Truth (the "T" in P.A.C.T.)
 
 ```
-Tier 1: Specs & Test Cases           <- The Law
-Tier 2: Tests                        <- The Verification
+Tier 1: Specs & Test Cases           <- The Law (CODE is the Law)
+Tier 2: Tests                        <- The Verification (DATA is the Truth)
 Tier 3: Implementation               <- The Mutable Reality
 ```
 
-When conflicts arise: Spec wins. Always.
+When conflicts arise: Spec wins. Always. The agent modifies code, never the spec.
 
 ## MCP Integration
 

{pactkit-2.2.0 → pactkit-2.3.0}/docs/specs/BUG-017.md

@@ -4,7 +4,7 @@
 |-------|-------|
 | ID | BUG-017 |
 | Title | /project-init playbook generates incomplete pactkit.yaml |
-| Status | Open |
+| Status | Draft |
 | Priority | P1 |
 | Release | 1.3.1 |
 

{pactkit-2.2.0 → pactkit-2.3.0}/docs/specs/BUG-029.md

@@ -6,7 +6,7 @@
 | Type | Bug |
 | Priority | High |
 | Release | 1.6.5 |
-| Status | Backlog |
+| Status | Draft |
 
 ## Summary
 

pactkit-2.3.0/docs/specs/BUG-slim-002.md

@@ -0,0 +1,115 @@
+# BUG-slim-002: Rules-Commands Instruction Collision Causes Plan/Act Stall
+
+| Field | Value |
+|-------|-------|
+| ID | BUG-slim-002 |
+| Status | Draft |
+| Priority | P1 |
+| Release | 2.2.0 |
+
+## Background
+
+When running `/project-plan` or `/project-act`, the AI agent frequently stalls (long thinking time, repeated actions, or apparent hang). Root cause analysis reveals that the global Rules (`01-core-protocol`, `02-hierarchy-of-truth`) contain instructions that **duplicate or conflict with** the phase-ordered instructions inside Command playbooks. The AI attempts to satisfy both layers simultaneously, resulting in repeated execution (e.g., `visualize` triggered up to 5 times per Story cycle), logical deadlocks (Rule 02 demands "read Spec before modifying code" but Plan is creating the Spec), and cascading sub-flows (Init Guard auto-triggers a full 7-phase `/project-init`).
+
+## Root Cause Analysis
+
+| ID | Problem | Source | Impact |
+|----|---------|--------|--------|
+| RC-1 | Rule 01 "Visual First" triggers `visualize` (3 modes) independently of Command-internal visualize phases | `rules.py` RULES_MODULES["core"] | 2-3x redundant visualize runs per command |
+| RC-2 | Rule 02 "Operating Guidelines" requires reading Spec before code modification, but Plan is creating the Spec (does not exist yet) | `rules.py` RULES_MODULES["hierarchy"] | Logical deadlock / wasted search for nonexistent file |
+| RC-3 | Plan Phase 0.5 Init Guard auto-executes full `/project-init` (7 phases) when any marker is missing | `commands.py` COMMANDS_CONTENT["project-plan.md"] | Cascading 7-phase sub-flow mid-Plan |
+| RC-4 | Plan Phase 0.7 Clarify Gate auto-triggers on 2 High signals without escape hatch | `commands.py` COMMANDS_CONTENT["project-plan.md"] | Implicit blocking wait for user input |
+| RC-5 | Act Phase 0.6 Consistency Check does full Spec/Board/TestCase cross-reference before any code is written | `commands.py` COMMANDS_CONTENT["project-act.md"] | Heavy text parsing phase that adds latency |
+| RC-6 | Act runs visualize 3 separate times: Phase 1 (trace), Phase 4 (Lazy Visualize), plus Rule 01 (Visual First) | Multiple sources | 3x redundant visualize in Act alone |
+
+## Target Call Chain
+
+```
+User invokes /project-plan or /project-act
+  -> Claude Code loads CLAUDE.md (@import all 8 rules)
+    -> Rule 01 "Visual First" fires (visualize x3 modes)
+    -> Rule 02 "Operating Guidelines" fires (search for Spec)
+  -> Command playbook executes
+    -> Phase 0.5 Init Guard (may cascade to /project-init x7 phases)
+    -> Phase 0.7 Clarify Gate (may block on user input)
+    -> Phase 1 Archaeology/Trace (visualize again)
+    -> [Act only] Phase 0.6 Consistency Check (heavy parsing)
+    -> [Act only] Phase 4 Lazy Visualize (visualize again)
+```
+
+## Requirements
+
+### R1: PDCA Command Exemption for Visual First
+Rule 01 "Visual First" MUST include a PDCA exemption clause stating that when a PDCA command (`/project-plan`, `/project-act`, `/project-check`, `/project-done`, `/project-hotfix`, `/project-sprint`, `/project-design`, `/project-init`) is active, the command's own visualize phases take precedence and the global "Visual First" rule is suppressed.
+
+### R2: Plan-Phase Exemption for Operating Guidelines
+Rule 02 "Operating Guidelines" MUST include a clause exempting `/project-plan` and `/project-design` from the "read Spec before modifying code" requirement, since these commands create (not modify) Specs.
+
+### R3: Init Guard Downgrade to Suggestion-and-Stop
+Plan Phase 0.5 Init Guard MUST be changed from auto-executing `/project-init` to printing a warning message and STOPPING. The user can then manually run `/project-init` if needed.
+
+### R4: Clarify Gate Threshold Increase
+Plan Phase 0.7 Clarify Gate SHOULD raise the auto-trigger threshold: require 2 High + 1 Medium signal (instead of 2 High alone). Single-sentence input (< 15 words) SHOULD be downgraded from Medium to Low signal.
+
+### R5: Act Consistency Check Simplification
+Act Phase 0.6 Consistency Check SHOULD be simplified to a lightweight existence check (does Spec exist? does Board entry exist?) instead of full cross-reference parsing. The detailed Spec-Board-TestCase alignment analysis SHOULD be deferred to `/project-check`.
+
+### R6: Act Visualize Deduplication
+Act Phase 1 MUST NOT run `visualize` if Phase 4 Lazy Visualize will run it anyway. Phase 1 SHOULD only run `visualize --focus <module>` (single targeted mode), not the full 3-mode scan. The full 3-mode scan remains in Phase 4 (post-implementation) via Lazy Visualize Protocol.
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|--------------|------|
+| 1 | `src/pactkit/prompts/rules.py` | Add PDCA exemption to "Visual First" in RULES_MODULES["core"] (R1) | None | Low |
+| 2 | `src/pactkit/prompts/rules.py` | Add Plan/Design exemption to "Operating Guidelines" in RULES_MODULES["hierarchy"] (R2) | None | Low |
+| 3 | `src/pactkit/prompts/commands.py` | Rewrite Plan Phase 0.5 Init Guard: warn + STOP instead of auto-execute (R3) | None | Low |
+| 4 | `src/pactkit/prompts/commands.py` | Adjust Clarify Gate threshold in Plan Phase 0.7 (R4) | None | Low |
+| 5 | `src/pactkit/prompts/commands.py` | Simplify Act Phase 0.6 to lightweight existence check (R5) | None | Low |
+| 6 | `src/pactkit/prompts/commands.py` | Deduplicate Act visualize: Phase 1 focus-only, Phase 4 full Lazy Visualize (R6) | None | Low |
+| 7 | `tests/` | Add/update tests to verify prompt content changes | Steps 1-6 | Low |
+
+## Acceptance Criteria
+
+### AC1: Visual First PDCA Exemption
+Given Rule 01 "Visual First" is deployed
+When a PDCA command (e.g., `/project-act`) is active
+Then the rule text includes a PDCA exemption clause and does not independently trigger visualize
+
+### AC2: Plan-Phase Spec Read Exemption
+Given Rule 02 "Operating Guidelines" is deployed
+When `/project-plan` or `/project-design` is active
+Then the rule text exempts these commands from "read Spec before modifying code"
+
+### AC3: Init Guard Warns Instead of Auto-Executing
+Given Plan Phase 0.5 Init Guard detects a missing marker
+When the guard evaluates
+Then it prints a warning with the missing markers and STOPs, without auto-executing `/project-init`
+
+### AC4: Clarify Gate Higher Threshold
+Given Plan Phase 0.7 Clarify Gate is evaluating user input
+When the input has exactly 2 High signals but 0 Medium signals
+Then Clarify is suggested (not auto-triggered)
+
+### AC5: Act Lightweight Consistency Check
+Given Act Phase 0.6 is executing
+When it checks Spec-Board alignment
+Then it only verifies existence (Spec file exists, Board entry exists) without cross-reference parsing
+
+### AC6: Act Visualize Runs Once Per Phase
+Given Act Phase 1 and Phase 4 both reference visualize
+When Act executes end-to-end
+Then Phase 1 runs only `--focus <module>` (1 mode) and Phase 4 runs Lazy Visualize (conditional 3 modes), with no duplication from Rule 01
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | Python source files modified (rules.py, commands.py) |
+| SEC-2 | No | No user input handling — prompt template changes only |
+| SEC-3 | No | No database operations |
+| SEC-4 | No | No frontend files |
+| SEC-5 | No | No auth/session logic |
+| SEC-6 | No | No API endpoints |
+| SEC-7 | No | No error handling changes |
+| SEC-8 | No | No dependency file changes |

pactkit-2.3.0/docs/specs/BUG-slim-003.md

@@ -0,0 +1,125 @@
+# BUG-slim-003: CLI Migration Gaps — Prompt Inconsistencies & Implementation Mismatches
+
+| Field | Value |
+|-------|-------|
+| ID | BUG-slim-003 |
+| Status | Draft |
+| Priority | P1 |
+| Release | 2.2.0 |
+
+## Background
+
+STORY-slim-014 migrated ~25 deterministic rules to Python CLI subcommands, but a post-migration audit revealed two categories of gaps:
+
+1. **Prompt inconsistencies**: Three CLI commands (`pactkit next-id`, `pactkit sec-scope`, `pactkit context`) exist but are not called in all relevant command playbooks. Some commands still instruct the LLM to perform the same logic manually, creating divergent execution paths.
+
+2. **Implementation mismatches**: Three modules have minor deviations from their canonical source or spec requirements.
+
+### Current State
+
+**Inconsistencies (CLI exists but prompt doesn't call it):**
+- `pactkit next-id`: Called in `project-plan` Phase 3.1, but NOT in `project-sprint` Phase 0, `project-hotfix` Phase 0, or `project-design` Phase 3 — all three still instruct manual `docs/specs/` scanning
+- `pactkit sec-scope`: Called in `project-check` Phase 0, but NOT in `project-plan` Phase 3.2 — Plan still asks the agent to manually apply the 8-row SEC detection table
+- `pactkit context`: Called in `project-done` Phase 4.5, but NOT in `project-plan` Phase 3.3 or `project-init` Phase 6 — both still ask the agent to write context.md directly
+
+**Implementation mismatches:**
+- `cleaners.py`: Java cleanup list is `["target/", "*.class", "build/"]` but canonical `LANG_PROFILES["java"]["cleanup"]` is `["target/", "build/", ".gradle/"]` — `.gradle/` missing, `*.class` is an undocumented addition
+- `guards.py`: Only checks `pactkit.yaml` file existence, not content completeness (R1 spec says "config completeness")
+- `validators.py`: `lint_lessons()` checks table header/separator but does not validate row format against `LESSONS_ROW_FORMAT` (3-column structure)
+
+## Target Call Chain
+
+```
+prompts/commands.py → PLAN_PROMPT / INIT_PROMPT → slimmed text referencing `pactkit next-id`, `pactkit sec-scope`, `pactkit context`
+prompts/workflows.py → SPRINT_PROMPT / HOTFIX_PROMPT / DESIGN_PROMPT → slimmed text referencing `pactkit next-id`
+src/pactkit/cleaners.py → _CLEANUP_PATTERNS["java"] → aligned with LANG_PROFILES
+src/pactkit/guards.py → check_init_markers() → extended with config completeness
+src/pactkit/validators.py → lint_lessons() → extended with row format check
+```
+
+## Requirements
+
+### R1: Fix prompt inconsistencies — `pactkit next-id`
+MUST replace manual `docs/specs/` scanning instructions with `pactkit next-id` calls in:
+- `workflows.py` SPRINT_PROMPT Phase 0 (line ~349)
+- `workflows.py` HOTFIX_PROMPT Phase 0 (line ~585)
+- `workflows.py` DESIGN_PROMPT Phase 3 (line ~739)
+
+### R2: Fix prompt inconsistency — `pactkit sec-scope`
+MUST replace the manual SEC-1~SEC-8 detection table application in `commands.py` Plan Phase 3.2 with a call to `pactkit sec-scope <changed-files>`, keeping the detection rules table as reference documentation only.
+
+### R3: Fix prompt inconsistency — `pactkit context`
+MUST replace manual context.md writing instructions with `pactkit context` calls in:
+- `commands.py` Plan Phase 3.3
+- `commands.py` Init Phase 6 (if present)
+
+### R4: Fix cleaners.py Java cleanup list
+MUST align `_CLEANUP_PATTERNS["java"]` with canonical `LANG_PROFILES["java"]["cleanup"]`: `["target/", "build/", ".gradle/"]`. Remove `*.class`.
+
+### R5: Extend guards.py config completeness check
+SHOULD extend `check_init_markers()` to optionally verify that `pactkit.yaml` contains expected top-level sections (developer, stack, agents, commands, skills, rules). Return missing sections in the result.
+
+### R6: Extend lint_lessons row format validation
+SHOULD extend `lint_lessons()` to verify that data rows (lines starting with `|` after the separator) have exactly 3 pipe-delimited columns matching `LESSONS_ROW_FORMAT`.
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|--------------|------|
+| 1 | `src/pactkit/prompts/workflows.py` | Replace manual scan in SPRINT/HOTFIX/DESIGN with `pactkit next-id` | None | Low |
+| 2 | `src/pactkit/prompts/commands.py` | Replace manual SEC table in Plan 3.2 with `pactkit sec-scope` | None | Low |
+| 3 | `src/pactkit/prompts/commands.py` | Replace manual context write in Plan 3.3 and Init 6 with `pactkit context` | None | Low |
+| 4 | `src/pactkit/cleaners.py` | Align Java cleanup list with LANG_PROFILES | None | Low |
+| 5 | `src/pactkit/guards.py` | Add config completeness check | None | Low |
+| 6 | `src/pactkit/validators.py` | Add LESSONS_ROW_FORMAT column validation | None | Low |
+| 7 | Tests | TDD for Steps 4-6 code changes | Steps 4-6 | Low |
+
+## Acceptance Criteria
+
+### Scenario 1: Sprint/Hotfix/Design call pactkit next-id
+- **Given** the SPRINT_PROMPT, HOTFIX_PROMPT, and DESIGN_PROMPT text
+- **When** searching for "Scan `docs/specs/`" or "determine the next available number"
+- **Then** those phrases are replaced with `pactkit next-id` invocations
+
+### Scenario 2: Plan Phase 3.2 calls pactkit sec-scope
+- **Given** the Plan command prompt text
+- **When** searching Phase 3.2 Security Scope
+- **Then** the text delegates to `pactkit sec-scope` rather than asking the agent to manually apply the detection table
+
+### Scenario 3: Plan and Init call pactkit context
+- **Given** the Plan Phase 3.3 and Init Phase 6 prompt text
+- **When** searching for context.md generation
+- **Then** both delegate to `pactkit context`
+
+### Scenario 4: Java cleanup matches LANG_PROFILES
+- **Given** `cleaners.py` `_CLEANUP_PATTERNS["java"]`
+- **When** compared with `LANG_PROFILES["java"]["cleanup"]`
+- **Then** they are identical: `["target/", "build/", ".gradle/"]`
+
+### Scenario 5: Guards check config completeness
+- **Given** a `pactkit.yaml` missing the `developer` section
+- **When** running `pactkit guard`
+- **Then** the output includes a warning about missing config sections
+
+### Scenario 6: lint_lessons validates row format
+- **Given** a lessons.md with a malformed row `| 2026-01 | lesson only |` (2 columns instead of 3)
+- **When** running `pactkit lint-lessons`
+- **Then** an error is reported about column count mismatch
+
+### Scenario 7: All existing tests pass
+- **Given** all changes applied
+- **When** running `pytest tests/ -v`
+- **Then** 2529+ tests pass with zero failures
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | Source code modified (cleaners.py, guards.py, validators.py) |
+| SEC-2 | No | No user input handling changes |
+| SEC-3 | No | No database operations |
+| SEC-4 | No | No frontend files |
+| SEC-5 | No | No auth/session code |
+| SEC-6 | No | No API endpoints |
+| SEC-7 | No | No error handling changes |
+| SEC-8 | No | No dependency file changes |

pactkit-2.3.0/docs/specs/BUG-slim-004.md

@@ -0,0 +1,103 @@
+# BUG-slim-004: Cross-Flow Integrity Gaps — Unreferenced CLI & Missing Lint in Hotfix
+
+| Field | Value |
+|-------|-------|
+| ID | BUG-slim-004 |
+| Status | Draft |
+| Priority | P2 |
+| Release | 2.2.0 |
+
+## Background
+
+A full end-to-end PDCA workflow audit (Plan→Act→Check→Done→Release, Sprint, Hotfix, Design) revealed 3 categories of cross-flow integrity gaps after the STORY-slim-014/015/016 CLI migration:
+
+1. **Hotfix skips lint entirely** — Plan/Act/Done all reference `pactkit lint`, but Hotfix has no lint step at all. Hotfixed code can merge with lint errors.
+2. **3 document validators never called** — `pactkit lint-context`, `pactkit lint-lessons`, `pactkit lint-testcase` are registered CLI subcommands with full test coverage, but zero prompt references. Done Phase 3 should use them.
+3. **`upgrade` subparser missing `--agent` flag** — `init` and `update` both have `--agent`, but `upgrade` does not, creating a parity gap.
+4. **Check Phase 3.1 duplicates `pactkit spec-lint`** — Check manually inspects "Does Spec have `## Acceptance Criteria`?" but `pactkit spec-lint` E006 already validates this. Should delegate.
+5. **Design missing `pactkit context`** — Plan/Done/Init all call `pactkit context` to update session context, but Design does not. After `/project-design` creates N stories, `context.md` is stale.
+
+### Target Call Chain
+
+```
+Hotfix Phase 2  → (missing) pactkit lint
+Done Phase 3    → (missing) pactkit lint-context, pactkit lint-lessons, pactkit lint-testcase
+cli.py upgrade  → (missing) --agent argument
+Check Phase 3.1 → (duplicate) manual AC check vs pactkit spec-lint E006
+Design Phase 5  → (missing) pactkit context
+```
+
+## Requirements
+
+### R1: Add lint step to Hotfix flow
+MUST update HOTFIX_PROMPT in `workflows.py` to include a lint step after tests pass (Phase 2), referencing `pactkit lint`. This aligns Hotfix with Done Phase 2.7 behavior.
+
+### R2: Reference document validators in Done prompt
+MUST update DONE_PROMPT in `commands.py` to call `pactkit lint-context`, `pactkit lint-lessons` (in Phase 3 Hygiene), validating `docs/product/context.md` and `docs/architecture/governance/lessons.md` structure after writing them. These are non-blocking checks (warn only).
+
+### R3: Add `--agent` flag to `upgrade` subparser
+MUST add the `--agent` argument to `upgrade_parser` in `cli.py` with the same choices as `init`/`update` (`claude`, `cursor`, `copilot`, `generic`, `all`).
+
+### R4: Forward `--agent` in upgrade handler
+MUST forward `args.agent` in the `upgrade` branch of `cli.py` `main()` to `deploy()`. Currently `deploy()` receives `agent` from `init`/`update` branches via `getattr(args, "agent", "claude")` but `upgrade` never sets it.
+
+### R5: Check Phase 3 should use `pactkit spec-lint` for Spec structure verification
+MUST update CHECK_PROMPT Phase 3.1 in `commands.py` to run `pactkit spec-lint docs/specs/{STORY_ID}.md` instead of manually checking "Does Spec have `## Acceptance Criteria`?" The E006 rule already validates this.
+
+### R6: Design must call `pactkit context` after board setup
+MUST update DESIGN_PROMPT in `workflows.py` to call `pactkit context` after Phase 4 (Board Setup), matching the pattern used by Plan (Phase 3.3), Done (Phase 4.5), and Init (Phase 6).
+
+## Acceptance Criteria
+
+### Scenario 1: Hotfix includes lint step
+- **Given** HOTFIX_PROMPT in `workflows.py`
+- **When** reading the Phase 2 section
+- **Then** it contains `pactkit lint` reference after the test step
+
+### Scenario 2: Done references document validators
+- **Given** DONE_PROMPT in `commands.py`
+- **When** reading Phase 3 Hygiene section
+- **Then** it contains `pactkit lint-context` and `pactkit lint-lessons`
+
+### Scenario 3: upgrade has --agent flag
+- **Given** `pactkit upgrade --help`
+- **When** reading help output
+- **Then** `--agent` appears with choices `claude`, `cursor`, `copilot`, `generic`, `all`
+
+### Scenario 5: Check uses spec-lint for Spec structure
+- **Given** CHECK_PROMPT in `commands.py`
+- **When** reading Phase 3.1
+- **Then** it contains `pactkit spec-lint` reference
+
+### Scenario 6: Design updates context.md
+- **Given** DESIGN_PROMPT in `workflows.py`
+- **When** reading after Phase 4
+- **Then** it contains `pactkit context` reference
+
+### Scenario 7: All existing tests pass
+- **Given** all changes applied
+- **When** running `pytest tests/ -v`
+- **Then** all existing tests pass with zero failures
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|--------------|------|
+| 1 | `src/pactkit/prompts/workflows.py` | R1: Add `pactkit lint` to Hotfix Phase 2 | None | Medium |
+| 2 | `src/pactkit/prompts/commands.py` | R2: Add `pactkit lint-context`/`pactkit lint-lessons` to Done Phase 3 | None | Medium |
+| 3 | `src/pactkit/cli.py` | R3+R4: Add `--agent` to upgrade_parser, forward in handler | None | Low |
+| 4 | `src/pactkit/prompts/commands.py` | R5: Add `pactkit spec-lint` to Check Phase 3.1 | None | Low |
+| 5 | `src/pactkit/prompts/workflows.py` | R6: Add `pactkit context` to Design after Phase 4 | None | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | Source code modified |
+| SEC-2 | No | No user input handling |
+| SEC-3 | No | No database operations |
+| SEC-4 | No | No frontend files |
+| SEC-5 | No | No auth/session code |
+| SEC-6 | No | No API endpoints |
+| SEC-7 | No | No new error handling paths |
+| SEC-8 | No | No dependency file changes |