closed-loop

name	closed-loop
description	Run the full audit → core-review → fix → fix-verify → gate → commit workflow on a harmony stage topic (NAPI / Engine / Audio / Video / NativeBuffer / Resource lifecycle / Input+EventBridge / SaveState+SRAM+Disk). Use when user says "跑闭环 X" / "audit + 修 X" / "完整审一下 X" / "/closed-loop". Drives the 8-step trust chain end-to-end with 4 mandatory human checkpoints.
disable-model-invocation	true
allowed-tools	Bash, Read, Grep, Glob, Edit, Write, Agent, TaskCreate, TaskUpdate, TaskList, TaskGet
model	sonnet
trigger	when user explicitly invokes /closed-loop, OR says "完整闭环走一遍 / audit + 修 / 闭环跑 X"

/closed-loop — Audit → Core-Review → Fix → Verify → Commit (harmony)

What this exists for

scripts/check/quick_signals.sh proves build/regression hygiene but doesn't catch semantic / cross-language / NativeBuffer-lifecycle bugs. The closed-loop catches what fast signals can't, and crucially does it with machine-re-verifiable trust between every stage:

sub-agents (broad discovery, parallel by topic)
    ↓ each finding has structured citation (file:line + evidence_excerpt)
    ↓ main Claude MECHANICALLY re-reads cited file:line via Read + grep
