@hunter-harness/workflow-harness 0.2.46 → 0.2.48

package/harness/bundles/general/codebuddy/scripts/harness_gate.py

@@ -124,6 +124,93 @@ def _read_json(path: Path) -> Any:
     return json.loads(path.read_text(encoding="utf-8-sig"))
 
 
+# ---------------------------------------------------------------------------
+# Gate severity tiering (P1 controllability)
+#
+# Hard invariants stay fail-closed in every mode:
+#   1. submit/merge identity & final-hash consistency (ledger/integration);
+#   2. archive integrity (manifest/minimal set, enforced in harness_archive);
+#   3. destructive-action protection (cleanup topology / protected paths).
+# The sites listed in SOFT_GATE_SITES guard regenerable bookkeeping
+# (plan-handoff projections, phase capsules, scenario coverage receipts,
+# test-guard tracking). In "lenient" mode a failure at one of those sites is
+# recorded as a WARN receipt (evidence/gate-warnings.ndjson) instead of
+# blocking the phase. Release phases (submit/merge/archive/release/deploy)
+# never downgrade.
+# ---------------------------------------------------------------------------
+
+GATE_RELEASE_PHASES = frozenset({"submit", "merge", "archive", "release", "deploy"})
+SOFT_GATE_SITES = frozenset({
+    "plan-handoff",
+    "capsule",
+    "scenario-coverage",
+    "test-guard",
+})
+GATE_WARNINGS_REL = Path("evidence") / "gate-warnings.ndjson"
+
+
+def gate_severity_mode(project: Path, change_dir: Path | None = None) -> str:
+    """Resolve gate severity mode: env > change gate-policy > project config.
+
+    Default is ``lenient`` (soft regenerable sites → WARN). Release phases and
+    the three hard invariants stay fail-closed; set ``HUNTER_HARNESS_GATE_MODE``
+    or ``gate-policy.json`` ``severityMode`` to ``strict`` to force fail-closed
+    soft sites as well.
+    """
+    env_mode = str(os.environ.get("HUNTER_HARNESS_GATE_MODE") or "").strip().lower()
+    if env_mode in {"strict", "lenient"}:
+        return env_mode
+    candidates: list[Path] = []
+    if change_dir is not None:
+        candidates.append(change_dir / "meta" / "gate-policy.json")
+    candidates.append(project / ".harness" / "config" / "gate-policy.json")
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            document = _read_json(path)
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(document, dict):
+            continue
+        value = str(document.get("severityMode") or "").strip().lower()
+        if value in {"strict", "lenient"}:
+            return value
+    return "lenient"
+
+
+def gate_soft_allowed(mode: str, phase: str, site: str) -> bool:
+    return (
+        mode == "lenient"
+        and phase not in GATE_RELEASE_PHASES
+        and site in SOFT_GATE_SITES
+    )
+
+
+def record_gate_warning(
+    change_dir: Path,
+    *,
+    phase: str,
+    site: str,
+    code: str,
+    message: str,
+) -> dict[str, Any]:
+    """Append a downgraded-gate receipt; the phase continues with WARN."""
+    entry = {
+        "ts": he.now_iso(),
+        "phase": phase,
+        "site": site,
+        "code": code,
+        "message": message,
+        "mode": "lenient",
+    }
+    path = change_dir / GATE_WARNINGS_REL
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8", newline="\n") as handle:
+        handle.write(json.dumps(entry, ensure_ascii=False, separators=(",", ":")) + "\n")
+    return entry
+
+
 def _write_json(path: Path, data: Any) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
@@ -1561,7 +1648,8 @@ def append_phase_event(
         he.atomic_append_line(events_file, line)
     rendered = False
     log_path = None
-    if type_ == "phase.end" or auto_sealed:
+    if (type_ == "phase.end" or auto_sealed) and \
+            he.execution_log_render_enabled(change_dir):
         events = he.load_events(events_file)
         content = he.render_execution_log(events)
         log_path = he.write_execution_log(change_dir, content)
@@ -1882,6 +1970,8 @@ def cmd_begin(args: argparse.Namespace) -> int:
             extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
         )
     change_dir = Path(resolved["changeDir"])
+    severity_mode = gate_severity_mode(project, change_dir)
+    gate_warnings: list[dict[str, Any]] = []
     plan_verification: dict[str, Any] | None = None
     if args.phase == "run":
         plan_verification = validate_plan_handoff(change_dir)
