@hunter-harness/workflow-harness 0.2.37 → 0.2.39

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "af97a6533498c853"
+  "coreHash": "6a2c743a1f8ceb0b"
 }

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=af97a6533498c853; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=6a2c743a1f8ceb0b; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -43,7 +43,7 @@ disallowed-tools:
 自动调用边界：
 
 - 归档涉及移动/删除原变更目录，支持被其他 skill 调用，但调用前必须确保前置条件已满足；也支持用户显式 `/harness-archive` 调用。
-- 归档前确认是强制阻断检查点，用户拒绝 → 终止流程，不执行任何操作。
+- 默认归档前确认是阻断检查点。若 `harness_archive.py auto-gate` 返回 `ARCHIVE_AUTO_GATE_SATISFIED`（Submit 或 Merge 已终态，archive-boundary snapshot 存在且全部归档门禁满足），后续 Archive 可无 AskQuestion 自动运行；其他情况仍须确认。
 
 ## 前置条件
 
@@ -106,9 +106,12 @@ disallowed-tools:
 - **Read `checklist.md`** — 归档前检查项
 - 发现多个未归档变更 → 让用户选择或终止
 
-### Phase 2：确认归档 ⚠️ 强制阻断
+### Phase 2：确认归档 / 自动门禁
 
-blocking user confirmation 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
+先运行 `harness_archive.py auto-gate --change-dir ".harness/changes/<change-name>" --intent <intent> --json`。
+
+- `autoArchiveAllowed=true`：记录 gate receipt，直接进入 Phase 3；无需 AskQuestion。
+- 否则：blocking user confirmation 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
 
 - **Read `reference.md`** — 确认对话框的内容格式
 
@@ -143,9 +146,9 @@ blocking user confirmation 让用户确认归档操作。**用户拒绝 → 终
 
 扫描排除 `.harness/archive/`；多个未归档变更 → 让用户选择或终止，不批量归档。
 
-### 二、归档前确认是强制阻断检查点
+### 二、归档前确认或自动门禁
 
-blocking user confirmation 确认；用户拒绝 → 终止，不执行任何操作。
+`auto-gate` 只有在 Submit/Merge 终态、`meta/state-snapshot.json` 含 archive-boundary base、且 `status.archivable=true` 时才允许无确认执行。未满足时 blocking user confirmation；用户拒绝 → 终止，不执行任何操作。
 
 ### 三、文件移动只用内置工具或 PowerShell
 
@@ -218,7 +221,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## 交互白名单
 
-**仅允许**归档确认（Phase 2 blocking user confirmation）；拒绝 → 终止，不执行任何移动。
+仅当 `auto-gate` 未满足时，允许归档确认（Phase 2 blocking user confirmation）；拒绝 → 终止，不执行任何移动。
 
 ## 执行日志
 

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

@@ -69,7 +69,7 @@ const risks = list(current.findings).length
 const statusTone = (raw) => {
   const status = String(raw || "UNKNOWN").toUpperCase();
   if (/FAIL|ERROR|BLOCKED/.test(status)) return "danger";
-  if (/WARN|CONDITIONAL|PARTIAL|NOT_RUN|UNKNOWN|SKIP/.test(status)) return "warning";
+  if (/WARN|CONDITIONAL|PARTIAL|NOT_RUN|UNKNOWN|SKIP|EVIDENCE_MISSING/.test(status)) return "warning";
   if (/ADVISORY|REUSED|NOT_APPLICABLE/.test(status)) return "neutral";
   return "success";
 };
@@ -77,7 +77,7 @@ const STATUS_LABELS = {
   OK: "通过", PASS: "通过", PASSED: "通过", CONDITIONAL_OK: "有条件通过",
   WARN: "警告", ADVISORY: "建议", FAIL: "失败", FAILED: "失败", ERROR: "错误",
   BLOCKED: "阻塞", NOT_RUN: "未运行", SKIPPED: "已跳过",
-  NOT_APPLICABLE: "不适用", UNKNOWN: "未知"
+  NOT_APPLICABLE: "不适用", UNKNOWN: "未知", EVIDENCE_MISSING: "证据缺失"
 };
 const pill = (raw) => {
   const status = String(raw || "UNKNOWN").toUpperCase();
@@ -115,7 +115,17 @@ const verificationStatus = (value) => {
 };
 const verificationNote = (key, raw) => {
   const value = record(raw);
-  if (key === "unitTests") return `${value.passRate || `${value.run ?? 0} 项`} · 失败 ${value.failures ?? 0}`;
+  if (key === "unitTests") {
+    const unique = numeric(value.uniqueTestCount);
+    const uniqueLabel = unique === null ? "唯一用例未记录" : `唯一 ${unique} 项`;
+    return `${value.passRate || `${value.run ?? 0} 次执行`} · ${uniqueLabel} · 重跑 ${value.rerunCount ?? 0}`;
+  }
+  if (key === "dbCompatibility") {
+    const evidence = record(verification.dbCompatibilityEvidence);
+    return evidence.status === "EVIDENCE_MISSING"
+      ? "缺少可验证的类型化账本/收据"
+      : evidence.reason || evidence.evidenceHash || "类型化兼容性证据";
+  }
   if (key === "apiTests") return `${value.passRate || `${value.passed ?? 0}/${value.total ?? 0}`} · 阻塞 ${value.blocked ?? 0}`;
   if (key === "browserE2E") return `${value.passed ?? 0}/${value.total ?? 0} 通过 · ${value.failed ?? 0} 失败 · 重试 ${value.retries ?? 0}`;
   if (value.checks !== undefined) return `${value.checks} 项检查`;
@@ -135,6 +145,8 @@ const groups = [
   const statuses = values.map(verificationStatus);
   const groupStatus = statuses.some((status) => /FAIL|ERROR|BLOCKED/.test(String(status)))
     ? "FAIL"
+    : statuses.some((status) => /EVIDENCE_MISSING/.test(String(status)))
+    ? "EVIDENCE_MISSING"
     : statuses.some((status) => /WARN|CONDITIONAL|PARTIAL/.test(String(status)))
     ? "WARN"
     : statuses.length && statuses.every((status) => /NOT_APPLICABLE/.test(String(status)))
@@ -147,6 +159,13 @@ const groups = [
 });
 const passedGroups = groups.filter((group) => group.status === "OK").length;
 const productCommit = identity.productCommit || data.productCommit || data.finalCommit;
+const identityChain = [
+  ["检查点", identity.checkpointCommit || data.checkpointCommit],
+  ["产品", productCommit],
+  ["功能尖端", identity.featureTip || data.featureTip],
+  ["合并", identity.mergeCommit || data.mergeCommit || identity.featureMergeHash],
+  ["发布尖端", identity.releaseTip || data.releaseTip || identity.releaseTipHash]
+].filter(([, value]) => value).map(([label, value]) => `${label} ${shortHash(value)}`).join(" → ") || "N/A";
 const wallClock = timing.workflowWallClockMs ?? record(data.durations).totalMs;
 
 const groupHtml = groups.map((group) => `
@@ -201,7 +220,7 @@ const html = `<!doctype html>
   ${recordOnly ? '<div class="record-only">归档意图：仅记录 · 未请求发布</div>' : ""}
 </section>
 <section class="metrics">
-  <article class="metric"><small>产品提交</small><strong><code title="${esc(productCommit || "N/A")}">${esc(shortHash(productCommit))}</code></strong></article>
+  <article class="metric"><small>产品提交链</small><strong><code title="${esc(identityChain)}">${esc(identityChain)}</code></strong></article>
   <article class="metric"><small>验证概览</small><strong>${passedGroups}/${groups.length} 组通过</strong><small>按后端 / Geo / 前端 / 浏览器 / API</small></article>
   <article class="metric"><small>风险与动作</small><strong>${risks.length} / ${actions.length}</strong><small>当前风险 / 人工动作</small></article>
   <article class="metric"><small>全流程耗时</small><strong>${esc(duration(wallClock))}</strong><small>活动 ${esc(duration(timing.stageActiveExecutionMs))}</small></article>
@@ -234,6 +253,7 @@ const html = `<!doctype html>
 <details><summary>命令证据（${commands.length}）</summary><div class="table-wrap"><table><thead><tr><th>阶段</th><th>命令</th><th>结果</th></tr></thead><tbody>${commandHtml}</tbody></table></div></details>
 <details><summary>技术元数据</summary><div><dl>
   <dt>产品提交</dt><dd><code>${esc(productCommit || "N/A")}</code></dd>
+  <dt>检查点 → 产品 → 功能尖端 → 合并 → 发布尖端</dt><dd><code>${esc(identityChain)}</code></dd>
   <dt>产品树哈希</dt><dd><code>${esc(identity.productTreeHash || data.productTreeHash || "N/A")}</code></dd>
   <dt>环境哈希</dt><dd><code>${esc(identity.environmentHash || data.environmentHash || "N/A")}</code></dd>
   <dt>基线提交</dt><dd><code>${esc(identity.baseCommit || data.baseCommit || "N/A")}</code></dd>

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=af97a6533498c853; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=6a2c743a1f8ceb0b; 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=af97a6533498c853; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=6a2c743a1f8ceb0b; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

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

@@ -2654,6 +2654,55 @@ def build_snapshot(project: Path) -> KnowledgeSnapshot:
     )
 
 
+def archive_delta(
+    archive_records: list[dict[str, Any]],
+    previous_index: dict[str, Any] | None,
+) -> dict[str, set[str]]:
+    """Classify archive summaries without treating the whole corpus as dirty."""
+    previous_items = (
+        previous_index.get("archives", {}).get("items", [])
+        if isinstance(previous_index, dict)
+        else []
+    )
+    previous = {
+        str(item.get("summaryData")): str(item.get("summarySha256") or "")
+        for item in previous_items
+        if isinstance(item, dict) and item.get("summaryData")
+    }
+    current = {
+        str(item.get("summaryData")): str(item.get("summarySha256") or "")
+        for item in archive_records
+        if item.get("summaryData")
+    }
+    added = set(current) - set(previous)
+    changed = {
+        path for path in set(current) & set(previous)
+        if current[path] != previous[path]
+    }
+    return {
+        "added": added,
+        "changed": changed,
+        "removed": set(previous) - set(current),
+        "dirty": added | changed,
+    }
+
+
+def restore_unchanged_entry_state(
+    entry: dict[str, Any],
+    previous_entries: dict[str, dict[str, Any]],
+    *,
+    is_dirty: bool,
+) -> None:
+    """Keep historical lifecycle decisions out of a warm ingest hot path."""
+    if is_dirty:
+        return
+    previous = previous_entries.get(str(entry.get("id") or ""))
+    if previous is None:
+        return
+    entry["status"] = previous.get("status", entry.get("status"))
+    entry["lifecycle"] = json_clone(previous.get("lifecycle", entry.get("lifecycle", {})))
+
+
 def build_index(
     project: Path,
     incremental: bool = True,
@@ -2684,19 +2733,21 @@ def build_index(
     ensure_knowledge_dirs(knowledge)
     reporter.emit("snapshot", len(summary_paths), len(summary_paths), force=True)
 
+    old_index: dict[str, Any] | None = None
+    index_path = knowledge / "index.json"
+    if index_path.exists():
+        try:
+            old_index = read_json(index_path)
+        except (OSError, json.JSONDecodeError):
+            old_index = None
+    delta = archive_delta(archive_records, old_index)
+
     # No-op fast path: inputs (archive checksums + config + schema) are unchanged.
     # Write nothing — entries, sqlite, index and views all stay byte-identical,
     # so a repeated ingest is a true no-op (design §3.5, cluster 6, UT-025).
     # Also require index.sqlite to exist so a query never sees a stale index.json
     # pointing at a missing sqlite (API-009 single ensure-current).
     if incremental:
-        old_index: dict[str, Any] | None = None
-        index_path = knowledge / "index.json"
-        if index_path.exists():
-            try:
-                old_index = read_json(index_path)
-            except (OSError, json.JSONDecodeError):
-                old_index = None
         if (
             isinstance(old_index, dict)
             and old_index.get("inputsHash") == inputs_hash
@@ -2716,6 +2767,10 @@ def build_index(
                     "sqliteRebuild": 0,
                     "sqliteUpsert": 0,
                     "sqliteDelete": 0,
+                    "archivesAdded": 0,
+                    "archivesChanged": 0,
+                    "archivesRemoved": 0,
+                    "archivesDelta": 0,
                 }
             )
             result = dict(old_index)
@@ -2751,7 +2806,17 @@ def build_index(
         "sqliteDelete": 0,
         "summaryHashesReused": 0,
         "summaryHashesComputed": 0,
+        "archivesAdded": len(delta["added"]),
+        "archivesChanged": len(delta["changed"]),
+        "archivesRemoved": len(delta["removed"]),
+        "archivesDelta": len(delta["dirty"]) + len(delta["removed"]),
+    }
+    previous_entries = {
+        str(entry.get("id")): entry
+        for _, entry in load_entry_files(knowledge)
+        if entry.get("id")
     }
+    dirty_entry_ids: set[str] = set()
 
     for summary_index, summary_path in enumerate(summary_paths, start=1):
         summary_rel = rel_to_project(project, summary_path)
@@ -2790,6 +2855,15 @@ def build_index(
                 archive_entries = rebind_cached_archive_entries(
                     project, summary_path, summary_hash, archive_entries
                 )
+            is_dirty = summary_rel in delta["dirty"] or not incremental
+            for entry in archive_entries:
+                restore_unchanged_entry_state(
+                    entry,
+                    previous_entries,
+                    is_dirty=is_dirty,
+                )
+                if is_dirty and entry.get("id"):
+                    dirty_entry_ids.add(str(entry["id"]))
             # 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))
@@ -2833,9 +2907,24 @@ def build_index(
         seen.add(fp)
         deduped.append(entry)
 
-    ingest_mode.update(apply_batch_git_freshness(project, deduped))
+    freshness_entries = [
+        entry
+        for entry in deduped
+        if (
+            str(entry.get("id") or "") in dirty_entry_ids
+            or (
+                entry.get("status") in {"active", "candidate"}
+                and str(entry.get("id") or "") not in previous_entries
+            )
+        )
+    ]
+    ingest_mode.update(apply_batch_git_freshness(project, freshness_entries))
     reporter.emit("near-deduplicate", 0, len(deduped), force=True)
-    near_dedupe = dedupe_near_duplicates(deduped, progress=reporter)
+    near_dedupe = dedupe_near_duplicates(
+        deduped,
+        progress=reporter,
+        dirty_entry_ids=dirty_entry_ids if incremental else None,
+    )
     ingest_mode["nearDuplicatesMerged"] = near_dedupe["merged"]
     ingest_mode["similarityCandidates"] = near_dedupe["similarityCandidates"]
     ingest_mode["exactSimilarityComparisons"] = near_dedupe["exactSimilarityComparisons"]
@@ -2920,7 +3009,22 @@ def build_index(
     )
 
     reporter.emit("sqlite", 0, len(indexed_entries), force=True)
-    sqlite_stats = write_sqlite(knowledge / "index.sqlite", indexed_entries)
+    sqlite_dirty_entries = [
+        entry
+        for entry in indexed_entries
+        if (
+            str(entry.get("id") or "") in dirty_entry_ids
+            or (
+                entry.get("status") in {"active", "candidate"}
+                and str(entry.get("id") or "") not in previous_entries
+            )
+        )
+    ]
+    sqlite_stats = write_sqlite(
+        knowledge / "index.sqlite",
+        indexed_entries,
+        dirty_entries=sqlite_dirty_entries if incremental else None,
+    )
     ingest_mode.update(sqlite_stats)
     ingest_mode["sqliteRowsTouched"] = (
         sqlite_stats.get("sqliteUpsert", 0) + sqlite_stats.get("sqliteDelete", 0)
@@ -3288,13 +3392,19 @@ def assert_persistence_invariants(
         )
 
 
-def write_sqlite(path: Path, entries: list[dict[str, Any]]) -> dict[str, Any]:
+def write_sqlite(
+    path: Path,
+    entries: list[dict[str, Any]],
+    *,
+    dirty_entries: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
     """Persist entries to SQLite using a transactional dirty-set.
 
-    Reads existing rows, then upserts only changed entries and deletes removed
-    ones within a single transaction. When the schema version changes or the
-    table is missing, performs a full rebuild. If nothing changed the file is
-    not touched (cluster 6, design §3.5 — true incremental).
+    The normal path compares existing row payloads. Incremental callers may
+    provide the known dirty entries instead, avoiding a full JSON digest of
+    unchanged historical rows. Both paths delete rows absent from the current
+    closure in one transaction. When the schema version changes or the table
+    is missing, performs a full rebuild.
     """
     path.parent.mkdir(parents=True, exist_ok=True)
     stats: dict[str, Any] = {
@@ -3315,18 +3425,52 @@ def write_sqlite(path: Path, entries: list[dict[str, Any]]) -> dict[str, Any]:
         need_rebuild = (not table_exists) or existing_version != SQLITE_SCHEMA_VERSION
 
         existing_map: dict[str, str] = {}
-        if not need_rebuild:
+        existing_status: dict[str, str] = {}
+        dirty_mode = dirty_entries is not None and not need_rebuild
+        if not need_rebuild and not dirty_mode:
             rows = con.execute("select id, entry_json from entries").fetchall()
             existing_map = {str(row[0]): str(row[1]) for row in rows}
+        elif dirty_mode:
+            rows = con.execute("select id, status from entries").fetchall()
+            existing_map = {str(row[0]): "" for row in rows}
+            existing_status = {str(row[0]): str(row[1] or "") for row in rows}
 
         new_map: dict[str, str] = {}
-        for entry in entries:
+        entries_to_serialize = list(dirty_entries or []) if dirty_mode else list(entries)
+        if dirty_mode:
+            # HH-KNOW-20260730-002: archive-delta dirty sets miss lifecycle-only
+            # transitions (promote/demote/conflict/supersede) on unchanged
+            # archives. Reconcile those by status without digesting every row.
+            seen_serialize_ids = {
+                str(entry.get("id") or "")
+                for entry in entries_to_serialize
+                if isinstance(entry, dict) and entry.get("id")
+            }
+            for entry in entries:
+                if not isinstance(entry, dict) or not entry.get("id"):
+                    continue
+                eid = str(entry["id"])
+                if eid in seen_serialize_ids:
+                    continue
+                if existing_status.get(eid) != str(entry.get("status") or ""):
+                    entries_to_serialize.append(entry)
+                    seen_serialize_ids.add(eid)
+        for entry in entries_to_serialize:
             if isinstance(entry, dict) and entry.get("id"):
                 new_map[str(entry["id"])] = json.dumps(entry, ensure_ascii=False)
 
-        to_upsert = [eid for eid in new_map if new_map[eid] != existing_map.get(eid)]
-        to_delete = [eid for eid in existing_map if eid not in new_map]
-        stats["sqliteUnchanged"] = len(new_map) - len(to_upsert)
+        current_ids = {
+            str(entry["id"])
+            for entry in entries
+            if isinstance(entry, dict) and entry.get("id")
+        }
+        to_upsert = (
+            list(new_map)
+            if dirty_mode
+            else [eid for eid in new_map if new_map[eid] != existing_map.get(eid)]
+        )
+        to_delete = [eid for eid in existing_map if eid not in current_ids]
+        stats["sqliteUnchanged"] = len(entries) - len(to_upsert)
 
         if not need_rebuild and not to_upsert and not to_delete:
             # nothing to do; leave the file (and its mtime) untouched
@@ -3372,6 +3516,11 @@ def write_sqlite(path: Path, entries: list[dict[str, Any]]) -> dict[str, Any]:
             con.execute(f"pragma user_version = {SQLITE_SCHEMA_VERSION}")
             stats["sqliteRebuild"] = 1
             # full rebuild => every entry must be (re)inserted
+            new_map = {
+                str(entry["id"]): json.dumps(entry, ensure_ascii=False)
+                for entry in entries
+                if isinstance(entry, dict) and entry.get("id")
+            }
             to_upsert = list(new_map.keys())
             to_delete = []
 
@@ -4121,6 +4270,62 @@ def sync_status(
         action = "ingested"
         reasons = []
 
+    # HH-KNOW-20260730-001: an up-to-date index is not the whole story --
+    # maintenance-outbox items enqueued by `harness archive` still need to be
+    # drained (auto-supersede/reverify-stale/judge-export) before the project
+    # is truly caught up. Drain here whenever the index is current: either it
+    # was just refreshed above, or it was already current on entry. When the
+    # caller did not request an update and the index is stale, skip the drain
+    # -- maintain_knowledge() would otherwise trigger an implicit rebuild via
+    # its own build_index(incremental=True) call, contradicting "don't force
+    # rebuild" for a plain status check.
+    index_current = not reasons
+    outbox_root = _outbox_root(project)
+    maintenance: dict[str, Any]
+    next_action: str | None = None
+    maintain_hint = (
+        "python harness/harness-knowledge-ingest/scripts/harness_knowledge.py "
+        "maintain --project <project> --drain"
+    )
+
+    if index_current:
+        drain_result = drain_maintenance_outbox(project)
+        outbox_ok = bool(drain_result.get("ok")) and drain_result.get("remaining", 0) == 0
+        maintenance = {
+            "attempted": True,
+            "skipped": False,
+            "ok": outbox_ok,
+            "processed": drain_result.get("processed", 0),
+            "remaining": drain_result.get("remaining", 0),
+            "staleRunningRecovered": drain_result.get("staleRunningRecovered", 0),
+            "results": drain_result.get("results", []),
+        }
+        if not outbox_ok:
+            next_action = (
+                "Maintenance outbox is not fully drained. Retry `hunter-harness sync`, "
+                f"or run `{maintain_hint}` to process the remaining items."
+            )
+    else:
+        pending_count = len(list((outbox_root / "pending").glob("*.json"))) if outbox_root.is_dir() else 0
+        failed_count = len(list((outbox_root / "failed").glob("*.json"))) if outbox_root.is_dir() else 0
+        running_count = len(list((outbox_root / "running").glob("*.json"))) if outbox_root.is_dir() else 0
+        outbox_ok = pending_count == 0 and failed_count == 0
+        maintenance = {
+            "attempted": False,
+            "skipped": True,
+            "skippedReason": "index out of date; rerun with --update to rebuild and drain",
+            "ok": outbox_ok,
+            "pending": pending_count,
+            "failed": failed_count,
+            "running": running_count,
+        }
+        next_action = (
+            "Run `hunter-harness sync` (or sync --update) to rebuild the index; "
+            "the maintenance outbox drain is skipped while the index is stale."
+        )
+
+    ok = index_current and bool(maintenance.get("ok"))
+
     result = {
         "project": str(project),
         "upToDate": not reasons,
@@ -4131,6 +4336,9 @@ def sync_status(
             "index": str(index_path),
             "sqlite": str(sqlite_path),
         },
+        "maintenance": maintenance,
+        "ok": ok,
+        "nextAction": next_action,
     }
     if refreshed is not None:
         result["index"] = summarize_index(refreshed)
@@ -4522,16 +4730,33 @@ def dedupe_near_duplicates(
     threshold: float = NEAR_DUPLICATE_THRESHOLD,
     *,
     progress: ProgressReporter | None = None,
+    dirty_entry_ids: set[str] | None = None,
     max_exact_comparisons: int = 50_000,
     time_budget_ms: int = 2_000,
 ) -> dict[str, Any]:
-    """Merge near duplicates through sparse buckets and an explicit work budget."""
+    """Merge near duplicates through sparse buckets and an explicit work budget.
+
+    Full / offline path (``dirty_entry_ids is None``): keep historical semantics —
+    every non-superseded status participates, and pairs stay scoped to the same
+    ``(archive, type)`` group.
+
+    Online hot path (``dirty_entry_ids`` provided): exclude stale/superseded from
+    the comparison corpus, keep archive scoping, and only emit pairs that touch
+    at least one dirty entry (HH-KNOW-20260730-002).
+    """
     started = time.monotonic()
     deadline = started + max(0, time_budget_ms) / 1_000
     merges: list[dict[str, Any]] = []
-    active_entries = [
-        entry for entry in entries if entry.get("status") != "superseded"
-    ]
+    if dirty_entry_ids is None:
+        active_entries = [
+            entry for entry in entries if entry.get("status") != "superseded"
+        ]
+    else:
+        active_entries = [
+            entry
+            for entry in entries
+            if entry.get("status") in {"active", "candidate"}
+        ]
     normalized = {id(entry): entry_compare_text(entry) for entry in active_entries}
     similarity_cache: dict[tuple[int, int], float] = {}
     similarity_candidates = 0
@@ -4540,6 +4765,8 @@ def dedupe_near_duplicates(
 
     grouped: dict[tuple[str, str], list[dict[str, Any]]] = {}
     for entry in active_entries:
+        # Same-archive scoping is intentional: near-dup merges are intra-archive.
+        # Cross-archive evolution/conflict is handled by supersede/review paths.
         key = (
             str(entry.get("source", {}).get("archive") or ""),
             str(entry.get("type") or ""),
@@ -4580,6 +4807,13 @@ def dedupe_near_duplicates(
                 for right_identity in members[left_index + 1 :]:
                     if left_identity == right_identity:
                         continue
+                    if dirty_entry_ids is not None and not (
+                        str(entry_by_identity[left_identity].get("id") or "")
+                        in dirty_entry_ids
+                        or str(entry_by_identity[right_identity].get("id") or "")
+                        in dirty_entry_ids
+                    ):
+                        continue
                     candidate_pairs.add(tuple(sorted((left_identity, right_identity))))
 
     def similarity(left: dict[str, Any], right: dict[str, Any]) -> float:
@@ -5451,15 +5685,35 @@ 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."""
+def drain_maintenance_outbox(
+    project: Path, limit: int = 50, *, stale_running_seconds: float = 300.0
+) -> dict[str, Any]:
+    """Advance all retryable maintenance items in one bounded invocation.
+
+    Crash recovery: a `running` item left behind by a process that died
+    mid-maintenance never returns to `pending`/`failed` on its own, so it
+    would stall forever. Once a `running` item is older than
+    `stale_running_seconds` it is treated as stuck and re-included here.
+    `claim_outbox` returns a `running` item as-is (it only claims from
+    pending/failed/pending-judge), and `maintain_knowledge` does NOT early
+    return for `status == "running"` (only for `"completed"`) -- it falls
+    through to the try block and retries the maintenance steps in place, so
+    simply including the stale id in the drain batch is sufficient recovery.
+    """
     project = project.resolve()
     root = _outbox_root(project)
-    all_archive_ids = sorted({
+    now = time.time()
+    retryable_ids = {
         path.stem
         for status in ("pending", "failed")
         for path in (root / status).glob("*.json")
-    })
+    }
+    stale_running_ids = {
+        path.stem
+        for path in (root / "running").glob("*.json")
+        if now - path.stat().st_mtime >= stale_running_seconds
+    }
+    all_archive_ids = sorted(retryable_ids | stale_running_ids)
     archive_ids = all_archive_ids[:max(0, limit)]
     results = [maintain_knowledge(project, archive_id) for archive_id in archive_ids]
     return {
@@ -5467,6 +5721,7 @@ def drain_maintenance_outbox(project: Path, limit: int = 50) -> dict[str, Any]:
         "project": str(project),
         "processed": len(results),
         "remaining": max(0, len(all_archive_ids) - len(results)),
+        "staleRunningRecovered": len(stale_running_ids & set(archive_ids)),
         "results": results,
     }
 

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=af97a6533498c853; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=6a2c743a1f8ceb0b; 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=af97a6533498c853; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=6a2c743a1f8ceb0b; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

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=af97a6533498c853; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=6a2c743a1f8ceb0b; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose
@@ -146,7 +146,7 @@ review 结果默认只作参考，不阻塞 submit/archive；报告措辞遵循
 
 ### 四、Shell 安全 / 敏感信息 / 证据化报告 / CodeGraph 探索
 
-git diff/log 命令通过 `powershell.exe -Command "..."` 执行；review-report 中如发现明文 token/密码/密钥，必须列入 RED 问题并在报告中以 `<TOKEN_REDACTED>` 等占位符引用；RED/YELLOW/OK 结论必须基于实际 diff 内容，不得凭印象判断。代码探索必须优先使用 CodeGraph MCP 工具（`mcp__codegraph__codegraph_explore`），不允许通过普通 Bash 调 codegraph 命令（已列入 `disallowed-tools`）；MCP 不可用时降级为 Grep/Glob + Read，并在执行日志记录降级原因。遵循 `../protocols/powershell-protocol.md` / `sensitive-info-protocol.md` / `evidence-based-reporting-protocol.md`。
+git diff/log 命令通过 `powershell.exe -Command "..."` 执行；review-report 中如发现明文 token/密码/密钥，必须列入 RED 问题并在报告中以 `<TOKEN_REDACTED>` 等占位符引用；RED/YELLOW/OK 结论必须基于实际 diff 内容，不得凭印象判断。代码探索必须优先使用 CodeGraph MCP 工具（`mcp__codegraph__codegraph_explore`），不允许通过普通 Bash 调 codegraph 命令（已列入 `disallowed-tools`）；采纳任何返回源码前，按 `reference.md` 的 C12 合同校验 executionRoot/rootPath、worktreeId、repositoryId、HEAD 与 index snapshot，`IDENTITY_MISMATCH` 必须读取实际 worktree，不得当作 stale 忽略；MCP 不可用时降级为 Grep/Glob + Read，并在执行日志记录降级原因。遵循 `../protocols/powershell-protocol.md` / `sensitive-info-protocol.md` / `evidence-based-reporting-protocol.md`。
 
 ### 五、state snapshot 与源码重验