pactkit 2.23.0__tar.gz → 2.24.1__tar.gz

{pactkit-2.23.0 → pactkit-2.24.1}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [2.24.1] - 2026-08-27
+
+### Fixed
+- **Enforcement probes resolve the project venv's pytest** — 2.24.0's static probes checked `importlib` in the *current* interpreter, so a pipx-installed CLI (whose venv has no pytest) reported commit-gate and coverage-gate as `unavailable` even though the gates themselves run the project venv's pytest perfectly. Probes now resolve the interpreter the same way the gates do (`pytest_command`).
+
+## [2.24.0] - 2026-08-27
+
+### Added
+- **Run event streams (append-only)** — every workflow-state mutation appends a typed event (`step_entered`, `checkpoint_written`, `evidence_invalidated`, `blocker_raised/cleared`, `run_completed`, `run_archived`) beside its checkpoint, written inside the same lock. The checkpoint JSON stays the projection; the event log holds the history the overwrite-style checkpoint cannot. Crash-tolerant: a torn trailing line is skipped and counted, never corrupts earlier lines.
+- **`pactkit stats`** — per-run friction metrics (duration, blocker dwell by kind, step rework, authorization decisions) with `--format json` for dashboards; pre-2.24 runs degrade to `events: unavailable` instead of failing. `/project-done` now records a friction snapshot per story. `pactkit continuation events <story>` inspects a run's stream.
+- **Gate enforcement completeness reporting** — every gate declares `full / degraded / unavailable` instead of degrading silently through a WARN line: commit-gate and coverage-gate record their observed status, `pactkit doctor --json` exposes an `enforcement` section (plus orphaned specs, config drift, graph provider, deploy parity, codex capabilities), and human doctor output gains per-gate summary lines. Self-lock degradation is now queryable, not silent.
+- **Codex native hooks thin registration** — `pactkit init --format codex` merges a PreToolUse→`pactkit commit-gate --hook` entry into the project's `.codex/hooks.json` (Codex's hooks engine is deliberately Claude-wire-compatible: tool_name `Bash`, exit 2 + stderr block — verified against 0.149.1; hooks.json discovery requires ≥0.114.0). User entries are preserved verbatim, unmergeable structures are left byte-identical, `config.toml` is never touched, deployment output carries the one-time trust-confirmation notice, and the git pre-commit fallback stays active until trust is confirmed. `pactkit doctor` probes the local Codex version and reports engine/deployment/trust state.
+- **Authorization audit trail** — `authorization_asked`/`authorization_granted` events fire automatically at authorization-blocker transitions (asked carries the sanitized question), and `pactkit continuation deny <story> --reason` records the state machine's first machine-expressible "no": an `authorization_denied` audit event plus a blocked-checkpoint rewrite (`denied: <reason>`), with double-deny and non-authorization denials rejected. `pactkit stats` reports per-run decision counts.
+- **outcome_unknown crash recovery** — commit-gate opens an attempt fence (with pid) *before* running; the terminal record closes it. A crash between the two leaves a machine-observable open fence: `resume` blocks with an actionable reason (live pid → "still active, wait"; dead pid → "re-run the gate") — no time-window guessing. Re-running the gate closes the fence and restores normal decisions. Projects without fences behave exactly as before.
+- **Command manifest v2 (reference digests)** — the ownership ledger for codex command skills records the sha256 of every deployed reference file (`record_deployed_reference`/`read_command_references`); stale-reference cleanup consumes these proofs, restoring the whole-directory retirement of disabled commands that core's 5311c56 ownership narrowing had inadvertently broken. v1 manifests read compatibly; corrupt manifests degrade to empty proofs.
+
+### Fixed
+- **pactkit-codex 2.23.0 ownership regression** (never published) — `skills/*/references/**` files dropped out of the deployed manifest's files table after the ownership narrowing, so stale references could never be retired; the command manifest v2 reference ledger (above) repairs deletion proofs without re-render comparisons (the codex render pipeline depends on deploy-time `enabled_commands`, making content replay structurally unusable as ownership evidence).
+- **`pactkit continuation events` path traversal** — story IDs are validated before the event-stream path is built (QA follow-up).
+- **hooks.json merge safety** — invalid user structures (`hooks` non-dict, `PreToolUse` non-list) are left byte-identical with an explicit report instead of being rewritten; merges run under a best-effort inter-process lock that proceeds unlocked on timeout (deployment never hangs).
+- **Blocker dwell undercount** — consecutive re-raises within one blocker episode no longer restart the dwell measurement; the episode is anchored at its first raise.
+
+### Changed
+- **`hook_entry` dual-host normalization** — legacy codex array-form commands are joined before matching, and the payload `cwd` overrides the CLI-resolved project root on both hosts.
+- **Golden CLI surface** — pins the new `stats` subcommand, `continuation deny`/`events` actions, and `doctor --json`.
+
 ## [2.23.0] - 2026-08-27
 
 ### Added

