@hunter-harness/workflow-harness 0.2.8 → 0.2.10

package/harness/bundles/java/claude-code/scripts/harness_test_guard.py

@@ -21,6 +21,12 @@ import time
 from pathlib import Path
 from typing import Any
 
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+import harness_paths  # noqa: E402
+
 SCHEMA_VERSION = 1
 MODE = "force-track-touched"
 MANIFEST_REL = Path("evidence") / "test-tracking.json"
@@ -166,13 +172,18 @@ def _change_dir(project: Path, change_dir: Path | str) -> Path | None:
     return resolved if any(_inside(resolved, root) for root in allowed_roots) else None
 
 
+def _state_root(change_root: Path) -> Path:
+    return Path(harness_paths.resolve_state_dir_for_contract(change_root))
+
+
 def _manifest_path(change_root: Path) -> Path | None:
-    evidence = change_root / MANIFEST_REL.parent
-    manifest = change_root / MANIFEST_REL
+    state_root = _state_root(change_root)
+    evidence = state_root / MANIFEST_REL.parent
+    manifest = state_root / MANIFEST_REL
     expected_evidence = evidence.absolute()
     resolved_evidence = evidence.resolve()
     if (
-        not _inside(resolved_evidence, change_root.resolve())
+        not _inside(resolved_evidence, state_root.resolve())
         or os.path.normcase(str(resolved_evidence))
         != os.path.normcase(str(expected_evidence))
     ):
@@ -181,9 +192,10 @@ def _manifest_path(change_root: Path) -> Path | None:
 
 
 def _manifest_target_inside(change_root: Path, manifest: Path) -> bool:
+    state_root = _state_root(change_root)
     resolved = manifest.resolve()
     return (
-        _inside(resolved, change_root.resolve())
+        _inside(resolved, state_root.resolve())
         and _inside(resolved, manifest.parent.absolute())
     )
 
