paceaitian · paceaitian · Aug 16, 2026 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026
diff --git a/.gitignore b/.gitignore
@@ -23,6 +23,8 @@ tests/*
 !tests/test-migrate-v7.js
 !tests/run-all.js
 !tests/test-run-all.js
+!tests/test-codex-adapter.js
+!tests/test-mcp-server.js
 # 例外：agent 测试框架是产品资产（v6.0.0 起），但运行结果除外
 !tests/agent-tests/
 tests/agent-tests/results/

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -26,7 +26,7 @@ PACEflow 的运行时行为必须由以下位置定义：
 node tests/run-all.js
 
 # 迭代时按名分片只跑某套件（子串匹配套件名：pace-utils / hooks-e2e /
-# session-layers / migrate-v7 / agent-helpers / run-all-self / plugin-validate / git-diff-check）
+# session-layers / migrate-v7 / agent-helpers / codex-adapter / mcp-server / run-all-self / plugin-validate / git-diff-check）
 PACE_TEST_FILTER=hooks-e2e node tests/run-all.js
 
 # 发版后核整段 release 区间 whitespace：push 后 @{upstream}..HEAD=0，upstream 区间查不到已推送的
@@ -43,15 +43,15 @@ PACE_RELEASE_BASE=<上一个 release 的 commit> node tests/run-all.js
 ```bash
 # 从 paceflow/ 运行（或从仓库根 node paceflow/bump-version.js）
 node bump-version.js --dry-run v7.2.16   # 先预览将改哪些文件
-node bump-version.js v7.2.16             # 同步 5 处：constants.js PACE_VERSION / plugin.json / marketplace.json / REFERENCE.md 标题 / README.md 版本行（footer）
+node bump-version.js v7.2.16             # 同步 6 处：constants.js PACE_VERSION / .claude-plugin/plugin.json / .codex-plugin/plugin.json / marketplace.json / REFERENCE.md 标题 / README.zh-CN.md 版本行（footer）
 ```
 
 脚本**不覆盖**、仍需手动的两处：
 
 - `README.md` 版本历史表格新增一行 changelog（人读描述，脚本不生成）
 - `CLAUDE.md` 等散文里残留的版本号（如有）
 
-收尾走上面「常用验证」：`node tests/run-all.js` 8/8 → commit → push → 三向确认 `git rev-parse HEAD` == `git rev-parse origin/master` == `git ls-remote origin master`（防 commit/push 链短路推旧 HEAD 静默漏发）。
+收尾走上面「常用验证」：`node tests/run-all.js` 10/10 → commit → push → 三向确认 `git rev-parse HEAD` == `git rev-parse origin/master` == `git ls-remote origin master`（防 commit/push 链短路推旧 HEAD 静默漏发）。
 
 push 三向确认后，**打 tag + 建 GitHub release**——漏这步会让版本史断档、用户看不到 release notes（v7.0~v7.2.14 就因发版流程没写这步全缺、后来批量回填）：
 

diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 
 PACEflow keeps coding agents on a verifiable engineering workflow during long, stateful tasks. It enforces workflow transitions at tool boundaries, persists task state outside the model context, and restores that state across sessions and context compaction.
 
-PACEflow is currently implemented as a **Claude Code plugin**, while its underlying reliability model—deterministic gates, persistent artifacts, verification, and review—addresses problems common to long-running coding agents.
+PACEflow ships as a **Claude Code plugin** that also installs into **OpenAI Codex CLI** (same plugin directory, same hook scripts, artifact writes via a bundled MCP server on Codex — see [Codex CLI (MVP)](#codex-cli-mvp)). Its underlying reliability model—deterministic gates, persistent artifacts, verification, and review—addresses problems common to long-running coding agents.
 
 ## Why PACEflow?
 
@@ -40,7 +40,7 @@ The model still plans, implements, verifies, and reviews the code. A PACEflow ga
 | Across sessions | Active change state and relevant project memory are restored on startup, resume, and compaction. |
 | During record-keeping | A dedicated `artifact-writer` maintains structured artifacts, reducing record-keeping in the main coding context. |
 
-The current implementation uses Claude Code hooks, so the gates run at tool boundaries rather than depending only on prompt compliance.
+The current implementation uses the host's lifecycle hooks (Claude Code hooks; Codex CLI hooks through a thin host adapter), so the gates run at tool boundaries rather than depending only on prompt compliance.
 
 ## The PACE lifecycle
 
@@ -62,7 +62,7 @@ Plan → Artifact → Check → Execute → Verify → Review → Close
 
 ## Installation
 
-PACEflow currently requires **Claude Code 2.1.218 or newer**. Two hard dependencies: the hook manifest uses the `hooks[].args` execution form (introduced in 2.1.139), and it registers the `SubagentStart` hook event (earliest version verified to support it: 2.1.218). **A host that does not recognize any event name in a plugin's hooks.json silently drops the plugin's entire hook set** (verified empirically) — on older hosts every PACEflow gate would fail without any warning.
+On Claude Code, PACEflow requires **Claude Code 2.1.218 or newer** (Codex CLI: see [below](#codex-cli-mvp)). Two hard dependencies: the hook manifest uses the `hooks[].args` execution form (introduced in 2.1.139), and it registers the `SubagentStart` hook event (earliest version verified to support it: 2.1.218). **A host that does not recognize any event name in a plugin's hooks.json silently drops the plugin's entire hook set** (verified empirically) — on older hosts every PACEflow gate would fail without any warning.
 
 Run these commands inside Claude Code:
 
@@ -77,7 +77,7 @@ Restart Claude Code after installation, then enable PACEflow in a project:
 /paceflow:enable
 ```
 
-The plugin registers nine hook event types, four user skills, five user commands, and one `artifact-writer` agent.
+The plugin registers twelve hook event types, four user skills, five user commands, and one `artifact-writer` agent.
 
 ### Optional Obsidian storage
 
@@ -89,6 +89,19 @@ $PACE_VAULT_PATH/projects/<project-name>/
 
 The choice is persisted in `.pace/artifact-root`. Headless environments can set `PACE_ARTIFACT_ROOT` to `local`, `vault`, or an absolute path.
 
+### Codex CLI (MVP)
+
+PACEflow also installs into OpenAI Codex CLI (verified end-to-end on codex-cli 0.147.0 on Linux and Windows). Codex reads the same plugin directory through `.codex-plugin/plugin.json`: hooks are registered from `hooks/hooks.codex.json` — every entry runs `hooks/codex-adapter.js`, which translates Codex events (`apply_patch`, MCP tool calls, plain-text output) for the shared hook scripts, so the gate logic is the same code — and artifact writes go through the bundled `paceflow` MCP server instead of the `artifact-writer` subagent (Codex subagent prompts are opaque to hooks and hooks do not fire inside subagents).
+
+```text
+codex plugin marketplace add paceaitian/paceflow
+codex plugin add paceflow@paceaitian-paceflow
+```
+
+Then review and trust the hooks with `/hooks` (automation can pass `--dangerously-bypass-hook-trust`) and start a new thread. Enable PACEflow per project with the helper the SessionStart hook prints (`set-artifact-root.js --choice local|vault`).
+
+MVP scope on Codex: the write gate on `apply_patch`/Bash, the Stop gate, SessionStart/UserPromptSubmit injection, and the MCP tools `get_context` / `reserve_artifact_id` / `create_chg` / `update_chg` (approve, approve-and-start, update-status, append, verify, review) / `close_chg` / `record_finding`. Not covered yet: `archive-chg`, `update-finding`, `record-correction`, `update-index`, batch create — and, as a host limitation, file writes made inside Codex subagents are not gated. Details in the [reference manual](REFERENCE.md#52-codex-cli-宿主).
+
 ## Quick start
 
 After installation and `/paceflow:enable`:
@@ -134,7 +147,7 @@ PACEflow registers hooks for twelve lifecycle events:
 
 - `SessionStart` restores project and change context.
 - `UserPromptSubmit` injects a one-line active-change summary on each user turn when this session has a running or closing-required change (second anti-forgetting channel; silent when paused or nothing matches).
-- `PreToolUse` guards code writes, shell mutations, agent dispatches, approvals, artifact writes, and runtime control files.
+- `PreToolUse` guards code writes made through Write/Edit/MultiEdit (the code-write gate), agent dispatches, approvals, and artifact / runtime-control writes — including shell commands that would mutate artifacts or `.pace`. Shell writes to ordinary code files are not gated: the gate is a reminder against forgetting, not a sandbox.
 - `PostToolUse` and `PostToolUseFailure` record or surface follow-up requirements.
 - `SubagentStart` and `Notification` are logging-only observers (lifecycle accounting and host-event field collection).
 - `SubagentStop` fires on every subagent stop (including mid-run idles on host 2.1.232+); it observes `artifact-writer` reports and closes change ownership only on a terminal SUCCESS report.
@@ -169,7 +182,7 @@ Git worktrees and Claude Code worktrees share PACEflow artifacts and runtime sta
 
 ## Runtime scope and trust boundary
 
-The released implementation targets **Claude Code** because its hook lifecycle exposes the boundaries PACEflow needs. The broader model—persistent workflow state, deterministic tool gates, human approval, verification, review, and session recovery—can be evaluated on other coding-agent runtimes only where equivalent lifecycle controls exist.
+The released implementation targets **Claude Code** and, as an MVP, **OpenAI Codex CLI** — both expose the lifecycle hooks PACEflow needs (Codex implements the same hook protocol; the differences are handled by `hooks/codex-adapter.js`, and Codex lacks subagent-aware hooks, so on Codex the artifact writer is an MCP server rather than a subagent). The broader model—persistent workflow state, deterministic tool gates, human approval, verification, review, and session recovery—can be evaluated on other coding-agent runtimes only where equivalent lifecycle controls exist.
 
 PACEflow is not:
 
@@ -193,7 +206,7 @@ node tests/run-all.js
 
 The aggregate runner also performs Claude plugin validation and `git diff --check`. For focused iteration, set `PACE_TEST_FILTER` to a suite-name substring before running the same command.
 
-The runtime published through the Claude Code marketplace lives under `plugin/`. Repository maintenance material, tests, and historical design documents live under `tests/`, `docs/`, and `internal/`.
+The runtime published through the Claude Code marketplace lives under `plugin/` (Codex reads the same directory through `plugin/.codex-plugin/plugin.json`). Repository maintenance material, tests, and historical design documents live under `tests/`, `docs/`, and `internal/` — the Codex port research and acceptance records are in `docs/research-2026-08-15-codex-port-feasibility.md` and `docs/research/codex-port/`.
 
 ## Documentation