{pactkit-2.23.0 → pactkit-2.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pactkit
-Version: 2.23.0
+Version: 2.24.1
 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
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
-Requires-Dist: pactkit-codex<2.24.0,>=2.23.0; extra == 'all'
+Requires-Dist: pactkit-codex<2.25.0,>=2.24.0; extra == 'all'
 Requires-Dist: pactkit-opencode>=2.9.0; extra == 'all'
 Requires-Dist: ruff>=0.4; extra == 'all'
 Requires-Dist: tree-sitter-go>=0.25; extra == 'all'
@@ -31,7 +31,7 @@ Requires-Dist: tree-sitter-java>=0.23; extra == 'all'
 Requires-Dist: tree-sitter-typescript>=0.23; extra == 'all'
 Requires-Dist: tree-sitter>=0.25; extra == 'all'
 Provides-Extra: codex
-Requires-Dist: pactkit-codex<2.24.0,>=2.23.0; extra == 'codex'
+Requires-Dist: pactkit-codex<2.25.0,>=2.24.0; extra == 'codex'
 Provides-Extra: lint
 Requires-Dist: ruff>=0.4; extra == 'lint'
 Provides-Extra: opencode

pactkit-2.24.1/docs/architecture/governance/lessons/LESSON-20260827093143-3236113033.md

@@ -0,0 +1,10 @@
+---
+schema_version: 1
+id: LESSON-20260827093143-3236113033
+date: '2026-08-27'
+story_id: STORY-slim-20260827fc9de5542ad7
+context: STORY-slim-20260827fc9de5542ad7
+tags: []
+---
+
+Adapter-rendered artifacts (codex command references) need deploy-time digest recording via record_deployed_reference in command_ownership.py — content re-render comparison cannot prove ownership because _filter_codex_command_reference_sections in deployer.py depends on deploy-time enabled_commands

pactkit-2.24.1/docs/architecture/governance/lessons/LESSON-20260827095642-059a7e996b.md

@@ -0,0 +1,10 @@
+---
+schema_version: 1
+id: LESSON-20260827095642-059a7e996b
+date: '2026-08-27'
+story_id: STORY-slim-20260827024e71df170f
+context: STORY-slim-20260827024e71df170f
+tags: []
+---
+
+Codex hooks engine is deliberately Claude-Code wire-compatible (hook_names.rs serializes shell tool as 'Bash'; pre_tool_use.rs honors exit 2 + stderr block) — hook_entry in commit_gate.py needed only array-command normalization and payload-cwd root resolution, zero protocol fork

pactkit-2.24.1/docs/architecture/governance/lessons/LESSON-20260827102057-e04522a6fc.md

@@ -0,0 +1,10 @@
+---
+schema_version: 1
+id: LESSON-20260827102057-e04522a6fc
+date: '2026-08-27'
+story_id: STORY-slim-20260827eddbe9669c87
+context: STORY-slim-20260827eddbe9669c87
+tags: []
+---
+
+Terminal-only status ledgers cannot detect interruption — record_attempt in enforcement.py must open a running fence BEFORE the verification runs so a crash between attempt and outcome leaves a machine-observable unknown; resume in continuation.py then blocks on the open fence until the gate re-runs

{pactkit-2.23.0 → pactkit-2.24.1}/docs/architecture/governance/rules.md

@@ -15,7 +15,7 @@
 
 ## Invariants
 
-1. All 4651+ tests must pass before any commit to `main`.
+1. All 4711+ 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.24.1/docs/product/harness-comparison-2026-08-27.md

@@ -0,0 +1,242 @@
+# PactKit vs DeepSeek Harness / Codex CLI — 对比分析与提升清单
+
+> 日期：2026-08-27
+> 对比对象：
+> - [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（本地 checkout：`/Users/slim/workspaces/deepseek-harness`，版本 0.1.1-rc.2，developer preview）— 全功能 agent 运行时（**机制思想参照系**）
+> - [Codex CLI](https://github.com/openai/codex)（本地 checkout：`/Users/slim/workspaces/codex`，Rust workspace ~120 crates）— **PactKit 的部署宿主之一**（宿主对齐参照系）
+>
+> 结论用途：PactKit 后续版本改进候选清单（非承诺排期）
+
+---
+
+## 0. 一句话结论
+
+**对比 dsh（运行时参照系）**：PactKit 在证据治理和 fail-closed 设计上领先（dsh 完全没有 PDCA / Spec / Board 对应物）；dsh 值得抄的不是功能，而是三个机制思想：
+
+1. **事件溯源的会话模型**（append-only 事件流替代覆盖式 checkpoint）
+2. **自报降级状态的诚实门**（gate 必须声明自己的 enforcement completeness）
+3. **"文档由代码生成且 CI 防漂移"的工程纪律**（生成式目录 + 漂移门）
+
+**对比 Codex（宿主参照系）**：宿主的扩展面进化速度超过了 pactkit-codex adapter 的利用程度 —— Codex 现已拥有**12 事件生命周期 hooks 引擎、插件+marketplace 系统、Starlark 确定性策略引擎**，而 adapter 目前只部署 skills/rules/prompts 静态文件，`commit-gate` 的 hook 通道只接了 Claude 侧。宿主已经把"确定性拦截"的原生机制造好了，PactKit 没用上。
+
+其中 dsh 线的前两条（事件流 + 诚实门）正好是 PactKit 当前"collecting friction data"阶段缺的那双眼睛；Codex 线则是**不新增语义、只接通既有机制**就能拿到的拦截力升级。
+
+---
+
+## 1. 定位差异（为什么不是逐功能对比）
+
+三个项目不在同一层：
+
+- **dsh** 是完整的 agent **运行时**：基于 Cordis（vendored）的"一切皆插件"架构，自己驱动模型、执行工具、管理会话，含 Web UI、沙箱、subagent、工作流引擎。
+- **Codex CLI** 是 PactKit 的**宿主**之一：OpenAI 的 Rust 实现 coding agent，拥有 OS 级沙箱、12 事件 hooks 引擎、插件系统。它既是"可借鉴机制的来源"，也是"必须对齐的部署目标"。
+- **PactKit** 是骑在宿主 CLI（Claude Code / OpenCode / Codex）之上的**治理层**：不驱动模型，只做确定性验证（evidence-typed workflow registry、fail-closed gates、部署完整性）。
+
+因此对比有两条线：
+- **dsh 线**：哪些机制性思想可以移植到 PactKit 的治理定位内。两家是互补关系——dsh 甚至把 Claude Code 和 Codex 当作 subagent 后端（`packages/subagent/subagent-claude-code` / `subagent-codex`），它缺的 PDCA/证据层正是 PactKit 的主场。
+- **Codex 线**：宿主的原生扩展面（hooks / 插件 / 策略层）与 pactkit-codex adapter 当前利用度之间的**已查证差距**（见第 4 节）。
+
+---
+
+## 2. 能力对比总览（dsh 线）
+
+| 维度 | deepseek-harness | PactKit | 差距性质 |
+|---|---|---|---|
+| 运行时 | 完整 agent loop（Cordis 插件化，一切可插拔） | 无（寄生于宿主） | 定位使然，不补 |
+| 会话模型 | **append-only 事件流**，"model-visible ⟺ logged" 不变量；fork/resume/compaction/telemetry 全部从同一条流推导 | 扁平 JSON checkpoint（`continuation.py`），覆盖式写入 | **可移植，价值高** |
+| 崩溃恢复 | 持久化屏障（模型请求/副作用前先落盘）+ `TOOL_OUTCOME_UNKNOWN` 恢复语义 | 按 step checkpoint；artifact 消失会 fail 而非 brick，但无"结果未知"中间态 | **可移植** |
+| 工具安全 | 单调 guard（只能拒绝不能放行）+ fail-closed 审批 + **每次审批落一对 `asked/decided` 审计事件** | 授权门控 Story 写入（结构性防篡改），但授权决策本身无审计流 | **可移植** |
+| 证据/治理 | 无 PDCA 对应物（仅 Agent Notes 设计决策记录 + 运行时不变量注册表） | **PactKit 主场**：workflow registry、fail-closed gates、delivery evidence、commit/coverage gate | PactKit 领先 |
+| 可观测性 | OTel、token meter、session query 工具、事件回放 | doctor stdout + H1-H7 静态审计 + observe.py（web 指标）；无 agent 行为级追踪 | **可移植，价值高** |
+| 文档工程 | 生成式目录（工具/配置/事件 catalog）+ type-equiv 漂移门 + 双语 blob-hash 配对 + 自定义 merge driver | prompt↔CLI 一致性 CI + golden CLI snapshot | 部分可移植 |
+| 测试纪律 | 逐文件 100% 覆盖率门 + **任何 model-visible 变更必须同 PR 带真实组合 snapshot 测试**（ACP + headless + Chromium 双 SDK） | 288 单测 + 部署完整性检查 + golden help snapshot | **可移植** |
+| 沙箱/并行/模型路由 | Landlock/Seatbelt 沙箱、continuable 后台 subagent、LLM 适配层 | 均无 | 定位使然，不补 |
+
+---
+
+## 3. 可移植提升点 — dsh 线（按优先级）
+
+### P0 — 直接服务当前阶段（collecting friction data + enterprise adoption）
+
+#### P0-1. Checkpoint 升级为 append-only 事件流
+
+**dsh 机制**：`packages/core/session` —— Session 是类型化事件的只追加日志；不变量 "model-visible ⟺ logged"（凡是到达模型请求的内容必须可从日志重建，由运行时不变量强制）。fork、resume、compaction、telemetry、UI 全是这条流的投影。
+
+**PactKit 现状**：`continuation.py` 是覆盖式 JSON —— 只知道 run 的*当前状态*，丢失*历史*（evidence 被推翻过几次、blocker 挂了多久、重试了几次）。
+
+**落地做法**：
+- `.pactkit/continuations/runs/<id>/` 下新增 `events.jsonl`；step 进入、evidence 记录/失效、blocker 升降各追加一条带时间戳事件
+- 现有 JSON checkpoint 保留，作为事件的投影物化视图（兼容既有 `finish_guard` 读取路径）
+- 改动面集中在 `ContinuationEngine` 内部，是 P0-2 的前提
+
+#### P0-2. Friction 数据管道（run 指标采集与导出）
+
+**背景**：项目记忆里写着 "Feature-complete, collecting friction points. No new features until friction data" —— 但 PactKit 目前**没有任何结构化的 run 指标出口**，friction data 实际上收不上来。
+
+**落地做法**：基于 P0-1 的事件流，新增 `pactkit stats`（或 `pactkit runs`）命令，输出：
+- 每 run 时长、evidence 重试次数、blocker 停留时长（按 blocker kind 分桶）
+- gate 通过 / 降级 / 拦截比例
+- 哪条 rule 被触发、哪个 workflow step 最常返工
+- JSON 导出（`--format json`），将来接任何 dashboard 都有数据源
+
+这是 dsh token-meter + session stats 的治理版对应物，也是 enterprise 客户的必问项（"你们的流程到底省了多少返工"）。
+
+#### P0-3. Gate 执行完整度上报（"honest sandbox" 思想）
+
+**dsh 机制**：沙箱后端必须自报 enforcement completeness（`full|partial`），调用方被迫正视缺口，不许假装全覆盖。
+
+**PactKit 现状**：已有雏形——commit-gate 自锁保护是 fail-open + WARN（`commit_gate.py`），但这属于"悄悄降级"。
+
+**落地做法**：
+- 统一约定：每个 gate 输出机器可读的 enforcement 状态（`full / degraded / unavailable`）
+- `doctor` 汇总所有 gate 的当前降级状态
+- 企业客户审计时，"你们的门什么时候是虚掩的"是必答题；答案应该在 `pactkit doctor --json` 里
+
+### P1 — 机制强度提升
+
+#### P1-1. 授权审计事件对
+
+**dsh 机制**：每次审批落一对 `approval/asked` + `approval/decided` 审计事件到不可变日志，不可抵赖。
+
+**PactKit 现状**：`user_input / authorization` blocker 只是暂停等待，人来解除，但**决策本身没有留痕**。
+
+**落地做法**：在 P0-1 事件流里落 `authorization/asked` + `authorization/granted|denied` 事件对。enterprise 场景的合规刚需，且实现几乎免费（依赖 P0-1）。
+
+#### P1-2. 崩溃恢复语义补全：`outcome_unknown` 中间态
+
+**dsh 机制**：`packages/session/session-checkpoint-policy` 在每个模型请求和副作用工具体之前落持久化屏障；崩溃恢复时注入模型可见的 `TOOL_OUTCOME_UNKNOWN` 结果，专门设计成不破坏 KV-cache 前缀，避免 agent 假设成功或失败。
+
+**PactKit 现状**：`revalidate_artifacts` 只处理"artifact 消失"一种情况。commit-gate 跑到一半被 Ctrl-C 时，run 没有明确表达"验证结果未知"。
+
+**落地做法**：checkpoint 状态机增加 `outcome_unknown`（或 evidence 级别的 unknown 标记），恢复时强制重跑该验证步骤而非沿用旧结论。
+
+#### P1-3. 设计决策记录（Agent Notes 的治理版）
+
+**dsh 机制**：`.agents/notes/` 强制每个非平凡 PR 附带一份带生命周期的决策记录（`proposed/implemented/rejected` × 类型分类，路径编码生命周期），pre-commit 门检查"同一 PR 必须有 note"。
+
+**PactKit 现状**：有 lessons.md（教训）和 stories（任务），但缺**"为什么这么做"的决策层**。
+
+**落地做法**：与现有 `pactkit scaffold` / commit-gate 基础设施契合——加一个 note 模板 + commit-gate 规则："本 commit 触及 governance/spec/architecture 文件时须有对应 decision note"。对 enterprise adoption 价值极高（他们最怕不可追溯的架构决定）。
+
+### P2 — 工程纪律（低成本，防漂移）
+
+#### P2-1. 生成式目录 + 漂移门
+
+**dsh 机制**：从源码生成工具/配置/事件目录进文档（`scripts/gen-cordis-catalog.ts` 等），CI 检查再生成是否 diff 为零；`type-equiv` 门抽取源码声明+JSDoc，文档粘贴漂移即 fail。
+
+**PactKit 落地**：`workflow_registry.py`（所有 workflow 的 evidence 要求表）和 `RULE_DEFINITIONS`（16 条规则）目前只存在于代码里——生成 `docs/reference/` 目录页并 CI 校验，规则和证据要求永不与文档漂移。是现有 prompt↔CLI 一致性 CI 的同一思想延伸。
+
+#### P2-2. 组装后 prompt 的跨宿主 snapshot 测试
+
+**dsh 机制**：任何 model-visible 变更必须同 PR 带真实组合的 snapshot 测试（无 key、真实组装、多表面）。
+
+**PactKit 落地**：已有 golden CLI help snapshot 与部署完整性检查，但**没有三个宿主渲染出的最终 prompt 的字节级快照**。加一个 e2e：deploy 到临时目录，对 Claude / OpenCode / Codex 三个 profile 的产物做 snapshot。prompt 模板改动导致的静默回归（2.21/2.22 withdrawn 这类事故）会被直接拦住。
+
+#### P2-3. 配置分层组合（profile → 项目 → 用户 overlay）
+
+**dsh 机制**：profile / bundle / patch 三层 last-write-wins + `--dump-config` 打印最终组合树。
+
+**PactKit 落地**：`pactkit.yaml` + `FormatProfile` 目前是平面的。做成层叠 + `pactkit config dump`；多团队 enterprise 场景"公司基线覆盖项目覆盖个人"是常见诉求。
+
+---
+
+## 4. Codex CLI 对比（宿主视角）
+
+Codex 与 dsh 的角色不同：它不是"抄思想"的对象，而是 PactKit 的部署目标。本节回答两个问题：**(a) Codex harness 有哪些机制 PactKit 可以借力或借鉴；(b) pactkit-codex adapter 相对 Codex 现有扩展面的真实差距在哪**（差距部分已逐一查证 PactKit 源码）。
+
+### 4.1 Codex 值得关注的 harness 机制
+
+| 机制 | 位置 | 与 PactKit 的关系 |
+|---|---|---|
+| **12 事件 hooks 引擎**：PreToolUse（可 block + 改写输入 + 附加上下文）、PermissionRequest（可裁决）、PostToolUse、Pre/PostCompact、SessionStart/End、SubagentStart/Stop、Stop、Interrupt；支持 shell 命令和 **MCP 调用**两种 handler | `codex-rs/hooks/src/lib.rs`，schema 在 `hooks/schema/generated/` | commit-gate 可增加 Codex 原生通道（现在只有 Claude hook + git pre-commit） |
+| **Hook 信任机制**：第三方 hook 需 content-hash 信任确认才启用；企业 `allow_managed_hooks_only=true` 可全锁 | `hooks/src/registry.rs` | adapter 部署 hook 的安全前提（对应 feedback: 绝不静默改用户工具配置） |
+| **插件 + marketplace 系统**：一个 `.codex-plugin` manifest 捆绑 skills + hooks + MCP servers + apps | `codex-rs/plugin/src/manifest.rs`, `core-plugins/` | PactKit 已有 Claude plugin（`pactkit-plugin/`），Codex 有等价分发形态 |
+| **Anthropic 兼容 SKILL.md + 隐式调用检测**：命令匹配 skill 脚本时触发审批 | `codex-rs/skills/` | PactKit skills 天然可迁移；隐式调用 = 免提示词的确定性触发点 |
+| **Starlark execpolicy**：命令前缀规则 `allow/prompt/forbidden` + justification + 加载时自测试 | `codex-rs/execpolicy/` | "策略即数据"——PactKit 规则的宿主原生执行版 |
+| **沙箱策略 + permission profiles 作为配置数据**：read-only / workspace-write / danger-full-access，分域文件系统策略 | `protocol/src/config_types.rs` | PactKit 的 write_scope 治理可编译到这一层 |
+| **分层配置栈**：enterprise `requirements.toml` → managed → project `.codex/config.toml` → profile | `codex-rs/config/src/loader/` | 与 P2-3 配置分层的诉求完全同构，可参考其合并语义 |
+| **Guardian auto-review**：`approvals_reviewer=auto_review` 让一个专门 subagent 顶在审批环里 | `codex-rs/core/src/guardian/` | PactKit Check 阶段自动化评审的宿主内对应物 |
+| **不可变 rollout JSONL + SQLite 状态库**：追加式会话记录，fork/revert 保 thread id | `codex-rs/rollout/` | 佐证 P0-1 方向：三家（dsh/Codex/Claude）都是事件流模式 |
+| **app-server JSON-RPC**：VS Code 同款协议，可编程 approve/steer turn | `codex-rs/app-server/` | PactKit 未来做监督面板的免费通道（`pactkit supervise`） |
+
+### 4.2 已查证的 adapter 差距（最 actionable 的部分）
+
+以下四条均已在 PactKit 源码中逐一定位确认：
+
+1. **commit-gate 只接了 Claude hook 通道**
+   `commit_gate.py:274`（`install_hook`）只 merge `.claude/settings.json`；Codex 宿主上仅有 git pre-commit 兜底（退出码语义也不同：Claude exit 2 / git exit 1）。而 Codex 现在有原生 PreToolUse（可 block + `updated_input` 改写）和 Stop 事件——拦截时点可以从"提交时"提前到"工具调用时"，且能把修正反馈直接注入对话。
+
+2. **Codex profile 的能力模型已过时**
+   `profiles.py:212` 的 codex `FormatProfile` 把 `"hooks"` 列入 `excluded_agent_fields`（基于"Codex 没有 hooks"的旧假设，现在 Codex 有 SubagentStart/Stop 等 hooks）；`supports_model_routing=False` 也与 Codex 现有的 `model_providers`/profiles 机制不符。能力标志目前是**硬编码快照**，而 Codex 的 wire 格式（hook schema、app-server）与二进制版本钉死。
+
+3. **MCP 只是声明，没有部署动作**
+   `supports_mcp=True`，但 `deployer.py:305` 仅打印一句 "Configure in Claude Code settings.json → mcpServers" 的手动提示；没有生成 Codex `[mcp_servers]` 配置段，也没有 Claude 侧的自动注册。PactKit 的治理工具（board / continuation / doctor）本可以作为 MCP server 原生暴露给宿主调用。
+
+4. **没有 Codex 插件分发形态**
+   PactKit 为 Claude 打了 `pactkit-plugin/` 插件包，Codex 现在有完全对等的机制（一个包捆绑 skills+hooks+MCP，marketplace 可发现），但 adapter 没有 `.codex-plugin` manifest 输出。发布流程第 6 步天然可以扩展出 Codex 目标。
+
+### 4.3 Codex 线新增提升项
+
+#### P0-4. pactkit-codex adapter 接入 Codex hooks 引擎
+
+**落地做法**：
+- commit-gate 增加 Codex 通道：生成 `.codex/hooks.json`（PreToolUse 拦截 Bash git commit / Stop 事件检查 run 状态），handler 复用现有 `pactkit commit-gate --hook` 入口（Codex hook 事件名与 Claude Code 风格对齐，输入/输出 schema 需按 `hooks/schema/generated/` 适配）
+- **信任机制红线**：Codex hook 需要 content-hash 信任确认才生效，企业环境可能 `allow_managed_hooks_only`。部署绝不能静默写入（对应 codex config.toml 两次被清空的事故教训）——部署时显式告知用户需要信任确认，`doctor` 增加 Codex hook 信任状态检测
+- 同步修正 `profiles.py` 的 codex 能力标志（hooks 不再排除）
+
+#### P1-4. Codex 插件分发形态
+
+生成 `.codex-plugin/` manifest（捆绑 skills + hooks.json + MCP server 声明），对称于现有 Claude plugin 发布流程。发布 checklist 第 6 步扩展为双目标。
+
+#### P1-5. write_scope 编译到宿主策略层
+
+PactKit 的 write_scope（Spec `Touches` ∪ 项目配置）目前只存在于 prompt 规则层。编译为：
+- Codex：`sandbox_workspace_write` 边界 / permission profile / execpolicy 前缀规则
+- Claude：permissions allowlist
+
+从"模型被提示不要越界"升级为"宿主结构性拒绝越界"。这是 PactKit"确定性核心"哲学在宿主侧的自然延伸。
+
+#### P2-4. 治理工具 MCP 化
+
+把 board / continuation / doctor 的关键子命令包成 MCP server：宿主可以原生调用（不再依赖 CLI 可用性探针），Codex 的 hook handler 甚至可以直接是 MCP 调用而不必 shell out。
+
+#### P2-5. doctor 增加 Codex 版本/能力探测
+
+Codex 的 hook schema 与 wire 格式和二进制版本钉死。`pactkit doctor` 探测本机 Codex 版本，按版本动态判定能力标志（替代 `profiles.py` 的硬编码快照），避免 adapter 对着旧能力模型部署。
+
+---
+
+## 5. 明确不抄的部分（及理由）
+
+| 不抄 | 理由 |
+|---|---|
+| 运行时 / LLM 适配层 / token meter / compaction / Code Mode / 沙箱 | 这是宿主的职责。抄了就变成第二个 harness，与"治理层"定位冲突。dsh 与 PactKit 是互补关系 |
+| Web UI | 宿主有 UI。P0-2 的 stats 做 JSON 导出即可，将来任何 dashboard 都有数据源；Codex 的 app-server JSON-RPC 已提供监督通道 |
+| Cordis 插件运行时 / DI 容器 | PactKit 的 entry-point deployer 机制已覆盖"第三方扩展部署器"这个真实需求 |
+| 双语 blob-hash 配对 + 自定义 merge driver | PactKit 双语内容量小（仅站点），收益配不上复杂度 |
+| 逐文件 100% 覆盖率门 | PactKit 已有自己的覆盖率门治理宿主项目；对自身可参考但不强制 |
+| Guardian auto-review 的完整实现 | 思路值得借鉴（Check 阶段自动评审），但审批环自动化是宿主职责；PactKit 只需保证自己的 review 工具产出结构化证据供其消费 |
+
+---
+
+## 6. 依赖关系与建议顺序
+
+```
+dsh 线：
+P0-1 事件流 ──┬──> P0-2 friction 管道
+              └──> P1-1 授权审计对
+P0-3 gate 完整度上报（独立）
+P1-2 outcome_unknown（依赖 checkpoint 状态机改动，可与 P0-1 同期）
+P1-3 决策记录（独立，靠 commit-gate）
+P2-1/P2-2/P2-3（独立，纯工程纪律）
+
+Codex 线：
+P0-4 Codex hooks 接入（独立；先于 P1-4，是插件包的内容物之一）
+P1-4 Codex 插件形态（依赖 P0-4 的 hooks.json + P2-4 的 MCP 声明更佳）
+P1-5 write_scope → 宿主策略层（独立）
+P2-4 治理工具 MCP 化（独立）
+P2-5 doctor 版本探测（独立，小改动）
+```
+
+若只做一件事：**做 P0-1 + P0-2**。它不改变治理语义、改动面可控，且直接解决"friction data 收不上来"这个当前阶段的卡点。
+
+若做两件事：加 **P0-4（Codex hooks 接入）**。它不新增任何治理语义——只是把已有的 commit-gate 接到宿主已造好的原生拦截机制上，投入最小、拦截时点提升最大，且 2.23.0 发布尾巴里的 codex ownership 契约缺口正好在这次 adapter 升级中一并补齐。

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827024e71df170f.yaml

@@ -0,0 +1,31 @@
+schema_version: 1
+id: STORY-slim-20260827024e71df170f
+title: P0 可观测性与拦截力升级：run 事件流、friction 统计、gate 完整度上报、Codex 原生 hooks 接入
+spec_path: docs/specs/STORY-slim-20260827024e71df170f.md
+status: archived
+tasks:
+- id: task-2eef2a1c10
+  title: R1 事件流写入：continuation.py 锁内追加 events/*.jsonl + 归档随行
+  completed: true
+- id: task-700f96873a
+  title: R2 pactkit stats 聚合命令 + golden CLI snapshot 更新
+  completed: true
+- id: task-73ac7e9fc9
+  title: R3 enforcement 状态模型（full/degraded/unavailable）+ doctor 聚合
+  completed: true
+- id: task-c0f0c78797
+  title: R4 Codex hooks.json 薄注册（create-if-absent，依赖 ownership 契约修复）
+  completed: true
+- id: task-75e82809da
+  title: R4b Codex hook schema 适配 + doctor 真实能力检测 + profiles 能力标志修正
+  completed: true
+- id: task-db9a33cfeb
+  title: 单测：AC1-AC3 事件流（投影一致/blocker 对/崩溃安全）
+  completed: true
+- id: task-e99a493355
+  title: e2e：AC7-AC9 config.toml 字节不变 + hooks 幂等 + doctor 检测
+  completed: true
+created_at: '2026-08-27T08:48:58+00:00'
+updated_at: '2026-08-27T09:56:42+00:00'
+completed_at: '2026-08-27T09:56:00+00:00'
+archived_at: '2026-08-27T09:56:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-2026082727cc4ab535e7.yaml

@@ -0,0 +1,11 @@
+schema_version: 1
+id: STORY-slim-2026082727cc4ab535e7
+title: '[P2-1 backlog] 生成式目录 + 漂移门'
+spec_path: docs/specs/STORY-slim-2026082727cc4ab535e7.md
+status: backlog
+tasks:
+- id: task-bfca30c6d4
+  title: workflow_registry + RULE_DEFINITIONS 生成 docs/reference/ 目录页，CI 校验 diff 为零
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-2026082730b5954cf538.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-2026082730b5954cf538
+title: '[P2-4 backlog] 治理工具 MCP 化'
+spec_path: docs/specs/STORY-slim-2026082730b5954cf538.md
+status: backlog
+tasks:
+- id: task-d3e006470a
+  title: board/continuation/doctor 关键子命令包成 MCP server（[mcp_servers] 配置段生成）
+  completed: false
+- id: task-277db672a9
+  title: Codex hook handler 可走 MCP 不必 shell out
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827625b870eb7da.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-20260827625b870eb7da
+title: '[P2-3 backlog] 配置分层组合（企业基线→项目→用户 overlay）'
+spec_path: docs/specs/STORY-slim-20260827625b870eb7da.md
+status: backlog
+tasks:
+- id: task-2679e2e287
+  title: pactkit.yaml 层叠 last-write-wins + pactkit config dump
+  completed: false
+- id: task-c1d42aa3f3
+  title: 参考 Codex config loader 与 dsh profile/bundle/patch 语义
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-202608277ec1236a7b99.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-202608277ec1236a7b99
+title: '[P1-2 backlog] outcome_unknown 崩溃恢复中间态'
+spec_path: docs/specs/STORY-slim-202608277ec1236a7b99.md
+status: backlog
+tasks:
+- id: task-ff2e3a5ece
+  title: checkpoint 状态机增加 outcome_unknown（evidence 级 unknown 标记）
+  completed: false
+- id: task-ded01b6504
+  title: 恢复时强制重跑验证步骤而非沿用旧结论（Ctrl-C 半途场景）
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827833e7a200f9a.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-20260827833e7a200f9a
+title: '[P2-2 backlog] 跨宿主 prompt snapshot 测试'
+spec_path: docs/specs/STORY-slim-20260827833e7a200f9a.md
+status: backlog
+tasks:
+- id: task-01ebdf0a92
+  title: deploy 到临时目录，对 Claude/OpenCode/Codex 三 profile 产物做字节级 snapshot
+  completed: false
+- id: task-a763670641
+  title: 拦截 prompt 模板静默回归（2.21/2.22 类事故）
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827855bf3efaec3.yaml

@@ -0,0 +1,15 @@
+schema_version: 1
+id: STORY-slim-20260827855bf3efaec3
+title: '[P1-3 backlog] 设计决策记录（Agent Notes 治理版）'
+spec_path: docs/specs/STORY-slim-20260827855bf3efaec3.md
+status: backlog
+tasks:
+- id: task-3591472ca8
+  title: decision note 模板 + commit-gate 规则：触及 governance/spec/architecture 文件须有对应
+    note
+  completed: false
+- id: task-f613d0b46d
+  title: enterprise adoption：可追溯架构决定
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-2026082799fa651655be.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-2026082799fa651655be
+title: '[P2-5 backlog] 宿主版本/能力探测泛化'
+spec_path: docs/specs/STORY-slim-2026082799fa651655be.md
+status: backlog
+tasks:
+- id: task-5de27982c1
+  title: 大部分已被 STORY-slim-20260827024e71df170f R4/R5（Codex 探测）覆盖
+  completed: false
+- id: task-c4fe968bfc
+  title: 剩余：OpenCode/Copilot 的版本探测与 profiles 能力标志动态化
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827c67e3add6af5.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-20260827c67e3add6af5
+title: '[P1-1 backlog] 授权审计事件对：authorization/asked + granted|denied 落事件流'
+spec_path: docs/specs/STORY-slim-20260827c67e3add6af5.md
+status: backlog
+tasks:
+- id: task-4c09090c5f
+  title: 依赖 P0 事件流（STORY-slim-20260827024e71df170f）落地后在 blocker 升降路径落审计事件对
+  completed: false
+- id: task-d235e1cc19
+  title: enterprise 合规刚需，实现成本低
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827d0ae0dfada51.yaml

@@ -0,0 +1,15 @@
+schema_version: 1
+id: STORY-slim-20260827d0ae0dfada51
+title: '[P1-5 backlog] write_scope 编译到宿主策略层'
+spec_path: docs/specs/STORY-slim-20260827d0ae0dfada51.md
+status: backlog
+tasks:
+- id: task-58344cf3ec
+  title: Spec Touches∪项目 write_scope 编译为 Codex sandbox/permission profile + Claude
+    allowlist
+  completed: false
+- id: task-b0d252b40a
+  title: 从 prompt 劝告升级为宿主结构性拒绝
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827eddbe9669c87.yaml

@@ -0,0 +1,25 @@
+schema_version: 1
+id: STORY-slim-20260827eddbe9669c87
+title: Continuation 状态机补强：授权审计事件对与 outcome_unknown 恢复语义
+spec_path: docs/specs/STORY-slim-20260827eddbe9669c87.md
+status: archived
+tasks:
+- id: task-a8efbbeec3
+  title: R1 授权审计事件对（asked/granted 自动 + denied 显式，双路径发射）
+  completed: true
+- id: task-d110c08951
+  title: R2 pactkit continuation deny 命令（锁内、前置校验、blocked 重写）
+  completed: true
+- id: task-2421d25f0b
+  title: R3 验证尝试围栏 record_attempt + commit-gate 接入
+  completed: true
+- id: task-117b0a1a81
+  title: R4 resume/finish_guard outcome_unknown 交叉检查（阻塞与解除）
+  completed: true
+- id: task-7f72e34442
+  title: R5 stats 授权决策计数 + golden CLI 更新
+  completed: true
+created_at: '2026-08-27T10:10:27+00:00'
+updated_at: '2026-08-27T10:22:05+00:00'
+completed_at: '2026-08-27T10:20:23+00:00'
+archived_at: '2026-08-27T10:22:05+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827fb6291b717eb.yaml

@@ -0,0 +1,14 @@
+schema_version: 1
+id: STORY-slim-20260827fb6291b717eb
+title: '[P1-4 backlog] Codex 插件分发形态（.codex-plugin manifest）'
+spec_path: docs/specs/STORY-slim-20260827fb6291b717eb.md
+status: backlog
+tasks:
+- id: task-0d580253d2
+  title: 生成 .codex-plugin manifest 捆绑 skills+hooks+MCP 声明
+  completed: false
+- id: task-f164041c5b
+  title: 依赖 P0-4 hooks.json；对称于现有 Claude plugin 发布流程
+  completed: false
+created_at: '2026-08-27T08:49:42+00:00'
+updated_at: '2026-08-27T08:49:42+00:00'

pactkit-2.24.1/docs/product/stories/STORY-slim-20260827fc9de5542ad7.yaml

@@ -0,0 +1,26 @@
+schema_version: 1
+id: STORY-slim-20260827fc9de5542ad7
+title: Codex command references 所有权契约修复：command manifest v2 记录 reference 摘要
+spec_path: docs/specs/STORY-slim-20260827fc9de5542ad7.md
+status: archived
+tasks:
+- id: task-d1692f4bfa
+  title: 'core: command_ownership.py v2 schema + record_deployed_reference + v1 兼容读取
+    + 单测'
+  completed: true
+- id: task-c0be7952ec
+  title: 'adapter: deploy_codex_command_skills 渲染时记录 reference 摘要（snapshot 事务内）'
+  completed: true
+- id: task-f1131d32f2
+  title: 'adapter: _cleanup_stale_command_references 证明来源 ∪ command manifest v2'
+  completed: true
+- id: task-7879b106f3
+  title: 'adapter tests: 修复两个红测试 + AC3/AC5/AC6 覆盖'
+  completed: true
+- id: task-2100a3eacd
+  title: 'core tests: v2 单测 + 全量回归'
+  completed: true
+created_at: '2026-08-27T09:16:45+00:00'
+updated_at: '2026-08-27T09:33:12+00:00'
+completed_at: '2026-08-27T09:33:12+00:00'
+archived_at: '2026-08-27T09:33:12+00:00'