@@ -267,6 +279,52 @@ def _validate_file(project: Path, raw: str) -> tuple[Path | None, str | None, st
     return resolved, rel, None
 
 
+def _contract_is_v2(change_root: Path) -> bool:
+    try:
+        contract = harness_paths.load_change_contract(change_root)
+    except (OSError, ValueError):
+        return False
+    if harness_paths.contract_layout_kind(contract) == "split-v1":
+        return True
+    version = contract.get("schemaVersion")
+    return isinstance(version, int) and version >= 2
+
+
+def _byte_hash(path: Path) -> str:
+    return "sha256:" + hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def logical_file_hash(repo_root: Path, rel: str) -> str:
+    """Logical identity for a tracked file (RET-10).
+
+    Text files hash with git blob semantics (path filters/attributes applied,
+    so LF/CRLF spellings of one logical text agree). Binary files keep byte
+    hash. Indeterminate content falls back to byte hash.
+    """
+    path = repo_root / rel
+    content = path.read_bytes()
+    attr = _git(repo_root, "check-attr", "text", "--", rel)
+    attr_out = attr.stdout.strip() if attr.returncode == 0 else ""
+    if attr_out.endswith(": unset"):
+        return _byte_hash(path)
+    if b"\x00" in content:
+        return _byte_hash(path)
+    try:
+        content.decode("utf-8")
+    except UnicodeDecodeError:
+        return _byte_hash(path)
+    proc = subprocess.run(
+        ["git", "hash-object", "--path", rel, "--stdin"],
+        input=content,
+        capture_output=True,
+        cwd=str(repo_root),
+        check=False,
+    )
+    if proc.returncode != 0:
+        return _byte_hash(path)
+    return "gitblob:" + proc.stdout.decode("ascii").strip()
+
+
 def _entry_shape_valid(item: Any) -> bool:
     return (
         isinstance(item, dict)
@@ -280,6 +338,78 @@ def _entry_shape_valid(item: Any) -> bool:
     )
 
 
+def _entry_shape_valid_v2(item: Any) -> bool:
+    if not isinstance(item, dict):
+        return False
+    if not isinstance(item.get("path"), str) or not item["path"]:
+        return False
+    logical = item.get("logicalHash")
+    binary = item.get("binaryHash")
+    logical_ok = isinstance(logical, str) and (
+        logical.startswith("gitblob:") or logical.startswith("sha256:")
+    )
+    binary_ok = binary is None or (
+        isinstance(binary, str) and binary.startswith("sha256:")
+    )
+    if not (logical_ok or binary_ok):
+        return False
+    if item.get("reason") not in REASONS:
+        return False
+    if type(item.get("ignored")) is not bool:
+        return False
+    if not isinstance(item.get("introducedBy"), str) or not item["introducedBy"]:
+        return False
+    touched = item.get("touchedBy")
+    if not isinstance(touched, list) or not all(isinstance(t, str) for t in touched):
+        return False
+    return item.get("commitScope") in ("current-change", "foreign-change")
+
+
+def _validate_existing_manifest_v2(
+    project: Path,
+    manifest: Any,
+    *,
+    allow_hash_drift: set[str] | None = None,
+    require_files: bool,
+) -> tuple[str | None, dict[str, dict[str, Any]]]:
+    if (
+        not isinstance(manifest, dict)
+        or manifest.get("schemaVersion") != 2
+        or manifest.get("mode") != MODE
+    ):
+        return "MANIFEST_INVALID", {}
+    repository_id = manifest.get("repositoryId")
+    if not isinstance(repository_id, str) or not repository_id.startswith("sha256:"):
+        return "MANIFEST_INVALID", {}
+    if repository_id != harness_paths.repository_identity(project):
+        return "MANIFEST_PROJECT_MISMATCH", {}
+    entries = manifest.get("files")
+    if not isinstance(entries, list):
+        return "MANIFEST_INVALID", {}
+    if require_files and not entries:
+        return "EMPTY_MANIFEST", {}
+
+    allowed_drift = allow_hash_drift or set()
+    validated: dict[str, dict[str, Any]] = {}
+    for item in entries:
+        if not _entry_shape_valid_v2(item):
+            return "MANIFEST_INVALID", {}
+        rel = item["path"]
+        if rel in validated:
+            return "MANIFEST_INVALID", {}
+        path, normalized, error = _validate_file(project, rel)
+        if error or normalized != rel or path is None:
+            return error or "MANIFEST_INVALID", {}
+        expected = item.get("logicalHash") or item.get("binaryHash")
+        if expected != logical_file_hash(project, rel) and rel not in allowed_drift:
+            return "HASH_DRIFT" if require_files else "MANIFEST_INVALID", {}
+        ignored_now = _is_ignored(project, rel)
+        if item["ignored"] != ignored_now:
+            return "MANIFEST_INVALID", {}
+        validated[rel] = dict(item)
+    return None, validated
+
+
 def _validate_existing_manifest(
     project: Path,
     manifest: Any,
@@ -366,7 +496,12 @@ def record(
                     return _result(
                         False, action, "MANIFEST_INVALID", [], error=str(exc)
                     )
-                error, existing_files = _validate_existing_manifest(
+                validator = (
+                    _validate_existing_manifest_v2
+                    if isinstance(existing, dict) and existing.get("schemaVersion") == 2
+                    else _validate_existing_manifest
+                )
+                error, existing_files = validator(
                     project_root,
                     existing,
                     allow_hash_drift={rel for _, rel in validated},
@@ -375,25 +510,54 @@ def record(
                 if error:
                     return _result(False, action, error, [])
 
-            for path, rel in validated:
-                ignored = _is_ignored(project_root, rel)
-                tracked = _git(
-                    project_root, "ls-files", "--error-unmatch", "--", rel
-                ).returncode == 0
-                existing_files[rel] = {
-                    "path": rel,
-                    "sha256": _sha256(path),
-                    "reason": reason,
-                    "ignored": ignored,
-                    "trackedBefore": tracked,
+            if _contract_is_v2(change_root):
+                change_id = change_root.name
+                for path, rel in validated:
+                    ignored = _is_ignored(project_root, rel)
+                    previous = existing_files.get(rel, {})
+                    touched = [
+                        item for item in previous.get("touchedBy", [])
+                        if isinstance(item, str)
+                    ]
+                    if change_id not in touched:
+                        touched.append(change_id)
+                    digest = logical_file_hash(project_root, rel)
+                    existing_files[rel] = {
+                        "path": rel,
+                        "logicalHash": digest,
+                        "binaryHash": None if digest.startswith("gitblob:") else digest,
+                        "reason": reason,
+                        "ignored": ignored,
+                        "introducedBy": previous.get("introducedBy", change_id),
+                        "touchedBy": touched,
+                        "commitScope": "current-change",
+                    }
+                manifest = {
+                    "schemaVersion": 2,
+                    "repositoryId": harness_paths.repository_identity(project_root),
+                    "mode": MODE,
+                    "files": [existing_files[key] for key in sorted(existing_files)],
+                }
+            else:
+                for path, rel in validated:
+                    ignored = _is_ignored(project_root, rel)
+                    tracked = _git(
+                        project_root, "ls-files", "--error-unmatch", "--", rel
+                    ).returncode == 0
+                    existing_files[rel] = {
+                        "path": rel,
+                        "sha256": _sha256(path),
+                        "reason": reason,
+                        "ignored": ignored,
+                        "trackedBefore": tracked,
+                    }
+
+                manifest = {
+                    "schemaVersion": SCHEMA_VERSION,
+                    "mode": MODE,
+                    "projectRoot": str(project_root),
+                    "files": [existing_files[key] for key in sorted(existing_files)],
                 }
-
-            manifest = {
-                "schemaVersion": SCHEMA_VERSION,
-                "mode": MODE,
-                "projectRoot": str(project_root),
-                "files": [existing_files[key] for key in sorted(existing_files)],
-            }
             _write_json(manifest_path, manifest)
     except LockUnavailable:
         return _result(False, action, "MANIFEST_LOCKED", [])
@@ -412,12 +576,18 @@ def _stage_locked(
         return _result(False, action, "MANIFEST_MISSING", [])
     except (OSError, json.JSONDecodeError) as exc:
         return _result(False, action, "MANIFEST_INVALID", [], error=str(exc))
-    error, entries = _validate_existing_manifest(
-        project_root, manifest, require_files=True
-    )
+    is_v2 = isinstance(manifest, dict) and manifest.get("schemaVersion") == 2
+    validator = _validate_existing_manifest_v2 if is_v2 else _validate_existing_manifest
+    error, entries = validator(project_root, manifest, require_files=True)
     if error:
         return _result(False, action, error, [])
-    rels = list(entries)
+    rels = [
+        rel
+        for rel, entry in entries.items()
+        if not is_v2 or entry.get("commitScope") == "current-change"
+    ]
+    if not rels:
+        return _result(True, action, "STAGED", [])
 
     before_cached_result = _git(project_root, "diff", "--cached", "--name-only")
     if before_cached_result.returncode != 0:
@@ -467,15 +637,38 @@ def _stage_locked(
         temp_index.unlink(missing_ok=True)
 
 
-def _glob_files_for_pattern(base: Path, pattern: str) -> list[Path]:
-    normalized = pattern.replace("\\", "/")
-    if normalized.endswith("/**"):
-        prefix = normalized[:-3].rstrip("/")
-        root = base / prefix
-        if not root.is_dir():
-            return []
-        return [path for path in root.rglob("*") if path.is_file()]
-    return [path for path in base.glob(normalized) if path.is_file()]
+def _path_is_excluded(rel: str, excluded_roots: list[str]) -> bool:
+    rel_parts = tuple(os.path.normcase(part) for part in rel.split("/") if part)
+    for excluded in excluded_roots:
+        excluded_parts = tuple(
+            os.path.normcase(part) for part in excluded.split("/") if part
+        )
+        if excluded_parts and rel_parts[: len(excluded_parts)] == excluded_parts:
+            return True
+    return False
+
+
+def _walk_matching_files(
+    base: Path, patterns: list[str], excluded_roots: list[str]
+) -> list[Path]:
+    """Walk once and prune excluded roots before matching recursive globs."""
+    matches: list[Path] = []
+    for root_raw, dir_names, file_names in os.walk(base, followlinks=False):
+        root = Path(root_raw)
+        root_rel = root.relative_to(base).as_posix()
+        prefix = "" if root_rel == "." else root_rel + "/"
+        dir_names[:] = [
+            name
+            for name in dir_names
+            if not _path_is_excluded(prefix + name, excluded_roots)
+        ]
+        for name in file_names:
+            rel = prefix + name
+            if _path_is_excluded(rel, excluded_roots):
+                continue
+            if any(_matches_pattern(rel, pattern) for pattern in patterns):
+                matches.append(root / name)
+    return matches
 
 
 def _enumerate_allowed_test_files(project_root: Path) -> dict[str, str]:
@@ -484,20 +677,22 @@ def _enumerate_allowed_test_files(project_root: Path) -> dict[str, str]:
     config = _profile_config(project_root)
     if config is None:
         patterns = ["test/**", "tests/**", "src/test/**"]
+        excluded_roots = [
+            ".git", ".harness", "node_modules", "dist", "build", "__pycache__"
+        ]
     else:
-        patterns, _excluded = config
+        patterns, excluded_roots = config
     base = project_root.resolve()
     seen: set[str] = set()
-    for pattern in patterns:
-        for match in _glob_files_for_pattern(base, pattern):
-            resolved = match.resolve()
-            if not _inside(resolved, base):
-                continue
-            rel = resolved.relative_to(base).as_posix()
-            if rel in seen or not _allowed_test_path(project_root, rel):
-                continue
-            seen.add(rel)
-            found[rel] = _sha256(resolved)
+    for match in _walk_matching_files(base, patterns, excluded_roots):
+        resolved = match.resolve()
+        if not _inside(resolved, base):
+            continue
+        rel = resolved.relative_to(base).as_posix()
+        if rel in seen or not _allowed_test_path(project_root, rel):
+            continue
+        seen.add(rel)
+        found[rel] = _sha256(resolved)
     return found
 
 
@@ -510,7 +705,7 @@ def begin(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     manifest_path = _manifest_path(change_root)
     if manifest_path is None:
         return _result(False, action, "MANIFEST_PATH_OUTSIDE_PROJECT", [])
-    snapshot_path = change_root / SNAPSHOT_REL
+    snapshot_path = _state_root(change_root) / SNAPSHOT_REL
     if not _manifest_target_inside(change_root, snapshot_path):
         return _result(False, action, "SNAPSHOT_PATH_OUTSIDE_PROJECT", [])
 
@@ -542,7 +737,7 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
-    snapshot_path = change_root / SNAPSHOT_REL
+    snapshot_path = _state_root(change_root) / SNAPSHOT_REL
     if not snapshot_path.is_file():
         return _result(False, action, "SNAPSHOT_MISSING", [])
     try:

package/harness/bundles/java/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codebuddy",
-  "coreHash": "b4f114b99a359f4d"
+  "coreHash": "1bf389ebc64b017d"
 }

package/harness/bundles/java/codebuddy/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/java/codebuddy/harness-apidoc/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。使用场景：接口文档、前端接口文档、API 文档生成
 ---
-<!-- generated by harness_deploy.py; core=b4f114b99a359f4d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=1bf389ebc64b017d; overlay=java; agent=codebuddy; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=b4f114b99a359f4d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=1bf389ebc64b017d; overlay=java; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -86,8 +86,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/java/codebuddy/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/java/codebuddy/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/java/codebuddy/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/java/codebuddy/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=b4f114b99a359f4d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=1bf389ebc64b017d; overlay=java; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/java/codebuddy/harness-knowledge-ingest/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-ingest
 description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
   knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
 ---
-<!-- generated by harness_deploy.py; core=b4f114b99a359f4d; overlay=java; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=1bf389ebc64b017d; overlay=java; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -136,6 +136,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/java/codebuddy/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