main Claude (single reviewer + implementer)
    ↓ judges REAL / REAL_LOWER / DESIGN / FALSE_POSITIVE per-finding
    ↓ fixes REAL findings directly via Edit
    ↓ if fix touches entry/src/main/cpp/app/napi/** → MUST dispatch
      napi-boundary-reviewer agent BEFORE applying the edit
    ↓ re-dispatches same audit topic on the fix code
sub-agents (fix verification)
    ↓ each fix-finding cites the fix code (where the new guard lives)
    ↓ main Claude re-verifies fix citations via Read + grep
gate gauntlet (bash scripts/check/quick_signals.sh)
    ↓ green
human checkpoint
    ↓ approves commit message + scope
git commit

No step trusts the previous step's claim. This is harmony's adapted form of the trust chain pattern; see [[harness-fusion-2026-05-24]].

When to invoke

Use this skill when:

• User explicitly says /closed-loop or "跑闭环" / "audit + 修" / "完整审"
• User asks to deep-audit + fix a specific scope (one of the 8 topics below, or a custom scope)
• A major milestone is about to commit and we want one last semantic sweep

Do NOT use this skill for:

• Quick sanity check (use bash scripts/check/quick_signals.sh)
• Single-file lookup (use Read/Grep)
• Plain agent dispatch without verification (just use Agent tool directly)
• UI / ArkTS-only fixes (different workflow, ts/ets layer doesn't have NativeBuffer lifetime hazards that justify the full 8-step gauntlet)

Topics (8 fixed, harmony-tuned)

每个 topic 的完整 scope / files / hazards / done-criteria 模板见 topics/T<n>-<name>.md。 本表只列 ID + name + 一句话 scope,主流程节点引用 topic file 详情(progressive disclosure)。

ID	Name	Scope (one-liner)	Details
T1	NAPI 边界	ArkTS ↔ C++ 互调的 NAPI 层	topics/T1-napi.md
T2	Engine 状态机	LibretroEngine 状态机 + 消息队列 + retro_run 调度	topics/T2-engine.md
T3	Audio bridge	AudioBridge 重采样 / DRC / RingBuffer / underrun	topics/T3-audio.md
T4	VideoPipeline	VideoPipeline 模式协商 + 渲染(CPU/GLES/Vulkan)	topics/T4-video.md
T5	NativeBuffer 用法	Cross-cutting OH_NativeBuffer_* / OH_NativeWindow_* 配对	topics/T5-nativebuffer.md
T6	资源生命周期	XComponent / NativeWindow / EGL / fd / SRAM/SaveState 文件	topics/T6-resource.md
T7	Input / EventBridge 跨层	输入 + 跨语言事件路由(ArkTS hub ↔ C++ bridge ↔ libretro input)	topics/T7-input.md
T8	SaveState / SRAM / Disk I/O 持久化	SaveState + SRAM + Disk Control 全链路 I/O	topics/T8-savestate.md

新增 topic: 复制 topics/T<n>.md 模板(任一现存的拿来改),把新行加到上表。 主 SKILL.md 不再变长。

The 8 fix steps (Step 0 是 sprint contract，不计入 fix step；Step 5 Rebuild 已并入 Step 7)

Contract block(2026-05-29 加,见 memory feedback_task_contract_missing)

每个 Step 开头的 5 段契约块统一使用以下缩写格式(避免 SKILL 膨胀):

> **In**:  <上一步产物 file/state>
> **Out**: <我交什么 → 下一步如何 trust>
> **Role**: [L1 脚本 / L2 MCP / L3 subagent / L4 主 AI] + [NOT 越权]
> **Done**: [ ] checklist 可勾选

ROLE 4 层:L1 脚本(机械事实)/L2 MCP(语义查询)/L3 subagent(并行发现)/L4 主 AI(推理判断)。 越权(任何方向)= bug,见 memory feedback_skill_role_separation。

---

Step 0 — Done criteria(sprint contract,开工前定)

In: user 指定 topic(T1-T8)+ AUDIT_DIR 已建 Out: AUDIT_DIR/DONE.md — 本次 audit 边界 + done-checklist → Step 1+ 据此约束 scope Role: [L4 主 AI] cat topic 模板 + 按本次范围调整 checkbox; [NOT] 不开工 audit Done: [ ] AUDIT_DIR/DONE.md 含 scope-in / scope-out / 完成判据,user 已 review

外网共识(Addy Osmani):"写下 done-condition 阻止 scope drift 比任何 prompt 调整都管用"。 项目 memory feedback_completeness_is_scenario_not_form 反复出现的根因——开工时未明确 "什么叫审完",fix 完了才回头问 "够不够"。

动作:在创建 AUDIT_DIR 之后(Step 1 之前)立刻:

1. cat .claude/skills/closed-loop/topics/T<n>-<name>.md 拿到该 topic 的 hazards 清单 + done-criteria 模板(2026-05-28 progressive disclosure 拆分)
2. 把模板 copy 到 AUDIT_DIR/DONE.md,按本次 audit 的具体范围调整 checkbox

# Done criteria — audit-<TS> (topic: T<n>)

## 边界(必明确,防 scope drift)
- Scope in:  <文件 glob / 目录列表 / 行为子集>
- Scope out: <显式排除的相邻子系统,例如 "T7 不审 ArkTS 侧 keymap UI">

## 完成条件(场景驱动,逐条 checkbox,fix 完逐条勾选)
- [ ] 所有 P0 finding 已 fix 或显式标记 WONT_FIX(理由必填)
- [ ] 所有 fix 通过 Step 5/6 verify(verify agent 报 FIXED + 主 Claude citation 确认)
- [ ] Step 7 quick_signals 全 PASS
- [ ] 业务侧"会踩坑的真实场景"(由用户/topic 性质给出)逐条验证:
  - [ ] <场景 1,例如 T7: 切核重启后 input 不再重发已释放 TSFN>
  - [ ] <场景 2,例如 T7: ArkTS 侧 hub 离页后 C++ 侧 listener 自动清理>
  - [ ] ...
- [ ] napi-boundary-reviewer(若 fix 涉及 NAPI)verdict ≠ block
- [ ] audit-evaluator(若有)drift ≤ 20%

## 不在本次范围(显式 defer)
- <项 1: 理由 + defer 到哪个 audit>
- <项 2>

约束:

• 完成条件 MUST 是场景驱动,不是"checklist 填空"(memory feedback_completeness_is_scenario_not_form)
• 场景由 topic 性质 + 项目 memory 共同决定;不要凭空发明
• DONE.md 一旦写定,Step 1 之后不许悄悄改——确实要改 scope 必须显式记录 "scope drift: <原因>"

State after step 0: AUDIT_DIR/DONE.md 存在,scope + checkbox 全部填写。

Step 1 — Audit dispatch

In: Step 0 产出 AUDIT_DIR/DONE.md(scope 边界已定) Out: AUDIT_DIR/agent-<topic-id>.md × N(structured findings,机器可验)→ Step 2 逐条字节比对 Role: [L4 主 AI] 决定 topic + 写 prompt + dispatch; [L3 subagent] 并行 broad scan,structured output; [NOT] subagent 不判 verdict(留 Step 3 主 AI) Done: [ ] N 个 agent 报告齐;[ ] 每条 finding 有 file:line + evidence_excerpt

Ask user which topic(s) (default: ask user to choose, do NOT auto-default to all 8 — the audit is expensive). Create docs/audit/audit-<YYYYMMDD-HHMMSS>/ directory; remember this path as AUDIT_DIR.

For each chosen topic, dispatch ONE Sonnet agent (use Agent tool with model: "sonnet" per [[feedback_subagent_model]] — never Haiku). Each agent must:

• Write findings to AUDIT_DIR/agent-<topic-id>.md
• Use this finding format (strict):

## F<N>: <one-line claim>

- severity: P0 | P1 | P2
- file: <relative path>
- line: <single line or N-M range>
- evidence_excerpt: |
    <copy of the cited lines, verbatim, ≤8 lines>
- claim: <full explanation, why it's a bug, what should happen>
- suggested_fix: <one-paragraph repair shape; do NOT write the patch>

• Receive constraint: "DO NOT modify files. DO NOT run hvigorw / cmake. DO NOT invent citations — only cite lines you actually Read."
• Hazards source: agent prompt 必须 包含一行 先 cat .claude/skills/closed-loop/topics/T<n>-<name>.md 指示——hazards 详情在 topic file 里,不再在主 prompt 里转述(主 prompt 短、agent 自取 hazards)。
• TOOL POLICY (MANDATORY): Using Grep to answer "who calls X / where is X defined / what references X" is FORBIDDEN in this agent. For symbol/reference/caller lookup you MUST use MCP tools: mcp__cclsp__find_references | mcp__cclsp__find_definition | mcp__cclsp__get_incoming_calls | mcp__serena__find_referencing_symbols | mcp__cclsp__find_workspace_symbols. Grep is allowed ONLY for non-symbol file-content text searches.

Dispatch ALL agents in PARALLEL (single message, multiple Agent tool calls).

State after step 1: AUDIT_DIR/agent-*.md exists (one per topic).

Step 2 — Citation verify (Read + grep, manual)

In: Step 1 产出 AUDIT_DIR/agent-*.md(每 topic structured findings) Out: AUDIT_DIR/VERIFIED.md(分桶: VERIFIED / CITATION_DRIFT / FORMAT_ERROR / FILE_MISSING)→ Step 3 只 review VERIFIED 的 Role: [L4 主 AI] 逐条 Read file:line + grep evidence_excerpt 字节比对; [L1 机械] grep/Read 字节匹配; [NOT] 不判 finding 真伪(留 Step 3),不修代码 Done: [ ] 每条 finding 都有一个 verdict 桶;[ ] VERIFIED.md 表格生成

For each finding in each agent-<topic>.md:

1. Read the cited file at the cited line range.
2. Compare actual file content to evidence_excerpt:
   • VERIFIED — bytes match (allow trivial whitespace drift)
   • CITATION_DRIFT — same code exists but ±N lines off
   • FILE_MISSING — file path doesn't exist
   • FORMAT_ERROR — agent's finding malformed
3. Stamp each finding with the verdict in a new file AUDIT_DIR/VERIFIED.md (table form, one row per finding).

This replaces carbon's scripts/audit-verify.mjs — keep it manual to avoid scaffolding scripts before they prove their weight.

State after step 2: AUDIT_DIR/VERIFIED.md exists with VERIFIED count.

─── CHECKPOINT A (auto-pass unless user said "stop after each step") ───

Report counts: "X VERIFIED / Y CITATION_DRIFT / Z FORMAT_ERROR / W FILE_MISSING across N topics." Do not pause unless user explicitly asked.

Step 3 — Main Claude core-review

In: Step 2 产出 AUDIT_DIR/VERIFIED.md(只看 VERIFIED 桶) Out: AUDIT_DIR/CORE-REVIEW.md(每条 finding 配 verdict: REAL / REAL_LOWER / MITIGATED / DESIGN / FALSE_POSITIVE)+ Top-P0 提示给 user CHECKPOINT B Role: [L4 主 AI] verdict 判定 + 严重度 calibration; [L2 MCP] 必用 cclsp/serena/ast-grep 看影响面 + web_search 验上游规则现状; [NOT] 不直接 grep 替代 LSP(MCP 静态文字不够,见 feedback_mcp_static_text_insufficient) Done: [ ] 每条 VERIFIED finding 有 verdict;[ ] 用 MCP 验证过影响面;[ ] rule-based finding 已 web verify

For EACH finding stamped VERIFIED:

1. Read the cited file at the cited line range, plus ±20 lines surrounding context. NEVER skip this — step 2 only proves the bytes match, not that the agent's interpretation is correct.
2. Judge the finding's claim and assign a verdict:
   • REAL — confirmed bug at the cited severity
   • REAL_LOWER — confirmed but severity overstated (specify the true severity)
   • MITIGATED — code does the cited thing but upstream check makes it unreachable
   • DESIGN — intentional, not a bug
   • FALSE_POSITIVE — agent misread the code
3. Append to AUDIT_DIR/CORE-REVIEW.md:

## Agent <topic-id> — N VERIFIED

| # | Severity | Verdict | Notes |
|---|---|---|---|
| F1 | P0 | REAL | <one-line why it stands at this severity> |
| F2 | P0 | REAL_LOWER P1 | <one-line why severity is overstated> |

End with final tally: total REAL by severity + cross-agent calibration notes (e.g., "T4 over-labels P0 on geometry resize").

Trust rule: do not treat any finding as REAL until its cited code has been read in this step. Skipping the Read means trusting the sub-agent verbatim — exactly the failure mode this workflow prevents.

LSP / AST 协同（2026-05-26 ECP2 加；总览见 root CLAUDE.md "MCP / Skill 工具决策树"）：

判 verdict 前 MUST 先用 MCP——Grep/Read 不是等效替代，不是 fallback：

• mcp__cclsp__find_references / mcp__serena__find_referencing_symbols — 看 finding 影响面（多 caller 同问题 → severity 上调；单 caller → 可能 REAL_LOWER）
• mcp__cclsp__get_diagnostics_for_file — LSP 已知的 type/warning 可能直接判 FALSE_POSITIVE（LSP 不报警 = 编译器满意）
• mcp__ast-grep__find_code — 看 finding pattern 是否泛存在（譬如 finding 说 "F12 mmap 用错" → mmap( 模式扫，看是单点还是全项目通病）
• mcp__cclsp__get_hover — 看相关类型 / 函数签名，NAPI 边界改动尤其有用
• mcp__sequential-thinking__sequentialthinking — 罕见 finding 拿不准时多角度推理（不滥用）

用 Grep/Read 之前必须问自己：MCP 能回答这个问题吗？能 → 用 MCP；不能（如内容文本搜索）→ 再用 Grep。

Web verify 前置(2026-05-29 加):

判 verdict 之前,如果 finding 引用的是本地规则(CLAUDE.md / AGENTS.md / scanner pattern / memory rule),必跑 web verify 检查规则是否仍然代表上游官方现状:

1. 识别 finding 引用的规则出处
2. mcp__web-search__web_search "<framework> <feature> <year> best practice"
3. 对比:本地规则 vs 上游
   - 一致 → 按 verdict 流程判
   - 上游已演进 → verdict = FALSE_POSITIVE 或 REAL_LOWER + 加 meta-finding(本地规则需更新)

例外(可跳 verify):安全/正确性硬约束(mmap / 跨线程加锁) / 项目业务约定(LOG_DOMAIN / 路径 glob) / session 内 < 30 分钟刚下的决策。

详见 memory feedback_local_rule_may_lag_upstream。

State after step 3: AUDIT_DIR/CORE-REVIEW.md exists with verdict per finding.

─── CHECKPOINT B (MANDATORY HUMAN) ───

Surface the verdict table. Ask:

Found N REAL findings (M P0, K P1, L P2) + Q REAL_LOWER. Top P0:
 - F1: <claim> @ <file:line>
 - F2: ...
What to fix? [all REAL P0+P1 / specific list / discuss / skip fix step]

Wait for explicit user response. Do not proceed without it.

If user picks specific findings, write that list to AUDIT_DIR/FIX-PLAN.md so step 4 has a stable to-do.

Step 4 — Main Claude fixes

In: Step 3 产出 AUDIT_DIR/CORE-REVIEW.md + user CHECKPOINT B 选定的 finding 列表(AUDIT_DIR/FIX-PLAN.md) Out: 代码改动(working tree dirty)+ 改动文件清单 → Step 5 fix-verify agent 按此清单重审 Role: [L4 主 AI] 直接 Edit 修 REAL findings; [L3 napi-boundary-reviewer agent] 改 app/napi/** 前 MUST 先 dispatch(见 feedback_napi_reviewer_no_skip); [NOT] 不改 FALSE_POSITIVE / DESIGN finding Done: [ ] 所有 user 选定 finding 都已 Edit;[ ] napi 改动已经过 napi-reviewer;[ ] working tree diff 可读

For each finding the user approved (per FIX-PLAN.md):

1. Re-read the cited code + surrounding context to find the right place for the bounds check / null guard / buffer release / state-machine guard.
2. If the fix touches entry/src/main/cpp/app/napi/**: BEFORE applying the Edit, dispatch the napi-boundary-reviewer agent with the proposed change description. Wait for its review. Apply only after review passes (or document the override in CORE-REVIEW.md).
3. Apply the fix via Edit. Each fix must:
   • Be minimal — don't refactor while fixing
   • Be comment-traceable — add // Audit F<N>: <one-line> near the new code
   • Not change behavior for valid inputs — fixes are defensive
4. Group fixes by file. Batch all fixes for one file into one Edit sequence to minimize regressions.

Do not dispatch a generic "fix agent". Per the trust chain rationale, main Claude is the implementer. The only sub-agent dispatch in step 4 is the napi-boundary-reviewer pre-review, which is verification, not implementation.

LSP 协同（2026-05-26 ECP2 加）：

每个 fix 前 MUST 先查 MCP——Grep/Read 不是等效替代：

• mcp__cclsp__find_references — 看这个函数 / 类型在哪些其他地方被引用，fix 是否影响 caller 行为
• mcp__cclsp__get_incoming_calls — 调用链谁触发，理解 fix 的实际触发条件
• mcp__serena__get_diagnostics_for_file — fix 前后看 type warning 是否变化

用 Grep/Read 之前必须问自己：MCP 能回答这个问题吗？能 → 用 MCP；不能 → 再用 Grep。

NAPI 边界改动的 LSP 协同与 napi-boundary-reviewer agent 并行——agent 跑深度审；MCP 跑覆盖面。

State after step 4: uncommitted edits in the working tree, listed by git diff --stat.

─── CHECKPOINT C (MANDATORY HUMAN) ───

Show user git diff --stat + (if C++ built) the build PASS/FAIL line. Ask:

N files changed (+X -Y). C++ build: <OK / FAIL>. Diff looks reasonable?
[continue to fix-verify / inspect specific file / revert specific fix]

Wait for response. Do not proceed without it.

Step 5 — Fix-verify agent dispatch

In: Step 4 产出代码改动 + AUDIT_DIR/FIX-PLAN.md 列出的 finding ID Out: <FIXVERIFY_DIR>/agent-<topic>-fixverify.md(每条 fix 配 verdict: FIXED / PARTIAL / UNFIXED)→ Step 6 字节验证 Role: [L3 subagent per topic] 重审 fix 代码; [L2 MCP] subagent 必用 mcp__web-search__web_search 验 fix 引用的本地规则是否仍代表上游官方现状; [NOT] subagent 不找 NEW issues(constraint 强制),不修代码 Done: [ ] 每个受影响 topic 有一份 fixverify 报告;[ ] 每条原 finding 配 FIXED/PARTIAL/UNFIXED 之一;[ ] rule-based fix 已 web verify(skipped 要标 reason)

Create docs/audit/audit-<ORIGINAL_TS>-fixverify/ (suffix the original audit dir's timestamp — aids correlation).

Dispatch ONE Sonnet agent per affected topic (usually just the topics user picked findings from in step 3). Each agent's prompt MUST include:

1. The list of original findings to re-check (read from AUDIT_DIR/agent-<topic>.md)
2. The strict finding format (same as step 1)
3. Verdict field added: verdict: FIXED | PARTIAL | UNFIXED
4. New citation must point at the fix code (where the new guard / check / release lives), not the original buggy line
5. Constraint: "DO NOT find NEW issues; only verify the listed originals"
6. TOOL POLICY (MANDATORY): Same as audit agent — Grep for symbol/reference lookup is FORBIDDEN. Use mcp__cclsp__find_references | mcp__cclsp__find_definition | mcp__serena__find_referencing_symbols for any caller/definition lookup.
7. WEB VERIFY (2026-05-29 加): 若 fix 引用了本地规则(CLAUDE.md / AGENTS.md / memory / scanner pattern)判 FIXED,必跑 mcp__web-search__web_search 验证规则仍代表 上游官方现状(见 memory feedback_local_rule_may_lag_upstream)。例外:
   • 项目业务约定(LOG_DOMAIN / 路径 glob / EmuUiTokens)— 标 skipped: 业务约定
   • 安全/正确性硬约束(mmap / 跨线程加锁)— 标 skipped: 上游契约稳定
   • session 内 < 30 分钟刚下的决策 — 标 skipped: 无脱节窗口 未 verify 的 rule-based fix 不得判 FIXED;改判 PARTIAL: rule unverified。
8. WEB VERIFY 证据字段(2026-05-29 加,机制 2): 在每条 finding 末尾必须加结构化字段:

   web_verify:
     status: verified-upstream | skipped | not-applicable
     queries: ["<query 1>", "<query 2>"]   # status=verified-upstream 时必填,≥1 query
     reason: "<一句话说明 verify 结果或 skipped 理由>"
   

   • not-applicable: fix 未引用本地规则(纯字节修),不需 verify
   • skipped: 见上面 3 类例外,reason 必填
   • verified-upstream: queries 必含至少 1 条 mcp__web-search__web_search 实跑的查询 主 AI Step 6 会扫所有 finding 必须含此字段;缺字段 = subagent 越权,要求重跑。

Output to <FIXVERIFY_DIR>/agent-<topic>-fixverify.md.

Step 6 — Citation verify on the fix-verify reports (Read + grep, manual)

In: Step 5 产出 fixverify 报告 Out: <FIXVERIFY_DIR>/FIX-VERIFY-SUMMARY.md(每条 fix 字节级验证 + 跨模型 calibration)→ Step 7 gate Role: [L4 主 AI] Read fix 代码 + 比对 fixverify evidence_excerpt; [L4 主 AI] 对 Step 5 标 PARTIAL: rule unverified 的 fix 兜底跑 mcp__web-search__web_search; [L1 grep] 机制扫 finding 数 vs web_verify 块数(缺即 subagent 越权); [NOT] 不容忍 UNFIXED,不容忍 rule unverified 进 Step 7,不容忍 web_verify 字段缺失 Done: [ ] 每条 fix 验证字节是否落地;[ ] 0 条 UNFIXED;[ ] 0 条 rule unverified;[ ] 每条 finding 含 web_verify 字段(grep 验证)

Same procedure as step 2, but on the fix-verify reports. The fix code must exist where the agent claims; a CITATION_DRIFT here often means the agent's evidence_excerpt is the right code but the line range is off-by-a-few — read the code yourself to confirm the fix is actually correct (line-range drift ≠ fix failure).

Rule verify 兜底(2026-05-29 加): Step 5 subagent 标 PARTIAL: rule unverified 的 fix 在本步必须由主 AI 跑 mcp__web-search__web_search 兜底 verify:

• 若 verify 通过(本地规则仍代表上游)→ 升级为 FIXED
• 若 verify 发现规则过时 → 改为 META: rule outdated,加 meta-finding 进 FIX-VERIFY-SUMMARY.md (该 finding 不算 fix 失败,但建议下次会话改本地修) 未兜底 verify 的 rule unverified 项不得放行进 Step 7 gate。

机制化 scan(2026-05-29 加,机制 2): 主 AI 必须扫每个 agent-<topic>-fixverify.md 报告里的每条 finding 是否含 web_verify: 结构化字段(Step 5 prompt 第 8 条要求的):

# 主 AI 做的机械扫(脚本示例,主 AI 可直接 grep):
for f in <FIXVERIFY_DIR>/agent-*-fixverify.md; do
  finding_count=$(grep -cE '^## F[0-9]+:' "$f")
  verify_count=$(grep -cE '^\s+web_verify:' "$f")
  if [[ $finding_count -ne $verify_count ]]; then
    echo "[FAIL] $f: ${finding_count} findings but only ${verify_count} web_verify blocks — subagent 越权"
    # 要求重跑该 topic 的 Step 5 subagent
  fi
done

此 scan 是机制兜底,不是纪律 — 缺字段强制重跑。

Cross-model verification(2026-05-28 加,可选):

P0 finding 或涉及线程/生命周期/NAPI 的 fix,强烈建议对 audit-evaluator 启用 cross-validate mode:

• 第一次 dispatch:Agent(audit-evaluator, model=sonnet, MODE=cross-validate) — Phase A
• 第二次 dispatch:Agent(audit-evaluator, model=opus, MODE=cross-validate-phase-b, PHASE_A_REPORT=<path>) — Phase B

漂移收敛规则:任一 Phase B DISAGREE_A → 取 Phase B 判定回 Step 4;UNCERTAIN → CHECKPOINT D。

参考 HN vibe42 实操 + Anthropic sycophancy 实证。

Step 7 — Gate gauntlet(含 C++ 增量 rebuild)

In: Step 6 产出 FIX-VERIFY-SUMMARY.md(0 UNFIXED) Out: gate PASS 信号 + .last-quick-signals.txt 时间戳 → Step 8 stage+commit Role: [L1 脚本] bash scripts/check/quick_signals.sh + 可选 hvigorw / cmake; [L4 主 AI] 解读 gate 输出 + 必要时回 Step 4 修问题 Done: [ ] regression / hygiene / ui-fixes / cxx-build 全 PASS;[ ] gate 输出时间戳已写入

2026-05-28 重构:原 Step 5 "Rebuild (if C++ changed)" 已合并进本步—— quick_signals.sh chain 内置 cmake --build(避免重复 rebuild step)。

如需在 quick_signals 之前单独验 C++ build(罕见,例如想看 build 详细错误而不是 quick_signals 简略输出),可手动跑:

ls entry/.cxx/*/*/*/build.ninja 2>/dev/null
cmake --build "entry/.cxx/<config>/<arch>/<abi>" --target libentry_static

否则直接进 Gate gauntlet。

bash scripts/check/quick_signals.sh

Quick signals chains: check_regression_guards.sh + check_repo_hygiene.sh

• incremental cmake --build. All must be green. If any fails, fix that first (loop back to step 4 — do not commit a half-fixed state).

If quick_signals reports SKIP for cmake --build because DevEco Sync hasn't been run, run a full sync once via DevEco Studio UI, then re-run.

Done-criteria gate(2026-05-28 加): 打开 AUDIT_DIR/DONE.md,逐条 checkbox 自检:

• 全部勾上 → 通过
• 有未勾 → 要么补漏(回 Step 4)、要么显式升为 WONT_FIX(理由写进 DONE.md 同一条)
• 场景类未勾(场景没法在本环境验证)→ 标 [DEFER-MANUAL] + 写明用户/真机什么时候验

不许"checkbox 大部分勾上,凑合 commit"——feedback_completeness_is_scenario_not_form 的原话:完整不是形式美,是场景驱动。

─── CHECKPOINT D (MANDATORY HUMAN) ───

Draft the commit message:

<scope>: <one-line subject under 70 chars>

<body explaining WHY, not just WHAT. Reference the audit dir for traceability.>

Verification:
  bash scripts/check/quick_signals.sh → PASS
  audit fix-verify: X/X FIXED, all citations VERIFIED
  napi-boundary-reviewer (if applicable): <verdict>

Audit artifacts:
  docs/audit/<AUDIT_DIR_NAME>/ (original + CORE-REVIEW.md)
  docs/audit/<FIXVERIFY_DIR_NAME>/ (fix verification)

Co-Authored-By: Claude Opus 4.7 (1M context) <[e-mail]>

Show user the full draft. Wait for "go" / "edit X" / "abort".

Step 8 — Stage + commit

In: Step 7 产出 gate PASS + 代码改动 + AUDIT_DIR Out: git commit(commit message 含 audit dir 路径)→ HEAD 推进 1 个 commit Role: [L1 git] git add / git commit; [L4 主 AI] 写 commit message + 经 user CHECKPOINT C 确认; [NOT] 不 push(用户决定) Done: [ ] commit 已落地;[ ] commit message 引用 AUDIT_DIR 路径;[ ] working tree clean

Explicit file list, no git add -A. Only stage files YOU edited in step 4 + the audit artifacts under docs/audit/. Files modified by the user pre-session stay out unless explicitly approved.

git add <file1> <file2> ... docs/audit/<AUDIT_DIR_NAME>/
git status -s    # confirm clean staging
git commit -m "$(cat <<'EOF' ... EOF)"
git log --oneline -3

Report commit hash to user. Done.

State machine: resuming from a partial run

If the user comes back mid-flow and says "继续闭环" / "/closed-loop resume", detect state via artifacts (no script — use ls docs/audit/*/):

