@hunter-harness/workflow-harness 0.2.8 → 0.2.10

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "0d4dcc4204125f4d"
+  "coreHash": "43088896a4556b69"
 }

package/harness/bundles/general/claude-code/contracts/workflow-policy.json

@@ -2,21 +2,21 @@
   "schemaVersion": 1,
   "riskTiers": {
     "fast": {
-      "description": "Low-risk docs/comments/non-behavioral config; no API/DB/security/concurrency.",
+      "description": "Low-risk docs/comments/non-behavioral config; no API/DB/security/concurrency. Policy notes: checkpointRules apply only when meta/implementation-checkpoints.json defines the entry for this change; missing file/entry = disabled (gate must not require --task).",
       "defaultPhases": ["plan", "run", "submit", "archive"],
       "requiredValidations": ["unitTest"],
       "conditionalStages": ["review", "package", "apidoc"],
       "upgradeTriggers": ["api-change", "security", "migration", "concurrency", "breaking-contract"]
     },
     "standard": {
-      "description": "Ordinary production code and non-breaking API/features.",
+      "description": "Ordinary production code and non-breaking API/features. Policy notes: requiredValidations may close DEGRADED when ledger status=NOT_RUN and evidence starts with 'DEGRADED: <reason>' (close code CLOSED_DEGRADED, phase status <= WARN); do not fake OK with unrelated tests.",
       "defaultPhases": ["plan", "run", "test", "submit", "archive"],
       "requiredValidations": ["compile", "unitTest", "unitTestFull"],
       "conditionalStages": ["review", "package", "apidoc"],
       "upgradeTriggers": ["auth", "security", "delete", "migration", "concurrency", "artifact-protocol", "shared-state", "breaking-api"]
     },
     "full": {
-      "description": "Auth/security/delete/migration/concurrency/service protocol/shared state/breaking contracts.",
+      "description": "Auth/security/delete/migration/concurrency/service protocol/shared state/breaking contracts. Policy notes: (1) DEGRADED close — ledger status=NOT_RUN and evidence 'DEGRADED: <reason>' → CLOSED_DEGRADED with phase <= WARN; never fake OK with unrelated tests. (2) checkpointRules — only when plan created meta/implementation-checkpoints.json entry; missing file/entry = not enabled, gate must not require --task.",
       "defaultPhases": ["plan", "run", "test", "review", "submit", "archive"],
       "requiredValidations": ["compile", "unitTest", "unitTestFull", "apiTest"],
       "conditionalStages": ["package", "apidoc"],

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=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -103,8 +103,8 @@ AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，
 ### Phase 3：执行归档
 
 1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
-2. 如需维护者结论，在移动前补全 `meta/archive-meta.md`；不得在 finalize 后修改已校验的归档文件。
-3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（事件、移动、collect、render、validate、manifest 比对）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
+2. `meta/archive-meta.md` **由 `harness_archive.py finalize` 自动生成**（与 summary-data `finalStatus` 同源）；**禁止 agent 手写**该文件，手写视为数据丢失。维护者结论写入 events（decision/issue）即可，finalize 会汇总到 summary / archive-meta。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。**finalize 失败或 validate 报错时不删除原目录**。
 
 - **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
 - **Read `templates/summary-data-template.json`** — summary-data 数据结构

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

@@ -11,8 +11,8 @@ description: harness-archive 的归档流程、manifest、summary-data、final-s
 - **Phase 2 确认归档（强制阻断）**：AskUserQuestion 确认，拒绝即终止。
 - **Phase 3 执行归档**：
   1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ... --json` 做前置检查。
-  2. 需要维护者结论时，在移动前补全 `meta/archive-meta.md` 的 `maintenanceNotes` / `knownRisks` / `manualActions`；finalize 后不再修改归档内容。
-  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 报错或 validate 失败时不删除原 changes 目录**。
+  2. `meta/archive-meta.md` 由 finalize 生成（与 summary `finalStatus` 同源）；禁止手写。维护者结论写入 events 即可。finalize 在 before-manifest 前执行 cleanup（删除 lock/pid/launcher/credential，截断超大日志）。
+  3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ... --archive-root ".harness/archive" --json`；读 JSON 结果。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**finalize 报错或 validate 失败时不删除原 changes 目录**。finalize 为冻结优先（freeze-first）：collect 前先 fsync 事件并写 `evidence/evidence-cutoff.json`，cutoff 后不再追加事件；随后依次执行 source consistency（层 1，写入 `reportPipeline.sourceConsistency`）→ render → renderer consistency（层 2），任一层失败即恢复原目录并非零退出。
 - **Phase 4 验证与提示**：见 `checklist.md` 归档后验证项。
 
 ## manifest 生成
@@ -39,7 +39,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 
 ## summary-data.json 与 harness_archive.py
 
-`reports/final/summary-data.json` 只能由 `harness_archive.py finalize`（归档时）或 `replay`（回放时）生成/校验；**禁止 agent 临场手写或拼装等价数据**，也不存在独立的 `report collect`/`report validate` CLI（参见 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json` schemaVersion 2.2）。必须保留原 final report 维度。必须包含：
+`reports/final/summary-data.json` 只能由 `harness_archive.py finalize`（归档时）或 `replay`（回放时）生成/校验；**禁止 agent 临场手写或拼装等价数据**，也不存在独立的 `report collect`/`report validate` CLI（参见 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json` schemaVersion 2.3）。必须保留原 final report 维度。必须包含：
 
 - `businessGoal`：本次变更为了做什么；
 - `stageStatus`：plan/run/test/review/submit/archive；
@@ -68,20 +68,38 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 `validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不再作为独立 `report validate` CLI 调用）。finalize 在 validate error 存在时恢复原 `.harness/changes/<change>` 目录并 exit 非 0，绝不归档未通过校验的变更。
 
+## repair（归档后修复，不改写原版）
+
+归档后发现 source/renderer 不一致时，使用显式修复（`replay` 仍为只读）：
+
+```powershell
+python <skills-root>/scripts/harness_archive.py repair --archive-dir ".harness/archive/<archive-id>" --json
+```
+
+repair 在 archive 外生成候选版本，两层 validator 通过后写入不可变 `derived/v<N>/`（summary-data.json + final-summary.html + repair-record.json），并更新 `derived/authoritative.json` pointer；原 summary、HTML、manifest 不覆盖。知识层仅从 authoritative pointer 且 hash 校验通过的版本提取。
+
 ## archive-meta.md 模板
 
+由 `harness_archive.py finalize` 生成（手写视为数据丢失）。frontmatter 与 summary-data 同源：
+
 ```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>
+---
+archive-id: YYYY-MM-DD-<change-name>
+change-name: <change-name>
+archived-at: YYYY-MM-DD HH:mm
+final-commit: <hash>
+base-commit: <hash>
+final-status: <OK|WARN|CONDITIONAL_OK|FAIL>   # 与 summary-data.finalStatus 同源
+source: harness-archive
+---
+# 归档元数据 — <change-name>
+## 阶段状态
+## 变更文件
+## 已知风险
 ```
 
+cleanup 步骤（before-manifest 前）：删除 `events.ndjson.lock`、`runtime/*.pid`、launcher、credential/token/secret 文件名；截断 `logs/**/*.log` 超过 64KB 的尾部保留。
+
 ## 目录结构与最终状态规则
 
 - 默认渲染器：`templates/render-summary.mjs`，输入 `reports/final/summary-data.json`，输出 `reports/final/final-summary.html`。

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

@@ -56,6 +56,10 @@ const actions = list(data.manualActions);
 const files = list(data.changedFiles);
 const commands = list(record(data.reportPipeline).commands);
 const timeline = list(data.timeline);
+const statusReasons = list(data.finalStatusReasons);
+const reasonHtml = statusReasons.length
+  ? `<small>${statusReasons.map((item) => esc(item)).join(" · ")}</small>`
+  : "";
 
 const stageHtml = stages.map(([name, status]) => `<div class="row"><span>${esc(name)}</span>${pill(status)}</div>`).join("") || '<p class="empty">没有阶段状态记录</p>';
 const verificationHtml = [
@@ -81,7 +85,7 @@ const html = `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><met
 *{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="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 证据生成${data.riskTier ? ` · riskTier=${esc(data.riskTier)}` : ""}</span></div>${reasonHtml ? `<div class="status">${reasonHtml}</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>

package/harness/bundles/general/claude-code/harness-archive/templates/summary-data-template.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "2.2",
+  "schemaVersion": "2.3",
   "changeName": "<change-name>",
   "businessGoal": "本次变更为了做什么",
   "finalStatus": "OK | WARN | CONDITIONAL_OK | FAIL",
@@ -119,7 +119,11 @@
         "phase": "archive"
       }
     ],
-    "validationIssues": []
+    "validationIssues": [],
+    "sourceConsistency": {
+      "ok": true,
+      "issues": []
+    }
   },
   "uncommittedTestEvidence": [],
   "maintenanceNotes": [],

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=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -153,6 +153,8 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 
 仅在用户点名单条、或 `manualReview=true` 需人工确认时使用 `promote` / `demote`。日常归档后不要逐条人工复核。
 