@@ -1894,16 +1984,25 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 or plan_verification.get("message")
                 or "finalized plan verification failed"
             )
-            return emit_error(
-                code,
-                message,
-                as_json=as_json,
-                extra={
-                    key: value
-                    for key, value in plan_verification.items()
-                    if key not in {"ok", "code", "error", "message"}
-                },
-            )
+            if gate_soft_allowed(severity_mode, args.phase, "plan-handoff"):
+                gate_warnings.append(record_gate_warning(
+                    change_dir,
+                    phase=args.phase,
+                    site="plan-handoff",
+                    code=code,
+                    message=message,
+                ))
+            else:
+                return emit_error(
+                    code,
+                    message,
+                    as_json=as_json,
+                    extra={
+                        key: value
+                        for key, value in plan_verification.items()
+                        if key not in {"ok", "code", "error", "message"}
+                    },
+                )
     concurrency_block = hc.check_concurrency_block(project, resolved["changeId"])
     if concurrency_block is not None:
         record_blocked_attempt(
@@ -1998,7 +2097,18 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 skills_root=Path(args.skills_root).expanduser(),
             )
         except ValueError as exc:
-            return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
+            if gate_soft_allowed(severity_mode, args.phase, "capsule"):
+                gate_warnings.append(record_gate_warning(
+                    change_dir,
+                    phase=args.phase,
+                    site="capsule",
+                    code="PHASE_CAPSULE_MISMATCH",
+                    message=str(exc),
+                ))
+                # Stale capsule is regenerable state: rebuild it below.
+                capsule = None
+            else:
+                return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
     claim = hc.claim_lease(
         project,
         change_id=resolved["changeId"],
@@ -2022,18 +2132,27 @@ def cmd_begin(args: argparse.Namespace) -> int:
             if args.phase in {"run", "test"}:
                 guard_result = htg.begin(execution_root, change_dir)
                 if not guard_result.get("ok"):
-                    hc.release_lease(
-                        project,
-                        change_id=resolved["changeId"],
-                        phase=args.phase,
-                        run_id=run_id,
-                    )
-                    return emit_error(
-                        str(guard_result.get("code", "TEST_GUARD_BEGIN_FAILED")),
-                        "test guard begin failed",
-                        as_json=as_json,
-                        extra=guard_result,
-                    )
+                    if gate_soft_allowed(severity_mode, args.phase, "test-guard"):
+                        gate_warnings.append(record_gate_warning(
+                            change_dir,
+                            phase=args.phase,
+                            site="test-guard",
+                            code=str(guard_result.get("code", "TEST_GUARD_BEGIN_FAILED")),
+                            message="test guard begin failed (downgraded to WARN)",
+                        ))
+                    else:
+                        hc.release_lease(
+                            project,
+                            change_id=resolved["changeId"],
+                            phase=args.phase,
+                            run_id=run_id,
+                        )
+                        return emit_error(
+                            str(guard_result.get("code", "TEST_GUARD_BEGIN_FAILED")),
+                            "test guard begin failed",
+                            as_json=as_json,
+                            extra=guard_result,
+                        )
             state_root = Path(hp.resolve_state_dir_for_contract(change_dir)).resolve()
             current_head = _git_text(execution_root, "rev-parse", "--verify", "HEAD")
             ledger, _ = hl.load_ledger(change_dir)
@@ -2091,6 +2210,8 @@ def cmd_begin(args: argparse.Namespace) -> int:
         "planVerification": plan_verification,
         "projection": projection,
         "executionRootSource": execution_hint["source"],
+        "gateSeverityMode": severity_mode,
+        "gateWarnings": gate_warnings,
     }
     emit(payload, as_json=as_json)
     return 0
@@ -2108,6 +2229,8 @@ def cmd_close(args: argparse.Namespace) -> int:
             extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
         )
     change_dir = Path(resolved["changeDir"])
+    severity_mode = gate_severity_mode(project, change_dir)
+    gate_warnings: list[dict[str, Any]] = []
     blocked = foundation_gate_blocks(getattr(args, "task", None), change_dir)
     if blocked:
         return emit_error(
@@ -2204,18 +2327,27 @@ def cmd_close(args: argparse.Namespace) -> int:
                 allow_head_advance=args.phase in {"run", "submit", "merge"},
             )
         except ValueError as exc:
-            persist_close_failure(
-                change_dir,
-                args.phase,
-                run_id,
-                capsule,
-                status="CAPSULE_VALIDATION_FAILED",
-                error={
-                    "code": "PHASE_CAPSULE_MISMATCH",
-                    "message": str(exc),
-                },
-            )
-            return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
+            if gate_soft_allowed(severity_mode, args.phase, "capsule"):
+                gate_warnings.append(record_gate_warning(
+                    change_dir,
+                    phase=args.phase,
+                    site="capsule",
+                    code="PHASE_CAPSULE_MISMATCH",
+                    message=str(exc),
+                ))
+            else:
+                persist_close_failure(
+                    change_dir,
+                    args.phase,
+                    run_id,
+                    capsule,
+                    status="CAPSULE_VALIDATION_FAILED",
+                    error={
+                        "code": "PHASE_CAPSULE_MISMATCH",
+                        "message": str(exc),
+                    },
+                )
+                return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
 
     projection = evaluate_projection_gate(project, args.phase)
     if not projection.get("ok"):
@@ -2294,20 +2426,29 @@ def cmd_close(args: argparse.Namespace) -> int:
     if args.phase in {"run", "test"}:
         coverage = _validate_scenario_coverage(change_dir)
         if not coverage.get("ok"):
-            persist_close_failure(
-                change_dir,
-                args.phase,
-                run_id,
-                capsule,
-                status="SCENARIO_VALIDATION_FAILED",
-                error=coverage,
-            )
-            return emit_error(
-                str(coverage.get("code", "SCENARIO_COVERAGE_FAILED")),
-                str(coverage.get("message", "scenario coverage validation failed")),
-                as_json=as_json,
-                extra={k: v for k, v in coverage.items() if k not in {"ok", "message", "code"}},
-            )
+            if gate_soft_allowed(severity_mode, args.phase, "scenario-coverage"):
+                gate_warnings.append(record_gate_warning(
+                    change_dir,
+                    phase=args.phase,
+                    site="scenario-coverage",
+                    code=str(coverage.get("code", "SCENARIO_COVERAGE_FAILED")),
+                    message=str(coverage.get("message", "scenario coverage validation failed")),
+                ))
+            else:
+                persist_close_failure(
+                    change_dir,
+                    args.phase,
+                    run_id,
+                    capsule,
+                    status="SCENARIO_VALIDATION_FAILED",
+                    error=coverage,
+                )
+                return emit_error(
+                    str(coverage.get("code", "SCENARIO_COVERAGE_FAILED")),
+                    str(coverage.get("message", "scenario coverage validation failed")),
+                    as_json=as_json,
+                    extra={k: v for k, v in coverage.items() if k not in {"ok", "message", "code"}},
+                )
 
     close_status = args.status
     close_code = "PHASE_CLOSED"
@@ -2316,6 +2457,12 @@ def cmd_close(args: argparse.Namespace) -> int:
         # Degraded close: phase.end status must not exceed WARN (OK → WARN).
         if close_status == "OK":
             close_status = "WARN"
+    if gate_warnings:
+        # Lenient-mode downgrades: phase closes, but never better than WARN.
+        if close_status == "OK":
+            close_status = "WARN"
+        if close_code == "PHASE_CLOSED":
+            close_code = "CLOSED_WITH_WARNINGS"
 
     close_transaction: dict[str, Any] = {}
     if capsule is not None:
@@ -2340,20 +2487,29 @@ def cmd_close(args: argparse.Namespace) -> int:
         else:
             guard_result = htg.close(execution_root, change_dir)
             if not guard_result.get("ok"):
-                if capsule is not None:
-                    close_transaction.update({
-                        "status": "GUARD_CLOSE_FAILED",
-                        "lastError": guard_result,
-                        "updatedAt": he.now_iso(),
-                    })
-                    write_phase_capsule(change_dir, args.phase, run_id, capsule)
-                return emit_error(
-                    str(guard_result.get("code", "TEST_GUARD_CLOSE_FAILED")),
-                    "test guard close failed",
-                    as_json=as_json,
-                    extra=guard_result,
-                )
-            if capsule is not None:
+                if gate_soft_allowed(severity_mode, args.phase, "test-guard"):
+                    gate_warnings.append(record_gate_warning(
+                        change_dir,
+                        phase=args.phase,
+                        site="test-guard",
+                        code=str(guard_result.get("code", "TEST_GUARD_CLOSE_FAILED")),
+                        message="test guard close failed (downgraded to WARN)",
+                    ))
+                else:
+                    if capsule is not None:
+                        close_transaction.update({
+                            "status": "GUARD_CLOSE_FAILED",
+                            "lastError": guard_result,
+                            "updatedAt": he.now_iso(),
+                        })
+                        write_phase_capsule(change_dir, args.phase, run_id, capsule)
+                    return emit_error(
+                        str(guard_result.get("code", "TEST_GUARD_CLOSE_FAILED")),
+                        "test guard close failed",
+                        as_json=as_json,
+                        extra=guard_result,
+                    )
+            if guard_result.get("ok") and capsule is not None:
                 close_transaction["guardClosed"] = True
                 close_transaction["updatedAt"] = he.now_iso()
                 write_phase_capsule(change_dir, args.phase, run_id, capsule)