Has AUDIT_DIR/DONE.md ?
├── no  → step 0 not done, must write DONE.md first
└── yes → has AUDIT_DIR/agent-*.md ?
   ├── no  → step 1 not done, resume step 1
   └── yes → has AUDIT_DIR/VERIFIED.md ?
      ├── no  → resume step 2 (citation-verify)
      └── yes → has AUDIT_DIR/CORE-REVIEW.md ?
         ├── no  → resume step 3 (core-review)
         └── yes → has AUDIT_DIR/FIX-PLAN.md ?
            ├── no  → resume CHECKPOINT B (ask user what to fix)
            └── yes → git diff non-empty?
               ├── no  → resume step 4 (fixing)
               └── yes → has FIXVERIFY_DIR ?
                  ├── no  → resume step 5 (dispatch fix-verify agents)
                  └── yes → has FIXVERIFY_DIR/<reports> ?
                     ├── no  → resume step 5 (dispatch fix-verify agents)
                     └── yes → green gates ?
                        ├── no  → resume step 6-7 (citation-verify + gate)
                        └── yes → DONE.md checkbox 全勾?
                           ├── no  → 补漏 / 升 WONT_FIX + 理由 / 改 scope
                           └── yes → resume CHECKPOINT D (commit draft)

Pick the most recent timestamped dir as the "active" one if multiple exist.

