pactkit 2.17.0__tar.gz → 2.18.0__tar.gz

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

@@ -10,10 +10,10 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.11"
 

{pactkit-2.17.0 → pactkit-2.18.0}/.github/workflows/publish.yml

@@ -12,10 +12,10 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -45,10 +45,10 @@ jobs:
       id-token: write
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 

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

@@ -4,6 +4,15 @@ All notable changes to PactKit will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [2.18.0] - 2026-08-17
+
+### Added
+- **Deployment manifest content hashes** (STORY-slim-141) — `write_deploy_manifest` now records a per-file sha256 under a `files` field (skills/commands-as-skills/agents/managed rules/guides; merge-semantics files like `CLAUDE.md` and user configs are structurally excluded). `pactkit doctor` deepens the parity check from component-name lists to content level: hash mismatch or missing-on-disk becomes an explicit `Content drift:` report, so "version stamp says new, content is old" deployments can no longer pass silently. Pre-2.18 manifests degrade to a warning; unreadable files and corrupted `files` fields degrade per SEC-7 and never crash doctor. Manifest keys are POSIX-normalized for cross-platform consistency.
+- **Adapter version skew warning in doctor** (STORY-slim-142) — doctor now reads adapter package metadata (`pactkit-opencode` etc.) and warns when an installed adapter lags behind core, with a `pipx inject` upgrade hint. The manifest's version field is core-stamped and could never reveal adapter skew.
+
+### Fixed
+- **`deploy(format="all", target=...)` no longer deploys adapters** (STORY-slim-142) — adapter deployers cannot honor `-t` and previously always wrote into real home dirs, which let test-suite or preview `init` calls silently overwrite live deployments (root cause of repeated `~/.config/opencode` stale-content incidents). With an explicit target, adapters are skipped with a printed notice; `target=None` behavior is unchanged.
+
 ## [2.17.0] - 2026-08-13
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.17.0
+Version: 2.18.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

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

@@ -71,3 +71,5 @@
 | 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 |

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

@@ -2,8 +2,6 @@
 
 | Date | Lesson | Context |
 |------|--------|---------|
-| 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 |
 | 2026-04-01 | Graduated safety language: retire MANDATORY keyword across prompts/commands.py, workflows.py, skills.py — use CRITICAL for safety gates (T1) and MUST for required steps (T2). Consistency prevents AI from treating all-caps keywords as equally urgent. | prompts/commands.py:MANDATORY→MUST/CRITICAL |
 | 2026-04-01 | Multi-stack visualize: _detect_stack() returning single str masks Go/TS/Java files in mixed projects; _build_class_graph hardcoded ast.parse() silently skips non-Python via except. Fix: _detect_stacks() returns list, extract_classes() ABC on all 4 analyzers. | visualize.py:_detect_stacks,_build_class_graph |
@@ -53,3 +51,5 @@
 | 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 |
+| 2026-08-17 | check_deploy_parity 新增 hash 路径漏了 SEC-7 降级守卫（PermissionError/AttributeError 穿透 doctor）——Spec Security Scope 逐条自查 + 独立评审实重现能抓作者盲区 | doctor.py:check_deploy_parity |
+| 2026-08-17 | deploy(format=all) 的 adapter 分支无视 target 直写真实 home——跨环境副作用必须显式审查 target/HOME 语义；测试通过 subprocess 调 CLI 时 HOME 未隔离即真实机器 | deployer.py:deploy |

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

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

@@ -48,3 +48,20 @@
 - [x] doctor parity 检查(能力矩阵感知)
 - [x] 跨仓: pactkit-codex 消费契约+版本 bump
 - [x] 单测
+
+### [STORY-slim-141] Deployment manifest content hash verification
+> Spec: docs/specs/STORY-slim-141.md
+
+- [x] TDD 测试 AC1-AC6 (RED)
+- [x] deploy_manifest.py: _hash_deployed_files + files 字段
+- [x] doctor.py: 内容级 parity 比对 + 旧 manifest 降级
+- [x] 回归 test_story_slim139
+
+### [STORY-slim-142] deploy format=all with target must skip adapters + adapter skew guard
+> Spec: docs/specs/STORY-slim-142.md
+
+- [x] TDD spy 测试 AC1-AC4 (RED)
+- [x] deployer.py: format=all+target 跳过 adapter
+- [x] doctor.py: adapter 版本偏斜 warning
+- [x] 运维: 本机 adapter 升级 2.17.0
+- [x] AC3 双跑全量套件验证

