@hunter-harness/workflow-harness 0.2.5 → 0.2.6

package/harness/bundles/general/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "5cadfa54663ecdbf"
+  "coreHash": "e29fb748896b6f88"
 }

package/harness/bundles/general/claude-code/harness-archive/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=5cadfa54663ecdbf; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e29fb748896b6f88; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -66,6 +66,7 @@ disallowed-tools:
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/knowledge/change/code 指纹，不再重复跑全量 `harness-sync`、知识重建或代码库扫描。只有对应 segment 变化或缺失时才定向刷新；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 
@@ -202,7 +203,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -211,3 +212,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

package/harness/bundles/general/claude-code/harness-archive/reference.md

@@ -92,4 +92,4 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 ## 执行日志记录
 
-归档只向 `events.ndjson` 追加事件（schema_version 2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。
+归档只向 `events.ndjson` 追加事件（schema_version 3，兼容读取 v1/v2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。

package/harness/bundles/general/claude-code/harness-archive/templates/render-summary.mjs

@@ -1,171 +1,94 @@
 #!/usr/bin/env node
-// render-summary.mjs
-// Deterministic UTF-8 renderer for harness archive final-summary.html.
-// Input: summary-data.json (schemaVersion 2.2). Output: final-summary.html.
-// Keeps UTF-8, avoids PowerShell string interpolation issues.
-// All numbers come from summary-data.json or manifest — never re-inferred here.
-
-import fs from 'node:fs';
-import path from 'node:path';
+// Compact deterministic renderer for Harness archive summary-data.json.
+import fs from "node:fs";
+import path from "node:path";
 
 const args = process.argv.slice(2);
-function getArg(name, fallback) {
-  const i = args.indexOf(name);
-  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
-}
-
-const summaryPath = getArg('--summary', args[0]);
-const outPath = getArg('--out', args[1] || 'final-summary.html');
+const arg = (name, fallback) => {
+  const index = args.indexOf(name);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+};
+const summaryPath = arg("--summary", args[0]);
+const outPath = arg("--out", args[1] || "final-summary.html");
 if (!summaryPath) {
-  console.error('Usage: node render-summary.mjs --summary summary-data.json --out final-summary.html');
+  console.error("Usage: node render-summary.mjs --summary summary-data.json --out final-summary.html");
   process.exit(2);
 }
 