Reference

• Fast signals gate: scripts/check/quick_signals.sh
• NAPI sub-agent: .claude/agents/napi-boundary-reviewer.md
• Regression / hygiene scripts: scripts/ci/check_regression_guards.sh + check_repo_hygiene.sh
• Trust chain rationale: [[harness-fusion-2026-05-24]] / docs/plans/2026-05-24-harness-fusion-design.md
• Sub-agent model floor (Sonnet min, no Haiku): [[feedback_subagent_model]]
• Worktree isolation caveat: [[feedback_agent_worktree_isolation]]
• Hook stdin lesson: post-edit-cpp.sh history (heredoc + json.load conflict)
• 审计经验教训(必读): [[feedback_t7_audit_lessons]] — 5 条:
  1. find_references 是审计核心(Step 3 verdict 前必跑)
  2. SDK 限制用构建验证(Step 7 gate cxx-build),不靠记忆
  3. 跨层耦合 finding 必须同批修(Step 4 FIX-PLAN 一起)
  4. catch 块禁止 removeListener/unsubscribe(订阅生命周期反模式)
  5. NAPI 层独立批次 + napi-boundary-reviewer 预审(Step 4 改 app/napi/** 时)

Anti-patterns to refuse

If user pushes for any of these, refuse and explain why:

• "Skip core-review, just fix what the agent said" — exact failure mode this workflow exists to prevent. Sub-agent claims are unverified until step 3.

• "Auto-commit without showing me the diff" — CHECKPOINT C exists because fixes can look right in code but still subtly break behavior.

• "Dispatch a fix agent for each finding" — adds a new trust layer without a verifier. Main Claude is the implementer, by design.

• "Run all 8 steps no checkpoints" — checkpoints B/C/D exist for decision authority. Removing them gives Claude autonomy that isn't earned yet on this codebase.

• "Fix the warnings I just noticed while you're in there" — scope creep. Each finding gets a minimal fix; off-scope cleanup goes in a separate commit.

• "Skip the napi-boundary-reviewer for this one NAPI fix" — NAPI edits have hidden env / thread / ref-lifetime hazards that the reviewer agent is specifically tuned to catch.

• "Skip Step 0 because 'we know what we're auditing'" — Step 0 是 sprint contract,memory feedback_completeness_is_scenario_not_form 反复 踩过这个坑。开工不写 done criteria 等于让 fix scope 飘。3 分钟写 DONE.md 比 fix 完反复追问 "审完了吗" 省时间。

What this skill does NOT cover

• ets/ets-only fixes — different workflow (or use auto-commit-cicd after manual review).
• Vendored libretro upstream code — entry/src/main/cpp/core/libretro/ is blocked by guard-vendored-libretro.sh; patches must go upstream.
• PR creation / pushing to remote — stop at local commit; user decides when to push.