pactkit 2.16.0__tar.gz → 2.17.0__tar.gz

{pactkit-2.16.0 → pactkit-2.17.0}/.github/workflows/pactkit.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          pip install -e ".[visualize]"
           pip install pytest ruff
           pactkit init
 

{pactkit-2.16.0 → pactkit-2.17.0}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.17.0] - 2026-08-13
+
+### Added
+- **`pactkit done-verify`** (STORY-slim-136) — Mechanical archive-honesty gate for `/project-done`. Verifies requirement→test evidence chains, checkbox↔case-file consistency (with code-span stripping), zero-production-caller components (WARN), and Spec/Board/archive status consistency. Any FAIL blocks archiving and commit (exit 1). Wired into project-done Phase 3 as a mandatory step.
+- **`pactkit commit-gate`** (STORY-slim-138, STORY-slim-140) — Pre-commit test gate with skip≠pass transparency (passed/failed/skipped reported separately; skips always listed). Two channels sharing one pipeline: Claude Code PreToolUse hook (auto-installed into `.claude/settings.json` by init/update) and git pre-commit (auto-installed for non-Claude formats). Self-lock protection: gate-internal failures always allow with a loud WARN. Direct commits on main/master/develop force the full unit suite.
+- **`pactkit deps check/install`** (STORY-slim-137) — External dependency registry (node/codegraph/gh) with platform-aware guided install. `pactkit init` CLI only reports (CI/air-gap safe); `/project-init` Phase 1.5 asks before installing. `enterprise.no_external` refuses installs.
+- **`pactkit schema config`** (STORY-slim-135) — Discoverability report for every pactkit.yaml key: default, effective value, and source file.
+- **Deployment parity check in `pactkit doctor`** (STORY-slim-139) — Every deploy writes `.pactkit-deployed.json`; doctor compares per-format manifests against the registry and FormatProfile capability matrix, turning silent deployment drift into explicit `Deployed drift:` reports.
+
+### Changed
+- **Schema-driven pactkit.yaml** (STORY-slim-135) — `CONFIG_SCHEMA` is now the single source for defaults, validation, deep-merge behavior, and rendering. Fresh `pactkit init` writes a minimal yaml (stack + developer only) instead of a 94-line default wall; absent keys resolve through defaults. Multi-copy sync keeps `.claude`/`.codex`/`.github`/`.opencode` copies identical (canonical = `.claude` first); doctor reports copy drift.
+- **Skill deployment single source** (STORY-slim-139) — `SKILL_MANIFEST` + public `get_skill_manifest()` contract; codex/copilot adapters consume it (restoring pactkit-garden/audit/report which a stale hardcoded list had silently dropped), opencode already conformant.
+- **Rule map migration** — `COMMAND_RULES_MAP` keys migrated to the merged `pactkit` rule file; inline embedding no longer duplicates globally-loaded constitution content per command.
+
+### Fixed
+- **Codex adapter never touches an existing `config.toml`** — after two wipe incidents (custom TOML writer stringified arrays; parse-failure path rewrote managed-only content), the policy is now create-if-absent only. Existing files stay byte-identical.
+- **OpenCode global instructions** — the merge logic no longer strips `rules/pactkit.md` from the always-load layer.
+- **`install_git_hook` idempotency** — re-running no longer clobbers chained third-party pre-commit hooks.
+- **Config copy precedence incident** — canonical selection uses explicit preference order, not key-count heuristics (an inflated default-wall copy could otherwise overwrite hand-curated config).
+
+## [2.16.1] - 2026-07-23
+
+### Fixed
+- **Bedrock VS Code plugin model compatibility** (STORY-slim-134) — Removed `model:` field from all `/project-*` command frontmatter. Claude Code was resolving `model: sonnet/opus` to Anthropic's latest model ID (e.g., `us.anthropic.claude-sonnet-4-5-20250929-v1:0`), bypassing `ANTHROPIC_DEFAULT_SONNET_MODEL` env var in VS Code plugin environments. Commands now inherit the session default model set by the user's provider env vars.
+
 ## [2.16.0] - 2026-07-13
 
 ### Added