{pactkit-2.17.0 → pactkit-2.18.0}/docs/product/context.md

@@ -1,5 +1,5 @@
 # Project Context (Auto-generated)
-> Last updated: 2026-08-13T17:47:41+08:00 by pactkit context
+> Last updated: 2026-08-17T14:59:59+08:00 by pactkit context
 
 ## Sprint Status
 Backlog: 5 | In Progress: 0 | Done: 0 stories
@@ -16,11 +16,11 @@ None
 * 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），否则词表元讨论自身误报
+- check_deploy_parity 新增 hash 路径漏了 SEC-7 降级守卫（PermissionError/AttributeError 穿透 doctor）——Spec Security Scope 逐条自查 + 独立评审实重现能抓作者盲区
+- deploy(format=all) 的 adapter 分支无视 target 直写真实 home——跨环境副作用必须显式审查 target/HOME 语义；测试通过 subprocess 调 CLI 时 HOME 未隔离即真实机器
 
 ## Next Recommended Action
 `/project-plan`

pactkit-2.18.0/docs/specs/STORY-slim-141.md

@@ -0,0 +1,129 @@
+# STORY-slim-141: Deployment manifest content hash verification
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-141 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.18.0 |
+
+## Background
+
+2026-08-17 实测发现：`~/.config/opencode/` 的 `.pactkit-deployed.json` 声明 `pactkit_version: 2.17.0` 且组件清单与 registry 完全一致，但 3 个已部署文件（`rules/pactkit.md`、`skills/_rules/04-architecture-principles.md`、`skills/_rules/07-engineering-concerns.md`）内容停留在旧版 —— 占位符未渲染、已排除的 project-sprint 段落仍然存在。
+
+根因：STORY-slim-139 的 parity check（`doctor.py:check_deploy_parity`）只比对**组件清单**（skills/commands/agents 名字列表），不校验**文件内容**。`pactkit_version` 字段记录的是部署时刻的 CLI 版本，不代表落盘内容。这造成「版本戳新、内容旧」的静默漂移。
+
+本 Story 将 manifest 升级为携带逐文件 sha256，doctor 的 parity check 下沉到文件内容级。
+
+## Requirements
+
+### R1: Manifest 携带逐文件内容 hash (MUST)
+
+`write_deploy_manifest()` 在写完组件清单后，扫描 deploy_root 内所有 **pactkit 拥有的已部署文件**，计算 sha256，写入 manifest 的 `"files"` 字段：`{"<relative/path>": "<sha256 hex>"}`。
+
+- 覆盖范围 = manifest 声明组件对应的落盘文件：`skills/{name}/**`（含 commands-as-skills）、`agents/{name}.md`、managed rules（`rules/` 及 `skills/_rules/` 下由 VALID_RULES 部署的文件）
+- **MUST NOT** 哈希用户可改/合并语义的文件：`CLAUDE.md`、`AGENTS.md`、`opencode.json`、`config.toml`、`.pactkit-version`、`.pactkit-deployed.json` 自身
+- 签名保持向后兼容（adapter 包 pactkit-opencode / pactkit-codex 直接调用此函数，签名变更会导致 adapter 破坏）
+
+### R2: doctor parity check 下沉到文件内容级 (MUST)
+
+`check_deploy_parity()` 在组件清单比对通过后，若 manifest 含 `"files"` 字段，逐文件重新计算 sha256 并比对：
+
+- hash 不匹配 → drift detail：`Content drift: {format} {path} — redeploy via pactkit update`
+- manifest 中声明但磁盘缺失的文件 → drift detail
+- 磁盘比对 MUST 在报告前完成全部文件扫描（不因首个 mismatch 短路，一次报告所有漂移文件）
+
+### R3: 向后兼容旧 manifest (MUST)
+
+manifest 缺少 `"files"` 字段（pre-2.18 部署）→ 降级为 warning（`re-run pactkit update to enable content verification`），**不计入 drift**、不影响 doctor 退出码语义（与现有 missing-manifest 行为一致）。
+
+### R4: 用户追加内容不产生误报 (MUST)
+
+用户在 `CLAUDE.md` 等合并语义文件中的追加内容 MUST NOT 触发 content drift（由 R1 的排除清单保证）。用户修改 pactkit 拥有的文件（如 `rules/pactkit.md`）SHOULD 被报告为 drift —— 这是特性而非误报（提示用户改动将在下次 update 被覆盖）。
+
+### R5: 确定性 (MUST)
+
+hash 计算 MUST 为纯代码实现（sha256，hex digest），禁止 LLM 判断参与比对（Code Enforces, Prompt Instructs）。文件读取使用 bytes 模式避免编码差异。
+
+## Acceptance Criteria
+
+### AC1: 部署后 manifest 包含逐文件 hash (R1, R5)
+
+- **Given** 一个干净的 deploy target 目录
+- **When** 执行 `pactkit init -t <dir> --format classic --no-git --no-external --non-interactive`
+- **Then** `<dir>/.pactkit-deployed.json` 含 `"files"` 字段，覆盖所有 pactkit 拥有的落盘文件（skills/commands/agents/managed rules），每个值为 64 位 hex sha256，且不含 `CLAUDE.md`、`.pactkit-version`、`.pactkit-deployed.json`
+
+### AC2: 内容漂移被 doctor 检出 (R2)
+
+- **Given** 已完成部署且 manifest 含 `"files"`
+- **When** 手工篡改一个 pactkit 拥有的已部署文件（如 `rules/pactkit.md` 追加一行）后运行 `pactkit doctor`
+- **Then** 输出包含该文件路径的 `Content drift` detail，doctor 退出码为 1（NEEDS ATTENTION）
+
+### AC3: 未漂移时 doctor 不误报 (R2, R4)
+
+- **Given** 部署后未改动任何 pactkit 文件，仅在 `CLAUDE.md` 末尾追加用户内容
+- **When** 运行 `pactkit doctor`
+- **Then** 无 `Content drift` 输出（parity 部分不产生 issue）
+
+### AC4: 旧版 manifest 降级为 warning (R3)
+
+- **Given** 一个不含 `"files"` 字段的 `.pactkit-deployed.json`（模拟 pre-2.18 部署）
+- **When** 运行 `pactkit doctor`
+- **Then** 输出 warning 提示重新部署以启用内容校验，且不计入 drift、不影响退出码
+
+### AC5: 声明文件在磁盘缺失被检出 (R2)
+
+- **Given** 部署完成后删除一个 manifest 声明的文件（如 `skills/pactkit-board/SKILL.md`）
+- **When** 运行 `pactkit doctor`
+- **Then** 输出该文件缺失的 drift detail，退出码为 1
+
+### AC6: adapter 签名兼容 (R1)
+
+- **Given** 现有 `write_deploy_manifest(deploy_root, format_name, config)` 调用方（core deployer + 外部 adapter 包）
+- **When** 本 Story 完成后
+- **Then** 函数签名不变，adapter 无需修改即可获得 hash 能力（纯内部行为增强）
+
+## Target Call Chain
+
+```
+pactkit init/update
+  └─ cli.py → generators/deployer.py:_deploy_classic() (及各 format deployer)
+       └─ deploy_manifest.py:write_deploy_manifest(deploy_root, format, config)   ← R1 修改点
+            └─ NEW: _hash_deployed_files(deploy_root, components) → {"files": {...}}
+
+pactkit doctor
+  └─ cli.py:767 → doctor.py:check_deploy_parity(project_root)                     ← R2 修改点
+       ├─ 现有: expected_components() 清单比对
+       └─ NEW: manifest["files"] 逐文件 sha256 比对                               ← R3 兼容分支
+```
+
+Adapter 调用链（外部 repo，签名兼容由 R1 保证）：`pactkit-opencode/pactkit-codex → write_deploy_manifest()`
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `tests/unit/test_story_slim141_manifest_hash.py` | 新建：AC1-AC6 的 TDD 测试（RED） | None | Low |
+| 2 | `src/pactkit/deploy_manifest.py` | 新增 `_hash_deployed_files()` + 排除清单常量；`write_deploy_manifest` 写入 `files` 字段 | Step 1 | Low |
+| 3 | `src/pactkit/doctor.py` | `check_deploy_parity` 增加 files 比对分支 + 旧 manifest warning 分支 | Step 2 | Medium — 勿破坏现有清单比对与 SEC-2/SEC-7 降级行为 |
+| 4 | `tests/unit/test_story_slim139_skill_manifest.py` | 回归：现有 parity 测试不受影响 | Step 3 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | 修改 source code（deploy_manifest.py, doctor.py） |
+| SEC-2 | No | 无用户输入处理（hash 对象为部署器自身产物） |
+| SEC-3 | No | 无数据库 |
+| SEC-4 | No | 无前端 |
+| SEC-5 | No | 无认证逻辑 |
+| SEC-6 | No | 无 API/路由 |
+| SEC-7 | Yes | manifest JSON 损坏/文件不可读时必须降级为 warning（沿用现有 SEC-7 try/except 模式），禁止 crash doctor |
+| SEC-8 | No | 无依赖变更（hashlib 为标准库） |
+
+## Out of Scope
+
+- adapter 包（pactkit-opencode / pactkit-codex / pactkit-copilot）的发布与重部署 —— 它们自动继承 core 的新 manifest 行为
+- 对历史已部署目录的批量修复（由用户在下次 `pactkit update` 时自然获得）
+- `CLAUDE.md` / `AGENTS.md` 等合并语义文件的内容校验（结构上无法区分 pactkit 段与用户追加段）
+- 部署性能优化（hash 扫描为 O(文件数)，pactkit 文件约 100 个，无需优化）

