npm - hunter-harness - Versions diffs - 0.1.2 → 0.2.0 - Mend

hunter-harness 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (566) hide show

package/resources/harness/bundles/java/codex/harness-archive/reference.md ADDED Viewed

@@ -0,0 +1,103 @@
+---
+description: harness-archive 的归档流程、manifest、summary-data、final-summary 渲染、目录结构与最终状态规则。
+---
+# harness-archive 参考
+## 归档流程（对齐 SKILL.md Workflow）
+- **Phase 0 读取上下文**：读 SKILL.md / 本文件 / 共用协议（`../protocols/archive-report-protocol.md`、`../protocols/report-pipeline-protocol.md`、`../protocols/state-layout-protocol.md`、`../protocols/powershell-protocol.md`、`../protocols/sensitive-info-protocol.md`、`../protocols/evidence-based-reporting-protocol.md`）/ 解析 `$ARGUMENTS`。
+- **Phase 1 确认归档对象**：Glob `.harness/changes/*/plans/*-plan.md`（排除 archive），展示概要；多变更让用户选择或终止。
+- **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
+- **Phase 3 执行归档**：
+  1. append `phase.start` 事件（`harness_events.py append`）。
+  2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
+  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。
+  4. 模型补写 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`（脚本留空占位）。
+  5. append `phase.end` 事件。**finalize 报错或 validate 失败时不删除原 changes 目录**。
+- **Phase 4 验证与提示**：见 `checklist.md` 归档后验证项。
+## manifest 生成
+manifest 每项包含：
+```json
+{"path":"...","size":123,"sha256":"...","lastModified":"..."}
+```
+建议使用固定脚本，禁止内联复杂 PowerShell（包含 `$`、`$_`、`@{}`、script block、管道 JSON 输出）：
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-archive/scripts/gen-manifest.ps1" -RootPath ".harness/changes/<change>" -OutputPath ".harness/changes/<change>/evidence/archive-manifest-before.json"
+```
+移动到 archive 目录后，再生成 after manifest：
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-archive/scripts/gen-manifest.ps1" -RootPath ".harness/archive/<date-change>" -OutputPath ".harness/archive/<date-change>/evidence/archive-manifest-after.json"
+```
+**校验 before/after 时排除 execution-log**（通用）：`logs/execution-log.md` 在归档过程会追加结束记录（Phase 4），before（移动前含开始记录）与 after（含开始+结束记录）sha256 必然不同——这是预期追加，非文件损坏。校验脚本需跳过 `logs/execution-log.md`，其他 moved 文件 sha256 必须一致；若其他文件 missing/mismatch，才表示移动损坏，不得删除原目录。
+## summary-data.json 与 harness_archive.py
+默认由 `harness_archive.py finalize`（或 `replay`）生成/校验 `reports/final/summary-data.json`；CLI 不可用时按 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json`（schemaVersion 2.2）生成等价数据。必须保留原 final report 维度。必须包含：
+- `businessGoal`：本次变更为了做什么；
+- `stageStatus`：plan/run/test/review/submit/archive；
+- `diffStat`：filesChanged/insertions/deletions/range —— 来自 `git diff --numstat` + `git diff --stat <base>..<head>`，不得手写；
+- `durations`：totalMinutes + stages[{stage,skill,startedAt,endedAt,minutes,result}] —— 从 `logs/execution-log.md` 各 `[N] harness-<skill>` 小节的 `开始`/`结束`/`耗时` 解析；
+- `skillCalls`：每个 skill 的调用次数（含重入）+ 结果 —— 从 execution-log 统计；
+- `verification`：单元/API/覆盖展示，含 passRate —— 来自 `evidence/verification-ledger.json`；
+- `changedFiles`：path/summary/insertions/deletions —— 来自 `git diff --numstat <base>..<head>`；
+- `reviewSummary`：red/yellow + redFixed/redConfirmed/yellowFixed/yellowDeferred 修复进度；
+- `maintenanceNotes`：给后续维护者看的结论；
+- `knownRisks`：剩余风险或人工确认项。
+报告必须突出业务目标和维护者结论。所有统计数字只能来自 events、summary-data、ledger 或 manifest，不得手写另一套。历史 archive 没有 `events.ndjson` 时，允许从 ledger/log/manifest 回放，并在 `reportPipeline.sources` 中记录来源。
+## final-summary 渲染
+默认使用 Node.js 渲染器：
+```powershell
+powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-archive/templates/render-summary.mjs' --summary '.harness/archive/<date-change>/reports/final/summary-data.json' --out '.harness/archive/<date-change>/reports/final/final-summary.html'"
+```
+如模板脚本位于 skill 目录，则先复制到 archive 目录或直接引用 skill 路径。
+禁止模型临场手写大段 HTML。确需临时修 HTML，只能修模板，不得让统计数字脱离 `summary-data.json`。
+渲染后必须执行：
+```powershell
+powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<date-change>' --json"
+```
+存在 validate error 时，不得删除原 `.harness/changes/<change>` 目录。
+## archive-meta.md 模板
+```markdown
+# Archive Meta — <change-name>
+- archivedAt: YYYY-MM-DD HH:mm
+- finalCommit: <hash>
+- sourceDir: .harness/changes/<change-name>
+- archiveDir: .harness/archive/YYYY-MM-DD-<change-name>
+- movedFiles: <from manifest>
+- generatedFiles: archive-meta.md, summary-data.json, final-summary.html, manifests
+- totalArchiveFiles: <from after manifest>
+```
+## 目录结构与最终状态规则
+- 默认渲染器：`templates/render-summary.mjs`，输入 `reports/final/summary-data.json`，输出 `reports/final/final-summary.html`。
+- `render-summary.mjs` 是默认 UTF-8 渲染器；finalize 内嵌调用，不得由模型临场写 HTML。
+- 新路径优先：`meta/`、`logs/`、`evidence/`、`reports/final/`、`scripts/`、`backups/uncommitted-tests/`。旧路径只做读取兼容，不再写大量根目录文件。
+- 当 `summary-data.json.verification.apiTests.status=USER_SKIPPED` 或 `verification.dbCompatibility.status=BLOCKED_BY_DBA`，最终状态必须是 `CONDITIONAL_OK`。
+- 复杂 PowerShell 命令写入 `scripts/*.ps1` 后 `-File` 执行，禁止内联 `$` / `$_`。
+## 执行日志记录
+归档只向 `events.ndjson` 追加事件（schema_version 2）；`logs/execution-log.md` 由 `harness_events.py append` 自动渲染，禁止手工 Edit。事件类型与脚本用法见 SKILL.md `## 执行日志` 与 `../protocols/report-pipeline-protocol.md`。

