pactkit 2.1.1__tar.gz → 2.3.0__tar.gz

{pactkit-2.1.1 → pactkit-2.3.0}/.gitignore

@@ -30,6 +30,18 @@ Thumbs.db
 docs/architecture/graphs/
 docs/architecture/snapshots/
 
+# PactKit - IP protection (keep locally, not tracked in git)
+# Only BUG-*.md specs are tracked; STORY/HOTFIX contain sensitive design details
+docs/specs/STORY-*.md
+docs/specs/HOTFIX-*.md
+docs/test_cases/STORY-*_case.md
+docs/test_cases/HOTFIX-*_case.md
+docs/product/sprint_board.md
+docs/product/context.md
+docs/product/archive/
+docs/product/prd.md
+docs/architecture/governance/
+
 # Claude Code local config
 .claude/
 

pactkit-2.3.0/.opencode/memory/project.md

@@ -0,0 +1,7 @@
+---
+description: ''
+label: project
+limit: 5000
+read_only: false
+---
+

{pactkit-2.1.1 → pactkit-2.3.0}/.opencode/pactkit.yaml

@@ -2,7 +2,7 @@
 # Edit this file to customize which components are deployed.
 # Remove items from a list to disable them. Default: all enabled.
 
-version: "2.1.1"
+version: "2.2.0"
 stack: python
 root: .
 developer: "slim"
@@ -60,6 +60,10 @@ rules:
 # CI/CD — set provider to github or gitlab to generate pipeline config
 ci:
   provider: github
+  # runner: ubuntu-latest
+  # language_version: "3.11"
+  # github_host: ""  # GHE server (empty = github.com)
+  # actions_ref: ""  # GHE actions prefix
 
 # Issue Tracker — set provider to github to link stories to issues
 issue_tracker:

{pactkit-2.1.1 → pactkit-2.3.0}/AGENTS.md

@@ -65,3 +65,10 @@ src/pactkit/
 
 @./docs/product/context.md
 output MUST use Chinese
+
+## PDCA Execution Lessons
+
+- **/project-done 不要重复跑回归测试**：如果 `/project-act` 阶段刚跑过全量测试且全绿，Done 阶段直接引用该结果，不要再跑一次。只有在 Done 阶段有额外文件修改（非 doc-only）时才重新跑。
+- **大文件一次读完**：`lessons.md` 等治理文件直接一次性读取，不要分多次小范围读取再拼凑。
+- **并行写多个独立文件**：rules.md、lessons.md、context.md、sprint_board.md 的更新互不依赖，应并行执行，不要串行。
+- **流程指令是指导，不是死板清单**：当上下文已经包含某个步骤的结果时（如测试结果、lint 结果），直接复用，不要机械重复执行。

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

@@ -4,6 +4,44 @@ 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
+- **Context-Aware Rule Loading** (STORY-slim-011) — `COMMAND_RULES_MAP` maps each of 11 commands to only the rules it needs, reducing per-command token usage by 20-83%. Classic format uses `@import` injection; OpenCode format embeds rule content inline. Credential safety rule (`09`) is force-injected into every command regardless of configuration.
+- **Stack-Aware CI Pipeline Generation** (STORY-slim-012) — `CI_PROFILES` in `workflows.py` supports Python, Node.js, Go, and Java stacks with correct setup actions, install commands, and test runners. New `pactkit.yaml` CI config fields: `runner`, `language_version`, `github_host`, `actions_ref`.
+- **GitHub Enterprise (GHE) Support** — Explicit `ci.github_host` configuration for GHE Server environments, with `ci.actions_ref` prefix replacement for custom action mirrors. Auto-detection fallback via `_detect_ghe()`.
+- **OpenCode CI Parity** — `_deploy_opencode()` now calls `_deploy_ci()`, ensuring CI pipeline files are generated regardless of deployment format.
+- **CI Status Feedback** — `/project-done` Phase 4 now includes optional CI status check via `gh run list` after push (non-blocking).
+- **GitLab CI Stack-Aware** — GitLab CI templates now use correct Docker images and commands per stack (e.g., `node:20` + `npm ci` for Node projects).
+
+### Changed
+- `_deploy_ci()` refactored from hardcoded Python-only templates to parameterized builders (`_build_github_workflow()`, `_build_gitlab_ci()`).
+- `generate_default_yaml()` now outputs commented CI configuration fields (`runner`, `language_version`, `github_host`, `actions_ref`) for user discoverability.
+- CLAUDE.md no longer contains global rule `@import` directives — rules are now injected at command level.
+- OpenCode `opencode.json` instructions reduced to only `09-credential-safety.md` — other rules injected per-command.
+
 ## [2.1.1] - 2026-03-18
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactkit
-Version: 2.1.1
+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:
 