pactkit-2.18.0/docs/specs/STORY-slim-142.md

@@ -0,0 +1,120 @@
+# STORY-slim-142: deploy format=all with target must skip adapters + adapter skew guard
+
+| Field | Value |
+|-------|-------|
+| ID | STORY-slim-142 |
+| Status | Done |
+| Priority | P1 |
+| Release | 2.18.0 |
+
+## Background
+
+2026-08-17，STORY-slim-141 的内容级 parity check 在 commit gate 实战中检出真实漂移，二分定位出完整污染链：
+
+1. `tests/unit/test_story_slim056.py` 中 `test_unicode_project_path` 等测试调用 `pactkit init -t <tmp>`（默认 `format=all`）
+2. `deploy(format="all")` 遍历 `_DEPLOYER_REGISTRY`，其中 `fmt_target = target if fmt_name == "classic" else None`（`deployer.py:~285`）—— **adapter 格式无视 `-t`，永远部署到真实 home**（`~/.config/opencode`）
+3. 本机安装的 `pactkit-opencode` 是 **2.9.1**（repo 源已 2.17.0）：渲染逻辑陈旧（占位符未解析、project-sprint 未排除），且不调用 `write_deploy_manifest`（slim-139 时还未发布）
+4. 结果：每次全量测试跑完，真实 opencode 部署被 2.9.1 陈旧内容覆盖且 manifest 不更新 → 下一次 `doctor` 必报 content drift → `test_doctor_runs` 对同文件内执行顺序产生隐式依赖（pass 留给别人，fail 留给自己）
+
+这同时解释了 2026-08-13 发布日后的首次漂移事件（同签名：占位符 + sprint 段落）。
+
+## Requirements
+
+### R1: format=all + 显式 target 时跳过 adapter 部署 (MUST)
+
+`deploy(format="all", target=<非None>)` 时，MUST 跳过所有 adapter 格式（opencode/codex/copilot 等非 classic），并打印一行说明：`Skipping adapter formats (…): -t target only applies to classic`。
+
+理由：adapter deployer 不接受 target（永远写各自默认 home 目录），带 target 的调用语义是"预览/测试"，把内容写进用户真实 home 在任何场景下都是错的。此改动从污染源头根治——**不需要修改任何现有测试**（遵守 Pre-existing Test Protocol），`test_unicode_project_path` 等自动获得隔离。
+
+`target=None` 的真实 init/update 行为 MUST 保持不变（adapter 正常部署到各自 home）。
+
+### R2: 回归测试——target 模式零 home 副作用 (MUST)
+
+新增测试验证：注册一个 spy adapter deployer 后调用 `deploy(format="all", target=tmp_path)`：
+
+- spy adapter 的 `deploy()` MUST NOT 被调用
+- classic 内容正确部署到 tmp_path
+- 输出含跳过说明
+
+### R3: doctor 报告 adapter 与 core 的版本偏斜 (SHOULD)
+
+`pactkit doctor` 增加 adapter 包版本检查：通过 `importlib.metadata.version("pactkit-opencode")` 等读取已装 adapter 版本，major.minor 落后于 core `pactkit.__version__` 时输出 warning（含升级提示 `pipx inject pactkit pactkit-opencode==X`）。warning 不计入 drift、不影响退出码。
+
+理由：本次事故的 root cause 是 adapter 2.9.1 配 core 2.17.0；manifest 的 `pactkit_version` 字段由 core 生成，无法反映 adapter 自身版本，必须直接读包元数据。
+
+### R4: 向后兼容 (MUST)
+
+- `deploy()` 签名不变；`format="all", target=None` 行为完全不变
+- 现有测试（含 slim056 全套）MUST NOT 修改，且修复后全量套件通过
+
+## Acceptance Criteria
+
+### AC1: target 模式跳过 adapter (R1)
+
+- **Given** 已安装 pactkit-opencode adapter（registry 含 opencode）
+- **When** 调用 `deploy(format="all", target=tmp_path)`（或 CLI `pactkit init -t <dir>` 默认 format=all）
+- **Then** adapter 的 deploy() 不被调用，`~/.config/opencode` 内容零变化，输出含跳过说明，classic 正常部署到 tmp_path
+
+### AC2: 真实 init 行为不变 (R1, R4)
+
+- **Given** 同上环境
+- **When** 调用 `deploy(format="all")`（target=None）
+- **Then** classic + 所有已注册 adapter 均正常部署到各自默认目录
+
+### AC3: 全量套件自洁 (R1, R2, R4)
+
+- **Given** opencode 部署处于干净状态（doctor 无 content drift）
+- **When** 连续运行两次全量 `pytest tests/unit/`
+- **Then** 两次均全绿（含 `test_story_slim056.py::TestDoctorCommand::test_doctor_runs` 单测独立运行也通过）
+
+### AC4: adapter 版本偏斜 warning (R3)
+
+- **Given** 安装的 pactkit-opencode 版本落后于 core（如 2.9.1 vs 2.17.0）
+- **When** 运行 `pactkit doctor`
+- **Then** 输出含版本偏斜 warning 与升级提示，且退出码语义不变（不计入 drift）
+
+## Target Call Chain
+
+```
+pactkit init -t <dir>          (CLI 默认 format=all)
+  └─ cli.py → deployer.py:deploy(format="all", target=<dir>)
+       └─ for fmt in _DEPLOYER_REGISTRY:                    ← R1 修改点
+            fmt_target = target if fmt == "classic" else None   ← BUG: adapter 无视 target
+            → R1: target 非 None 且 fmt != classic → skip + 提示
+
+pactkit doctor
+  └─ doctor.py:check_deps() 附近                              ← R3 新增点
+       └─ importlib.metadata.version("pactkit-opencode") vs pactkit.__version__
+```
+
+污染链实证（2026-08-17）：`test_unicode_project_path` → `run_pactkit("init", "-t", tmp)` → format=all → adapter 2.9.1 写 `~/.config/opencode`（陈旧渲染、不写 manifest）→ slim-141 parity 检出 drift。
+
+## Implementation Steps
+
+| Step | File | Action | Dependencies | Risk |
+|------|------|--------|-------------|------|
+| 1 | `tests/unit/test_story_slim142_all_target_isolation.py` | 新建：AC1/AC2 spy deployer 测试（RED） | None | Low |
+| 2 | `src/pactkit/generators/deployer.py` | `deploy(format="all")` 分支：target 非 None 时跳过 adapter + 提示 | Step 1 | Medium — 勿影响 target=None 主路径 |
+| 3 | `src/pactkit/doctor.py` | adapter 版本偏斜检查（importlib.metadata） | None | Low |
+| 4 | 运维（非代码） | 本机升级 adapter：`pipx inject pactkit <path-to-pactkit-opencode>` + `.venv` 同步升级，验证 doctor 无 drift | Step 2 合并后 | Low |
+| 5 | 回归 | 连续两次全量套件 + slim056 单测独立运行（AC3） | Step 2, 4 | Low |
+
+## Security Scope
+
+| Check | Applicable | Reason |
+|-------|------------|--------|
+| SEC-1 | Yes | 修改 source code（deployer.py, doctor.py） |
+| SEC-2 | No | 无外部输入解析（target 为既有参数） |
+| SEC-3 | No | 无数据库 |
+| SEC-4 | No | 无前端 |
+| SEC-5 | Yes | sec-scope 命中 auth/session 模式（deployer 含 token 相关字串）——本次改动不触碰凭据逻辑，仅需确认跳过逻辑不影响 MCP/凭据部署提示 |
+| SEC-6 | No | 无 API/路由 |
+| SEC-7 | Yes | importlib.metadata.PackageNotFoundError（adapter 未安装）必须静默跳过，不得 crash doctor |
+| SEC-8 | No | 无新依赖（importlib.metadata 为标准库） |
+
+## Out of Scope
+
+- adapter 包（pactkit-opencode 2.9.1 → 2.17.0）的版本升级本身 —— 属运维动作（Step 4），不改 adapter 仓库代码
+- adapter deployer 支持自定义 target 的能力（如需 preview adapter 部署，另立 story）
+- 测试套件的全面 HOME 隔离改造（R1 从源头消除污染向量后，slim056 无需修改；其余测试若有个案另议）
+- `test_doctor_runs` 对真实机器状态的隐性依赖重构 —— R1 修复后该测试恢复确定性，不追求完美隔离

