@hunter-harness/workflow-harness 0.2.59 → 0.2.61

package/harness/bundles/general/cursor/scripts/harness_context.py

@@ -810,10 +810,15 @@ def close_transition(
     artifact_entries: list[dict[str, Any]] = []
     for raw in artifacts or []:
         requested = Path(raw)
+        artifact_bases: list[Path] = []
+        for base in (project, contract_root, state_root):
+            resolved_base = base.resolve()
+            if resolved_base not in artifact_bases:
+                artifact_bases.append(resolved_base)
         candidates = (
             [requested]
             if requested.is_absolute()
-            else [project / requested, contract_root / requested]
+            else [base / requested for base in artifact_bases]
         )
         valid: list[Path] = []
         for candidate in candidates:
@@ -838,10 +843,11 @@ def close_transition(
                 "ok": False,
                 "code": "TRANSITION_ARTIFACT_INVALID",
                 "path": raw,
-                "acceptedBases": [str(project), str(contract_root)],
+                "acceptedBases": [str(base) for base in artifact_bases],
                 "examples": [
                     str(contract_root / "meta" / "plan-finalization.json"),
                     f".harness/changes/{change}/meta/plan-finalization.json",
+                    f".harness/state/changes/{change}/evidence/verification-ledger.json",
                     "meta/plan-finalization.json",
                 ],
             }

package/harness/bundles/general/cursor/scripts/harness_events.py

@@ -1077,6 +1077,11 @@ def split_phase_attempts(phase_events: list[dict[str, Any]]) -> list[dict[str, A
         "external.wait",
         "issue",
         "ci.wait",
+        # Preparation is intentionally outside the formal phase lifecycle.
+        # A blocked preflight must remain visible in the raw timeline without
+        # manufacturing an attempt or inflating the phase duration/count.
+        "phase.prepare.start",
+        "phase.prepare.end",
     }
     for event in phase_events:
         if event.get("type") == "phase.start":

package/harness/bundles/general/cursor/scripts/harness_ledger.py

@@ -1053,6 +1053,40 @@ def ledger_evidence_identity(ledger: dict[str, Any]) -> str:
     return "sha256:" + hashlib.sha256(canonical).hexdigest()
 
 
+def _immutable_change_base(
+    change_dir: Path,
+    project_root: Path,
+) -> str:
+    roots = [change_dir]
+    try:
+        state_root = harness_paths.resolve_state_dir_for_contract(
+            change_dir,
+            project_root,
+        )
+        if state_root.resolve() != change_dir.resolve():
+            roots.insert(0, state_root)
+    except (OSError, ValueError):
+        pass
+    for root in roots:
+        for relative in (
+            Path("meta") / "state-snapshot.json",
+            Path("state-snapshot.json"),
+        ):
+            path = root / relative
+            if not path.is_file():
+                continue
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8-sig"))
+            except (OSError, json.JSONDecodeError, TypeError):
+                continue
+            if not isinstance(payload, dict):
+                continue
+            value = str(payload.get("changeBase") or "").strip()
+            if value:
+                return value
+    return ""
+
+
 def migrate_ledger_for_write(
     change_dir: Path,
     ledger: dict[str, Any],
@@ -1089,6 +1123,15 @@ def migrate_ledger_for_write(
     if not _nonempty_str(resolved_base):
         resolved_base = ledger.get("baseCommit")
     if not _nonempty_str(resolved_base):
+        resolved_base = _immutable_change_base(change_dir, repo_root)
+    if not _nonempty_str(resolved_base):
+        if record_migration:
+            raise LedgerMigrationError(
+                "immutable change base is missing; recapture the Plan boundary "
+                "or pass an explicit --base-commit instead of using write-time HEAD"
+            )
+        # A genuinely new ledger establishes its identity at the first write.
+        # Existing ledgers are handled above and may never take this fallback.
         resolved_base = current_head
     resolved_diff = diff_hash
     if not _nonempty_str(resolved_diff):
@@ -2795,9 +2838,43 @@ def cmd_diff_hash(args: argparse.Namespace) -> int:
     repo_raw = getattr(args, "repo", None)
     repo = Path(repo_raw).expanduser().resolve() if repo_raw else Path.cwd().resolve()
     base = getattr(args, "base", None)
-    change_dir = getattr(args, "change_dir", None)
+    change_dir_raw = getattr(args, "change_dir", None)
     try:
-        diff_hash, meta = compute_diff_hash(repo, base=base, change_dir=change_dir)
+        change_dir = resolve_path(change_dir_raw) if change_dir_raw else None
+        if change_dir is not None and _contract_is_v2(change_dir):
+            resolved_base = str(base or "").strip()
+            if not resolved_base:
+                existing, _ = load_ledger(change_dir)
+                if isinstance(existing, dict):
+                    resolved_base = str(existing.get("baseCommit") or "").strip()
+            if not resolved_base:
+                resolved_base = _immutable_change_base(change_dir, repo)
+            if not resolved_base:
+                raise ValueError(
+                    "immutable change base is missing; capture the Plan boundary "
+                    "or pass --base"
+                )
+            detail = compute_ownership_diff(
+                repo,
+                base=resolved_base,
+                change_dir=change_dir,
+            )
+            payload = {
+                "ok": True,
+                "action": "diff-hash",
+                "identityScope": "change-ownership",
+                "algorithmVersion": "ownership-content-changeset-1",
+                "base": resolved_base,
+                "head": _git_text(repo, "rev-parse", "--verify", "HEAD"),
+                **detail,
+            }
+            emit_json(payload, as_json=as_json)
+            return 0
+        diff_hash, meta = compute_diff_hash(
+            repo,
+            base=base,
+            change_dir=str(change_dir) if change_dir is not None else None,
+        )
     except (OSError, RuntimeError, ValueError) as exc:
         return emit_error(str(exc), as_json=as_json)
     payload = {"ok": True, "action": "diff-hash", "diffHash": diff_hash}

package/harness/bundles/general/cursor/scripts/harness_profile.py

@@ -838,13 +838,20 @@ def _node_commands(project: Path) -> dict[str, Any]:
         "src/**/*.tsx",
         "test/**/*.ts",
         "test/**/*.tsx",
+        "tests/**/*.ts",
+        "tests/**/*.tsx",
         "packages/*/src/**/*.ts",
         "packages/*/src/**/*.tsx",
         "packages/*/test/**/*.ts",
         "packages/*/test/**/*.tsx",
+        "packages/*/tests/**/*.ts",
+        "packages/*/tests/**/*.tsx",
         "apps/*/src/**/*.ts",
         "apps/*/src/**/*.tsx",
         "apps/*/test/**/*.ts",
+        "apps/*/test/**/*.tsx",
+        "apps/*/tests/**/*.ts",
+        "apps/*/tests/**/*.tsx",
     ]
     # harness dogfood: canonical Python + .mjs sources feed npm run check (vitest
     # imports harness-test/scripts; smoke:pack runs sync-harness.mjs).

package/harness/bundles/general/cursor/scripts/harness_state.py

@@ -119,6 +119,10 @@ def capture_snapshot(
         "schemaVersion": SNAPSHOT_SCHEMA_VERSION,
         "generatedAt": now_iso(),
         "changeName": change_name,
+        # The first captured Git boundary is the immutable identity of the
+        # change.  Later phases may advance HEAD, but must never silently move
+        # the base and collapse the archive range.
+        "changeBase": base or "",
         "project": {"root": str(project.resolve())},
         "worktree": {"root": str(Path(worktree_root).resolve())},
         "git": {"base": base or "", "head": head or ""},
@@ -250,10 +254,25 @@ def capture_current_state(
     base: str = "",
     head: str = "HEAD",
 ) -> tuple[dict[str, Any], list[str]]:
-    resolved_head = _git(project, "rev-parse", head) or head
-    resolved_base = _git(project, "rev-parse", base) if base else ""
-    files = discover_segment_files(project, change_dir, base=resolved_base, head=resolved_head)
+    git_head = _git(project, "rev-parse", head)
+    resolved_head = git_head or head
     previous = load_snapshot(change_dir)
+    previous_git = previous.get("git") if isinstance(previous, dict) else None
+    previous_base = (
+        str(previous.get("changeBase") or "").strip()
+        if isinstance(previous, dict)
+        else ""
+    )
+    if not previous_base and isinstance(previous_git, dict):
+        previous_base = str(
+            previous_git.get("base") or previous_git.get("baseCommit") or ""
+        ).strip()
+    requested_base = _git(project, "rev-parse", base) if base else ""
+    # First capture establishes the boundary.  A later --base value is an
+    # observation hint only; changing the boundary requires the explicit
+    # archive range-adoption receipt.
+    resolved_base = previous_base or requested_base or git_head
+    files = discover_segment_files(project, change_dir, base=resolved_base, head=resolved_head)
     fresh = capture_snapshot(
         change_dir,
         change_name=change_name,

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "claude-code",
-  "coreHash": "4045fc0e7244d3e6"
+  "coreHash": "c4b98f515e0ec1ae"
 }

package/harness/bundles/java/claude-code/README.md

@@ -23,18 +23,18 @@
 
 ## 共用规则文件（强制约束）
 
-跨 skill 共用的强制约束规则全部集中在 `protocols/` 下（8 个 protocol；其中 report pipeline 用于结构化事件、summary-data 生成和 final-summary 校验），各 skill 通过相对路径引用：
+跨 skill 共用的强制约束规则全部集中在 `protocols/` 下（8 个 protocol；其中 report pipeline 用于结构化事件，以及 summary-data 的生成与校验），各 skill 通过相对路径引用：
 
 | 文件 | 作用 |
 |------|------|
 | `protocols/powershell-protocol.md` | Shell 执行安全策略：Windows/中文路径下禁止普通 Bash，所有 git/构建命令必须通过 `powershell.exe -Command "..."` 执行；命令被拒绝时不得回退普通 Bash；所有"成功"必须有明确证据（构建成功 / git 输出 / 文件存在 / exit code 0） |
-| `protocols/sensitive-info-protocol.md` | 敏感信息脱敏：token、密码、Authorization header、Cookie、API key、access/secret key 不得明文出现在 execution-log、报告、commit message、final-summary 中；引用时统一替换为 `<TOKEN_REDACTED>` / `<PASSWORD_REDACTED>` / `<SECRET_REDACTED>` |
+| `protocols/sensitive-info-protocol.md` | 敏感信息脱敏：token、密码、Authorization header、Cookie、API key、access/secret key 不得明文出现在 execution-log、报告、commit message、summary-data 中；引用时统一替换为 `<TOKEN_REDACTED>` / `<PASSWORD_REDACTED>` / `<SECRET_REDACTED>` |
 | `protocols/evidence-based-reporting-protocol.md` | 证据化报告：所有 skill 输出必须区分 ✅ 真实成功 / 🟡 静态验证或用户跳过 / ❌ 失败或被拒绝；禁止把"静态验证"写成"测试通过"，禁止把"命令被拒绝"写成"成功" |
 | `protocols/ledger-protocol.md` | 验证账本：每个变更目录维护 `verification-ledger.json`，记录 compile/unitTest/apiTest 的结果+证据+diffHash+作用范围；后续阶段先读 ledger 判定是否可复用，避免跨阶段重复编译/测试；post-test 变更按 7 类分类，决定是否重跑 |
 | `protocols/state-layout-protocol.md` | 状态目录分层：`.harness/changes/<cn>/` 下按 `meta/`、`logs/`、`evidence/`、`reports/`、`scripts/`、`backups/` 子目录分层写入；读取时先读新路径再兼容旧路径 |
 | `protocols/submit-protocol.md` | 固定提交交互：提交方式与 commit message 确认使用固定选项模板，禁止 AI footer |
-| `protocols/archive-report-protocol.md` | 归档报告：`summary-data.json` + 模板渲染 `final-summary.html`，含 manifest/checksum 真实性规则 |
-| `protocols/report-pipeline-protocol.md` | 报告流水线：`events.ndjson` + `harness_archive.py finalize/replay` + final-summary 一致性校验 |
+| `protocols/archive-report-protocol.md` | 归档报告：`summary-data.json`、manifest/checksum 与真实性规则 |
+| `protocols/report-pipeline-protocol.md` | 报告流水线：`events.ndjson` + `harness_archive.py execute/replay` + 数据一致性校验 |
 
 每个 skill 的 SKILL.md 关键规则章节都通过相对路径引用这些 protocol（`../protocols/powershell-protocol.md` 等）。
 
@@ -85,8 +85,7 @@
 │       │   ├── test/
 │       │   ├── review/
 │       │   └── final/
-│       │           ├── summary-data.json
-│       │           └── final-summary.html  # 最终报告（代码量+产出清单+测试/审查摘要）
+│       │           └── summary-data.json   # 平台展示使用的最终报告数据
 │       ├── events.ndjson                   # 结构化事件层（新流程推荐；历史 archive 可缺失）
 │       └── backups/
 ├── <change-name>/                   # 当前未归档变更（最多 1 个，不提交）
@@ -160,9 +159,9 @@
 - **Bash 拒绝、PowerShell 重试、降级、跳过、用户确认都必须记录**
 - 日志状态统一使用 `✅OK / 🟡WARN(原因) / ❌FAIL(原因)`
 - harness-archive 归档时从日志汇总：时间线、总用时、Skill 调用统计
-- `harness_archive.py finalize/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
+- `harness_archive.py execute/replay` 优先从 `events.ndjson` 汇总命令、验证、artifact、问题和决策；旧 archive 缺少 events 时才回放 execution-log/ledger/manifest
 - sync 默认不关联具体变更目录，仅在已有变更目录时追加日志和 events
-- archive 是例外：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加阶段边界
+- archive 是例外：`execute` 负责一次准备记录和一次正式 `phase.start` / `phase.end`，调用者不得重复追加阶段边界，也不得串行运行 `auto-gate`、`status`、`finalize`
 
 ## Skill 目录结构
 
@@ -211,8 +210,7 @@ harness-skills/
     ├── checklist.md            # 归档前后检查项
     ├── reference.md            # 归档操作 + 占位符真实性规则
     └── templates/
-        ├── summary-data-template.json  # final-summary 数据结构
-        └── render-summary.mjs          # final-summary UTF-8 固定渲染脚本
+        └── summary-data-template.json  # 最终报告数据结构
 ```
 
 ## Skill 列表
@@ -280,11 +278,11 @@ harness-skills/
 | **submit hash 记录** | pre-pull local hash + final pushed hash 双标注（主目录）；worktree 模式 submit 段只本地 commit，合并段产生 `mergeFinalHash`，archive 以 `mergeFinalHash` 为准（无则回退 final pushed hash） |
 | **archive 阶段 1** | 归档前确认实际计划阶段的证据与结局；有 Git 时核对最终提交身份，无 Git、无 upstream 或跳过 submit 时使用内容清单身份。发布候选资格与本地封存分开判断；阶段边界由 finalize 单进程维护，调用者不额外 append |
 | **archive 文件移动** | 只用 PowerShell 或 Read+Write+验证，**禁止 Bash mv/cp/rm**；移动失败时不删除原目录 |
-| **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） |
+| **archive 最终报告** | 必须运行 `harness_archive.py execute`，由内部 finalize 生成权威 `summary-data.json` 并完成 validate。平台直接读取该 JSON；本地不生成重复的 HTML 报告。无测试或无 review 时必须标记 `NOT_RUN` / `ADVISORY_NOT_RUN`，禁止伪造 100% 通过率。状态演进须真实展示（✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP） |
 
 ### 敏感信息脱敏
 
-- token / Authorization / Cookie / Redis 密码 / 数据库密码 / API key / access&secret key 不得明文出现在 execution-log、报告、commit message、final-summary 中
+- token / Authorization / Cookie / Redis 密码 / 数据库密码 / API key / access&secret key 不得明文出现在 execution-log、报告、commit message、summary-data 中
 - 引用敏感值时统一使用占位符：`<TOKEN_REDACTED>` / `<PASSWORD_REDACTED>` / `<SECRET_REDACTED>` / `<API_KEY_REDACTED>` / `<AUTH_HEADER_REDACTED>` / `<COOKIE_REDACTED>`
 - 命令示例使用占位符，不复述真实值
 - 测试中临时使用的 token 在持久化测试报告中必须替换为占位符
@@ -426,7 +424,7 @@ npx hunter-harness   # 初始化阶段检查环境/CodeGraph/基础状态（非
 /harness-test         # 运行测试（30条避坑规则）
 /harness-review       # 代码审查
 /harness-submit       # 提交代码（worktree 模式含合并；/harness-merge 为别名）
-/harness-archive      # 归档产出（harness_archive.py finalize），释放工作区
+/harness-archive      # 归档产出（harness_archive.py execute），释放工作区
 ```
 
 ## 避坑知识来源
@@ -455,8 +453,8 @@ npx hunter-harness   # 初始化阶段检查环境/CodeGraph/基础状态（非
 - `protocols/sensitive-info-protocol.md`：敏感信息脱敏（token/密码/密钥占位符化，已取代原 `harness-plan/sensitive-info.md`，各 skill 引用此版本）。
 - `protocols/evidence-based-reporting-protocol.md`：证据化报告（✅/🟡/❌ 三态，已取代原 `harness-plan/evidence-based-reporting.md`，各 skill 引用此版本）。
 - `protocols/submit-protocol.md`：固定提交交互、中文 commit 文件、禁止 AI footer。
-- `protocols/archive-report-protocol.md`：summary-data + template 渲染 final-summary、manifest/checksum。
-- `protocols/report-pipeline-protocol.md`：events.ndjson + `harness_archive.py finalize/replay` + final-summary 一致性校验。
+- `protocols/archive-report-protocol.md`：summary-data、manifest/checksum 与平台归档展示合同。
+- `protocols/report-pipeline-protocol.md`：events.ndjson + `harness_archive.py execute/replay` + summary-data 一致性校验。
 - `protocols/state-layout-protocol.md`：`.harness/changes/<cn>/` 子目录分层（meta/logs/evidence/reports/scripts/backups），读取先新后旧。
 
 各 skill 的 `SKILL.md` 只保留阶段目标和硬门禁，细节优先引用这些协议，避免在多个 skill 中复制并产生冲突。
@@ -477,4 +475,4 @@ backups/    未提交但用于验证的测试文件等备份
 
 读取时先读新路径，再兼容旧路径。详见 `protocols/state-layout-protocol.md`。
 
-Archive 最终报告默认运行 `harness_archive.py finalize`，再使用 `harness-archive/templates/render-summary.mjs` 从 `summary-data.json` 渲染，避免 PowerShell 中文乱码、模型长 HTML 生成中断和日志汇总统计漂移。
+Archive 常规入口为 `harness_archive.py execute`，内部 finalize 生成 `summary-data.json`。Hunter Platform 直接读取该文件，避免本地重复渲染和两份报告数据不一致。

package/harness/bundles/java/claude-code/harness-apidoc/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=4045fc0e7244d3e6; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=claude-code; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose
@@ -43,7 +43,7 @@ disallowed-tools:
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol

package/harness/bundles/java/claude-code/harness-archive/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=4045fc0e7244d3e6; overlay=java; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=c4b98f515e0ec1ae; overlay=java; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -47,7 +47,7 @@ disallowed-tools:
 - **产品候选验证**：
   - 有远端 CI：保留 `product-candidate-ci.json` 兼容证据；归档会把有效的 legacy schema v1 证据迁移为 `remote-claimed` 的 schema v2 `product-candidate-verification.json`，不会冒充 `remote-attested`。
   - `remote-attested` 必须同时带远端运行 URL 与 `verification.attestationDigest`；只有 URL、旧 JSON 哈希或 ledger 哈希只能达到 `remote-claimed`。
-  - 无 CI：先运行 `harness_archive.py certify-local --change-dir ... --project . --json`，只复用身份一致且完整的 `unitTestFull` ledger 证据，不重复执行测试。
+  - 无 CI：`execute` 在候选收据缺失时自动尝试本地认证，只复用身份一致且完整的 `unitTestFull` ledger 证据，并在产品内容未变化时把提交前验证安全重绑定到当前 HEAD；认证不会执行测试。只有需要单独诊断认证结果时才手工运行 `certify-local`。
   - `release-candidate` 要求候选验证通过；正常本地完成或结束未完成变更使用 `--intent record-only`，固定 `releaseEligible=false`，但仍生成 ZIP 并上传平台。
 
 ## Inputs
@@ -64,62 +64,60 @@ disallowed-tools:
 6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
 7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
 8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --base <baseCommit> --json`；`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
+9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
 
 状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
 > 片段：read-protocol
 
 ## Workflow
 
-先用 `harness_change.py resolve [--change] --json` 解析 change；多个 active change 未显式选择时返回 `CHANGE_SELECTION_REQUIRED`，禁止按 Glob/mtime 自动选择。`harness_archive.py finalize` 内部负责且仅负责一次 `harness_gate.py begin` 与 `harness_gate.py close`。调用者禁止重复调用阶段门禁，避免重复事件和幽灵 change 目录。
+先用 `harness_change.py resolve [--change] --json` 解析 change；多个 active change 未显式选择时返回 `CHANGE_SELECTION_REQUIRED`，禁止按 Glob/mtime 自动选择。常规路径只运行一次 `harness_archive.py execute`。该命令一次性完成状态采集、自动门禁和 finalize，并复用同一份预检结果。调用者不得再串行运行 `auto-gate`、`status` 和 `finalize`，避免重复扫描、重复事件和幽灵 change 目录。
 
 ### Phase 0：读取规则和上下文
 
 1. 读取本文件。
-2. 按需读取 `reference.md`（归档流程、manifest、summary-data、final-summary 渲染、目录结构与最终状态规则）。
-3. 读取共用约束：
-   - `../protocols/archive-report-protocol.md`
-   - `../protocols/state-layout-protocol.md`
-   - `../protocols/powershell-protocol.md`
-   - `../protocols/sensitive-info-protocol.md`
-   - `../protocols/evidence-based-reporting-protocol.md`
-   - `../protocols/report-pipeline-protocol.md`
-4. 用 `harness_change.py resolve [--change] --json` 解析 `$ARGUMENTS`；多个 active change 时让用户选择。
+2. 用 `harness_change.py resolve [--change] --json` 解析 `$ARGUMENTS`；多个 active change 时让用户选择。
+3. 按共享读取协议刷新一次状态快照。首次 Plan 已记录的 `changeBase` 必须保持不变，归档阶段不得把当前 HEAD 写回为基线。
+4. 常规路径不预读全部参考资料。仅在 `execute` 返回阻断或需要解释结果时，读取 `reference.md` 和对应协议章节。
 
 ### Phase 1：确认归档对象（扫描未归档变更）
 
-使用 resolver 返回的 active changes 展示变更概要；同时读取 `plannedPhases`、已完成阶段、Git 能力、平台连接和待上传 ZIP 状态。
+使用 resolver 返回的 active changes 展示变更概要；同时读取 `plannedPhases`、已完成阶段和用户表达的生命周期结局。Git remote 与平台连接不是归档前置条件，不在这里额外探测。
 
-- **Read `checklist.md`** — 归档前检查项
 - 发现多个未归档变更 → 让用户选择或终止
 
-### Phase 2：确认归档 / 自动门禁
+### Phase 2：确定归档结局
 
-先运行 `harness_archive.py auto-gate --change-dir "<executionRoot>" --intent <intent> --json`。
+根据用户当前指令确定一次归档结局：
 
-- `autoArchiveAllowed=true`：记录 gate receipt，直接进入 Phase 3；无需 AskQuestion。
-- 否则用中文提供：①正常完成并归档（本地验证、不可发布）；②作为发布候选归档；③结束未完成变更；④取消。选择③后继续选择“主动废弃”或“被其他方案替代”，并填写中文原因。不要把无 upstream 显示为阻止保存。
+- 明确要求发布候选：`--intent release-candidate --closure completed`。
+- 正常完成但不要求发布：`--intent record-only --closure completed`。
+- 主动停止或被其他方案替代：`--intent record-only --closure abandoned|superseded --closure-reason "<中文原因>"`。
 
-- **Read `reference.md`** — 确认对话框的内容格式
+信息已经明确时，不重复询问。信息不足且会改变结局时，才用中文提供「正常完成」「发布候选」「主动废弃」「被其他方案替代」「取消」。无 upstream 不阻止保存。
 
 ### Phase 3：执行归档
 
-1. 对“发布候选”使用 `--intent release-candidate --closure completed`；对正常本地完成使用 `--intent record-only --closure completed`；主动废弃或被替代分别使用 `--intent record-only --closure abandoned|superseded --closure-reason "<中文原因>"`。先运行 `status`；有可复用全量 ledger 时可运行 `certify-local`，不得重复测试。
-2. `meta/archive-meta.md` **由 `harness_archive.py finalize` 自动生成**（与 summary-data `finalStatus` 同源）；**禁止 agent 手写**该文件，手写视为数据丢失。维护者结论写入 events（decision/issue）即可，finalize 会汇总到 summary / archive-meta。
-3. 运行 `harness_archive.py finalize --change-dir "<executionRoot>" --archive-root ".harness/archive" --intent <...> --closure <...> [--closure-reason "..."] --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest、archive-meta、ZIP、上传与服务端知识状态）。finalize 内部只负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**本地不执行知识 ingest**；服务端在 ZIP 持久保存并解包后 ingest。失败时保留原目录、ZIP 和回执。
+1. 不要为归档预先补跑测试或手工修 ledger。候选收据缺失时，`execute` 会先尝试复用身份一致的全量 ledger 完成本地认证；无法认证时保留结构化原因，`record-only` 仍按事实归档，`release-candidate` 则由发布门禁决定是否阻断。
+2. 运行一次 `harness_archive.py execute --change-dir "<executionRoot>" --archive-root ".harness/archive" --intent <...> --closure <...> [--closure-reason "..."] --json`。`execute` 只采集一次状态，并把准备耗时、正式归档耗时和唯一阶段轮次写入事件。调用者不得在它前后再运行 `auto-gate`、`status`、`finalize` 或手工追加 archive 阶段边界。
+3. `meta/archive-meta.md` 与 `reports/final/summary-data.json` 均由脚本生成。禁止手写、补字段或手工修改 ledger 以绕过门禁。
+4. `execute` 失败时，先按 `reasonCode` 处理，不要盲目重跑：
+   - `ARCHIVE_BASE_EQUALS_FEATURE_TIP`：正常完成不允许空范围归档。仅可选择受控认领既有提交范围、改为未完成封存，或取消。
+   - 受控认领既有范围：先展示 base、tip 和产品文件清单；获得用户明确确认后运行 `adopt-existing-range --base <base> --tip <tip> --reason "<中文原因>" --confirm-existing-range --json`，再重跑一次 `execute`。禁止直接编辑 snapshot 或 ledger。
+   - `abandoned` / `superseded`：允许没有产品增量，但必须保存中文原因，并固定 `releaseEligible=false`。
+   - 其他阻断：读取 `reference.md` 中对应错误的恢复说明；原变更目录必须保留。
+
+   **本地不执行知识 ingest**；服务端在 ZIP 持久保存并解包后 ingest。失败时保留原目录、ZIP 和回执。
    - **归档包上传**：始终先生成一个确定性 ZIP；有远程凭据时再调用 `npx hunter-harness archive upload`。ZIP 仅包含 `summary-data.json`、`spec/**/*.md`、`plans/**/*.md`、`archive-meta.md`、`change-context.json` 和稳定 manifest；明确排除 logs、review/test 报告、HTML、缓存、备份、凭据和临时文件。
    - **失败可恢复**：无论远端凭据是否齐全，都先生成 ZIP 与 `<change-key>.upload.json`；上传或服务端 ingest 失败不破坏本地归档。待上传 ZIP 与逐 change 回执保留在 `.harness/state/local/archive-packages/`，可枚举独立重试。只有 CLI 核验 package hash 且服务端同时返回 `archive_status=durable`、`knowledge_status=ready` 后，才清理对应 ZIP 与回执；`indexing` 记为 pending，不记为失败。
    - **监控终态（C3）**：auto-upload 之后自动 `events-sync`，用归档前 change 路径派生的 `run_id` + 原 `change_key` 上报；失败只记 warning。
 
-- **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
-- **Read `templates/summary-data-template.json`** — summary-data 数据结构
-- **Read `templates/render-summary.mjs`** — final-summary 渲染脚本（finalize 内嵌调用）
+- **Read `reference.md`** — 仅在阻断恢复或需要解释输出字段时读取
+- **Read `templates/summary-data-template.json`** — 仅在排查 summary 校验失败时读取
 
 ### Phase 4：验证与提示
 
-验证归档目录完整 → 提示用户归档完成。
-
-- **Read `checklist.md`** — 归档后验证项
+以 `execute` 返回的 manifest、ZIP、上传回执和 `finalStatus` 为权威结果。只有返回字段缺失或不一致时，才读取 `checklist.md` 做人工诊断。不要为了重复确认成功结果再次扫描整个目录。
 
 ## P0 执行可信度规则
 
@@ -143,15 +141,15 @@ disallowed-tools:
 
 ### 二、归档前确认或自动门禁
 
-`auto-gate` 只有在实际计划最后阶段终态、边界快照存在且 `status.archivable=true` 时才允许无确认执行。未满足时按 Phase 2 的四个中文选项确认；用户取消则不执行移动。
+`execute` 内部运行自动门禁。实际计划最后阶段已终态、边界快照存在且 `status.archivable=true` 时直接执行；未满足时返回阻断且不移动原目录。用户取消后不得重跑。
 
 ### 三、文件移动只用内置工具或 PowerShell
 
 移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。
 
-### 四、数据化归档门禁（先数据后渲染）
+### 四、数据化归档门禁
 
-必须通过 `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`。
+必须通过 `harness_archive.py finalize` 生成权威 `reports/final/summary-data.json` 并完成 validate。平台监控直接读取该数据；本地不再生成重复的 HTML 报告。统计数字只能来自 summary-data、events、ledger 或 manifest。详见 `../protocols/report-pipeline-protocol.md`、`../protocols/archive-report-protocol.md`、`reference.md`。
 
 ### 五、manifest/checksum 必须存在
 
@@ -166,13 +164,15 @@ disallowed-tools:
 
 ### 七、verification-ledger 汇总状态
 
-归档前读 `evidence/verification-ledger.json`，提取各阶段 status、postTestClassification、复用关系，供 final-summary 真实展示状态演进。若 ledger 有 `postTestClassification`，final-summary 必须展示该分类及对应的复用/重测决策。
+归档前读 `evidence/verification-ledger.json`，提取各阶段 status、postTestClassification、复用关系，供 summary-data 真实记录状态演进。若 ledger 有 `postTestClassification`，summary-data 必须记录该分类及对应的复用/重测决策。
+
+门禁策略未声明 `database` 能力，且 `requiredValidations` / `requiredValidationsByPhase` 也未要求 `dbCompatibility` 时，数据库兼容性投影固定为 `NOT_APPLICABLE`，原因来自能力配置。不得要求纯前端、文档或无数据库项目伪造数据库证据。
 
-### 八、final-summary 不得伪造且必须展示状态演进
+### 八、summary-data 不得伪造且必须记录状态演进
 
 无测试报告 → 显示"未运行测试 / 静态验证"，不得 100% 通过率；无 review → "📝ADVISORY：未运行 review"。状态用 ✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP，复用前一阶段结果显示 🔁REUSED，**不得伪装成重新执行，不得无脑全绿**。
 
-**final-summary 是可再生展示投影，非硬产物**：`summary-data.json` 是最终报告的唯一权威数据源，必须产出并通过 validate/adequacy。HTML 渲染默认执行（Node 渲染器失败时自动 Python fallback），但渲染失败只记 warning，**不再回滚归档**；`finalize --no-html` 可完全跳过本地 HTML（配置远端平台时由平台按 summary-data.json 渲染）。
+`summary-data.json` 是最终报告的唯一权威数据源，必须产出并通过 validate/adequacy。平台按该文件展示归档结果，本地不维护第二份展示文件。
 
 ### 九、CONDITIONAL_OK 最终状态
 
@@ -180,15 +180,15 @@ API 测试 `USER_SKIPPED` 或 DB 兼容 `BLOCKED_BY_DBA` 时，最终状态必
 
 ### 十、未提交测试文件归档
 
-未提交但用于验证的测试文件必须归档到 `backups/uncommitted-tests/` 并在 final-summary 中展示。
+未提交但用于验证的测试文件必须归档到 `backups/uncommitted-tests/`，并在 summary-data 中记录。
 
 ### 十一、归档事件单一所有权
 
-finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，并在移动后继续向归档目录中的同一事件流追加。调用者不得在 finalize 前后重复追加阶段边界，否则会造成重复阶段或在原 changes 路径生成幽灵目录。归档后 events.ndjson 与自动渲染的 execution-log.md 一起位于 archive。
+`execute` 在一次性预检通过后负责且仅负责一次正式 `phase.start` / `phase.end`。准备阶段单独使用 `phase.prepare.start/end`，不计为归档重跑。调用者不得重复追加阶段边界。归档后 events.ndjson 与自动渲染的 execution-log.md 一起位于 archive。
 
 ### 十二、Shell 安全 / 敏感信息 / 证据化报告
 
-git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 final-summary.html 不得含明文 token/密码/密钥；归档报告必须区分 ✅真实成功 / 🟡跳过·静态验证 / ❌失败。
+git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 summary-data.json 不得含明文 token、密码或密钥；归档报告必须区分 ✅真实成功 / 🟡跳过·静态验证 / ❌失败。
 
 ### 十三、归档完整性与发布资格分离
 
@@ -196,27 +196,24 @@ git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 fi
 
 ## Output Format
 
-> 归档元数据格式见 `reference.md` 的 archive-meta 模板；最终报告由 `templates/summary-data-template.json` 数据结构 + `templates/render-summary.mjs` 固定脚本渲染。
+> 归档元数据格式见 `reference.md` 的 archive-meta 模板；最终报告使用 `templates/summary-data-template.json` 定义的数据结构。
 
 产出文件：
 
 - `.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 失败时 Python fallback）；渲染失败降级 warning，`--no-html` 可跳过
 - `.harness/archive/YYYY-MM-DD-<change-name>/evidence/archive-manifest-before.json` / `archive-manifest-after.json` — 归档前后 manifest/checksum
 
 ## 渐进披露
 
-- **Read `checklist.md`** 仅在 Phase 1 归档前检查和 Phase 4 验证时 — 含归档前检查项和归档后验证项
-- **Read `reference.md`** 仅在 Phase 0/2/3 时 — 含归档流程、archive-meta 格式、summary-data 字段说明、final-summary 渲染规则、目录结构与最终状态规则
-- **Read `reference.md`** 仅在 Phase 3 finalize 时 — summary-data、final-summary 校验与 archive-meta 补写
-- **Read `templates/summary-data-template.json`** 仅在 Phase 3 生成 `summary-data.json` 时 — 含最终报告数据结构
-- **Read `templates/render-summary.mjs`** 仅在 Phase 3 渲染 `final-summary.html` 时 — 固定 HTML 渲染脚本
+- **Read `checklist.md`** 仅在 `execute` 返回结果缺失或 manifest 不一致时
+- **Read `reference.md`** 仅在阻断恢复、受控范围认领或解释最终状态时
+- **Read `templates/summary-data-template.json`** 仅在 summary 校验失败时
 
 ## 交互白名单
 
-仅当 `auto-gate` 未满足时，允许归档确认（Phase 2 blocking user confirmation）；拒绝 → 终止，不执行任何移动。
+仅当生命周期结局不明确，或需要受控认领既有提交范围时，允许阻断式确认。拒绝后终止，不执行任何移动。
 
 ## 执行日志
 

package/harness/bundles/java/claude-code/harness-archive/checklist.md

@@ -8,11 +8,10 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 归档遵循 `../protocols/archive-report-protocol.md`，门禁要点见 SKILL.md `## 关键规则` 四/五/九：
 
-- 先写 `reports/final/summary-data.json`，再渲染 `reports/final/final-summary.html`。
+- 生成并校验 `reports/final/summary-data.json`；平台直接使用该文件展示结果。
 - 归档前生成 `evidence/archive-manifest-before.json`，移动后生成 `archive-manifest-after.json`。
-- final-summary 的统计只能来自 summary-data 或 manifest。
+- 归档统计只能来自 summary-data 或 manifest。
 - before/after checksum 不一致时，不得删除原目录。
-- 默认渲染器 `templates/render-summary.mjs`（finalize 内嵌调用）。
 - 需要跨工作区恢复时传 `--durable-root <独立存储>`；成功必须为 `ARCHIVED_DURABLE`，并验证 content-addressed object 与 durable receipt 可读回。
 - `restore-durable` 只恢复到不存在的目标；目标已存在或对象 digest 不符时 fail closed，禁止覆盖。
 - 未配置 durable root 时显式记录 `ARCHIVED_LOCAL_ONLY` 风险，不得把同工作区 move 宣称为独立备份。
@@ -33,9 +32,9 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 ## 归档前检查（Phase 1）
 
-> ⚠️ **单一所有权**：finalize 内部负责且仅负责一次 `phase.start` / `phase.end`。归档前检查不得自行追加 archive 阶段边界。
+> ⚠️ **单一所有权**：`execute` 负责一次准备记录和一次正式 `phase.start` / `phase.end`。归档前检查不得自行追加 archive 阶段边界。
 
-- [ ] 未在调用 finalize 前手工追加 archive 阶段边界
+- [ ] 未在调用 `execute` 前手工追加 archive 阶段边界，也未串行调用 `auto-gate`、`status`、`finalize`
 - [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
 - [ ] 已确认 `closure`：正常完成 / 主动废弃 / 被其他方案替代；后两者有中文 `closure-reason`
 - [ ] 正常完成按 `plannedPhases` 核对；提前结束只要求可识别变更与安全封存的最小材料
@@ -46,13 +45,16 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - [ ] Git 项目记录 dirty/HEAD/upstream；无 upstream 或仅本地 commit 允许归档，但 `releaseEligible=false`
 - [ ] 非 Git 项目生成确定性内容清单与产品树散列，并记录 `sourceControl=none`
 - [ ] 最终产品身份来自 Submit 收据或当前内容；提交前候选只允许在验证输入未变化时由 `certify-local` 自动重绑定
+- [ ] `changeBase` 来自首次 Plan 快照，后续阶段未用当前 HEAD 覆盖；正常完成时 base 与产品 tip 不得相同
+- [ ] 如使用既有提交范围，`meta/archive-range-adoption.json` 由 `adopt-existing-range --confirm-existing-range` 生成，未手工修改 ledger 或 snapshot
+- [ ] 主动废弃或被替代允许没有产品增量，但必须有中文原因，且不得声明为发布候选
 - [ ] **test/review 报告状态确认**：
   - ✅ `.harness/changes/<change-name>/tests/test-report-*.md` 存在 → 归档正常
-  - 🟡 不存在 → 必须在 archive-meta.md 和 final-summary.html 中标记"跳过测试"或"未运行测试"，不得伪造通过率
+  - 🟡 不存在 → 必须在 archive-meta.md 和 summary-data.json 中标记「跳过测试」或「未运行测试」，不得伪造通过率
   - ✅ `.harness/changes/<change-name>/reports/review/review-report-*.md` 存在（旧路径 `reviews/review-report-*.md` 兼容回退）→ 作为 📝ADVISORY 归档材料
   - 📝 `.harness/changes/<change-name>/reports/review/fixback-*.md` 存在 → 随 review 报告一并归档；默认 advisory，除非 `strict-review-gate=true`
   - 🟡 不存在但 `logs/execution-log.md` 有 harness-review 小节 → **review 已运行但未落盘**（harness-review `context:fork` 交接缝常见，见 `agent/case-candidates/2026-06-30-harness-review-forked-not-persisting-report.md`）：从 execution-log/会话补落盘到 `reports/review/review-report-YYYYMMDD-HHmm.md` 再归档，**不得误标"未运行 review"**（实际跑过）
-  - 🟡 不存在且 execution-log 无 review 小节 → 在 archive-meta.md 和 final-summary.html 中标记"📝ADVISORY：未运行 review"
+  - 🟡 不存在且 execution-log 无 review 小节 → 在 archive-meta.md 和 summary-data.json 中标记「📝ADVISORY：未运行 review」
 
 ## 归档后验证（Phase 4）
 
@@ -61,11 +63,9 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - [ ] before/after manifest 校验通过（排除 `logs/execution-log.md`——归档追加结束记录预期 sha256 变化；其他 moved 文件 sha256 必须一致，missing/mismatch=0）
 - [ ] archive-meta.md 由 finalize 自动生成且字段完整；调用者未手写或补改
 - [ ] summary-data.json 已生成，且为合法 JSON
-- [ ] final-summary.html 已由 `templates/render-summary.mjs` 渲染生成
-- [ ] **final-summary.html 真实性检查**：
+- [ ] **summary-data.json 真实性检查**：
   - 无测试报告时，`summary-data.json.verification.unitTests.status` / `summary-data.json.verification.apiTests.status` 必须标记为 `NOT_RUN`、`USER_SKIPPED`、`BLOCKED` 或 `STATIC_ONLY`，不得显示 100%
   - 无 review 报告时，`summary-data.json.reviewSummary.status` 必须标记为 `ADVISORY_NOT_RUN`，不得显示 100%
   - 跳过、复用、人工确认的部分必须明确标记，不伪装成 ✅
-  - final-summary.html 中不得残留 `{{...}}` 占位符
 - [ ] 原目录 `.harness/changes/<change-name>/` 已删除（仅在前面所有验证通过后）
 - [ ] .harness/ 下无残留未归档变更目录