{pactkit-2.16.0 → pactkit-2.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pactkit
-Version: 2.16.0
+Version: 2.17.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
@@ -130,7 +130,7 @@ pip install pactkit[all]         # Everything above + IDE adapters
 
 ### Recommended External Tools
 
-These tools enhance PactKit but cannot be distributed via pip:
+These tools enhance PactKit but cannot be distributed via pip. Run `pactkit deps check` to see what's missing and `pactkit deps install` for guided platform-aware installation:
 
 | Tool | Purpose | Install |
 |------|---------|---------|
@@ -280,7 +280,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 ## CLI Subcommands
 
-PactKit ships 26 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+PactKit ships 36 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 |
 |---------|---------|
@@ -310,6 +310,11 @@ PactKit ships 26 deterministic CLI subcommands — operations that were previous
 | `pactkit lint-context` | Validate context.md structure |
 | `pactkit lint-lessons` | Validate lessons.md structure |
 | `pactkit lint-testcase` | Validate test case structure |
+| `pactkit done-verify` | Archive honesty gate: requirement→test evidence chain, checkbox↔case consistency, status machine (blocks `/project-done` on FAIL) |
+| `pactkit commit-gate` | Pre-commit test gate with skip≠pass transparency; PreToolUse hook + git pre-commit channels, auto-installed per format |
+| `pactkit deps` | External dependency check (`deps check`) and guided install (`deps install`) for node/codegraph/gh |
+| `pactkit schema config` | List every pactkit.yaml key with default, effective value, and source |
+| `pactkit sync` | Sync codegraph index |
 
 ## Deployment Architecture
 

{pactkit-2.16.0 → pactkit-2.17.0}/README.md

@@ -85,7 +85,7 @@ pip install pactkit[all]         # Everything above + IDE adapters
 
 ### Recommended External Tools
 
-These tools enhance PactKit but cannot be distributed via pip:
+These tools enhance PactKit but cannot be distributed via pip. Run `pactkit deps check` to see what's missing and `pactkit deps install` for guided platform-aware installation:
 
 | Tool | Purpose | Install |
 |------|---------|---------|
@@ -235,7 +235,7 @@ PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands
 
 ## CLI Subcommands
 
-PactKit ships 26 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):
+PactKit ships 36 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 |
 |---------|---------|
@@ -265,6 +265,11 @@ PactKit ships 26 deterministic CLI subcommands — operations that were previous
 | `pactkit lint-context` | Validate context.md structure |
 | `pactkit lint-lessons` | Validate lessons.md structure |
 | `pactkit lint-testcase` | Validate test case structure |
+| `pactkit done-verify` | Archive honesty gate: requirement→test evidence chain, checkbox↔case consistency, status machine (blocks `/project-done` on FAIL) |
+| `pactkit commit-gate` | Pre-commit test gate with skip≠pass transparency; PreToolUse hook + git pre-commit channels, auto-installed per format |
+| `pactkit deps` | External dependency check (`deps check`) and guided install (`deps install`) for node/codegraph/gh |
+| `pactkit schema config` | List every pactkit.yaml key with default, effective value, and source |
+| `pactkit sync` | Sync codegraph index |
 
 ## Deployment Architecture
 

{pactkit-2.16.0 → pactkit-2.17.0}/docs/architecture/governance/archive/lessons_archive_202603.md