-AI coding assistants are powerful but unpredictable without structure. PactKit adds a **spec-driven governance layer**:
+```
+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
+```
 
-- **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
+- 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)
+
+> 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
 
@@ -140,6 +158,22 @@ Or run the full cycle in one command:
 | **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
 | **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |
 
+### Role-Based Command Guide
+
+Choose commands based on your role:
+
+| Role | Commands | What You Do |
+|------|----------|-------------|
+| **BA** | `/project-clarify` | Surface ambiguities, produce Clarified Brief |
+| **PM** | `/project-design` | Generate PRD, decompose into Stories |
+| **Architect** | `/project-plan`, `/project-init` | Create Specs, initialize project governance |
+| **Developer** | `/project-act`, `/project-hotfix` | TDD implementation, emergency fixes |
+| **QA** | `/project-check` | Security + quality audit, spec alignment |
+| **DevOps** | `/project-done`, `/project-release`, `/project-pr` | Commit, release, pull request |
+| **Team Lead** | `/project-sprint` | One-command PDCA orchestration (**Claude Code only**) |
+
+> **Solo developer?** Focus on `/project-plan` → `/project-act` → `/project-done`. Other commands become valuable when you have team collaboration or external stakeholders.
+
 ### Embedded Skills (auto-invoked by commands)
 
 | Skill | Embedded In | Purpose |
@@ -190,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:
@@ -198,9 +264,9 @@ PactKit supports two deployment formats:
 
 ```
 ~/.claude/
-├── CLAUDE.md                 <- Modular constitution (entry point with @import)
-├── rules/                    <- 7 rule modules
-├── commands/                 <- 11 command playbooks
+├── CLAUDE.md                 <- Project context entry point
+├── rules/                    <- 8 rule modules (loaded per-command, not globally)
+├── commands/                 <- 11 command playbooks (with per-command rule @imports)
 ├── agents/                   <- 9 agent definitions
 └── skills/                   <- 10 skill packages
 ```
@@ -210,7 +276,7 @@ PactKit supports two deployment formats:
 ```
 ~/.config/opencode/
 ├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
-├── rules/                    <- 8 rule modules (3 core always-load + 5 on-demand)
+├── rules/                    <- 8 rule modules (3 core always-load + 6 on-demand)
 ├── commands/                 <- 11 command playbooks (with model: routing)
 ├── agents/                   <- 9 agent definitions (mode: subagent)
 ├── skills/                   <- 10 skill packages (with SKILL.md frontmatter)
@@ -218,7 +284,7 @@ PactKit supports two deployment formats:
 ```
 
 Key OpenCode differences:
-- **Rules**: Core rules always loaded via `instructions`; on-demand rules via `@reference` in AGENTS.md (lazy loading, -62% tokens)
+- **Rules**: Per-command inline embedding; credential safety always loaded via `instructions` (context-aware loading, -20% to -83% tokens per command)
 - **Agents**: `mode: subagent`, no `name` field, tools as record format
 - **Commands**: `agent: build` + `model: provider/model-id` (model routing)
 - **Config**: `pactkit.yaml` in `.opencode/` (not `.claude/`)
@@ -265,9 +331,9 @@ docs/
 | `agents` | list | all 9 | Agent definitions to deploy |
 | `commands` | list | all 11 | Command playbooks to deploy |
 | `skills` | list | all 10 | Skills to deploy |