+**发布门禁**：promote / judge apply / autoPromote 会校验来源归档——`reportPipeline.sourceConsistency` 缺失或失败、authoritative pointer /hash 不通过的归档，其条目带 `lifecycle.publishBlocked`，只能停留在 quarantined candidate。先 `harness_archive.py repair` 修复并重新 ingest，再 promote（详见 `reference.md`「发布门禁」）。
+
 ### Phase 6：解释同步结果
 
 回复用户或交给后续 skill 前，应说明：

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

@@ -145,6 +145,13 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sugge
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' promote --project '<project-root>' --id '<entry-id>' --note '<人工确认说明>'"
 ```
 
+**发布门禁（archive publication gate）**：promote / judge apply / autoPromote 只处理来自**已验证归档**的条目。以下来源归档会被阻断并在条目上标记 `lifecycle.publishBlocked`（ingest 仍可生成 quarantined candidate，但不得 active/promote）：
+
+- 归档 summary 缺少 `reportPipeline.sourceConsistency`（source consistency 未运行）或 `ok=false`；
+- `derived/authoritative.json` pointer 缺失、版本目录不可读，或 repair record / pointer 的 summary hash 不匹配（DEGRADED）。
+
+修复路径：先运行 `harness_archive.py repair` 生成通过两层 validator 的新 derived version，再重新 ingest（旧错误条目标记 superseded），之后 promote 才放行。
+
 将一条 `candidate` 提升为 `active`，写入：
 
 ```text

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