@@ -2437,6 +2593,8 @@ def cmd_close(args: argparse.Namespace) -> int:
         "testGuard": guard_result,
         "event": event_result,
         "lease": release,
+        "gateSeverityMode": severity_mode,
+        "gateWarnings": gate_warnings,
     }
     emit(payload, as_json=as_json)
     return 0

package/harness/bundles/general/codebuddy/scripts/harness_headless.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Shared headless JSON envelope helpers for stage scripts (P5 contract)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def headless_envelope(
+    *,
+    command: str,
+    ok: bool,
+    exit_code: int,
+    change: str | None = None,
+    phase: str | None = None,
+    warnings: list[Any] | None = None,
+    errors: list[Any] | None = None,
+    result: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "ok": ok,
+        "command": command,
+        "change": change,
+        "phase": phase,
+        "exit_code": exit_code,
+        "warnings": warnings or [],
+        "errors": errors or [],
+        "result": result or {},
+    }
+
+
+def emit_headless(payload: dict[str, Any], *, stream=None) -> None:
+    out = stream or sys.stdout
+    print(json.dumps(payload, ensure_ascii=False, indent=2), file=out)

package/harness/bundles/general/codex/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codex",
-  "coreHash": "d8a2b0c8d6d3b3ae"
+  "coreHash": "45d6a7410e5db82b"
 }

package/harness/bundles/general/codex/README.md

@@ -221,17 +221,18 @@ harness-skills/
 |-------|----------|------|:--------:|:--------:|----------|
 | harness-sync | `/harness-sync` | 10 项元数据检查（7 核心 + 3 辅助） | 初始化检查 | ✅ | 控制台报告 + 自动更新 |
 | harness-codebase-map | `/harness-codebase-map` | 生成代码库地图（7 类文档 + summary + manifest） | `sync`/独立 | ✅ | `.harness/codebase/map/` |
-| harness-plan | `/harness-plan` | 需求→设计→任务拆分→**测试场景表** + 自动命名变更名 | `sync` | ✅ | `.harness/changes/<cn>/plans/` |
-| harness-run | `/harness-run` | TDD 循环 变更簇编码 | `plan` | ✅ | `.harness/changes/<cn>/sqls/` |
-| harness-test | `/harness-test` | 单元测试+接口测试+30条避坑 | `run` | ✅ | `.harness/changes/<cn>/reports/test/` |
-| harness-review | `/harness-review` | 6维度参考性审查（不阻塞后续流程） | `test` | ✅ | `.harness/changes/<cn>/reports/review/` |
-| harness-submit | `/harness-submit` 或 `/harness-merge`（别名） | commit+push（主目录）/ worktree：本地 commit→--no-ff 合并→push 主分支 | `review` | ✅ | ledger `mergeFinalHash` + 控制台报告 |
-| harness-archive | `/harness-archive` | 归档产出到 archive/YYYY-MM-DD-<cn>，释放工作区 | `submit` | ✅ | `.harness/archive/YYYY-MM-DD-<cn>/` |
+| harness-plan | `/harness-plan` | 需求→设计→任务拆分→**测试场景表** + 自动命名变更名 | `sync` | 手动 | `.harness/changes/<cn>/plans/` |
+| harness-run | `/harness-run` | TDD 循环 变更簇编码 | `plan` | 手动 | `.harness/changes/<cn>/sqls/` |
+| harness-test | `/harness-test` | 单元测试+接口测试+30条避坑 | `run` | 手动 | `.harness/changes/<cn>/reports/test/` |
+| harness-review | `/harness-review` | 6维度参考性审查（不阻塞后续流程） | `test` | 手动 | `.harness/changes/<cn>/reports/review/` |
+| harness-submit | `/harness-submit` 或 `/harness-merge`（别名） | commit+push（主目录）/ worktree：本地 commit→--no-ff 合并→push 主分支 | `review` | 手动 | ledger `mergeFinalHash` + 控制台报告 |
+| harness-archive | `/harness-archive` | 归档产出到 archive/YYYY-MM-DD-<cn>，释放工作区 | `submit` | 手动 | `.harness/archive/YYYY-MM-DD-<cn>/` |
 | harness-knowledge-query | `/harness-knowledge-query` | 查询 .harness/knowledge 历史上下文，生成需求 context pack | `sync`/独立 | ✅ | `.harness/knowledge/context-packs/` |
 | harness-knowledge-ingest | `/harness-knowledge-ingest` | 从 archive 整理/同步/维护知识索引（promote/demote/audit） | `archive` | ✅ | `.harness/knowledge/index.json` |
 
-> 所有 harness skill 均支持被其他 skill 调用。`harness-run`、`harness-submit`、`harness-archive` 涉及 git 写操作、文件移动或归档，被其他 skill 调用时必须确保前置条件已满足。
+> 生命周期 skill（plan → run → test → review → submit → archive）为**手动触发**：单阶段结束后停止，不自动接续下一阶段（已设 `disable-model-invocation`）。sync / codebase-map / knowledge 等辅助 skill 仍可按需被调用。`harness-run`、`harness-submit`、`harness-archive` 涉及 git 写操作、文件移动或归档，调用前必须确保前置条件已满足。
 > `<cn>` = change-name，由 harness-plan 阶段7确定。其他 skill 自动扫描未归档变更定位。
+> 门禁默认 `gate_severity_mode=lenient`（可再生 soft site → WARN）；发布阶段与 3 类硬不变量仍 fail-closed。可用 `HUNTER_HARNESS_GATE_MODE` 或 `gate-policy.json` 的 `severityMode` 强制 `strict`。
 
 ## 关键合规约束（强制）
 
@@ -279,7 +280,7 @@ harness-skills/
 | **submit hash 记录** | pre-pull local hash + final pushed hash 双标注（主目录）；worktree 模式 submit 段只本地 commit，合并段产生 `mergeFinalHash`，archive 以 `mergeFinalHash` 为准（无则回退 final pushed hash） |
 | **archive 阶段 1** | 归档前确认 commit 已 push、hash 与 submit/merge 记录一致、test/review 报告状态；阶段边界由 finalize 单进程维护，调用者不额外 append |
 | **archive 文件移动** | 只用 PowerShell 或 Read+Write+验证，**禁止 Bash mv/cp/rm**；移动失败时不删除原目录 |
-| **archive final-summary.html** | 默认运行 `harness_archive.py finalize`：由 events/ledger/log/manifest 生成 `summary-data.json`，再由 `templates/render-summary.mjs` 渲染 `final-summary.html`，内嵌 validate。无测试或无 review 时必须在 JSON 中标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。必须真实展示状态演进（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
+| **archive final-summary** | 必须运行 `harness_archive.py finalize` 生成权威 `summary-data.json` 并完成 validate；`final-summary.html` 为可选展示投影（默认渲染，失败只记 warning 不回滚；`finalize --no-html` 可跳过）。无测试或无 review 时必须在 JSON 中标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。状态演进须真实展示（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
 
 ### 敏感信息脱敏
 

package/harness/bundles/general/codex/harness-archive/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: harness-archive
-description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
-  .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
+description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
+  /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=d8a2b0c8d6d3b3ae; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=45d6a7410e5db82b; overlay=none; agent=codex; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -12,11 +12,9 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ## When to Use
 
-使用场景：
+仅当用户显式调用 `/harness-archive` 时执行。submit/merge 完成后**不自动**进入本阶段；用户口头说"归档/收尾"而未调用本 skill 时，先确认。
 
-- 用户说"归档 / 完成归档 / 收尾 / 打包产出物"。
-- submit 已推送、test/review 报告已就绪（或已明确标记跳过/未运行），需要封存变更产出。
-- 变更闭环最后一站，归档后从工作区移除 `.harness/changes/<change-name>/`。
+前置：submit 已推送、test/review 报告已就绪（或已明确标记跳过/未运行）。变更闭环最后一站，归档后从工作区移除 `.harness/changes/<change-name>/`。
 
 跳过场景：
 
@@ -25,8 +23,8 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 自动调用边界：
 
-- 归档涉及移动/删除原变更目录，支持被其他 skill 调用，但调用前必须确保前置条件已满足；也支持用户显式 `/harness-archive` 调用。
-- 默认归档前确认是阻断检查点。若 `harness_archive.py auto-gate` 返回 `ARCHIVE_AUTO_GATE_SATISFIED`（Submit 或 Merge 已终态，archive-boundary snapshot 存在且全部归档门禁满足），后续 Archive 可无 AskQuestion 自动运行；其他情况仍须确认。
+- 归档涉及移动/删除原变更目录，**禁止被其他 skill 自动调用**；只接受用户显式 `/harness-archive` 调用。
+- `harness_archive.py auto-gate` 只影响**本次显式调用内**是否需要归档确认对话：返回 `ARCHIVE_AUTO_GATE_SATISFIED`（Submit 或 Merge 已终态，archive-boundary snapshot 存在且全部归档门禁满足）时可跳过 AskQuestion 直接归档；其他情况仍须确认。auto-gate 不构成跨阶段自动触发的授权。
 
 ## 前置条件
 
@@ -139,7 +137,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ### 四、数据化归档门禁（先数据后渲染）
 
-必须通过 `harness_archive.py finalize` 生成 `reports/final/summary-data.json` 与 `final-summary.html` 并完成 validate；**禁止模型临场写 500+ 行 HTML**。统计数字只能来自 summary-data、events、ledger 或 manifest。详见 `../protocols/report-pipeline-protocol.md`、`../protocols/archive-report-protocol.md`、`reference.md`。
+必须通过 `harness_archive.py finalize` 生成权威 `reports/final/summary-data.json` 并完成 validate；`final-summary.html` 为可选展示投影（默认渲染；渲染失败只记 warning、不回滚归档；`finalize --no-html` 可完全跳过本地 HTML）。**禁止模型临场写 500+ 行 HTML**。统计数字只能来自 summary-data、events、ledger 或 manifest。详见 `../protocols/report-pipeline-protocol.md`、`../protocols/archive-report-protocol.md`、`reference.md`。
 
 ### 五、manifest/checksum 必须存在
 
@@ -160,7 +158,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 无测试报告 → 显示"未运行测试 / 静态验证"，不得 100% 通过率；无 review → "📝ADVISORY：未运行 review"。状态用 ✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP，复用前一阶段结果显示 🔁REUSED，**不得伪装成重新执行，不得无脑全绿**。
 
-**final-summary 必须产出**：Node 渲染器不可用/超时/exit 非 0/未产出文件时，`harness_archive.py` 自动用内置 Python fallback 渲染（含 changeName/finalStatus/commands/verification/changedFiles/archiveManifest/knownRisks/manualActions/maintenanceNotes，USER_SKIPPED/BLOCKED_BY_DBA/失败状态可见，全部 HTML 转义）。Node 与 Python fallback **都失败**时，finalize 立即恢复原 change 目录并 exit 非 0，**绝不归档一个没有 final-summary.html 的变更**。
+**final-summary 是可再生展示投影，非硬产物**：`summary-data.json` 是最终报告的唯一权威数据源，必须产出并通过 validate/adequacy。HTML 渲染默认执行（Node 渲染器失败时自动 Python fallback），但渲染失败只记 warning，**不再回滚归档**；`finalize --no-html` 可完全跳过本地 HTML（配置远端平台时由平台按 summary-data.json 渲染）。
 
 ### 九、CONDITIONAL_OK 最终状态
 
@@ -191,7 +189,7 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 - `.harness/archive/YYYY-MM-DD-<change-name>/meta/archive-meta.md` — 归档元数据
 - `.harness/archive/YYYY-MM-DD-<change-name>/events.ndjson` — 结构化事件层（新流程推荐；旧 archive 可缺失）
 - `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/summary-data.json` — 最终报告数据源
-- `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/final-summary.html` — 由 `render-summary.mjs` 渲染（Node 不可用或失败时由 `harness_archive.py` 内置 Python fallback 渲染）；**始终必须存在**，否则 finalize 恢复原 change 目录并 exit 非 0
+- `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/final-summary.html` — 可选展示投影，由 `render-summary.mjs` 渲染（Node 失败时 Python fallback）；渲染失败降级 warning，`--no-html` 可跳过
 - `.harness/archive/YYYY-MM-DD-<change-name>/evidence/archive-manifest-before.json` / `archive-manifest-after.json` — 归档前后 manifest/checksum
 
 ## 渐进披露

package/harness/bundles/general/codex/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=d8a2b0c8d6d3b3ae; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=45d6a7410e5db82b; overlay=none; agent=codex; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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