@heihei0299/matt-skills 1.6.4-test.0 → 1.6.4-test.1

package/.agents/skills/tdd-implement/SKILL.md

@@ -22,15 +22,14 @@ description: "Multi-task orchestrator: use when the user provides a spec/ticket
 
 | Step | 做什么 | 完成条件（可验证） | 详规 |
 |------|--------|-------------------|------|
-| ① 理解需求 | 读取 spec/ticket + `CONTEXT.md`/`docs/adr/`，澄清歧义 | 能复述需求且无未澄清歧义 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
-| ② 确认 Seams | 列出待测公共接口 seams（名称+输入+预期输出），向用户确认并生成 Todo | 用户明确同意 seams 清单；Todo 已生成 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
-| ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
-| ④ 完整测试套件 | 跑全量测试 | 全部测试通过（失败回 ③） | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
-| ⑤ Code Review | 按 [code-review](.agents/skills/code-review/SKILL.md) 双轴审查（Standards + Spec） | 双轴均通过 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
-| ⑥ Commit | 跑 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁四项后提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
-| ⑦ 收尾 | 文档对齐 → issue 状态与实施总结 → 目录卫生 | 文档已对齐、issue 已 `resolved`+总结落盘、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
-
-主代理串行时每 `task` 仍走上表 ①→⑦（每 issue 单独 `commit`，`code-review` + `commit-check` 双门禁逐 issue，全量由 A4 收敛）。
+| ① 理解需求 | 读取入口并建立验证矩阵 | 需求无待决歧义，验证命令已确定 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
+| ② 确认 Seams | 从明确 spec/ticket 生成 seams 与 Todo；详规列出的确认门槛例外（含破坏性操作） | seams/Todo 已生成且无待决歧义 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
+| ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
+| ④ 最终全量测试 | 所有 issue 完成后按验证矩阵只运行一次全量命令；多 issue 由 A4 执行，单 spec 在 issue 收尾后执行 | 全量测试通过 | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
+| ⑤ Code Review | 每个 issue 恰好执行一次 Standards + Spec 双轴 review；findings 只做 targeted 修复，不再次 review | 每个 issue 的一次 review 已完成 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
+| ⑥ Commit | 运行一次最终 commit-check 门禁并提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
+| ⑦ 收尾 | 复核门禁证据，处理 issue 总结与目录卫生 | 总结完成、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
+主代理串行时每个 `task` 先走 `①→②→③→⑤→⑥→⑦` 并单独 commit；所有 issue 完成后再执行阶段④全量收敛（单 spec 只有一个 issue，也在其收尾后执行一次）。
 
 ### 阶段间流转
 

package/.agents/skills/tdd-implement/references/orchestration.md

@@ -45,8 +45,8 @@ Ln = 最后一层
 ```
 for each 层 Li in L1..Ln:
   for each issue in Li（按编号顺序）:
-    主代理直接执行该 issue 的完整 ①→⑦：
-      ①理解需求 → ②确认 seams → ③红-绿循环（每 cycle 后 typecheck）→ ④相关测试 → ⑤code-review（双轴，逐 issue）→ ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）
+    主代理直接执行该 issue 的 issue 闭环：
+      ①理解需求 → ②生成 seams/Todo → ③红-绿循环（每 cycle 后 typecheck）→ ⑤一次 code-review → ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）；④全量测试不在 issue 闭环内执行
     产回执卡片（改动文件/测试结果/commit hash）并回写该 issue 文件后**强制更新 `progress.md` 该行**（`Status`/`Commit`/`Review`/`Tests`）后再取下一 issue
   层收敛：该层全部 issue `Status: resolved` 且 `progress.md` 同步为 `done`、各自独立 commit 已落盘、相关测试通过、`git status` 卫生、历史校验通过，才进下一层
 全部层串行完成后进入 A4
@@ -69,7 +69,7 @@ for each 层 Li in L1..Ln:
 ### A4. 全量收敛
 
 全部层串行完成且各自层收敛通过后，执行：
-1. **全量测试套件**：跑仓库完整测试套件（仅此一次全量）
+1. **全量测试套件**：这是多 issue 流程中唯一的全量回归点；全部层、全部 issue 串行完成后仅执行一次（失败修复后才允许必要重跑）
 2. **历史校验**：`git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即 `reflog` 恢复后重跑
 3. **目录卫生**：`git status` 无 `[DEBUG-...]` 残留、无未跟踪临时文件
 4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件

package/.agents/skills/tdd-implement/references/stages.md

@@ -24,13 +24,16 @@
 ### 操作
 
 1. 完整读取入口（`spec` 或 `issue`）内容
-2. 若存在 `CONTEXT.md` 和 `docs/adr/`，先阅读，确保术语和 ADR 决策不被违背
-3. 如有歧义，先向用户澄清再继续
+2. 使用读取预算：按需读取 `CONTEXT.md` 的相关术语；ADR 只读与 spec、触及符号或失败证据相关的条目，不批量读取无关文档
+3. 使用仓库规定的代码探索入口；探索结果包含完整源码时视为已读，不再次 `read` 同一文件，除非文件发生漂移或只返回调用路径
+4. 如有歧义，先向用户澄清再继续；无歧义时直接进入阶段②
+5. 建立一次验证矩阵：列出 targeted tests、typecheck、全量测试以及 spec 要求的 smoke、package 或 security checks，后续复用证据，避免等价命令重复执行
 
 ### 出口条件
 
 - 能用自己的话复述需求
 - 无未澄清的歧义
+- 验证矩阵已建立，且每项命令/检查已有明确触发条件
 
 ### 边界
 
@@ -46,14 +49,14 @@
 ### 操作
 
 1. 列出所有将要测试的公共接口（seams）
-2. 每个 seam 需包含：名称、输入、预期输出
-3. 向用户展示 seams 清单并确认
-4. 用户确认后才写任何测试代码
-5. seams 确认后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
+2. 每个 seam 包含：名称、输入、预期输出，以及对应的最小验证命令
+3. spec/ticket 已给出明确验收标准时，直接生成 Todo 并展示精简 seam 卡片；不等待用户确认
+4. 仅在歧义、验收缺口、范围变化、破坏性操作或互斥方案时暂停确认
+5. seams 确认门槛满足后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
 
 ### 出口条件
 
-- 用户明确同意了 seams 清单
+- seams/Todo 已生成，且没有待决的歧义、验收缺口或需要用户选择的方案
 
 ### 边界
 
@@ -76,7 +79,7 @@
 
 #### TDD 编排
 
-**红-绿循环前与循环中都查阅 tdd 技能各节**（Every section applies on every cycle）：TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写——好测试标准见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 指南见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)。
+**读取预算（TDD Reference Cache）**：在阶段③入口加载 tdd 技能的相关规则一次；每个 cycle 仅按当前 seam 定位需要的 [`tdd/tests.md`](.agents/skills/tdd/tests.md) 与 [`tdd/mocking.md`](.agents/skills/tdd/mocking.md) reference，不重复阅读全文。TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写。
 
 本阶段只执行编排：按阶段②生成的 todo 清单逐条推进（大小任务层次与 Subtodo 格式见 [Todo 规定](#todo-规定)），每完成一个 todo（红-绿 cycle + typecheck）立即更新其状态为 `done`，再进入下一个 todo。
 
@@ -135,19 +138,18 @@
 
 ### 入口条件
 
-- 阶段 ③ 完成，typecheck 通过
-
+- 所有 issue 已完成其实现、targeted tests、typecheck、一次 code-review、commit 和收尾；多 issue 从 orchestration A4 进入，单 spec 在唯一 issue 收尾后进入
+- 阶段④不是 issue 闭环步骤，不得在任一 issue 完成时提前执行
 ### 操作
-
-1. 运行仓库的完整测试套件（仅该 issue 相关 + typecheck 已在阶段③完成，全量由多 issue 时的 A4 统一执行；单 issue / 单 spec 场景此步即全量）
-2. 检查所有测试是否通过
-
+1. 按阶段①建立的验证矩阵，运行仓库规范的唯一全量测试命令；正常路径只执行一次
+2. 若失败，先运行失败测试或最小相关子集定位原因；修复对应 issue 后才重跑全量命令
+3. 记录最终全量结果，不同时运行等价命令（例如 `npm test` 与其展开命令），除非本次改动了 package script 本身
+4. 检查所有测试是否通过
 ### 出口条件
-
-- 全部测试通过
-
+- 全量测试通过
 ### 边界
-- 测试失败时回到阶段 ③ 修复，修复后重新运行完整套件——进入 review 前必须全绿
+- 多 issue 仅由 A4 在所有 issue 完成后执行；单 spec 在唯一 issue 收尾后执行
+- 全量测试失败时回到失败 issue 的修复路径；修复后只做必要的定向诊断和全量重跑
 
 ---
 
@@ -155,16 +157,14 @@
 
 ### 入口条件
 
-- 完整测试套件通过
-
+- 阶段③ targeted tests 和 typecheck 通过；阶段④全量测试尚未执行也不构成此阶段入口条件
 ### 操作
-
-1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前 issue 的改动：
+1. 每个 issue 恰好调用一次 [code-review 技能](.agents/skills/code-review/SKILL.md)，按**双轴**审查当前 issue 的改动：
    - **Standards 轴**：改动是否符合仓库文档化的编码标准（含 smell baseline 判断）
    - **Spec 轴**：改动是否忠实实现来源 spec/issue（逐条对照验收要求）
-   - 两轴独立报告、**互不掩盖**——一轴通过另一轴失败时仍须修复后重审
-2. **逐 issue 触发**：每 issue 绿后即审查，未通过则当 issue 打回重做（→③/②/①），不进入下一 issue
-3. 审查发现的问题按 [回退路由](#回退路由) 处理
+   - 两轴独立报告、**互不掩盖**；该 issue 不再次调用 code-review
+2. 审查发现的问题按 [回退路由](#回退路由) 处理，并只重跑受影响的 targeted checks；修复不触发第二次 review
+3. 记录该 issue 的一次 review 结果，通过后进入 commit 和收尾
 
 ### 出口条件
 
@@ -184,9 +184,10 @@
 
 ### 操作
 
-1. 调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md) 执行提交门禁——四项检查：①审查文档 ②对齐 README ③保持目录卫生 ④规范 commit message
+1. 在一次最终门禁中调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md)：完成三项检查——文档一致性、目录卫生、commit message；目录卫生包含敏感扫描，spec 要求时再执行 package dry-run 等必要检查
 2. **历史校验**：commit 前执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明历史被改写，立即经 `git reflog` 恢复 `BASE_HEAD` 后的提交，校验通过才继续
-3. 四项**全部通过才 commit**（含历史校验通过）：将工作提交到当前分支，附清晰的 commit message（单 issue 单提交，如 `feat(<feature>): <issue title> (#NN)`）；多 issue 时每 issue 独立提交后才取下一 issue
+3. 三项门禁、历史校验和必要检查全部通过才 commit；门禁证据保持为最终基线，未改文件不在 commit 后重复扫描或打包
+4. 将工作提交到当前分支，附清晰的 commit message（单 issue 单提交，如 `feat(<feature>): <issue title> (#NN)`）；多 issue 时每 issue 独立提交后才取下一 issue
 
 ### 出口条件
 
@@ -194,7 +195,7 @@
 
 ### 边界
 
-- Commit message 格式与内容由 commit-check ④ 把关（描述变更内容而非过程）
+- Commit message 格式与内容由 commit-check ③ 把关（描述变更内容而非过程）
 - 每 issue 独立提交，主代理串行时一 issue 一 commit 后再进入下一 issue 的 ①
 
 ## 阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）
@@ -205,7 +206,7 @@
 
 ### 操作
 
-1. **对齐文档**：检查 README 与 `docs/` 中涉及本次实现的描述（用法、CLI、配置、示例、架构、行为）是否与实现一致；不一致则更新文档，并单独 commit（message 遵循 commit-check ④ 规范，如 `docs: align README with <feature>`）
+1. **复核文档对齐**：以阶段⑥ commit-check 已记录的 README/docs/config/package 对齐证据为准；本阶段只复核并记录“无需更新”或已更新文件，不重复读取、编辑或追加 commit。若证据缺失或不一致，标记阶段⑥门禁失败并停止收尾，不将 issue 标为 resolved。
 2. 若本次实现有关联 issue/ticket（`.scratch/<feature-slug>/issues/`）：先审查该 issue——从 issue 提取验收标准（无显式验收标准节时以其正文行为要求为准），逐条转写为 checkbox 清单并逐条验证：通过标 `- [x]`，未通过保留 `- [ ]` 并注明缺口（证据：文件:行号 / 测试名）。全部打勾后才允许下一步：
 3. 将 `Status:` 行改为 `resolved`（无该行则追加），不改动 spec 与既有 Comments
 4. 在 issue 文件底部追加实施总结（`## 实施总结` 标题）：
@@ -246,7 +247,7 @@
 ### 拆分层级（大小任务层次）
 
 1. **大任务**：Goal/Ticket——整个实现单元，对应一次完整的 tdd-implement 流程
-2. **中任务**：Seam（阶段②确认）——一个红-绿循环单元，每 seam 一个 Todo
+2. **中任务**：Seam（阶段②生成）——一个红-绿循环单元，每 seam 一个 Todo
 3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
 4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
 
@@ -254,7 +255,7 @@
 
 ### Todo 清单格式
 
-阶段② seams 确认后立即生成 todo 清单，每个 seam 一个 todo：
+阶段② seams 生成且确认门槛满足后立即生成 todo 清单，每个 seam 一个 todo：
 
 - 编号：`T1`、`T2`、`T3`…
 - 描述：seam 名称 + 输入 + 预期输出

package/README.md

@@ -92,6 +92,25 @@ git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-ski
 
 pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边界」已按此表述）。
 
+## Codex CLI 支持
+
+本仓库将 Codex CLI 作为一等本地 harness 支持。Codex 与 pi、opencode、Claude 共用项目级 `.agents/skills/`，项目级 `AGENTS.md` 继续作为通用行为路由和约束入口。
+
+- **项目级技能**：`.agents/skills/`（唯一共享源）
+- **全局技能**：`~/.codex/skills/`
+- **不创建**：项目级 `.codex/skills/` 副本；Codex 技能不单独分叉
+- **安装映射**：`--tools codex` 使用 `.agents/skills/`，`--global --tools codex` 使用 `~/.codex/skills/`
+
+使用真实 Codex CLI 验证支持：
+
+```sh
+npm run codex:smoke                         # 默认 SKIP，不需要 Codex 凭证
+CODEX_E2E=1 npm run codex:smoke             # 显式运行真实 smoke test
+```
+
+真实 smoke test 使用临时 fixture、ephemeral 会话、read-only sandbox 和 JSONL 输出，验证 `AGENTS.md` 与最小 `codex-probe` skill 的 sentinel。结果分为 `PASS`、`SKIP`、`FAIL_ENV` 和 `FAIL_CONTRACT`；环境问题与契约失败分别返回非零退出码。运行结果会记录 `codex --version`，但不绑定最低 CLI 版本。
+
+本期不包含 Codex Cloud、Codex-specific commands、plugins 或 MCP 配置。
 ## harness 目录结构
 
 两个 harness 的技能加载目录结构如下（本项目只分发项目级目录，全局目录由用户自备）：
@@ -174,7 +193,7 @@ npm publish
 ```
 
 - `prepublishOnly` 自动跑全量测试（`node --test test/*.test.js`）
-- 发布内容 = `bin/` + `template/` + `.agents/skills/` + `README.md`，由 `package.json` 的 `files` 白名单控制，`npm pack` 可预览
+- 发布内容 = `bin/` + `template/` + `.agents/skills/` + `scripts/` + `config/` + `README.md`，由 `package.json` 的 `files` 白名单控制，`npm pack` 可预览
 - `template/` 与 `.agents/skills/` 是包内容：改动后需重新发版才对目标仓库生效
 
 ## 开发

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.6.4-test.0",
+  "version": "1.6.4-test.1",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "template/",
     ".agents/skills/",
     "scripts/sync-upstream.js",
+    "scripts/codex-smoke.js",
     "config/proprietary.json",
     "config/engineering.json",
     "README.md"
@@ -18,6 +19,7 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "prepublishOnly": "node --test test/*.test.js",
+    "codex:smoke": "node scripts/codex-smoke.js",
     "build:template": "node scripts/build-template.js"
   },
   "dependencies": {

package/scripts/codex-smoke.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const AGENTS_SENTINEL = 'MATT_CODEX_AGENTS_SENTINEL=agents-loaded';
+const SKILL_SENTINEL = 'MATT_CODEX_SKILL_SENTINEL=skill-loaded';
+
+function printResult(kind, message = '') {
+  process.stdout.write(`${kind}${message ? `: ${message}` : ''}\n`);
+}
+
+function commandOutput(result) {
+  return [result.stdout, result.stderr, result.error?.message]
+    .filter(Boolean)
+    .join('\n')
+    .trim();
+}
+
+function detectCodex() {
+  const result = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+  if (result.error || result.status !== 0) {
+    return { ok: false, reason: `Codex CLI unavailable: ${commandOutput(result) || 'codex was not found'}` };
+  }
+  return { ok: true, version: commandOutput(result).split(/\r?\n/, 1)[0] };
+}
+
+function createFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'matt-skills-codex-smoke-'));
+  const skillDir = path.join(root, '.agents', 'skills', 'codex-probe');
+  fs.mkdirSync(path.join(skillDir, 'agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'AGENTS.md'), [
+    '# Codex smoke fixture',
+    '',
+    `When responding to the smoke probe, include the exact marker ${AGENTS_SENTINEL}.`,
+  ].join('\n') + '\n');
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), [
+    '---',
+    'name: codex-probe',
+    'description: Use when validating Codex project skill discovery.',
+    '---',
+    '',
+    `When the probe asks you to use this skill, include the exact marker ${SKILL_SENTINEL}.`,
+  ].join('\n') + '\n');
+  fs.writeFileSync(path.join(skillDir, 'agents', 'openai.yaml'), [
+    'interface:',
+    '  display_name: Codex Probe',
+    '  short_description: Validate Codex skill discovery',
+  ].join('\n') + '\n');
+  return root;
+}
+
+function finalAgentMessage(stdout) {
+  const events = [];
+  let malformed = false;
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      malformed = true;
+    }
+  }
+  const turnCompleted = events.at(-1)?.type === 'turn.completed';
+  let text = '';
+  let agentMessageIndex = -1;
+  events.forEach((event, index) => {
+    if (event?.item?.type === 'agent_message' && typeof event.item.text === 'string') {
+      text = event.item.text;
+      agentMessageIndex = index;
+    }
+  });
+  return {
+    text,
+    completed: turnCompleted && agentMessageIndex >= 0 && agentMessageIndex < events.length - 1,
+    malformed,
+  };
+}
+
+function runCodex(fixture) {
+  const prompt = [
+    'Run the Codex support probe.',
+    'Use the codex-probe skill explicitly if it is available.',
+    'Follow the project AGENTS.md instructions.',
+    'In the final response state the exact markers required by the discovered project instructions, and do not modify files.',
+  ].join(' ');
+  return spawnSync('codex', [
+    'exec', '--ephemeral', '--sandbox', 'read-only', '--json',
+    '--skip-git-repo-check', prompt,
+  ], { cwd: fixture, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+}
+
+function run() {
+  if (process.env.CODEX_E2E !== '1') {
+    printResult('SKIP', 'set CODEX_E2E=1 to run the real Codex smoke test');
+    return 0;
+  }
+
+  const detected = detectCodex();
+  if (!detected.ok) {
+    printResult('FAIL_ENV', detected.reason);
+    return 1;
+  }
+  process.stdout.write(`Codex version: ${detected.version}\n`);
+
+  let fixture;
+  try {
+    fixture = createFixture();
+    const result = runCodex(fixture);
+    const final = finalAgentMessage(result.stdout || '');
+    if (final.malformed) {
+      printResult('FAIL_ENV', 'malformed JSONL event');
+      return 1;
+    }
+    if (!final.completed) {
+      printResult('FAIL_ENV', commandOutput(result) || 'Codex response did not contain a completed final response event');
+      return 1;
+    }
+    const missing = [
+      !final.text.includes(AGENTS_SENTINEL) && 'AGENTS.md sentinel',
+      !final.text.includes(SKILL_SENTINEL) && 'skill sentinel',
+    ].filter(Boolean);
+    if (missing.length) {
+      printResult('FAIL_CONTRACT', `missing ${missing.join(' and ')}`);
+      return 1;
+    }
+    if (result.error || result.status !== 0) {
+      printResult('FAIL_ENV', commandOutput(result) || 'Codex execution failed');
+      return 1;
+    }
+    printResult('PASS', 'AGENTS.md and codex-probe skill sentinels verified');
+    return 0;
+  } finally {
+    if (fixture) fs.rmSync(fixture, { recursive: true, force: true });
+  }
+}
+
+process.exitCode = run();

package/template/.agents/skills/tdd-implement/SKILL.md

@@ -22,15 +22,14 @@ description: "Multi-task orchestrator: use when the user provides a spec/ticket
 
 | Step | 做什么 | 完成条件（可验证） | 详规 |
 |------|--------|-------------------|------|
-| ① 理解需求 | 读取 spec/ticket + `CONTEXT.md`/`docs/adr/`，澄清歧义 | 能复述需求且无未澄清歧义 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
-| ② 确认 Seams | 列出待测公共接口 seams（名称+输入+预期输出），向用户确认并生成 Todo | 用户明确同意 seams 清单；Todo 已生成 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
-| ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
-| ④ 完整测试套件 | 跑全量测试 | 全部测试通过（失败回 ③） | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
-| ⑤ Code Review | 按 [code-review](.agents/skills/code-review/SKILL.md) 双轴审查（Standards + Spec） | 双轴均通过 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
-| ⑥ Commit | 跑 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁四项后提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
-| ⑦ 收尾 | 文档对齐 → issue 状态与实施总结 → 目录卫生 | 文档已对齐、issue 已 `resolved`+总结落盘、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
-
-主代理串行时每 `task` 仍走上表 ①→⑦（每 issue 单独 `commit`，`code-review` + `commit-check` 双门禁逐 issue，全量由 A4 收敛）。
+| ① 理解需求 | 读取入口并建立验证矩阵 | 需求无待决歧义，验证命令已确定 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
+| ② 确认 Seams | 从明确 spec/ticket 生成 seams 与 Todo；详规列出的确认门槛例外（含破坏性操作） | seams/Todo 已生成且无待决歧义 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
+| ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
+| ④ 最终全量测试 | 所有 issue 完成后按验证矩阵只运行一次全量命令；多 issue 由 A4 执行，单 spec 在 issue 收尾后执行 | 全量测试通过 | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
+| ⑤ Code Review | 每个 issue 恰好执行一次 Standards + Spec 双轴 review；findings 只做 targeted 修复，不再次 review | 每个 issue 的一次 review 已完成 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
+| ⑥ Commit | 运行一次最终 commit-check 门禁并提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
+| ⑦ 收尾 | 复核门禁证据，处理 issue 总结与目录卫生 | 总结完成、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
+主代理串行时每个 `task` 先走 `①→②→③→⑤→⑥→⑦` 并单独 commit；所有 issue 完成后再执行阶段④全量收敛（单 spec 只有一个 issue，也在其收尾后执行一次）。
 
 ### 阶段间流转
 

package/template/.agents/skills/tdd-implement/references/orchestration.md

@@ -45,8 +45,8 @@ Ln = 最后一层
 ```
 for each 层 Li in L1..Ln:
   for each issue in Li（按编号顺序）:
-    主代理直接执行该 issue 的完整 ①→⑦：
-      ①理解需求 → ②确认 seams → ③红-绿循环（每 cycle 后 typecheck）→ ④相关测试 → ⑤code-review（双轴，逐 issue）→ ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）
+    主代理直接执行该 issue 的 issue 闭环：
+      ①理解需求 → ②生成 seams/Todo → ③红-绿循环（每 cycle 后 typecheck）→ ⑤一次 code-review → ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）；④全量测试不在 issue 闭环内执行
     产回执卡片（改动文件/测试结果/commit hash）并回写该 issue 文件后**强制更新 `progress.md` 该行**（`Status`/`Commit`/`Review`/`Tests`）后再取下一 issue
   层收敛：该层全部 issue `Status: resolved` 且 `progress.md` 同步为 `done`、各自独立 commit 已落盘、相关测试通过、`git status` 卫生、历史校验通过，才进下一层
 全部层串行完成后进入 A4
@@ -69,7 +69,7 @@ for each 层 Li in L1..Ln:
 ### A4. 全量收敛
 
 全部层串行完成且各自层收敛通过后，执行：
-1. **全量测试套件**：跑仓库完整测试套件（仅此一次全量）
+1. **全量测试套件**：这是多 issue 流程中唯一的全量回归点；全部层、全部 issue 串行完成后仅执行一次（失败修复后才允许必要重跑）
 2. **历史校验**：`git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即 `reflog` 恢复后重跑
 3. **目录卫生**：`git status` 无 `[DEBUG-...]` 残留、无未跟踪临时文件
 4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件

package/template/.agents/skills/tdd-implement/references/stages.md

@@ -24,13 +24,16 @@
 ### 操作
 
 1. 完整读取入口（`spec` 或 `issue`）内容
-2. 若存在 `CONTEXT.md` 和 `docs/adr/`，先阅读，确保术语和 ADR 决策不被违背
-3. 如有歧义，先向用户澄清再继续
+2. 使用读取预算：按需读取 `CONTEXT.md` 的相关术语；ADR 只读与 spec、触及符号或失败证据相关的条目，不批量读取无关文档
+3. 使用仓库规定的代码探索入口；探索结果包含完整源码时视为已读，不再次 `read` 同一文件，除非文件发生漂移或只返回调用路径
+4. 如有歧义，先向用户澄清再继续；无歧义时直接进入阶段②
+5. 建立一次验证矩阵：列出 targeted tests、typecheck、全量测试以及 spec 要求的 smoke、package 或 security checks，后续复用证据，避免等价命令重复执行
 
 ### 出口条件
 
 - 能用自己的话复述需求
 - 无未澄清的歧义
+- 验证矩阵已建立，且每项命令/检查已有明确触发条件
 
 ### 边界
 
@@ -46,14 +49,14 @@
 ### 操作
 
 1. 列出所有将要测试的公共接口（seams）
-2. 每个 seam 需包含：名称、输入、预期输出
-3. 向用户展示 seams 清单并确认
-4. 用户确认后才写任何测试代码
-5. seams 确认后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
+2. 每个 seam 包含：名称、输入、预期输出，以及对应的最小验证命令
+3. spec/ticket 已给出明确验收标准时，直接生成 Todo 并展示精简 seam 卡片；不等待用户确认
+4. 仅在歧义、验收缺口、范围变化、破坏性操作或互斥方案时暂停确认
+5. seams 确认门槛满足后生成 todo 清单（每 seam 一个 todo，格式与状态机见 [Todo 规定](#todo-规定)）
 
 ### 出口条件
 
-- 用户明确同意了 seams 清单
+- seams/Todo 已生成，且没有待决的歧义、验收缺口或需要用户选择的方案
 
 ### 边界
 
@@ -76,7 +79,7 @@
 
 #### TDD 编排
 
-**红-绿循环前与循环中都查阅 tdd 技能各节**（Every section applies on every cycle）：TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写——好测试标准见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 指南见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)。
+**读取预算（TDD Reference Cache）**：在阶段③入口加载 tdd 技能的相关规则一次；每个 cycle 仅按当前 seam 定位需要的 [`tdd/tests.md`](.agents/skills/tdd/tests.md) 与 [`tdd/mocking.md`](.agents/skills/tdd/mocking.md) reference，不重复阅读全文。TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写。
 
 本阶段只执行编排：按阶段②生成的 todo 清单逐条推进（大小任务层次与 Subtodo 格式见 [Todo 规定](#todo-规定)），每完成一个 todo（红-绿 cycle + typecheck）立即更新其状态为 `done`，再进入下一个 todo。
 
@@ -135,19 +138,18 @@
 
 ### 入口条件
 
-- 阶段 ③ 完成，typecheck 通过
-
+- 所有 issue 已完成其实现、targeted tests、typecheck、一次 code-review、commit 和收尾；多 issue 从 orchestration A4 进入，单 spec 在唯一 issue 收尾后进入
+- 阶段④不是 issue 闭环步骤，不得在任一 issue 完成时提前执行
 ### 操作
-
-1. 运行仓库的完整测试套件（仅该 issue 相关 + typecheck 已在阶段③完成，全量由多 issue 时的 A4 统一执行；单 issue / 单 spec 场景此步即全量）
-2. 检查所有测试是否通过
-
+1. 按阶段①建立的验证矩阵，运行仓库规范的唯一全量测试命令；正常路径只执行一次
+2. 若失败，先运行失败测试或最小相关子集定位原因；修复对应 issue 后才重跑全量命令
+3. 记录最终全量结果，不同时运行等价命令（例如 `npm test` 与其展开命令），除非本次改动了 package script 本身
+4. 检查所有测试是否通过
 ### 出口条件
-
-- 全部测试通过
-
+- 全量测试通过
 ### 边界
-- 测试失败时回到阶段 ③ 修复，修复后重新运行完整套件——进入 review 前必须全绿
+- 多 issue 仅由 A4 在所有 issue 完成后执行；单 spec 在唯一 issue 收尾后执行
+- 全量测试失败时回到失败 issue 的修复路径；修复后只做必要的定向诊断和全量重跑
 
 ---
 
@@ -155,16 +157,14 @@
 
 ### 入口条件
 
-- 完整测试套件通过
-
+- 阶段③ targeted tests 和 typecheck 通过；阶段④全量测试尚未执行也不构成此阶段入口条件
 ### 操作
-
-1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前 issue 的改动：
+1. 每个 issue 恰好调用一次 [code-review 技能](.agents/skills/code-review/SKILL.md)，按**双轴**审查当前 issue 的改动：
    - **Standards 轴**：改动是否符合仓库文档化的编码标准（含 smell baseline 判断）
    - **Spec 轴**：改动是否忠实实现来源 spec/issue（逐条对照验收要求）
-   - 两轴独立报告、**互不掩盖**——一轴通过另一轴失败时仍须修复后重审
-2. **逐 issue 触发**：每 issue 绿后即审查，未通过则当 issue 打回重做（→③/②/①），不进入下一 issue
-3. 审查发现的问题按 [回退路由](#回退路由) 处理
+   - 两轴独立报告、**互不掩盖**；该 issue 不再次调用 code-review
+2. 审查发现的问题按 [回退路由](#回退路由) 处理，并只重跑受影响的 targeted checks；修复不触发第二次 review
+3. 记录该 issue 的一次 review 结果，通过后进入 commit 和收尾
 
 ### 出口条件
 
@@ -184,9 +184,10 @@
 
 ### 操作
 
-1. 调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md) 执行提交门禁——四项检查：①审查文档 ②对齐 README ③保持目录卫生 ④规范 commit message
+1. 在一次最终门禁中调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md)：完成三项检查——文档一致性、目录卫生、commit message；目录卫生包含敏感扫描，spec 要求时再执行 package dry-run 等必要检查
 2. **历史校验**：commit 前执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明历史被改写，立即经 `git reflog` 恢复 `BASE_HEAD` 后的提交，校验通过才继续
-3. 四项**全部通过才 commit**（含历史校验通过）：将工作提交到当前分支，附清晰的 commit message（单 issue 单提交，如 `feat(<feature>): <issue title> (#NN)`）；多 issue 时每 issue 独立提交后才取下一 issue
+3. 三项门禁、历史校验和必要检查全部通过才 commit；门禁证据保持为最终基线，未改文件不在 commit 后重复扫描或打包
+4. 将工作提交到当前分支，附清晰的 commit message（单 issue 单提交，如 `feat(<feature>): <issue title> (#NN)`）；多 issue 时每 issue 独立提交后才取下一 issue
 
 ### 出口条件
 
@@ -194,7 +195,7 @@
 
 ### 边界
 
-- Commit message 格式与内容由 commit-check ④ 把关（描述变更内容而非过程）
+- Commit message 格式与内容由 commit-check ③ 把关（描述变更内容而非过程）
 - 每 issue 独立提交，主代理串行时一 issue 一 commit 后再进入下一 issue 的 ①
 
 ## 阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）
@@ -205,7 +206,7 @@
 
 ### 操作
 
-1. **对齐文档**：检查 README 与 `docs/` 中涉及本次实现的描述（用法、CLI、配置、示例、架构、行为）是否与实现一致；不一致则更新文档，并单独 commit（message 遵循 commit-check ④ 规范，如 `docs: align README with <feature>`）
+1. **复核文档对齐**：以阶段⑥ commit-check 已记录的 README/docs/config/package 对齐证据为准；本阶段只复核并记录“无需更新”或已更新文件，不重复读取、编辑或追加 commit。若证据缺失或不一致，标记阶段⑥门禁失败并停止收尾，不将 issue 标为 resolved。
 2. 若本次实现有关联 issue/ticket（`.scratch/<feature-slug>/issues/`）：先审查该 issue——从 issue 提取验收标准（无显式验收标准节时以其正文行为要求为准），逐条转写为 checkbox 清单并逐条验证：通过标 `- [x]`，未通过保留 `- [ ]` 并注明缺口（证据：文件:行号 / 测试名）。全部打勾后才允许下一步：
 3. 将 `Status:` 行改为 `resolved`（无该行则追加），不改动 spec 与既有 Comments
 4. 在 issue 文件底部追加实施总结（`## 实施总结` 标题）：
@@ -246,7 +247,7 @@
 ### 拆分层级（大小任务层次）
 
 1. **大任务**：Goal/Ticket——整个实现单元，对应一次完整的 tdd-implement 流程
-2. **中任务**：Seam（阶段②确认）——一个红-绿循环单元，每 seam 一个 Todo
+2. **中任务**：Seam（阶段②生成）——一个红-绿循环单元，每 seam 一个 Todo
 3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
 4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
 
@@ -254,7 +255,7 @@
 
 ### Todo 清单格式
 
-阶段② seams 确认后立即生成 todo 清单，每个 seam 一个 todo：
+阶段② seams 生成且确认门槛满足后立即生成 todo 清单，每个 seam 一个 todo：
 
 - 编号：`T1`、`T2`、`T3`…
 - 描述：seam 名称 + 输入 + 预期输出