-| `rules` | list | all 7 | Constitution rule modules to deploy |
+| `rules` | list | all 8 | Constitution rule modules to deploy |
 | `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
-| `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`) |
+| `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`). Sub-fields: `runner` (default: `ubuntu-latest`), `language_version` (default: auto per stack), `github_host` (GHE server address), `actions_ref` (GHE actions prefix) |
 | `issue_tracker` | object | `provider: none` | External issue tracker (`github`, `none`) |
 | `hooks` | object | disabled | Opt-in hook templates (pre-commit, post-test, pre-push) |
 | `lint_blocking` | bool | `false` | Whether lint failures block commits |
@@ -283,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.1.1 → 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:
 
-AI coding assistants are powerful but unpredictable without structure. PactKit adds a **spec-driven governance layer**:
+```
+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
+```
 
-- **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
+- 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)
+
+> 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
 
@@ -114,6 +132,22 @@ Or run the full cycle in one command:
 | **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
 | **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |
 
+### Role-Based Command Guide
+
+Choose commands based on your role:
+
+| Role | Commands | What You Do |
+|------|----------|-------------|
+| **BA** | `/project-clarify` | Surface ambiguities, produce Clarified Brief |
+| **PM** | `/project-design` | Generate PRD, decompose into Stories |
+| **Architect** | `/project-plan`, `/project-init` | Create Specs, initialize project governance |
+| **Developer** | `/project-act`, `/project-hotfix` | TDD implementation, emergency fixes |
+| **QA** | `/project-check` | Security + quality audit, spec alignment |
+| **DevOps** | `/project-done`, `/project-release`, `/project-pr` | Commit, release, pull request |
+| **Team Lead** | `/project-sprint` | One-command PDCA orchestration (**Claude Code only**) |
+
+> **Solo developer?** Focus on `/project-plan` → `/project-act` → `/project-done`. Other commands become valuable when you have team collaboration or external stakeholders.
+
 ### Embedded Skills (auto-invoked by commands)
 
 | Skill | Embedded In | Purpose |
@@ -164,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:
@@ -172,9 +238,9 @@ PactKit supports two deployment formats:
 
 ```
 ~/.claude/
-├── CLAUDE.md                 <- Modular constitution (entry point with @import)
-├── rules/                    <- 7 rule modules
-├── commands/                 <- 11 command playbooks
+├── CLAUDE.md                 <- Project context entry point
+├── rules/                    <- 8 rule modules (loaded per-command, not globally)
+├── commands/                 <- 11 command playbooks (with per-command rule @imports)
 ├── agents/                   <- 9 agent definitions
 └── skills/                   <- 10 skill packages
 ```
@@ -184,7 +250,7 @@ PactKit supports two deployment formats:
 ```
 ~/.config/opencode/
 ├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
-├── rules/                    <- 8 rule modules (3 core always-load + 5 on-demand)
+├── rules/                    <- 8 rule modules (3 core always-load + 6 on-demand)
 ├── commands/                 <- 11 command playbooks (with model: routing)
 ├── agents/                   <- 9 agent definitions (mode: subagent)
 ├── skills/                   <- 10 skill packages (with SKILL.md frontmatter)
@@ -192,7 +258,7 @@ PactKit supports two deployment formats:
 ```
 
 Key OpenCode differences:
-- **Rules**: Core rules always loaded via `instructions`; on-demand rules via `@reference` in AGENTS.md (lazy loading, -62% tokens)
+- **Rules**: Per-command inline embedding; credential safety always loaded via `instructions` (context-aware loading, -20% to -83% tokens per command)
 - **Agents**: `mode: subagent`, no `name` field, tools as record format
 - **Commands**: `agent: build` + `model: provider/model-id` (model routing)
 - **Config**: `pactkit.yaml` in `.opencode/` (not `.claude/`)
@@ -239,9 +305,9 @@ docs/
 | `agents` | list | all 9 | Agent definitions to deploy |
 | `commands` | list | all 11 | Command playbooks to deploy |
 | `skills` | list | all 10 | Skills to deploy |
-| `rules` | list | all 7 | Constitution rule modules to deploy |
+| `rules` | list | all 8 | Constitution rule modules to deploy |
 | `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
-| `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`) |
+| `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`). Sub-fields: `runner` (default: `ubuntu-latest`), `language_version` (default: auto per stack), `github_host` (GHE server address), `actions_ref` (GHE actions prefix) |
 | `issue_tracker` | object | `provider: none` | External issue tracker (`github`, `none`) |
 | `hooks` | object | disabled | Opt-in hook templates (pre-commit, post-test, pre-push) |
 | `lint_blocking` | bool | `false` | Whether lint failures block commits |
@@ -257,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.1.1 → 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.1.1 → 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 |