-const data = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
-const esc = (v) => String(v ?? '').replace(/[&<>"']/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
-const arr = (v) => Array.isArray(v) ? v : [];
-const obj = (v) => v && typeof v === 'object' ? v : {};
-const num = (v) => Number(v) || 0;
-const badgeClass = (s) => {
-  const v = String(s ?? '').toUpperCase();
-  if (v.includes('FAIL') || v.includes('ERROR')) return 'bad';
-  if (v.includes('WARN') || v.includes('BLOCK') || v.includes('SKIP') || v.includes('CONDITIONAL') || v.includes('PARTIAL') || v.includes('NOT_RUN')) return 'warn';
-  if (v.includes('ADVISORY') || v.includes('REUSED')) return 'info';
-  return 'ok';
+const data = JSON.parse(fs.readFileSync(summaryPath, "utf8"));
+const esc = (value) => String(value ?? "").replace(/[&<>"']/g, (char) => ({
+  "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"
+})[char]);
+const list = (value) => Array.isArray(value) ? value : [];
+const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const number = (value) => Number(value) || 0;
+const shortHash = (value) => String(value || "N/A").slice(0, 10);
+const statusClass = (value) => {
+  const status = String(value || "UNKNOWN").toUpperCase();
+  if (/FAIL|ERROR/.test(status)) return "danger";
+  if (/WARN|BLOCK|SKIP|CONDITIONAL|PARTIAL|NOT_RUN|UNKNOWN/.test(status)) return "warning";
+  if (/ADVISORY|REUSED/.test(status)) return "neutral";
+  return "success";
 };
-const badge = (s) => `<span class="badge ${badgeClass(s)}">${esc(s || 'N/A')}</span>`;
-
-// pass-rate progress bar: parses "183/185" style strings
-const parseRate = (rate) => {
-  if (!rate) return null;
-  const m = String(rate).match(/(\d+)\s*\/\s*(\d+)/);
-  return m ? { passed: +m[1], total: +m[2] } : null;
+const pill = (value) => `<span class="pill ${statusClass(value)}">${esc(value || "UNKNOWN")}</span>`;
+const describe = (value) => {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object") return String(value ?? "");
+  return value.message || value.action || value.note || value.summary || JSON.stringify(value);
 };
-const rateBar = (rateStr, status) => {
-  const r = parseRate(rateStr);
-  if (!r || r.total <= 0) return `<span class="muted">N/A</span>`;
-  const pct = Math.round(r.passed / r.total * 100);
-  const cls = badgeClass(status || (r.passed >= r.total ? 'OK' : 'WARN'));
-  return `<div class="rate"><div class="bar-track"><div class="bar-fill ${cls}" style="width:${pct}%"></div></div><span class="muted small">${esc(rateStr)} · ${pct}%</span></div>`;
+const duration = (minutes) => {
+  const value = number(minutes);
+  if (value < 1) return `${Math.round(value * 60)} 秒`;
+  if (value < 60) return `${Math.round(value * 10) / 10} 分钟`;
+  return `${Math.floor(value / 60)} 小时 ${Math.round(value % 60)} 分钟`;
 };
 
-const stageRows = Object.entries(obj(data.stageStatus)).map(([k,v]) => `<tr><td>${esc(k)}</td><td>${badge(v)}</td></tr>`).join('\n') || `<tr><td colspan="2" class="muted">未记录阶段状态</td></tr>`;
-
-const verification = obj(data.verification);
-const unit = obj(verification.unitTests);
-const api = obj(verification.apiTests);
-const unitStatus = (num(unit.failures) + num(unit.errors)) > 0 ? 'WARN' : 'OK';
-const verificationRows = [
-  ['Unit Tests', `${rateBar(unit.passRate, unitStatus)}<div class="muted small">${esc(unit.run ?? 0)} run · ${esc(unit.failures ?? 0)} fail · ${esc(unit.errors ?? 0)} err · ${esc(unit.skipped ?? 0)} skip · ${esc(unit.source || 'not recorded')}</div>`],
-  ['API Tests', `${rateBar(api.passRate, api.status)}<div class="muted small">${esc(api.passed ?? 0)}/${esc(api.total ?? 0)} · ${esc(api.status || data.stageStatus?.test || 'N/A')}</div>`],
-  ['DB Compat', badge(verification.dbCompatibility || 'N/A')],
-  ['Coverage', esc(verification.coverageDisplay || 'N/A')],
-  ['Overall', badge(data.finalStatus || data.overallStatus || 'N/A')]
-].map(([a,b]) => `<tr><td>${a}</td><td>${b}</td></tr>`).join('\n');
-
-const diffStat = obj(data.diffStat);
-const changedRows = arr(data.changedFiles).map(f => `<tr><td><code>${esc(f.path || f.file || '')}</code></td><td>${esc(f.summary || f.change || '')}</td><td class="ins">+${esc(f.insertions ?? 0)}</td><td class="del">-${esc(f.deletions ?? 0)}</td></tr>`).join('\n') || `<tr><td colspan="4" class="muted">未记录变更文件</td></tr>`;
-const artifactList = arr(data.artifacts);
-const artifactRows = artifactList.map(a => `<tr><td>${esc(a.name || '')}</td><td><code>${esc(a.path || '')}</code></td><td>${esc(a.size || '')}</td><td><code>${esc(a.sha256 || '')}</code></td></tr>`).join('\n');
-const artifactCard = artifactList.length > 0 ? `<div class="card"><h2>📦 产物清单</h2><table><tr><th>名称</th><th>路径</th><th>大小</th><th>SHA-256</th></tr>${artifactRows}</table></div>` : '';
-const notes = arr(data.maintenanceNotes).map(n => `<li>${esc(n)}</li>`).join('\n') || `<li class="muted">无额外维护说明</li>`;
-const risks = arr(data.knownRisks).map(n => `<li>${esc(n)}</li>`).join('\n') || `<li class="muted">无已知遗留风险</li>`;
-const manual = arr(data.manualActions).map(n => `<li>${esc(n)}</li>`).join('\n') || `<li class="muted">无人工后续动作</li>`;
-const uncommittedList = arr(data.uncommittedTestEvidence);
-const uncommittedTests = uncommittedList.map(n => `<li>${esc(n)}</li>`).join('\n');
-const uncommittedCard = uncommittedList.length > 0 ? `<div class="card"><h2>🧪 未提交测试证据</h2><ul>${uncommittedTests}</ul></div>` : '';
-const review = obj(data.reviewSummary);
-const manifest = obj(data.archiveManifest);
-const timeline = arr(data.timeline).map(t => `<tr><td>${esc(t.stage || '')}</td><td>${badge(t.result || '')}</td><td>${esc(t.evidence || '')}</td></tr>`).join('\n');
-
-// durations + skillCalls (schema 2.1); fall back to timeline when absent
-const durations = obj(data.durations);
-const durStages = arr(durations.stages);
-const maxMin = durStages.reduce((m, s) => Math.max(m, num(s.minutes)), 0);
-const durRows = durStages.map(s => {
-  const min = num(s.minutes);
-  const pct = maxMin > 0 ? Math.round(min / maxMin * 100) : 0;
-  return `<div class="dur-row"><div class="dur-label">${esc(s.skill || s.stage || '')} <span class="muted small">${esc(s.result || '')}</span></div><div class="dur-track"><div class="dur-bar" style="width:${pct}%"></div></div><div class="dur-min">${esc(min)}m</div></div>`;
-}).join('\n');
-const skillCallsHtml = arr(data.skillCalls).map(s => `${esc(s.skill)}×${esc(s.count)} ${badge(s.result)}`).join(' ') || '<span class="muted">未记录</span>';
-
-const durCard = durStages.length > 0
-  ? `<div class="card"><h2>⏱️ 阶段耗时与 Skill 调用</h2>${durRows}<div class="muted small" style="margin-top:10px">Skill 调用：${skillCallsHtml}</div></div>`
-  : (timeline ? `<div class="card"><h2>阶段时间线</h2><table><tr><th>阶段</th><th>结果</th><th>证据</th></tr>${timeline}</table></div>` : '');
+const stages = Object.entries(record(data.stageStatus));
+const verification = record(data.verification);
+const unit = record(verification.unitTests);
+const api = record(verification.apiTests);
+const durations = record(data.durations);
+const durationStages = list(durations.stages);
+const maxMinutes = Math.max(1, ...durationStages.map((item) => number(item.minutes)));
+const diff = record(data.diffStat);
+const risks = list(data.knownRisks);
+const actions = list(data.manualActions);
+const files = list(data.changedFiles);
+const commands = list(record(data.reportPipeline).commands);
+const timeline = list(data.timeline);
 
-const totalLabel = durations.totalLabel || (durations.totalMinutes ? durations.totalMinutes + 'm' : 'N/A');
+const stageHtml = stages.map(([name, status]) => `<div class="row"><span>${esc(name)}</span>${pill(status)}</div>`).join("") || '<p class="empty">没有阶段状态记录</p>';
+const verificationHtml = [
+  ["单元测试", unit.status || ((number(unit.failures) + number(unit.errors)) > 0 ? "FAIL" : (number(unit.run) > 0 ? "OK" : "NOT_RUN")), `${number(unit.run)} 个 · ${number(unit.failures)} 失败 · ${number(unit.errors)} 错误`],
+  ["API 测试", api.status || "NOT_RUN", `${number(api.passed)}/${number(api.total)} 通过 · ${number(api.blocked)} 阻塞`],
+  ["数据库兼容", verification.dbCompatibility || "NOT_RUN", verification.coverageDisplay || "未记录覆盖率"]
+].map(([name, status, note]) => `<div class="row"><div><strong>${esc(name)}</strong><small>${esc(note)}</small></div>${pill(status)}</div>`).join("");
+const durationHtml = durationStages.map((item) => {
+  const width = Math.max(2, Math.round(number(item.minutes) / maxMinutes * 100));
+  const attempts = list(item.attempts).length;
+  return `<div class="duration"><div><span>${esc(item.skill || item.stage)}</span><span>${duration(item.minutes)}${attempts > 1 ? ` · ${attempts} 次尝试` : ""}</span></div><i><b style="width:${width}%"></b></i></div>`;
+}).join("") || '<p class="empty">没有可计算的阶段耗时</p>';
+const riskHtml = risks.map((item) => `<li>${esc(describe(item))}</li>`).join("") || "<li>未记录已知风险</li>";
+const actionHtml = actions.map((item) => `<li>${esc(describe(item))}</li>`).join("") || "<li>无需人工后续动作</li>";
+const fileRows = files.map((item) => `<tr><td><code>${esc(item.path || item.file)}</code></td><td class="plus">+${number(item.insertions)}</td><td class="minus">-${number(item.deletions)}</td></tr>`).join("") || '<tr><td colspan="3">没有变更文件证据</td></tr>';
+const timelineRows = timeline.map((item) => `<tr><td>${esc(item.phase || item.stage || "-")}</td><td>${esc(item.attempt || "-")}</td><td>${pill(item.status || item.result || item.type)}</td><td>${esc(item.executorTool || item.executor_tool || item.summary || "-")}</td></tr>`).join("") || '<tr><td colspan="4">没有时间线记录</td></tr>';
+const commandRows = commands.map((item) => `<tr><td>${esc(item.phase || "-")}</td><td><code>${esc(item.command)}</code></td><td>${pill(number(item.exit_code) === 0 ? "OK" : "FAIL")}</td></tr>`).join("") || '<tr><td colspan="3">没有命令证据</td></tr>';
 
-const html = `<!doctype html>
-<html lang="zh-CN">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>变更最终报告 - ${esc(data.changeName || '')}</title>
-<style>
-:root { color-scheme: dark; }
-* { box-sizing: border-box; }
-body { font-family: -apple-system,BlinkMacSystemFont,'Segoe UI','Microsoft YaHei',sans-serif; margin: 0; background: #0b1020; color: #e5e7eb; }
-main { max-width: 1120px; margin: 0 auto; padding: 32px; }
-.card { background: rgba(255,255,255,.06); border: 1px solid rgba(255,255,255,.12); border-radius: 16px; padding: 20px; margin: 16px 0; box-shadow: 0 12px 40px rgba(0,0,0,.18); }
-h1 { margin: 0 0 8px; font-size: 30px; }
-h2 { margin: 0 0 12px; font-size: 20px; }
-h3 { margin: 18px 0 8px; }
-.muted { color: #94a3b8; }
-.small { font-size: 12px; }
-table { width: 100%; border-collapse: collapse; table-layout: fixed; }
-th, td { border-bottom: 1px solid rgba(255,255,255,.12); padding: 10px; text-align: left; vertical-align: top; overflow-wrap: anywhere; }
-th { color: #cbd5e1; font-weight: 600; }
-tbody tr:nth-child(even) { background: rgba(255,255,255,.03); }
-tbody tr:hover { background: rgba(96,165,250,.08); }
-code { color: #bfdbfe; word-break: break-all; }
-.ins { color: #86efac; font-weight: 600; }
-.del { color: #fca5a5; font-weight: 600; }
-.badge { display: inline-block; padding: 4px 8px; border-radius: 999px; font-weight: 700; font-size: 12px; }
-.badge.ok { background: rgba(34,197,94,.16); color: #86efac; }
-.badge.warn { background: rgba(245,158,11,.18); color: #fcd34d; }
-.badge.bad { background: rgba(239,68,68,.18); color: #fca5a5; }
-.badge.info { background: rgba(59,130,246,.18); color: #93c5fd; }
-.grid { display: grid; grid-template-columns: repeat(auto-fit,minmax(200px,1fr)); gap: 16px; }
-.kpi { font-size: 18px; font-weight: 700; margin-top: 4px; word-break: break-all; }
-.hero { border-color: rgba(96,165,250,.35); background: linear-gradient(135deg, rgba(59,130,246,.12), rgba(255,255,255,.04)); }
-ul { margin-top: 8px; }
-.bar-track { background: rgba(255,255,255,.08); border-radius: 999px; height: 8px; overflow: hidden; margin: 4px 0; }
-.bar-fill { height: 100%; border-radius: 999px; }
-.bar-fill.ok { background: #22c55e; }
-.bar-fill.warn { background: #f59e0b; }
-.bar-fill.bad { background: #ef4444; }
-.bar-fill.info { background: #3b82f6; }
-.rate { display: flex; flex-direction: column; gap: 2px; min-width: 160px; }
-.dur-row { display: grid; grid-template-columns: 150px 1fr 50px; align-items: center; gap: 10px; padding: 6px 0; }
-.dur-label { color: #93c5fd; font-size: 13px; }
-.dur-track { background: rgba(255,255,255,.06); border-radius: 4px; height: 18px; overflow: hidden; }
-.dur-bar { height: 100%; background: linear-gradient(90deg, #3b82f6, #60a5fa); border-radius: 4px; }
-.dur-min { color: #94a3b8; font-size: 13px; text-align: right; }
-@media (max-width: 640px) { main { padding: 16px; } .grid { grid-template-columns: 1fr; } .dur-row { grid-template-columns: 100px 1fr 40px; } }
-</style>
-</head>
-<body><main>
-<div class="card hero">
-  <h1>变更最终报告：${esc(data.changeName || '')}</h1>
-  <p class="muted">${esc(data.businessGoal || '未记录业务目标')}</p>
-</div>
-<div class="grid">
-  <div class="card"><div class="muted">🎯 最终状态</div><div class="kpi">${badge(data.finalStatus || data.overallStatus || 'N/A')}</div></div>
-  <div class="card"><div class="muted">🔒 Final Commit</div><div class="kpi"><code>${esc(data.finalCommit || 'N/A')}</code></div><div class="muted small">${esc(data.finalCommitBranch || '')}</div></div>
-  <div class="card"><div class="muted">📊 代码变更</div><div class="kpi">${esc(diffStat.filesChanged ?? 'N/A')} 文件</div><div class="muted small"><span class="ins">+${esc(diffStat.insertions ?? 0)}</span> <span class="del">-${esc(diffStat.deletions ?? 0)}</span></div></div>
-  <div class="card"><div class="muted">⏱️ 总耗时</div><div class="kpi">${esc(totalLabel)}</div><div class="muted small">${esc(durStages.length)} 个阶段</div></div>
-  <div class="card"><div class="muted">📝 Review</div><div class="kpi">${esc(review.status || 'N/A')}</div><div class="muted small">RED ${esc(review.red ?? 0)}(修${esc(review.redFixed ?? 0)}/确${esc(review.redConfirmed ?? 0)}) · YEL ${esc(review.yellow ?? 0)}(修${esc(review.yellowFixed ?? 0)}/留${esc(review.yellowDeferred ?? 0)})</div></div>
-  <div class="card"><div class="muted">📦 Archive</div><div class="kpi">${esc(manifest.totalArchiveFiles ?? 'N/A')} 文件</div><div class="muted small">${esc(manifest.checksumStatus || 'N/A')}</div></div>
-</div>
-<div class="card"><h2>📋 阶段状态</h2><table><tr><th>阶段</th><th>状态</th></tr>${stageRows}</table></div>
-${durCard}
-<div class="card"><h2>🛡️ 验证明细</h2><table><tr><th>类型</th><th>结果</th></tr>${verificationRows}</table></div>
-<div class="card"><h2>📁 变更文件</h2><table><tr><th>文件</th><th>说明</th><th>+</th><th>-</th></tr>${changedRows}</table></div>
-${artifactCard}
-${uncommittedCard}
-<div class="card"><h2>👨‍🔧 给后续维护者</h2><ul>${notes}</ul></div>
-<div class="card"><h2>⚠️ 已知风险 / 人工确认项</h2><ul>${risks}</ul><h3>人工后续动作</h3><ul>${manual}</ul></div>
+const html = `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Harness 最终报告 · ${esc(data.changeName)}</title><style>
+:root{color-scheme:light dark;--bg:#f3f6fa;--card:#fff;--soft:#f7f9fc;--text:#182132;--muted:#667085;--line:#dce3ed;--blue:#2563eb;--good:#087443;--warn:#9b5a00;--bad:#b42318;--shadow:0 8px 24px rgba(18,35,70,.07)}
+@media(prefers-color-scheme:dark){:root{--bg:#0b1018;--card:#121925;--soft:#182130;--text:#eef3fb;--muted:#9aa8bc;--line:#29364a;--blue:#7aa9ff;--good:#55d99d;--warn:#f0bc63;--bad:#ff8b83;--shadow:0 12px 30px rgba(0,0,0,.25)}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:14px/1.5 Inter,"Segoe UI","Microsoft YaHei",sans-serif}main{width:min(1140px,calc(100% - 28px));margin:22px auto 44px}.hero,.card,.metric,details{background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow)}.hero{padding:23px 25px;border-top:3px solid var(--blue)}.eyebrow{color:var(--blue);font-weight:750;letter-spacing:.08em}h1{font-size:27px;line-height:1.2;margin:5px 0 7px;overflow-wrap:anywhere}.goal,.empty,small{color:var(--muted)}.status{display:flex;align-items:center;gap:10px;margin-top:16px}.metrics{display:grid;grid-template-columns:repeat(4,1fr);gap:11px;margin:11px 0}.metric{padding:14px 15px}.metric strong{display:block;font-size:19px;margin:4px 0}.grid{display:grid;grid-template-columns:1.12fr .88fr;gap:11px}.card{padding:17px;margin-bottom:11px}h2{font-size:16px;margin:0 0 10px}.row{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:9px 0;border-bottom:1px solid var(--line)}.row:last-child{border:0}.row small{display:block;margin-top:2px}.pill{display:inline-flex;border-radius:999px;padding:3px 9px;font-size:11px;font-weight:750;white-space:nowrap}.pill.success{color:var(--good);background:color-mix(in srgb,var(--good) 13%,transparent)}.pill.warning{color:var(--warn);background:color-mix(in srgb,var(--warn) 14%,transparent)}.pill.danger{color:var(--bad);background:color-mix(in srgb,var(--bad) 13%,transparent)}.pill.neutral{color:var(--blue);background:color-mix(in srgb,var(--blue) 12%,transparent)}.duration{margin:11px 0}.duration>div{display:flex;justify-content:space-between;color:var(--muted);font-size:12px}.duration>div span:first-child{color:var(--text);font-weight:650}.duration i{display:block;height:7px;background:var(--soft);border-radius:99px;overflow:hidden;margin-top:6px}.duration b{display:block;height:100%;background:linear-gradient(90deg,var(--blue),#7c70ff)}.risk{display:grid;grid-template-columns:1fr 1fr;gap:10px}.risk>div{background:var(--soft);border-radius:10px;padding:11px}.risk h3{font-size:13px;margin:0 0 5px}.risk ul{padding-left:18px;margin:0;color:var(--muted)}details{margin:9px 0}summary{cursor:pointer;padding:13px 15px;font-weight:650}details>div{padding:0 15px 15px;overflow:auto}table{width:100%;border-collapse:collapse}th,td{text-align:left;padding:8px 9px;border-bottom:1px solid var(--line);vertical-align:top}th{color:var(--muted);font-size:11px;letter-spacing:.04em}code{font-family:"Cascadia Code",Consolas,monospace;color:var(--blue);overflow-wrap:anywhere}.plus{color:var(--good)}.minus{color:var(--bad)}dl{display:grid;grid-template-columns:145px 1fr;gap:7px 11px}dt{color:var(--muted)}dd{margin:0;overflow-wrap:anywhere}
+@media(max-width:800px){.metrics{grid-template-columns:1fr 1fr}.grid,.risk{grid-template-columns:1fr}}@media(max-width:480px){main{width:calc(100% - 18px);margin-top:9px}.metrics{grid-template-columns:1fr}.hero{padding:19px}h1{font-size:23px}dl{grid-template-columns:1fr}}
+</style></head><body><main>
+<section class="hero"><div class="eyebrow">HARNESS EXECUTION REPORT</div><h1>${esc(data.changeName || "未命名变更")}</h1><p class="goal">${esc(data.businessGoal || "未记录业务目标")}</p><div class="status">${pill(data.finalStatus)}<span>基于事件、验证账本与 Git 证据生成</span></div></section>
+<section class="metrics"><article class="metric"><small>任务提交</small><strong><code title="${esc(data.finalCommit)}">${esc(shortHash(data.finalCommit))}</code></strong><small>${esc(data.finalCommitBranch || "未记录分支")}</small></article><article class="metric"><small>代码范围</small><strong>${number(diff.filesChanged)} 个文件</strong><small><span class="plus">+${number(diff.insertions)}</span> · <span class="minus">-${number(diff.deletions)}</span></small></article><article class="metric"><small>总耗时</small><strong>${esc(durations.totalLabel || duration(durations.totalMinutes))}</strong><small>${durationStages.length} 个阶段</small></article><article class="metric"><small>归档完整性</small><strong>${esc(record(data.archiveManifest).checksumStatus || "UNKNOWN")}</strong><small>${number(record(data.archiveManifest).totalArchiveFiles)} 个归档文件</small></article></section>
+<section class="grid"><div><article class="card"><h2>验证结论</h2>${verificationHtml}</article><article class="card"><h2>阶段耗时</h2>${durationHtml}</article></div><div><article class="card"><h2>阶段状态</h2>${stageHtml}</article><article class="card"><h2>风险与后续</h2><div class="risk"><div><h3>已知风险</h3><ul>${riskHtml}</ul></div><div><h3>人工动作</h3><ul>${actionHtml}</ul></div></div></article></div></section>
+<details><summary>变更文件（${files.length}）</summary><div><table><thead><tr><th>文件</th><th>新增</th><th>删除</th></tr></thead><tbody>${fileRows}</tbody></table></div></details>
+<details><summary>执行时间线与工具交接（${timeline.length}）</summary><div><table><thead><tr><th>阶段</th><th>尝试</th><th>状态</th><th>来源 / 摘要</th></tr></thead><tbody>${timelineRows}</tbody></table></div></details>
+<details><summary>命令证据（${commands.length}）</summary><div><table><thead><tr><th>阶段</th><th>命令</th><th>结果</th></tr></thead><tbody>${commandRows}</tbody></table></div></details>
+<details><summary>技术元数据</summary><div><dl><dt>完整提交</dt><dd><code>${esc(data.finalCommit || "N/A")}</code></dd><dt>基线提交</dt><dd><code>${esc(data.baseCommit || "N/A")}</code></dd><dt>Git 范围</dt><dd><code>${esc(diff.range || "N/A")}</code></dd><dt>报告数据版本</dt><dd>${esc(data.schemaVersion || "N/A")}</dd><dt>事实来源</dt><dd>${esc(list(record(data.reportPipeline).sources).join(" · ") || "N/A")}</dd></dl></div></details>
 </main></body></html>`;
 
 fs.mkdirSync(path.dirname(outPath), { recursive: true });
-fs.writeFileSync(outPath, html, 'utf8');
+fs.writeFileSync(outPath, html, "utf8");

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=5cadfa54663ecdbf; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e29fb748896b6f88; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -102,7 +102,7 @@ disallowed-tools:
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -111,3 +111,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

package/harness/bundles/general/claude-code/harness-knowledge-ingest/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=5cadfa54663ecdbf; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e29fb748896b6f88; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -236,7 +236,7 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 - 当前 `active` / `candidate` / `stale` 数量统计。
 - 产物路径（`index.json`、`index.sqlite`、`views/`、`reports/`）。
 - `lifecycle` 摘要：`validatorsApplied`、`candidateAutoPromoted`、`pendingAgentJudge` 等。
-- **已处理报告**（auto + judge 后）：promoted/dropped/superseded/kept/skipped 计数与 `reports/judge-decisions-*.json`、`judgements-*.json` 路径。
+- **已处理报告**（auto + judge 后）：promoted/dropped/superseded/kept/deferred/skipped 计数与 `reports/judge-decisions-*.json`、`judgements-*.json` 路径；人工判断还会追加到 `judgements/decisions.json`，后续 ingest 不得抹除。`defer` 必须带 `reviewAfter`，到期前不重复进入待判断清单。
 - 仅当 `upToDate=false` 时建议 `sync --update`；查询历史 → `/harness-knowledge-query`。**禁止**默认列出「请人工确认 N 条 candidate」待办。
 
 ## 渐进披露
@@ -249,7 +249,7 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -258,3 +258,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。

package/harness/bundles/general/claude-code/harness-knowledge-ingest/scripts/harness_knowledge.py

@@ -776,13 +776,14 @@ def write_cached_archive_entries(
 
 def load_preserved_entries(knowledge: Path) -> list[dict[str, Any]]:
     active_entries = load_entries_from_dir(knowledge / "entries" / "active")
-    demoted_entries = [
+    manually_decided_entries = [
         entry
-        for status in ["candidate", "stale"]
+        for status in ["candidate", "stale", "superseded", "conflicted"]
         for entry in load_entries_from_dir(knowledge / "entries" / status)
         if entry.get("lifecycle", {}).get("demotedAt")
+        or entry.get("lifecycle", {}).get("judgeAction")
     ]
-    return active_entries + demoted_entries
+    return active_entries + manually_decided_entries
 
 
 def combine_generated_with_preserved(knowledge: Path, generated: list[dict[str, Any]]) -> list[dict[str, Any]]:
@@ -3367,7 +3368,7 @@ def render_entry_for_context(entry: dict[str, Any], include_stale: bool = False)
 NEAR_DUPLICATE_THRESHOLD = 0.88
 AUTO_SUPERSEDE_SIMILARITY = 0.75
 AUTO_SUPERSEDE_WEAK_SIMILARITY = 0.55
-JUDGE_ACTIONS = {"promote", "drop", "supersede", "keep-conflict"}
+JUDGE_ACTIONS = {"promote", "drop", "supersede", "keep-conflict", "defer"}
 ENTRY_STATUSES = {"candidate", "active", "stale", "superseded", "conflicted"}
 
 
@@ -3829,6 +3830,8 @@ def judge_export(project: Path) -> dict[str, Any]:
     for entry in entries:
         if entry.get("status") != "conflicted":
             continue
+        if entry.get("lifecycle", {}).get("judgeAction") in {"keep-conflict", "defer"}:
+            continue
         for other_id in entry.get("lifecycle", {}).get("conflictsWith") or []:
             pair = tuple(sorted([entry["id"], str(other_id)]))
             if pair in seen_pairs:
@@ -3878,6 +3881,10 @@ def judge_export(project: Path) -> dict[str, Any]:
     for entry in entries:
         if entry.get("status") != "candidate":
             continue
+        if entry.get("lifecycle", {}).get("judgeAction") == "defer":
+            review_after = str(entry.get("lifecycle", {}).get("reviewAfter") or "")
+            if not review_after or review_after > dt.date.today().isoformat():
+                continue
         promote_candidates.append(
             {
                 "kind": "promote-candidate",
@@ -3984,6 +3991,18 @@ def apply_judge_decision(
         relocate_entry_file(knowledge, entry, source_path)
         path_by_id[entry["id"]] = knowledge / "entries" / "conflicted" / entry_filename(entry)
         after_status = "conflicted"
+    elif action == "defer":
+        lifecycle = entry.setdefault("lifecycle", {})
+        lifecycle["judgeAction"] = action
+        lifecycle["judgeReason"] = reason
+        lifecycle["deferredAt"] = now_iso()
+        lifecycle["reviewAfter"] = decision.get("reviewAfter")
+        lifecycle["lastCheckedAt"] = now_iso()
+        relocate_entry_file(knowledge, entry, source_path)
+        path_by_id[entry["id"]] = (
+            knowledge / "entries" / str(entry.get("status") or "candidate") / entry_filename(entry)
+        )
+        after_status = str(entry.get("status") or "candidate")
     else:
         raise ValueError(f"unsupported judge action: {action}")
 
@@ -3997,6 +4016,35 @@ def apply_judge_decision(
     }
 
 
+def persist_judge_decisions(knowledge: Path, applied: list[dict[str, Any]]) -> Path:
+    """Keep one durable latest decision per entry independently of generated reports."""
+    path = knowledge / "judgements" / "decisions.json"
+    current: dict[str, Any] = {"schemaVersion": 1, "decisions": {}}
+    if path.exists():
+        try:
+            loaded = read_json(path)
+            if isinstance(loaded, dict) and isinstance(loaded.get("decisions"), dict):
+                current = loaded
+        except (OSError, json.JSONDecodeError):
+            pass
+    decisions = dict(current.get("decisions") or {})
+    for record in applied:
+        decisions[str(record["id"])] = {
+            "id": record["id"],
+            "action": record["action"],
+            "reason": record.get("reason") or "",
+            "supersededBy": record.get("supersededBy"),
+            "status": record.get("after", {}).get("status"),
+            "decidedAt": now_iso(),
+        }
+    write_json(path, {
+        "schemaVersion": 1,
+        "updatedAt": now_iso(),
+        "decisions": dict(sorted(decisions.items())),
+    })
+    return path
+
+
 def judge_apply(project: Path, decisions_path: Path, force: bool = False) -> dict[str, Any]:
     project = project.resolve()
     knowledge = project / ".harness" / "knowledge"
@@ -4051,11 +4099,13 @@ def judge_apply(project: Path, decisions_path: Path, force: bool = False) -> dic
     }
     judgement_path = knowledge / "reports" / f"judgements-{timestamp()}.json"
     write_json(judgement_path, judgement)
+    decisions_ledger = persist_judge_decisions(knowledge, applied)
     index = refresh_outputs_from_entry_files(project, knowledge)
     return {
         "project": str(project),
         "generatedAt": judgement["generatedAt"],
         "judgement": str(judgement_path),
+        "decisionsLedger": str(decisions_ledger),
         "applied": len(applied),
         "errors": errors,
         "stats": index.get("stats", {}),
@@ -4262,6 +4312,26 @@ def maintain_knowledge(project: Path, archive_id: str) -> dict[str, Any]:
         }
 
 
+def drain_maintenance_outbox(project: Path, limit: int = 50) -> dict[str, Any]:
+    """Advance all retryable maintenance items in one bounded invocation."""
+    project = project.resolve()
+    root = _outbox_root(project)
+    all_archive_ids = sorted({
+        path.stem
+        for status in ("pending", "failed")
+        for path in (root / status).glob("*.json")
+    })
+    archive_ids = all_archive_ids[:max(0, limit)]
+    results = [maintain_knowledge(project, archive_id) for archive_id in archive_ids]
+    return {
+        "ok": all(result.get("ok") for result in results),
+        "project": str(project),
+        "processed": len(results),
+        "remaining": max(0, len(all_archive_ids) - len(results)),
+        "results": results,
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Build and query Harness knowledge indexes.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -4378,7 +4448,10 @@ def main(argv: list[str] | None = None) -> int:
         help="Single-process maintenance: claim outbox, ingest+dedupe, supersede, reverify, judge-export",
     )
     maintain.add_argument("--project", default=".", help="Project root containing .harness/knowledge")
-    maintain.add_argument("--archive-id", required=True, help="Archive id of the outbox item to maintain")
+    maintain_target = maintain.add_mutually_exclusive_group(required=True)
+    maintain_target.add_argument("--archive-id", help="Archive id of the outbox item to maintain")
+    maintain_target.add_argument("--drain", action="store_true", help="Process all pending/failed items once")
+    maintain.add_argument("--limit", type=int, default=50, help="Maximum items processed by --drain")
     maintain.add_argument("--json", action="store_true", help="Emit machine-readable JSON (default behavior)")
 
     args = parser.parse_args(argv)
@@ -4468,7 +4541,11 @@ def main(argv: list[str] | None = None) -> int:
         print(json.dumps(result, ensure_ascii=False, indent=2))
         return 0
     if args.command == "maintain":
-        result = maintain_knowledge(Path(args.project), args.archive_id)
+        result = (
+            drain_maintenance_outbox(Path(args.project), args.limit)
+            if args.drain
+            else maintain_knowledge(Path(args.project), args.archive_id)
+        )
         print(json.dumps(result, ensure_ascii=False, indent=2))
         return 0 if result.get("ok") else 1
     return 2

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=5cadfa54663ecdbf; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=e29fb748896b6f88; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 根据用户的新需求或排查问题，从项目本地 `.harness/knowledge` 中检索历史需求、决策、实现、风险和测试证据，并生成 AI 可读的 context pack。
@@ -147,7 +147,7 @@ powershell.exe -Command "python '<ingest-skill-dir>\scripts\harness_knowledge.py
 
 ## 执行日志
 
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
+`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
 
 ```powershell
 python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
@@ -156,3 +156,5 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 > **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
 
 > **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
+
+每次阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`；重试同一阶段时增加 `--attempt <n>`，不得覆盖或伪装成一次执行。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。