@@ -67,3 +67,7 @@
 | 2026-03-26 | Thin adapter conversion: pactkit-codex reduced from 15,356 lines (full fork) to 668 lines (thin adapter) by importing core via DeployerBase. Key: deploy_codex_playbooks needs explicit path replacement for ALL format prefixes (~/.claude/, ~/.config/opencode/ → ~/.codex/) | pactkit_codex/deployer.py:deploy_codex_playbooks |
 | 2026-03-27 | When migrating commands to skills (subdir/SKILL.md format), all path assertions in pre-existing tests must be updated in the same commit — 17 tests broke because they asserted flat commands/*.md paths | deployer.py:_deploy_commands |
 | 2026-03-30 | Frontend API path convention bugs are structurally preventable: ApiCallParser+api_convention_summary in trace phase surfaces prefix/wrapper conventions before implementation, eliminating a class of copy-paste path errors | visualize.py:ApiCallParser |
+| 2026-03-31 | Rendering-only changes to visualize.py can be isolated by extracting a shared render helper (_render_nested_call_graph) that both forward and reverse BFS call — keeps AST parsing untouched | visualize.py:_render_nested_call_graph |
+| 2026-03-31 | dict.update() on call_edges causes last-wins overwrite when scanning same-name functions across files; use extend-merge pattern instead | visualize.py:_build_call_graph |
+| 2026-03-31 | CLI args must mirror visualize.py standalone argparse; feature implemented in visualize.py but not exposed in cli.py is effectively dead code | cli.py:viz_parser |
+| 2026-03-31 | tree-sitter comment nodes are direct children of function body nodes (block/statement_block), enabling scoped dispatch hint queries without parent traversal. Per-language comment query needed: Go/TS use (comment), Java uses [(line_comment)(block_comment)]. | visualize.py:_extract_calls_from_body |

{pactkit-2.16.0 → pactkit-2.17.0}/docs/architecture/governance/lessons.md

@@ -2,10 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 2026-03-31 | Rendering-only changes to visualize.py can be isolated by extracting a shared render helper (_render_nested_call_graph) that both forward and reverse BFS call — keeps AST parsing untouched | visualize.py:_render_nested_call_graph |
-| 2026-03-31 | dict.update() on call_edges causes last-wins overwrite when scanning same-name functions across files; use extend-merge pattern instead | visualize.py:_build_call_graph |
-| 2026-03-31 | CLI args must mirror visualize.py standalone argparse; feature implemented in visualize.py but not exposed in cli.py is effectively dead code | cli.py:viz_parser |
-| 2026-03-31 | tree-sitter comment nodes are direct children of function body nodes (block/statement_block), enabling scoped dispatch hint queries without parent traversal. Per-language comment query needed: Go/TS use (comment), Java uses [(line_comment)(block_comment)]. | visualize.py:_extract_calls_from_body |
 | 2026-03-31 | config.py load_config() deep merge was single-level; adding check.pactguard (nested dict inside check) required upgrading to two-level merge to preserve sub-dict defaults like mode and blocking | src/pactkit/config.py:load_config |
 | 2026-03-31 | Adding pactkit-garden to VALID_SKILLS broke 5 hardcoded count assertions in test_config.py, test_pdca_slim.py, test_selective_deploy.py, test_prompt_structural_invariants.py, test_story_slim063.py — grep == 21 and == 10 in tests before releasing a new skill | tests/unit/test_pdca_slim.py:test_valid_skills_count |
 | 2026-03-31 | DETECTED_ENV in commands.py init playbook was unnecessary — _render_prompt(template, profile) already resolves per-format at deploy time. Added FORMAT_NAME to deployer.py var_map to enable pactkit init --format {FORMAT_NAME}. | deployer.py:_render_prompt |
@@ -53,3 +49,7 @@
 | 2026-06-29 | Large @inject rules (architecture 11KB, solution 8.4KB, engineering 4.3KB) removed from COMMAND_RULES_MAP — loaded on-demand via Read in playbooks. Saves ~12,500 tokens/PDCA session. | src/pactkit/prompts/rules.py:COMMAND_RULES_MAP |
 | 2026-07-02 | Hardcoding external tool CLI commands in SKILL_VISUALIZE_MD and deployer.py creates upgrade coupling — replaced with codegraph --help runtime discovery in _build_claude_md_managed_content() | src/pactkit/generators/deployer.py:_build_claude_md_managed_content |
 | 2026-07-13 | Adding project-debug required updating VALID_COMMANDS in config.py, VALID_SKILLS, COMMANDS_CONTENT registration in commands.py, and COMMAND_RULES_MAP in rules.py — plus 6 test files with hardcoded count assertions | src/pactkit/config.py:VALID_COMMANDS, src/pactkit/prompts/rules.py:COMMAND_RULES_MAP |
+| 2026-07-23 | Removing `model:` from COMMANDS_CONTENT frontmatter fixes Bedrock VS Code plugin errors — Claude Code resolves the alias to Anthropic's latest model ID, bypassing `ANTHROPIC_DEFAULT_SONNET_MODEL`; without it, commands inherit the session default model set by the user's env vars | src/pactkit/prompts/commands.py:COMMANDS_CONTENT |
+| 2026-08-13 | guardrail 测试（行数/字符数上限）触线时，优先把组装逻辑上移到 CLI 组合层而不是抬阈值——deployer 保持精简，init/update 的副作用归 cli 编排 | cli.py:init/update post-deploy housekeeping |
+| 2026-08-13 | 配置副本同步 canonical 不能用键数启发式（默认值墙副本键数多但意图少，会覆盖手工配置），必须用显式优先级——见 config.py:sync_config_copies 的 CANONICAL_PREFERENCE | config.py:sync_config_copies |
+| 2026-08-13 | 门禁词表扫描须先剥离 code fence/inline code span（done_verify.py:_strip_code_spans），否则词表元讨论自身误报 | done_verify.py:_strip_code_spans |

{pactkit-2.16.0 → pactkit-2.17.0}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4037+ tests must pass before any commit to `main`.
+1. All 4124+ 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.16.0 → pactkit-2.17.0}/docs/product/archive/archive_202607.md

@@ -18,3 +18,11 @@
 - [x] Create SKILL.md protocol with all phases
 - [x] Add to routing table in pactkit.md
 - [x] Register in available-skills list
+
+### [STORY-slim-134] remove model field from command frontmatter
+> Spec: docs/specs/STORY-slim-134.md
+
+- [x] 删除 commands.py frontmatter model 字段
+- [x] 删除 workflows.py frontmatter model 字段
+- [x] 运行测试套件
+- [x] redeploy plugin artifact

pactkit-2.17.0/docs/product/archive/archive_202608.md

@@ -0,0 +1,50 @@
+
+### [STORY-slim-137] pactkit deps: external dependency check and guided install
+> Spec: docs/specs/STORY-slim-137.md
+
+- [x] deps.py 注册表+check/install
+- [x] CLI 子命令+init 只读摘要+doctor 健康项
+- [x] project-init Phase 1.5 接线+plugin 同步
+- [x] mock 单测
+
+### [STORY-slim-138] pactkit commit-gate: pre-commit test gate with skip transparency
+> Spec: docs/specs/STORY-slim-138.md
+
+- [x] commit_gate.py 判定逻辑(regression+test-map+pytest -rs)
+- [x] --hook PreToolUse 模式+自锁防护
+- [x] settings.json hook 幂等部署+--git-hook
+- [x] mock/fixture 单测
+
+### [STORY-slim-136] pactkit done-verify: mechanical archive honesty gate
+> Spec: docs/specs/STORY-slim-136.md
+
+- [x] done_verify 模块: R项证据链+勾选诚实性+状态机核验
+- [x] 接线验证(零生产调用方 WARN)
+- [x] CLI 子命令注册
+- [x] project-done playbook 强制接线+plugin 同步
+- [x] 单测覆盖 AC2-AC5 场景
+
+### [STORY-slim-135] Schema-driven pactkit.yaml governance: minimal init, single renderer, drift detection
+> Spec: docs/specs/STORY-slim-135.md
+
+- [x] 引入 CONFIG_SCHEMA registry
+- [x] 渲染器收敛+init 极简输出
+- [x] pactkit schema config 可发现性
+- [x] 多副本同步写入+doctor 漂移检测
+- [x] golden 等价性测试+全量回归
+
+### [STORY-slim-140] commit-gate git-hook fallback for non-Claude environments
+> Spec: docs/specs/STORY-slim-140.md
+
+- [x] cli post-deploy 格式分派(无 classic→自动 git hook)
+- [x] 门禁通道状态输出
+- [x] 幂等/链式/no_git 单测
+
+### [STORY-slim-139] Skill manifest single source + adapter parity check
+> Spec: docs/specs/STORY-slim-139.md
+
+- [x] SKILL_MANIFEST 注册表+get_skill_manifest()
+- [x] _deploy_skills 迭代化+.pactkit-deployed.json 落盘
+- [x] doctor parity 检查(能力矩阵感知)
+- [x] 跨仓: pactkit-codex 消费契约+版本 bump
+- [x] 单测

pactkit-2.17.0/docs/product/context.md

@@ -0,0 +1,29 @@
+# Project Context (Auto-generated)
+> Last updated: 2026-08-13T17:47:41+08:00 by pactkit context
+
+## Sprint Status
+Backlog: 5 | In Progress: 0 | Done: 0 stories
+
+## Current Stories
+None
+
+## Recent Completions
+None
+
+## Active Branches
++ claude/naughty-euclid-e6a787
+  develop
+* main
+
+## Key Decisions
+- Adding project-debug required updating VALID_COMMANDS in config.py, VALID_SKILLS, COMMANDS_CONTENT registration in commands.py, and COMMAND_RULES_MAP in rules.py — plus 6 test files with hardcoded count assertions
+- Removing `model:` from COMMANDS_CONTENT frontmatter fixes Bedrock VS Code plugin errors — Claude Code resolves the alias to Anthropic's latest model ID, bypassing `ANTHROPIC_DEFAULT_SONNET_MODEL`; without it, commands inherit the session default model set by the user's env vars
+- guardrail 测试（行数/字符数上限）触线时，优先把组装逻辑上移到 CLI 组合层而不是抬阈值——deployer 保持精简，init/update 的副作用归 cli 编排
+- 配置副本同步 canonical 不能用键数启发式（默认值墙副本键数多但意图少，会覆盖手工配置），必须用显式优先级——见 config.py:sync_config_copies 的 CANONICAL_PREFERENCE
+- 门禁词表扫描须先剥离 code fence/inline code span（done_verify.py:_strip_code_spans），否则词表元讨论自身误报
+
+## Next Recommended Action
+`/project-plan`
+
+## Agent Continuation
+No active work session.

pactkit-2.17.0/docs/specs/STORY-slim-125.md

@@ -0,0 +1,72 @@
+# STORY-slim-125: Add model frontmatter to all PDCA command/skill prompts
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-125 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.14.0 |
+
+## Background
+
+Originally (v2.14.0), all PDCA command frontmatter included a `model:` field to ensure consistent model routing. However, this caused breakage in enterprise Bedrock deployments: Claude Code resolves `model: sonnet` to the latest Anthropic model ID (e.g., `us.anthropic.claude-sonnet-4-5-20250929-v1:0`), which may not be available in a user's Bedrock deployment.
+
+Superseded by STORY-slim-134 (v2.17.0): the `model:` field is removed from all command frontmatter. Commands now inherit the user's session-level default model, which is controlled by environment variables (`ANTHROPIC_DEFAULT_SONNET_MODEL`, etc.) that the user configures for their provider.
+
+## Requirements
+
+### R1: No PDCA command has model frontmatter (MUST)
+
+No command/skill prompt in `src/pactkit/prompts/commands.py` or `src/pactkit/prompts/workflows.py` MUST include a `model:` field in its frontmatter block. Commands inherit the session default model.
+
+### R2: Deploy produces no model field in SKILL.md (MUST)
+
+After `pactkit update`, no deployed `~/.claude/skills/project-*/SKILL.md` MUST contain a `model:` line in its YAML frontmatter.
+
+## Acceptance Criteria
+
+### AC1: No command has model field (R1)
+
+- **Given** the source prompts in `commands.py` and `workflows.py`
+- **When** their frontmatter is parsed
+- **Then** no command prompt contains a `model:` field
+
+### AC2: Deploy produces no model in SKILL.md (R2)
+
+- **Given** `pactkit update` is run
+- **When** deployed SKILL.md files are inspected
+- **Then** no `project-*` skill contains `model:` in frontmatter
+
+### AC3: project-design has no model field (R1)
+
+- **Given** the `project-design` prompt in `workflows.py`
+- **When** its frontmatter is read
+- **Then** no `model:` field is present
+
+## Target Call Chain
+
+```
+commands.py / workflows.py (prompt string with frontmatter)
+  → deployer.py _deploy_skills()
+    → writes ~/.claude/skills/project-*/SKILL.md
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/commands.py` | Add `model: sonnet` to check, done, clarify, init, release, pr frontmatter | None | Low |
+| 2 | `src/pactkit/prompts/workflows.py` | Add `model: sonnet` to sprint, hotfix; `model: opus` to design | None | Low |
+| 3 | `tests/unit/` | Test that all command prompts have model field | Steps 1-2 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 through SEC-8 | N/A | Prompt-only changes, no user input, no external systems |
+
+## Out of Scope
+
+- Changing embedded skill models (pactkit-trace, pactkit-draw, etc.) — already assigned
+- Validating model availability at runtime (Claude Code handles gracefully)
+- Adding model field to agent definitions (separate mechanism via `agent_models` config)

pactkit-2.17.0/docs/specs/STORY-slim-134.md

@@ -0,0 +1,102 @@
+# STORY-slim-134: remove model field from command frontmatter
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-134 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.17.0 |
+
+## Background
+
+Claude Code 在读取 command frontmatter 中的 `model: sonnet` / `model: opus` 字段时，会将 alias 解析成 Anthropic 官方最新的 model ID（如 `us.anthropic.claude-sonnet-4-5-20250929-v1:0`）。但企业用户通过 Bedrock 代理（如 genai-nexus）接入时，其部署往往只启用了较旧版本的模型，导致 VS Code 插件环境下所有 `/project-*` 命令都因模型不可用而报错。
+
+移除 frontmatter 中的 `model:` 字段后，command 会继承用户当前 session 的默认模型（由用户的 `ANTHROPIC_DEFAULT_SONNET_MODEL` 等环境变量或 Claude Code 设置控制），不再主动切换，从而避免 Bedrock 兼容性问题。
+
+## Requirements
+
+### R1: 移除 prompts/commands.py 中的 model 字段 (MUST)
+
+删除 `src/pactkit/prompts/commands.py` 中所有 command 字符串 frontmatter 里的 `model:` 行。涉及 9 处（`model: opus` × 2，`model: sonnet` × 7）。
+
+### R2: 移除 prompts/workflows.py 中的 model 字段 (MUST)
+
+删除 `src/pactkit/prompts/workflows.py` 中所有 command 字符串 frontmatter 里的 `model:` 行。涉及 4 处（`model: opus` × 1，`model: sonnet` × 3）。
+
+### R3: 同步更新 pactkit-plugin/commands/ (MUST)
+
+执行 `pactkit deploy --format plugin` 重新生成 `pactkit-plugin/commands/*.md`，确保 generated artifact 与 source 一致。
+
+### R4: 不影响 sprint 内联 model 引用 (MUST NOT)
+
+`workflows.py` 中 sprint 命令正文里对 `model: sonnet` 的**文本说明**（如 `A1 model: opus`）不得修改——这些是给 LLM 读的 prompt 指令，不是 frontmatter 字段。
+
+## Acceptance Criteria
+
+### AC1: commands.py 无 model 字段 (R1)
+
+- **Given** `src/pactkit/prompts/commands.py` 中各 command 字符串的 YAML frontmatter
+- **When** 检查每个 `---` 块内的字段列表
+- **Then** 不存在任何 `model:` 行；`description:` 和 `allowed-tools:` 字段保持不变
+
+### AC2: workflows.py 无 model 字段 (R2)
+
+- **Given** `src/pactkit/prompts/workflows.py` 中各 command 字符串的 YAML frontmatter
+- **When** 检查每个 `---` 块内的字段列表
+- **Then** 不存在任何 `model:` 行；正文中对模型的文字引用保持不变
+
+### AC3: plugin artifact 与 source 一致 (R3)
+
+- **Given** R1/R2 修改完成后执行 `pactkit deploy --format plugin`
+- **When** 检查 `pactkit-plugin/commands/*.md` 各文件的 frontmatter
+- **Then** 所有文件 frontmatter 中均无 `model:` 字段
+
+### AC5: sprint 正文模型引用不变 (R4)
+
+- **Given** R1/R2 修改完成
+- **When** 检查 `workflows.py` 中 sprint 命令正文（非 frontmatter）的内容
+- **Then** `A1 (system-architect, model: opus)`、`A2 (senior-developer, model: sonnet)` 等文字说明保持不变
+
+### AC4: 测试套件全通过 (R1-R4)
+
+- **Given** 修改完成
+- **When** 运行 `.venv/bin/pytest tests/ -v`
+- **Then** 所有测试通过，无新失败
+
+## Target Call Chain
+
+```
+src/pactkit/prompts/commands.py (COMMANDS_CONTENT 字符串常量，含 model: 字段)
+src/pactkit/prompts/workflows.py (SPRINT_PROMPT / HOTFIX_PROMPT 等，含 model: 字段)
+  → deployer._deploy_commands() — 原样写出字符串到文件
+  → pactkit-plugin/commands/*.md (generated artifact)
+  → Claude Code frontmatter 解析 → model alias → Bedrock model ID
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/prompts/commands.py` | 删除所有 frontmatter 中的 `model:` 行（9 处） | None | Low |
+| 2 | `src/pactkit/prompts/workflows.py` | 删除所有 frontmatter 中的 `model:` 行（4 处） | Step 1 | Low |
+| 3 | 运行测试 | `.venv/bin/pytest tests/ -v` 确保无回归 | Step 1-2 | Low |
+| 4 | `pactkit-plugin/commands/` | `pactkit deploy --format plugin` 重新生成 artifact | Step 1-2 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | N/A | 仅删除字符串字段，无新代码逻辑引入 |
+| SEC-2 | N/A | 无输入处理变更 |
+| SEC-3 | N/A | 无数据库相关 |
+| SEC-4 | N/A | 无前端文件 |
+| SEC-5 | N/A | 无认证/会话逻辑变更 |
+| SEC-6 | N/A | 无 API/路由变更 |
+| SEC-7 | N/A | 无错误处理变更 |
+| SEC-8 | N/A | 无依赖变更 |
+
+## Out of Scope
+
+- 不修改 `deployer.py` 中的 frontmatter 处理逻辑
+- 不为用户提供 model fallback 配置机制（该需求已明确放弃）
+- 不修改 sprint/hotfix 正文中对模型的文字说明（R4）

pactkit-2.17.0/docs/specs/STORY-slim-135.md

@@ -0,0 +1,134 @@
+# STORY-slim-135: Schema-driven pactkit.yaml governance: minimal init, single renderer, drift detection
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-135 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.17.0 |
+
+## Background
+
+pactkit.yaml 治理存在三个实测病灶（2026-08-13 全部在本仓库实锤）：
+
+1. **init 生成"默认值墙"**：`generate_default_yaml()` 给新项目倾泻 94 行配置，其中约 90 行是 `provider: none` / `enabled: false` / 默认阈值，用户真正要配的只有 `stack` + `developer` 两行。这与 STORY-slim-126 确立的方向（"缺失 key = 接受默认，保持 yaml 极简"，`auto_merge_config_file` 已停止回填）直接矛盾——合并侧说极简，脚手架侧说全量。更隐蔽的害处：init 把默认值显式固化进文件后，PactKit 日后调优默认值时存量项目永远拿着旧值（配置漂移温床）。
+
+2. **渲染逻辑双写（DRY 违反）**：`generate_default_yaml()` 与 `_rewrite_yaml()` 各自手写逐段渲染（ci/check/pactguard/observe/e2e/visualize…），注释文案都不一致。新增一个配置键需改 5~6 处：`get_default_config` → `DEEP_MERGE_KEYS` → `KNOWN_KEYS` → `_rewrite_yaml` → `generate_default_yaml` → `validate_config`，违反 Open-Closed 与 No Magic Values。
+
+3. **多副本漂移 + 静默优先级**：本项目同时存在 `.claude/`、`.codex/`、`.github/` 三份 pactkit.yaml，内容互不一致（`.codex` 副本 `developer: ""`，`.github` 副本残留 `version: 0.0.1`）。`find_pactkit_yaml()` 按 opencode > codex > copilot > classic 顺序取第一个命中，导致 `pactkit next-id` 静默读到 codex 副本、丢失 `slim` 前缀，输出 `STORY-074` 而非 `STORY-slim-135`——无任何告警。
+
+## Requirements
+
+### R1: CONFIG_SCHEMA 声明式注册表 (MUST)
+
+在 `src/pactkit/config.py` 引入单一 `CONFIG_SCHEMA` registry：每个配置键一条声明式条目，包含 `default`、`deep_merge`（bool）、`comment`（yaml 段落注释文案）、`validator`（校验函数）。`get_default_config()`、`validate_config()`、yaml 渲染全部改为由 `CONFIG_SCHEMA` 驱动生成——新增配置键 MUST 只需新增一条 registry 条目，不得再触碰多个函数体。
+
+### R2: init 只生成 stack + developer (MUST)
+
+`generate_default_yaml()` 的输出 MUST 只包含：文件头注释（含"运行 `pactkit schema config` 查看全部可配项"的指引）、`stack`、`developer`。不得输出 ci / issue_tracker / lint / venv / release / regression / check / done / e2e / visualize / command_models 等默认值段。默认值解析继续由 `load_config()` 合并完成，行为不变。
+
+### R3: 单一渲染器 (MUST)
+
+`_rewrite_yaml()` 与 `generate_default_yaml()` 的手写逐段渲染 MUST 收敛为同一个 schema 驱动的渲染函数。`auto_merge_config_file()`、`update_yaml_stack()` 重写 yaml 时复用同一渲染器；用户已有的显式配置键和值 MUST 原样保留（含未知键的 Custom 段，即 BUG-023 行为）。
+
+### R4: 多副本一致性治理 (MUST)
+
+- `pactkit init` / `pactkit update` 写配置时，MUST 将同一 canonical 内容同步到所有已存在的副本路径（`.claude/`、`.codex/`、`.github/`、`.opencode/`），消除静默漂移。
+- `pactkit doctor` MUST 新增副本漂移检测：多个副本的关键键（`stack`、`developer`）不一致时报告并给出修复建议。
+- `find_pactkit_yaml()` 的命中优先级 MUST 在 `pactkit schema config` 输出中可见，消除"静默读到非预期副本"。
+
+### R5: `pactkit schema config` 可发现性 (MUST)
+
+`pactkit schema` 新增 `config` 类型：输出全部可配键、默认值、当前生效值（merge 后）、来源（default / 哪个副本文件）。这是 R2 极简化的配套——用户改配置前能查到全部选项。
+
+### R6: 解析行为零回归 (MUST NOT)
+
+`load_config()` 对所有现有配置键的合并结果 MUST NOT 改变。对以下 fixture 集合的 merge 结果 MUST 与重构前逐键一致：94 行老版全量 yaml、本项目当前三份副本、空文件、仅含 `stack` 的极简文件、含未知自定义键的文件。
+
+## Acceptance Criteria
+
+### AC1: 新 init yaml 极简 (R2)
+
+- **Given** 在空目录执行 `pactkit init --format classic --non-interactive`
+- **When** 读取生成的 `.claude/pactkit.yaml`
+- **Then** 文件仅含头部注释 + `stack` + `developer`（≤ 12 行）；不存在 `check:`、`e2e:`、`visualize:`、`regression:` 等默认值段
+
+### AC2: schema 单一事实源 (R1, R3)
+
+- **Given** 重构完成后的 `src/pactkit/config.py`
+- **When** 检查 `get_default_config()`、`validate_config()`、渲染函数的实现
+- **Then** 三者均由 `CONFIG_SCHEMA` 驱动；代码中不再存在逐键手写的默认值字典、逐段手写的 yaml 渲染分支
+
+### AC3: 解析等价性 golden 测试 (R6)
+
+- **Given** fixture 集合：94 行老版 yaml、本项目三份当前副本、空文件、极简 yaml、含未知键 yaml
+- **When** 用重构后的 `load_config()` 加载并合并
+- **Then** 每个 fixture 的 merged dict 与重构前基准（重构时先固化快照）逐键一致
+
+### AC4: 重写路径统一渲染 (R3)
+
+- **Given** 一份显式自定义过的 pactkit.yaml（含自定义键 + 部分显式段）
+- **When** 执行 `pactkit update`（触发 auto_merge）和 `pactkit redetect-stack`
+- **Then** 重写后的文件保留全部用户显式键值；段落渲染与 init 输出同源（同一渲染函数）
+
+### AC5: 副本漂移被检测并修复 (R4)
+
+- **Given** 人为构造 `.claude/pactkit.yaml`（`developer: "slim"`）与 `.codex/pactkit.yaml`（`developer: ""`）不一致
+- **When** 执行 `pactkit doctor`，再执行 `pactkit update`
+- **Then** doctor 报告副本漂移及冲突键；update 后所有已存在副本内容一致，`pactkit next-id` 输出带 `slim` 前缀的 ID
+
+### AC6: schema config 可查全部键 (R5)
+
+- **Given** 本项目任意 pactkit.yaml
+- **When** 执行 `pactkit schema config`
+- **Then** 输出覆盖 `CONFIG_SCHEMA` 全部条目，每条含默认值、当前生效值、来源（default 或具体副本路径）
+
+### AC7: 测试套件全通过 (R1-R6)
+
+- **Given** 全部修改完成
+- **When** 运行 `.venv/bin/pytest tests/ -v`
+- **Then** 所有测试通过，无新失败
+
+## Target Call Chain
+
+```
+pactkit init → deployer._generate_pactkit_yaml() → config.generate_default_yaml(stack)
+pactkit update → deployer → config.auto_merge_config_file() → config._rewrite_yaml()
+pactkit redetect-stack → config.update_yaml_stack() → config._rewrite_yaml()
+pactkit {next-id,audit,doctor,observe,lint,...} → config.load_config()
+    ← find_pactkit_yaml() (PACTKIT_YAML_CANDIDATES 优先级: opencode > codex > copilot > classic)
+    ← get_default_config() + DEEP_MERGE_KEYS 深合并
+pactkit schema config (新) → CONFIG_SCHEMA + load_config() 生效值解析
+```
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `src/pactkit/config.py` | 引入 CONFIG_SCHEMA registry（每键 default/deep_merge/comment/validator） | None | Medium |
+| 2 | `src/pactkit/config.py` | get_default_config / validate_config 改为 schema 驱动；先固化现有 fixture 的 merge 快照作为 golden 基准 | Step 1 | High（行为回归风险，靠 AC3 golden 测试兜底） |
+| 3 | `src/pactkit/config.py` | 渲染器收敛：schema 驱动 render_config_yaml()，_rewrite_yaml / generate_default_yaml 复用；init 输出砍到 stack+developer | Step 1 | Medium |
+| 4 | `src/pactkit/schemas.py` + `cli.py` | schema 命令新增 config 类型（键/默认值/生效值/来源） | Step 1-2 | Low |
+| 5 | `src/pactkit/generators/deployer.py` | init/update 同步写所有已存在副本 | Step 3 | Medium |
+| 6 | `src/pactkit/doctor.py` | 新增副本漂移检测 | Step 5 | Low |
+| 7 | `tests/unit/` | CONFIG_SCHEMA 单测 + AC3 golden 测试 + AC5 漂移检测测试 | Step 1-6 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | 重构配置加载逻辑，须保证合法/非法 yaml 输入行为不回归（golden 测试覆盖） |
+| SEC-2 | Yes | pactkit.yaml 是用户可控输入；必须继续使用 `yaml.safe_load`，禁止引入 `yaml.load` |
+| SEC-3 | N/A | 无数据库相关（sec-scope 命中为关键词误报） |
+| SEC-4 | N/A | 无前端文件 |
+| SEC-5 | N/A | 无认证/会话逻辑（sec-scope 命中为关键词误报） |
+| SEC-6 | N/A | 无 API/路由变更 |
+| SEC-7 | Yes | yaml 解析失败、副本写入失败的错误处理路径须在重构后保持优雅降级 |
+| SEC-8 | N/A | 无依赖变更 |
+
+## Out of Scope
+
+- 不改 `find_pactkit_yaml()` 的优先级顺序本身（只要求可见性 + 副本一致，重排优先级是另一个决策）
+- 不为配置项做分层覆盖机制（global ~/.claude yaml vs project yaml 的覆盖语义维持现状）
+- 不迁移存量项目的 94 行老 yaml（它们继续有效；用户可手动精简，`schema config` 提供指引）
+- `pactkit deps` 外部依赖一键安装（codegraph/gh/node）——单独建卡，不在本故事