pactkit-2.18.0/docs/test_cases/STORY-slim-141_case.md

@@ -0,0 +1,76 @@
+# Test Case: STORY-slim-141 — Deployment manifest content hash verification
+
+> Spec: docs/specs/STORY-slim-141.md
+> Unit tests: tests/unit/test_story_slim141_manifest_hash.py (11 tests)
+
+## AC1: 部署后 manifest 包含逐文件 hash (R1, R5)
+
+```gherkin
+Given 一个干净的 deploy target 目录
+When 执行 pactkit init 部署 classic format
+Then .pactkit-deployed.json 含 "files" 字段
+And 覆盖 skills/commands/agents/managed rules 的落盘文件
+And 每个值为 64 位小写 hex sha256
+And 不含 CLAUDE.md / .pactkit-version / .pactkit-deployed.json
+```
+Verified by: TestManifestFiles::test_write_includes_files_hash, test_hash_is_sha256_hex, test_manifest_keys_are_posix
+
+## AC2: 内容漂移被 doctor 检出 (R2)
+
+```gherkin
+Given 已完成部署且 manifest 含 "files"
+When 篡改 rules/pactkit.md 后运行 parity 检查
+Then drift 为 True 且 details 包含该文件路径
+And 退出码语义为 NEEDS ATTENTION（drift → doctor exit 1，由 slim-139 测试覆盖 wiring）
+```
+Verified by: TestContentParity::test_content_drift_detected, test_multi_drift_no_short_circuit
+
+## AC3: 未漂移时 doctor 不误报 (R2, R4)
+
+```gherkin
+Given 部署后未改动任何 pactkit 文件
+When 仅在 CLAUDE.md 末尾追加用户内容并运行 parity 检查
+Then drift 为 False，无 Content drift 输出
+```
+Verified by: TestContentParity::test_no_false_positive_on_excluded_append
+
+## AC4: 旧版 manifest 降级为 warning (R3)
+
+```gherkin
+Given 一个不含 "files" 字段的 pre-2.18 manifest
+When 运行 parity 检查
+Then drift 为 False
+And warnings 包含 "content verification" 提示
+```
+Verified by: TestContentParity::test_old_manifest_without_files_warns
+
+## AC5: 声明文件在磁盘缺失被检出 (R2)
+
+```gherkin
+Given 部署完成且 manifest 含 "files"
+When 删除 manifest 声明的 skills/pactkit-board/SKILL.md
+Then drift 为 True 且 details 包含 "missing on disk"
+```
+Verified by: TestContentParity::test_missing_declared_file_detected
+
+## AC6: adapter 签名兼容 (R1)
+
+```gherkin
+Given 现有 write_deploy_manifest(deploy_root, format_name, config) 调用方
+When 本 Story 完成后以位置参数调用
+Then 函数签名不变，返回 manifest Path 且 payload 含 files 字段
+```
+Verified by: TestManifestFiles::test_signature_unchanged
+
+## SEC-7 补充场景（评审后新增）
+
+```gherkin
+Given manifest 声明的文件被 chmod 0（不可读）
+When 运行 parity 检查
+Then 降级为 warning（"unreadable"），不 crash，drift 不受影响
+
+Given manifest 的 "files" 字段类型损坏（list 而非 dict）
+When 运行 parity 检查
+Then 降级为 warning（"corrupt"），不 crash
+```
+Verified by: test_unreadable_file_warns_not_crashes, test_corrupt_files_field_warns_not_crashes