package/resources/harness/bundles/java/codex/harness-archive/scripts/gen-manifest.ps1 ADDED Viewed

@@ -0,0 +1,31 @@
+param(
+  [Parameter(Mandatory=$true)][string]$RootPath,
+  [Parameter(Mandatory=$true)][string]$OutputPath
+)
+$ErrorActionPreference = 'Stop'
+$root = (Resolve-Path $RootPath).Path
+# 排除 OutputPath 自身：重新生成 manifest 时旧 manifest 文件会被扫到，导致递归（新 manifest 含旧 manifest 的 sha256，fileCount 虚高 +1）。
+# OutputPath 不存在时（首次生成）$excludePath=$null，Where-Object 不过滤。
+$excludePath = $null
+if (Test-Path $OutputPath) {
+  $excludePath = (Resolve-Path $OutputPath).Path
+}
+$items = Get-ChildItem -Path $root -File -Recurse | Where-Object { $excludePath -eq $null -or $_.FullName -ne $excludePath } | Sort-Object FullName | ForEach-Object {
+  $relative = $_.FullName.Substring($root.Length).TrimStart('\','/') -replace '\\','/'
+  $hash = Get-FileHash -Path $_.FullName -Algorithm SHA256
+  [PSCustomObject]@{
+    path = $relative
+    sizeBytes = $_.Length
+    sha256 = $hash.Hash.ToLowerInvariant()
+  }
+}
+$result = [PSCustomObject]@{
+  root = $root
+  generatedAt = (Get-Date).ToString('s')
+  fileCount = @($items).Count
+  totalBytes = (@($items) | Measure-Object -Property sizeBytes -Sum).Sum
+  files = @($items)
+}
+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+[System.IO.File]::WriteAllText((Resolve-Path (Split-Path $OutputPath -Parent)).Path + [System.IO.Path]::DirectorySeparatorChar + (Split-Path $OutputPath -Leaf), ($result | ConvertTo-Json -Depth 8), $utf8NoBom)

package/resources/harness/bundles/java/codex/harness-archive/templates/render-summary.mjs ADDED Viewed

@@ -0,0 +1,171 @@
+#!/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';
+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');
+if (!summaryPath) {
+  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 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 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 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 totalLabel = durations.totalLabel || (durations.totalMinutes ? durations.totalMinutes + 'm' : 'N/A');
+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>
+</main></body></html>`;
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(outPath, html, 'utf8');

package/resources/harness/bundles/java/codex/harness-archive/templates/summary-data-template.json ADDED Viewed

@@ -0,0 +1,128 @@
+{
+  "schemaVersion": "2.2",
+  "changeName": "<change-name>",
+  "businessGoal": "本次变更为了做什么",
+  "finalStatus": "OK | WARN | CONDITIONAL_OK | FAIL",
+  "finalCommit": "<commit-hash>",
+  "finalCommitBranch": "<origin/branch>",
+  "baseCommit": "<base-commit-hash>",
+  "diffStat": {
+    "filesChanged": 0,
+    "insertions": 0,
+    "deletions": 0,
+    "range": "<base>..<head>"
+  },
+  "stageStatus": {
+    "plan": "OK",
+    "run": "OK | WARN",
+    "test": "OK | PARTIAL | USER_SKIPPED | BLOCKED_BY_DBA",
+    "review": "ADVISORY",
+    "submit": "OK",
+    "archive": "OK"
+  },
+  "durations": {
+    "totalLabel": "约 N 分",
+    "totalMinutes": 0,
+    "stages": [
+      {
+        "stage": "plan",
+        "skill": "harness-plan",
+        "startedAt": "YYYY-MM-DD HH:mm:ss",
+        "endedAt": "YYYY-MM-DD HH:mm:ss",
+        "minutes": 0,
+        "result": "OK | WARN | FAIL"
+      }
+    ]
+  },
+  "skillCalls": [
+    { "skill": "harness-plan", "count": 1, "result": "OK" }
+  ],
+  "verification": {
+    "unitTests": {
+      "run": 0,
+      "failures": 0,
+      "errors": 0,
+      "skipped": 0,
+      "passRate": "183/185",
+      "source": "committed | uncommitted-archived | not-run"
+    },
+    "apiTests": {
+      "status": "OK | PARTIAL | USER_SKIPPED | NOT_RUN",
+      "total": 0,
+      "passed": 0,
+      "failed": 0,
+      "blocked": 0,
+      "passRate": "34/35"
+    },
+    "dbCompatibility": "OK | BLOCKED_BY_DBA | NOT_RUN",
+    "coverageDisplay": "例如 29/29 或 USER_SKIPPED"
+  },
+  "timeline": [],
+  "changedFiles": [
+    { "path": "src/...", "summary": "说明", "insertions": 0, "deletions": 0 }
+  ],
+  "artifacts": [],
+  "reviewSummary": {
+    "status": "ADVISORY",
+    "red": 0,
+    "yellow": 0,
+    "redFixed": 0,
+    "redConfirmed": 0,
+    "yellowFixed": 0,
+    "yellowDeferred": 0,
+    "summary": ""
+  },
+  "archiveManifest": {
+    "movedFiles": 0,
+    "generatedFiles": 0,
+    "totalArchiveFiles": 0,
+    "checksumStatus": "OK | WARN | FAIL"
+  },
+  "reportPipeline": {
+    "schema_version": 1,
+    "generated_at": "YYYY-MM-DDTHH:mm:ss.sssZ",
+    "event_count": 0,
+    "sources": [
+      "events.ndjson",
+      "evidence/verification-ledger.json",
+      "logs/execution-log.md"
+    ],
+    "phases": {
+      "plan": { "duration_ms": null, "event_count": 0 },
+      "run": { "duration_ms": null, "event_count": 0 },
+      "test": { "duration_ms": null, "event_count": 0 },
+      "review": { "duration_ms": null, "event_count": 0 },
+      "submit": { "duration_ms": null, "event_count": 0 },
+      "archive": { "duration_ms": null, "event_count": 0 }
+    },
+    "commands": [
+      {
+        "command": "npm test",
+        "exit_code": 0,
+        "duration_ms": 0,
+        "phase": "run",
+        "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ"
+      }
+    ],
+    "verificationChecks": [
+      {
+        "name": "unit tests",
+        "status": "passed | failed | skipped | unknown",
+        "command": "npm test",
+        "source": "events.ndjson | evidence/verification-ledger.json"
+      }
+    ],
+    "artifacts": [
+      {
+        "path": "reports/final/final-summary.html",
+        "kind": "final-report",
+        "phase": "archive"
+      }
+    ],
+    "validationIssues": []
+  },
+  "uncommittedTestEvidence": [],
+  "maintenanceNotes": [],
+  "knownRisks": [],
+  "manualActions": []
+}

package/resources/harness/bundles/java/codex/harness-codebase-map/SKILL.md ADDED Viewed

@@ -0,0 +1,95 @@
+---
+name: harness-codebase-map
+description: 分析现有代码库并生成 .harness/codebase/map/
+  下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
+---
+<!-- generated by harness_deploy.py; core=9a7af3c66acaad35; overlay=java; agent=codex; do not edit -->
+# harness-codebase-map — 代码库地图
+## Purpose
+生成 hunter-harness 自有代码库地图 → `.harness/codebase/map/`（7 类文档）+ `map-summary.md` + `map-manifest.json`。供 plan/run/review 快速理解项目结构。
+## 核心边界
+- **只写** `.harness/codebase/map/`、`map-summary.md`、`map-manifest.json`、`.harness/reports/codebase-map-*.md`
+- **禁止** `.planning/`、Git 写操作、修改 `.codegraph/`、自动 commit/push
+- `harness-sync` 只**建议**刷新，不自动跑全量 map
+## When to Use
+首次接入、map 过期（sync 提示）、大型重构前、用户说「刷新 codebase map」。跳过：空项目（<5 源文件）、纯符号查询（用 CodeGraph）。
+## Arguments
+| 参数 | 含义 |
+|------|------|
+| （无） | 全量 7 文档 |
+| `--fast` | STACK + STRUCTURE + CONCERNS |
+| `--focus *` | tech / arch / quality / concerns / tech+arch |
+| `--paths p1,p2` | 增量路径（非法路径 → WARN，全非法须确认） |
+| `--status` / `--diff` | 只检查，不刷新 |
+| `--refresh` | 显式全量刷新 |
+## Workflow（薄编排）
+| Phase | 动作 |
+|-------|------|
+| 0 | 读 SKILL + `reference.md` / `checklist.md` / `templates/` + protocols |
+| 1 | 解析 `$ARGUMENTS` → 模式与扫描范围 |
+| 2 | 检查现有 map / manifest → `--status` 可在此结束 |
+| 3 | `New-Item` 确保输出目录（PowerShell，禁止 Bash mkdir） |
+| 4 | Glob/Grep/Read 扫描；git 只读查询经 PowerShell |
+| 5 | 写 7 文档（`templates/` + frontmatter）— 可并行 mapper agents |
+| 6 | 写 summary + manifest（schema → `templates/map-manifest.schema.json`） |
+| 7 | 更新 `.harness/context-index.json` codebase 入口（若存在） |
+| 8 | 控制台 + `.harness/reports/codebase-map-*.md` 报告 |
+逐步细节、frontmatter 字段、git 允许列表 → `reference.md` / `checklist.md`
+## Mapper Agent 策略
+优先并行 mapper（tech/arch/quality/concerns）；Agent 直写文档，主会话汇总。不可用 → 主会话顺序扫描 + 🟡WARN。
+## P0 执行可信度规则
+- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
+- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
+- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
+## 关键规则
+| # | 规则 |
+|---|------|
+| 1 | 唯一输出 `.harness/codebase/map/` |
+| 2 | `generated_reviewable`，不建议手工改 map 正文 |
+| 3 | 不 Git 写操作、不改业务代码 |
+| 4 | 不管理 CodeGraph |
+| 5 | 敏感信息脱敏 → `sensitive-info-protocol` |
+| 6 | 证据化输出 → `evidence-based-reporting-protocol` |
+## Output Format
+模式、范围、7/7 文档路径与行数、manifest/summary、context-index 状态、WARN/FAIL → `reference.md` 报告模板
+## 渐进披露
+- **Read `checklist.md`** — 执行前后检查
+- **Read `reference.md`** — manifest、mapper、扫描模式
+- **Read `templates/*`** — 各文档模板
+## 交互白名单
+**无** AskUserQuestion；参数/默认值 + `decision` 事件
+## 执行日志
+`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../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 "<触发指令>"
+```
+> **脚本接线**：`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 边界保持最新。

package/resources/harness/bundles/java/codex/harness-codebase-map/checklist.md ADDED Viewed

@@ -0,0 +1,126 @@
+# harness-codebase-map 检查清单
+## 执行前检查
+| 检查项 | 必须 | 说明 |
+|---|:---:|---|
+| 当前目录是项目根或已给出项目路径 | 是 | 需要能定位源码、配置和 `.harness/` |
+| 参数已解析 | 是 | 识别 full / fast / focus / paths / status / diff |
+| `--paths` 已做安全校验 | 条件 | 拒绝 `..`、绝对路径、shell 元字符 |
+| 已读取 `.harness/project.yaml` | 否 | 不存在时 profile 记为 unknown |
+| 已读取 `.harness/context-index.json` | 否 | 不存在时可创建最小结构 |
+| 已检查旧 map 状态 | 是 | 判断首次、缺失、过期、部分刷新 |
+| 已确认输出路径为 `.harness/codebase/map/` | 是 | 禁止 `.planning/codebase/` |
+| 已确认不执行 Git 写操作 | 是 | 禁止 add/commit/pull/merge/push/reset/checkout/rebase/clean；只允许 status / diff --name-only / rev-parse |
+## 参数模式检查
+| 模式 | 需要生成/检查 |
+|---|---|
+| `--status` | 只检查 map 完整性、manifest、summary、stale 状态 |
+| `--diff` | 对比 manifest 与当前代码状态，输出可能过期范围 |
+| full / `--refresh` | 生成或刷新 7 个文档 |
+| `--fast` | 默认刷新 `STACK.md`、`STRUCTURE.md`、`CONCERNS.md` |
+| `--focus tech` | `STACK.md`、`INTEGRATIONS.md` |
+| `--focus arch` | `ARCHITECTURE.md`、`STRUCTURE.md` |
+| `--focus quality` | `CONVENTIONS.md`、`TESTING.md` |
+| `--focus concerns` | `CONCERNS.md` |
+| `--paths` | 只扫描合法 repo-relative 路径，仍按 focus 决定输出文档 |
+## 输出文件检查
+全量模式必须存在：
+```text
+.harness/codebase/map/STACK.md
+.harness/codebase/map/INTEGRATIONS.md
+.harness/codebase/map/ARCHITECTURE.md
+.harness/codebase/map/STRUCTURE.md
+.harness/codebase/map/CONVENTIONS.md
+.harness/codebase/map/TESTING.md
+.harness/codebase/map/CONCERNS.md
+.harness/codebase/map-summary.md
+.harness/codebase/map-manifest.json
+```
+模板目录必须包含：
+```text
+templates/STACK.md
+templates/INTEGRATIONS.md
+templates/ARCHITECTURE.md
+templates/STRUCTURE.md
+templates/CONVENTIONS.md
+templates/TESTING.md
+templates/CONCERNS.md
+templates/map-summary.md
+templates/map-manifest.schema.json
+```
+局部刷新模式中，未刷新文件如果已存在，可以保留；如果不存在，必须在报告中标记 WARN。
+## 文档质量检查
+每个生成文档必须满足：
+- 有 YAML frontmatter。
+- 标明 `generator: harness-codebase-map`。
+- 标明 `file_kind: generated_reviewable`。
+- 包含实际文件路径，路径使用反引号包裹。
+- 不包含明文 token、password、secret、Authorization、Cookie、API key。
+- 不把猜测写成事实；不确定内容用“推测 / 待验证”。
+- 至少包含 “Analysis Date” 或 “Mapped At”。
+## Manifest 检查
+`map-manifest.json` 必须包含：
+- `generator`
+- `generated_at`
+- `mode`
+- `profile`
+- `last_mapped_commit`
+- `path_scope`
+- `documents[]`
+- 每个文档的 `path` / `document_type` / `sha256` / `line_count`
+- `warnings[]`
+## Context Index 检查
+如果 `.harness/context-index.json` 存在：
+- 必须保留未知字段。
+- 只更新 `codebase.map` 相关字段。
+- 不得覆盖 rules、knowledge、skills 其他索引。
+如果不存在：
+- 可创建最小结构。
+- 报告中标记 `context-index: created-minimal`。
+## 失败判定
+以下情况必须标记 `❌FAIL`：
+- 无法写入 `.harness/codebase/map/`。
+- 全量模式下 7 个文档未全部生成，且不是用户明确选择局部模式。
+- manifest 无法生成或 JSON 不可读。
+- 写入后的文件无法 Read 验证。
+以下情况标记 `🟡WARN`：
+- Agent 工具不可用，降级为顺序扫描。
+- 部分路径非法，被剔除。
+- 无法获取 git commit，使用 `unknown`。
+- context-index 不存在并创建了最小结构。
+- 局部刷新导致部分文档仍缺失。
+- 检测到可能敏感信息并已脱敏。
+## 结束前必检
+- [ ] 输出目录是 `.harness/codebase/map/`。
+- [ ] 没有创建 `.planning/`。
+- [ ] 没有修改 `.codegraph/`。
+- [ ] 没有执行 Git 写操作。
+- [ ] 所有写入文件已通过 Read 或文件存在检查验证。
+- [ ] 最终回复中列出生成文件、行数、状态和 warnings。