@@ -353,6 +353,95 @@ def changed_file_paths(summary: dict[str, Any]) -> list[str]:
     return files
 
 
+def archive_publication_status(project: Path, archive_rel: str) -> dict[str, Any]:
+    """Knowledge publication gate for one archive (API-006/RET-40).
+
+    Blocks judge/apply/promote when: source consistency never ran or failed,
+    the authoritative version is missing or hash-mismatched, or the archive
+    is DEGRADED/UNVERIFIED. Ordinary ingest may still build quarantined
+    candidates, but nothing from a blocked archive becomes active.
+    """
+    result: dict[str, Any] = {"status": "missing", "allowed": False, "reasons": []}
+    archive_dir = (Path(project) / archive_rel).resolve()
+    summary_path = archive_dir / "reports" / "final" / "summary-data.json"
+    if not summary_path.is_file():
+        result["reasons"].append("summary-data.json missing")
+        return result
+    try:
+        summary = json.loads(summary_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        result["reasons"].append("summary-data.json unreadable")
+        return result
+    if not isinstance(summary, dict):
+        result["reasons"].append("summary-data.json must be an object")
+        return result
+
+    # A versioned repair becomes authoritative only after its pointer and
+    # repair-record hashes are verified. Gate the authoritative summary, not
+    # the known-bad original that caused the repair.
+    pointer_path = archive_dir / "derived" / "authoritative.json"
+    if pointer_path.is_file():
+        try:
+            pointer = json.loads(pointer_path.read_text(encoding="utf-8"))
+            version = str(pointer.get("version") or "")
+            if re.fullmatch(r"v[0-9]+", version) is None:
+                raise ValueError("invalid authoritative version")
+            version_dir = (archive_dir / "derived" / version).resolve()
+            if not version_dir.is_relative_to((archive_dir / "derived").resolve()):
+                raise ValueError("authoritative version escapes derived root")
+            record = json.loads(
+                (version_dir / "repair-record.json").read_text(encoding="utf-8")
+            )
+            derived_path = version_dir / "summary-data.json"
+            summary_bytes = derived_path.read_bytes()
+            actual = "sha256:" + hashlib.sha256(summary_bytes).hexdigest()
+            if record.get("summarySha256") != actual:
+                result["status"] = "degraded"
+                result["reasons"].append("repair record summary hash mismatch")
+                return result
+            if pointer.get("summarySha256") not in {None, actual}:
+                result["status"] = "degraded"
+                result["reasons"].append("authoritative pointer hash mismatch")
+                return result
+            summary = json.loads(summary_bytes.decode("utf-8"))
+            if not isinstance(summary, dict):
+                raise ValueError("authoritative summary must be an object")
+            result["authoritativeVersion"] = version
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError, ValueError):
+            result["status"] = "degraded"
+            result["reasons"].append("authoritative version unreadable")
+            return result
+
+    consistency = (summary.get("reportPipeline") or {}).get("sourceConsistency")
+    if consistency is None:
+        result["status"] = "unverified"
+        result["reasons"].append("source consistency never ran")
+        return result
+    if not consistency.get("ok"):
+        result["status"] = "failed"
+        codes = [
+            str(i.get("code"))
+            for i in (consistency.get("issues") or [])
+            if isinstance(i, dict) and i.get("code")
+        ]
+        result["reasons"].append(
+            "source consistency failed" + (f": {', '.join(codes)}" if codes else "")
+        )
+        return result
+
+    final_status = str(summary.get("finalStatus") or "").upper()
+    if final_status not in {"OK", "CONDITIONAL_OK"}:
+        result["status"] = "degraded" if final_status == "DEGRADED" else "unverified"
+        result["reasons"].append(
+            f"authoritative finalStatus is not publishable: {final_status or 'missing'}"
+        )
+        return result
+
+    result["status"] = "ok"
+    result["allowed"] = True
+    return result
+
+
 def archive_summary_records(project: Path, summary_paths: list[Path]) -> list[dict[str, Any]]:
     records = []
     for summary_path in summary_paths:
@@ -939,6 +1028,9 @@ def apply_confidence_scores(entries: list[dict[str, Any]], config: dict[str, Any
 def should_auto_promote(entry: dict[str, Any], policy: dict[str, Any]) -> bool:
     if not policy["enabled"]:
         return False
+    # API-006/RET-40: entries from blocked archives stay quarantined.
+    if entry.get("lifecycle", {}).get("publishBlocked"):
+        return False
     if entry.get("type") not in set(policy["allowedTypes"]):
         return False
     if entry.get("status") == "stale" and not policy["allowStale"]:
@@ -1946,6 +2038,17 @@ def build_index(
                     ingest_mode["cacheWrites"] += 1
             else:
                 ingest_mode["archivesReused"] += 1
+            # API-006/RET-40: entries from archives failing the publication
+            # gate stay quarantined (candidate only, never active/promoted).
+            archive_rel = rel_to_project(project, archive_dir_from_summary(summary_path))
+            publication = archive_publication_status(project, archive_rel)
+            if not publication.get("allowed"):
+                for entry in archive_entries:
+                    lifecycle = entry.setdefault("lifecycle", {})
+                    lifecycle["publishBlocked"] = list(publication.get("reasons") or [])
+                    if entry.get("status") == "active":
+                        entry["status"] = "candidate"
+                        ingest_mode["activeAutoDemoted"] += 1
             entries.extend(archive_entries)
         except Exception as exc:  # keep one bad archive from blocking the index
             failures.append({"path": rel_to_project(project, summary_path), "error": str(exc)})
@@ -2064,6 +2167,20 @@ def promote_entry(project: Path, entry_id: str, note: str, allow_stale: bool = F
         raise ValueError(f"entry not found in promotable statuses: {entry_id}")
 
     source_path, entry = found
+    # API-006/RET-40: refuse promotion of entries from blocked archives.
+    blocked = (entry.get("lifecycle") or {}).get("publishBlocked")
+    if blocked:
+        raise ValueError(
+            "publication blocked: " + "; ".join(str(r) for r in blocked)
+        )
+    archive_rel = (entry.get("source") or {}).get("archive")
+    if archive_rel:
+        publication = archive_publication_status(project, archive_rel)
+        if not publication.get("allowed"):
+            raise ValueError(
+                "publication blocked: "
+                + "; ".join(str(r) for r in (publication.get("reasons") or []))
+            )
     entry["status"] = "active"
     lifecycle = entry.setdefault("lifecycle", {})
     lifecycle["promotedAt"] = now_iso()

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=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-plan/checklist.md

@@ -57,6 +57,12 @@ description: harness-plan 的阶段检查清单和覆盖检查列表。仅在执
 > - CodeGraph 如通过 MCP 调用，必须优先用 MCP 工具，不允许通过普通 Bash 调 codegraph 命令
 > - 禁止把子代理未经工具验证的文本结论当作"详尽报告"或代码证据采纳
 
+## 影响面检查（远程客户端路径）
+
+变更涉及 HTTP/RPC 客户端时，在设计/任务拆分前完成路径静态比对：
+
+- [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
+
 ## 阶段 4：设计审批包 ⚠️ 强制阻断（一次 AskUserQuestion）
 
 > 合并原「设计审核 + worktree + 场景表预览 + change-name」。推荐 worktree 读 `harness.json` `defaultWorktree`。

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -72,8 +72,8 @@ disallowed-tools:
 
 先运行 `python <skills-root>/scripts/harness_preflight.py check-agents --skills-root <skills-root> --agent harness-reviewer --json`。`usable=false` → **直接主会话审查**，记 `decision` 事件，**不委派**。`reasonCode=CUSTOM_AGENTS_UNSUPPORTED` 是当前工具没有自定义 agent 能力的正常 inline 路径，不显示缺失告警。`usable=true` 时用 Agent spawn `harness-reviewer`（只读, 6 维度）。返回空 / 无报告正文 → **不 retry**，降级主会话审查。
 
-3. **持久化报告（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`。未 Write → 🟡WARN，不得宣称 review 完成。
-4. **生成修复反馈（原生协议）** — 若报告存在 RED/YELLOW 问题，执行 `protocols.md` 的 `review-fixback-protocol`，将问题转化为结构化 fixback 清单并落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`。若无 RED/YELLOW，记录 `review-fixback-protocol: skipped(no findings)`。不调用 Superpowers `receiving-code-review`，也不记录外部 skill 降级。
+3. **持久化报告与事实 sidecar（强制，主会话）** — Agent 返回后主会话 Write 到 `reports/review/review-report-*.md`，并把同一批发现写成临时 JSON 后调用 `python <skills-root>/scripts/harness_review.py write-findings --change-dir <change-dir> --input <findings.json>`。权威计数来自 `reports/review/review-findings.json`，不是 Markdown。任一写入缺失 → 🟡WARN，不得宣称 review 完成。
+4. **生成修复反馈（原生协议）** — 若报告存在 RED/YELLOW 问题，执行 `protocols.md` 的 `review-fixback-protocol`，将问题转化为结构化 fixback 清单并落盘到 `.harness/changes/<change-name>/reports/review/fixback-YYYYMMDD-HHmm.md`；随后把 disposition 临时 JSON 交给 `python <skills-root>/scripts/harness_review.py write-dispositions --change-dir <change-dir> --input <dispositions.json>`，权威状态写入 `reports/review/fixback-dispositions.json`。若无 RED/YELLOW，也必须写空 findings sidecar，并记录 `review-fixback-protocol: skipped(no findings)`。不调用 Superpowers `receiving-code-review`，也不记录外部 skill 降级。
 5. **收尾** — append `phase.end` / `artifact` 事件；控制台输出摘要
 
 ## Review 定位（重要）

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

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/checklist.md

@@ -120,6 +120,11 @@ description: harness-run 的执行检查清单。仅在编码执行时读取。
 - [ ] 纯 Mock 数据访问层测试 → 标记为 🟡静态验证，交给 harness-test 真实 DB 验证
 - [ ] 如果必须自动化 → 使用真实数据访问层（非 mock）或可检查查询条件的测试方式
 
+### 编码前检查（远程客户端 / stub 同源错误）
+
+- [ ] 变更涉及 HTTP/RPC 客户端（Feign/RestTemplate/SDK 封装）时：取客户端注解路径（类级 + 方法级拼接），与服务提供方 controller 的 `@RequestMapping` + 方法级注解**完整拼接路径**逐一比对，在计划/执行记录中列出比对结果。只看方法级注解不算完成。
+- [ ] 修 stub/null 返回时，顺带核对同文件相邻声明（注解、常量、同类方法路径）是否同源错误，一并列出核对结果
+
 ### GREEN（最简实现 — 按变更簇批量实现）
 
 - [ ] 写最少代码让变更簇测试全部通过

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

@@ -522,12 +522,14 @@ powershell.exe -Command "<测试命令> <模块定位参数>"
 
 ```powershell
 python <skills-root>/scripts/harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json
-python <skills-root>/scripts/harness_ledger.py record --change-dir ".harness/changes/<change-name>" --verification compile --status PASS --command "<cmd>" --exit-code 0 --json
+python <skills-root>/scripts/harness_ledger.py record --change-dir ".harness/changes/<change-name>" --verification compile --status ok --command "<cmd>" --exit-code 0 --json
 ```
 
 > `content-changeset-2` 同时读取 tracked diff、标准 untracked 文件和 manifest 的精确测试路径。manifest 缺失时保持普通行为；manifest 存在但路径越界、内容 hash 漂移或结构非法时命令失败，ledger 不可复用。checkpoint commit 不改变各路径的工作树内容，因此提交前后 hash 保持一致。
 
 > 这样 harness-test 的 Phase 1 可读取 ledger 判断是否复用 run 的 unitTest（diffHash commit-invariant + reuse 规则 #2 允许 HEAD 前移 → run 的 checkpoint commit 不破坏复用），submit 也可复用 compile 结果。详见 `../protocols/ledger-protocol.md`。
+>
+> **Ledger v3（v2 契约 / split-v1 布局起）**：`record` 自动解析并强制顶层身份（`schemaVersion=3/repositoryId/changeName/baseCommit/currentHead/diffHash/ownershipHash`），缺字段非零退出、不写账本；`--metrics-json` 必须通过 typed schema（unit=`total/passed/failed`，apiContract=`scenariosTotal/passed/failed`，browserE2E=`total/passed/failed`，dbCompatibility=`applicability(+reason)`）；新增 `--base-commit/--diff-hash/--applicability/--applicability-reason`。legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
 
 阶段边界：`harness_gate.py begin/close`；测试跟踪：`harness_test_guard.py begin/close`。close 失败不得用自然语言覆盖。
 
@@ -789,6 +791,36 @@ powershell.exe -Command "git -C '<project-path>' diff --check"
 在 harness-test 通过前，不建议也不应进入 `/harness-submit`。
 ```
 
+## CLI 速查（gate / ledger）
+
+> 可直接复制；替换 `<skills-root>` / `<cn>` / `<dir>` / `<project>`。`--task` **仅在该 change 启用 checkpoint 时必需**（checkpoints 文件缺失或不含 pending foundation-gate 时不要传）。
+> `ledger record` 必需：`--duration-ms`、`--evidence`，以及 `--files`（逗号分隔源文件）或 `--profile-input <verificationKey> --project <project>`（从 build-profile 展开）。`status` 枚举: `ok|fail|not_run`（没有 PASS）。
+> `--skills-root` 仅用于 `begin`（及 `lint-skills`）：必须是 adapter 根（如 `.cursor/skills`），不是 `scripts/` 子目录。**`close` 不需要 `--skills-root`**（该子命令不接受此参数）。
+
+```powershell
+# gate begin/close（--task 仅在该 change 启用 checkpoint 时必需；close 不需要 --skills-root）
+python <skills-root>/scripts/harness_gate.py begin --change <cn> --phase run --skills-root <skills-root> [--task N]
+python <skills-root>/scripts/harness_gate.py close --change <cn> --phase run --status OK [--task N]
+
+# ledger 记录（status: ok|fail|not_run —— 没有 PASS）
+python <skills-root>/scripts/harness_ledger.py record --change-dir <dir> --verification unitTestFull --status ok --command "<完整命令>" --exit-code 0 --duration-ms 120000 --evidence "Tests run: 155, Failures: 0, Errors: 0, Skipped: 0" --coverage full --files "packages/core/src/index.ts"
+
+# 复用检查（--profile-input 取 verification key，不是文件路径；配合 --project）
+python <skills-root>/scripts/harness_ledger.py can-reuse --change-dir <dir> --verification unitTestFull --profile-input unitTestFull --project <project>
+```
+
+### 常见报错对照
+
+| 报错 | 原因 | 处理 |
+|------|------|------|
+| `unsupported status: PASS` | ledger status 无 PASS | 改用 `ok` / `fail` / `not_run` |
+| `TASK_NUMBER_REQUIRED` | 该 change 启用了 checkpoint（如 foundation-gate pending） | 补 `--task N` |
+| skills-root / BUNDLE_IDENTITY_* | `begin` 未传或传了 `.../scripts` 子目录（`close` 不接受该参数） | 仅对 `begin` 显式传 adapter 根：`.cursor/skills` / `.claude/skills`（含 `.harness-build.json`） |
+| `--profile-input` 指向文件路径 | 参数语义是 verification key | 传 `compile` / `unitTestFull` 等 key，不是 JSON 路径 |
+| `record requires --files or a non-empty --profile-input file set` | 缺少输入文件集 | 补 `--files` 或 `--profile-input <key> --project <project>` |
+| `--profile-input requires --project` | can-reuse/record 展开 profile 需要项目根 | 补 `--project <project>` |
+| `record` 缺 `--duration-ms` / `--evidence` | 参数为必填 | 按模板补齐 |
+
 ## 关键原则
 
 - 增量构建优先：`powershell.exe -Command "<构建命令> <模块定位参数>"`（Java 示例：`mvn compile -pl <module> -o -q`，不用 clean，用离线模式加速）

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=0d4dcc4204125f4d; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=43088896a4556b69; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -74,7 +74,7 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 ### 提交流程（步骤 0–7）
 
 0. **启动准备** — `harness_change.py resolve` 确定变更名；**`harness_gate.py begin --phase submit --change <id>`**；读 ledger，以 `harness_ledger.py diff-hash --repo . --base <baseCommit> --change-dir ".harness/changes/<change-name>" --json` 计算 diffHash + post-test 7 类分类（禁止手写 ledger / 手工 phase.end）
-1. **合并最新代码** — 主目录：`stash` → `pull --rebase` → `stash pop`；**worktree：N/A**（远端同步在合并段主分支完成）
+1. **合并最新代码** — 主目录与 worktree 均**不在业务工作区 stash/pull**；远端同步由合并段 integration transaction 在隔离 integration worktree 内完成（见「worktree 合并流程」）；**正常路径禁止 `git stash` / `stash pop`**
 2. **最终验证** — ledger 复用优先；**提交前最终门禁只调 `can-reuse`**（删除与 coverage 冲突的二次全量门禁）：`harness_ledger.py can-reuse --verification unitTestFull --scope module --project . --profile-input unitTestFull --command <resolved commands.unitTestFull.command>`。`--command` **按 profile key resolve**：读 `build-profile.json` 的 `commands.unitTestFull.command`（v2），或 `harness_profile.py resolve --project . --key unitTestFull --json` 取 resolved command，**不复制示例模块名**（文档示例只展示 key）。`--profile-input unitTestFull` 从 `verificationInputs.unitTestFull`（v2 由 `commands.unitTestFull.inputs` 派生）展开依赖闭包，**禁止用仅含 staged 文件的 `--files` 快捷方式**冒充全量闭包。`reuse=true` → 不再执行二次全量测试；仅 `reuse=false` 时执行**同一 resolved verification**（profile `unitTestFull` 命令），成功后用同一文件集、command、`scope=module` 经 **`harness_ledger.py record`** 写回 ledger `unitTestFull` 项。增量 `unitTest` 永远不能冒充 `unitTestFull` 门禁。
 3. **.gitignore + 精确暂存** ⚠️ — 检查 `.harness/` 在 `.gitignore`；**禁止 `git add -A`**。若存在 `evidence/test-tracking.json`，先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；失败即硬停止。无 manifest 时不使用 `-f`。manifest 之外的文件按精确业务路径正常暂存，**禁止全局 force-add**。
 4. **提交方式** — 主目录：AskUserQuestion 三选项（commit+push / 仅本地 / 取消）；**worktree：固定仅本地 commit**
@@ -86,15 +86,20 @@ worktree 合并前必须运行 `harness_change.py integration-lock acquire --run
 
 ### worktree 合并流程（requested=true，commit 后自动执行）
 
+合并由 `harness_integration.py` transaction 执行：隔离 integration worktree + journal + 保护 ref + 精确清理。skill 只负责确认提交信息、调用子命令、展示结构化结果；**禁止手工 `checkout --ours/--theirs`**。
+
 M0. append `phase.start`（phase=merge，若从 `/harness-merge` 重入则 note 标注重入）
-M1. **切回主目录主分支** — `symbolic-ref origin/HEAD` 读主分支名；必要时 stash；确认 checkout 主分支
-M2. **fetch + pull --rebase** — 记录是否引入他人提交（决定 M4 是否重跑验证）
-M3. **`git merge --no-ff worktree/<change-name>`** — 合并消息可让用户改文案，**方式固定 --no-ff**
-M4. **冲突处理** — 若 `CONFLICT` → **停下**，列出冲突文件，提示用户手动解决后重跑；**禁止 `checkout --theirs/--ours`**；状态 🟡WARN，不得宣称合并成功
-M5. **合并后验证** — 他人提交引入 → 必须重跑构建+测试；否则 ledger 复用 🔁REUSED
-M6. **push 主分支** — fetch 后 `log HEAD..@{u}` 非空则回 M2；否则 push，记录 `mergeFinalHash`
-M7. **清理 worktree** — `worktree remove` + `branch -D`（Windows 兜底见 `reference.md`）；更新 `worktree.json`（`created=false` + removedAt 等）
-M8. **ledger + 收尾** — 经 `harness_ledger.py record` 写入 `mergeFinalHash`；**`harness_gate.py close --phase merge`**（禁止手工 phase.end）；提示 `/harness-archive`
+M1. **preflight** — `harness_integration.py preflight --change <id> --run-id <run> --feature-branch worktree/<id> --target-branch <主分支> --temp-root <task temp>`；获取 integration lock、写 journal 与保护 ref；锁被持有即停止
+M2. **prepare** — fetch 后从已提交 target 创建临时 integration worktree；primary 的 dirty 状态不被触碰
+M3. **merge** — `--no-ff` 合并 feature 分支；merge diff 出现其他 Change 的 contract/runtime 路径 → 结构化拒绝；冲突 → step FAILED，**停下**列出冲突文件，人工解决后以 `recover` 续跑（已完成步骤返回 REUSED，不重复 merge/push）
+M4. **verify** — 在 integration worktree 内执行组合态验证；他人提交引入或 ledger 不可复用时必跑
+M5. **push** — 仅在验证身份与远端基线仍匹配时 push；远端漂移 → `TARGET_MOVED` 结构化失败，不继续
+M6. **cleanup** — `git worktree remove --force` 精确路径 + 临时分支 + （push 成功后）保护 ref；释放 integration lock；失败保留 journal 与诊断证据；更新 `worktree.json`（`created=false` + removedAt）
+M7. **ledger + 收尾** — 经 `harness_ledger.py record` 写入 `mergeFinalHash`（= journal `pushedHead`）；**`harness_gate.py close --phase merge`**（禁止手工 phase.end）；提示 `/harness-archive`
+
+> Ledger v3（v2 契约 / split-v1 布局起）：`record` 强制顶层身份（`schemaVersion=3/repositoryId/baseCommit/currentHead/diffHash/ownershipHash`，缺失非零退出、不写账本）与 typed metrics；legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
+
+正常路径**禁止创建、应用或删除仓库级 stash**。中断恢复：`harness_integration.py status` 读 journal，`recover` 从首个未完成步骤续跑；protection refs 只在 push 成功后的 cleanup 删除。
 
 ## P0 执行可信度规则