pactkit-2.18.0/docs/test_cases/STORY-slim-142_case.md

@@ -0,0 +1,46 @@
+# Test Case: STORY-slim-142 — deploy format=all with target skips adapters + adapter skew guard
+
+> Spec: docs/specs/STORY-slim-142.md
+> Unit tests: tests/unit/test_story_slim142_all_target_isolation.py (6 tests)
+
+## AC1: target 模式跳过 adapter (R1)
+
+```gherkin
+Given registry 中含 classic + opencode（spy deployer）
+When 调用 deploy(format="all", target=tmp_path)
+Then classic 以 target=tmp_path 调用
+And adapter deploy() 从未被调用
+And 输出含 "Skipping adapter formats (opencode): -t target only applies to classic"
+```
+Verified by: TestAllTargetSkipsAdapters::test_adapter_not_called_when_target_given
+
+## AC2: 真实 init 行为不变 (R1, R4)
+
+```gherkin
+Given 同上 spy registry
+When 调用 deploy(format="all", target=None)
+Then classic 与 opencode 均以 target=None 被调用（各自部署到默认目录）
+```
+Verified by: TestAllTargetSkipsAdapters::test_adapter_called_when_no_target
+
+## AC3: 全量套件自洁 (R1, R2, R4)
+
+```gherkin
+Given opencode 部署处于干净状态（doctor 无 content drift）
+When 连续运行两次全量 pytest tests/unit/
+Then 两次均全绿（4120 passed）
+And 两次运行之间 opencode manifest 与磁盘零漂移
+And test_story_slim056.py::TestDoctorCommand::test_doctor_runs 独立运行通过
+```
+Verified by: 2026-08-17 Act Phase 3 实测（双跑 + drift check NONE + 单测独立通过）
+
+## AC4: adapter 版本偏斜 warning (R3)
+
+```gherkin
+Given 安装的 pactkit-opencode 为 2.9.1 而 core 为 2.17.0
+When 调用 check_adapter_skew()
+Then 返回含包名、双版本号与 pipx inject 升级提示的 warning
+And adapter 版本与 core 一致时静默（空列表）
+And adapter 未安装 / 元数据缺失时静默不 crash（SEC-7）
+```
+Verified by: TestAdapterSkew 4 tests（outdated/current/missing/no-entry-points）

{pactkit-2.17.0 → pactkit-2.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pactkit"
-version = "2.17.0"
+version = "2.18.0"
 description = "Spec-driven agentic DevOps toolkit for AI coding assistants"
 readme = "README.md"
 license = "MIT"

{pactkit-2.17.0 → pactkit-2.18.0}/src/pactkit/__init__.py

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

{pactkit-2.17.0 → pactkit-2.18.0}/src/pactkit/cli.py

@@ -773,6 +773,12 @@ def main():
         for warning in parity["warnings"]:
             print(f"  ⚠️  {warning}")
 
+        # STORY-slim-142 R3: adapter package version skew (report-only)
+        from pactkit.doctor import check_adapter_skew
+
+        for warning in check_adapter_skew():
+            print(f"  ⚠️  {warning}")
+
         if not has_issues:
             print("Health: OK")
         else: