@hunter-harness/workflow-harness 0.2.55 → 0.2.56

package/harness/bundles/java/codex/scripts/harness_ledger.py

@@ -145,7 +145,91 @@ def _hash_text(value: str) -> str:
 
 def command_set_hash(command: str) -> str:
     """Stable identity for the exact command set represented by one target."""
-    return _hash_text(str(command).strip())
+    return _hash_text(canonical_command(command))
+
+
+def canonical_command(command: str) -> str:
+    """Normalize supported launch wrappers without mixing runner notes into identity."""
+    value = re.sub(r"\s+", " ", str(command).strip())
+    value = re.sub(r"\s*\(safe runner\)\s*$", "", value, flags=re.I)
+    value = re.sub(r"^npx(?:\s+--no-install)?\s+", "", value, flags=re.I)
+    return value.strip()
+
+
+def default_environment_hash(project_root: Path | None = None) -> str:
+    payload = {
+        "osName": os.name,
+        "platform": sys.platform,
+        "pythonImplementation": sys.implementation.name,
+        "projectFilesystem": "windows" if os.name == "nt" else "posix",
+    }
+    return _hash_text(json.dumps(payload, sort_keys=True, separators=(",", ":")))
+
+
+def default_toolchain_hash(project_root: Path | None = None) -> str:
+    root = Path(project_root).resolve() if project_root is not None else None
+    manifests: list[dict[str, str]] = []
+    if root is not None:
+        for name in (
+            "package.json", "pyproject.toml", "pom.xml", "build.gradle",
+            "build.gradle.kts", "go.mod", "Cargo.toml",
+        ):
+            path = root / name
+            if path.is_file():
+                manifests.append({
+                    "name": name,
+                    "sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+                })
+    payload = {
+        "python": sys.version.split()[0],
+        "implementation": sys.implementation.name,
+        "manifests": manifests,
+    }
+    return _hash_text(json.dumps(payload, sort_keys=True, separators=(",", ":")))
+
+
+def frozen_ownership_check(change_dir: Path) -> dict[str, Any]:
+    """Reject evidence writes after a Run capsule's ownership scope changed."""
+    try:
+        state_root = Path(
+            harness_paths.resolve_state_dir_for_contract(change_dir)
+        ).resolve()
+        contract = harness_paths.load_change_contract(change_dir)
+    except (OSError, ValueError, json.JSONDecodeError):
+        return {"ok": True, "code": "OWNERSHIP_FREEZE_NOT_APPLICABLE"}
+    capsule_root = state_root / "runtime" / "phase-context"
+    if not capsule_root.is_dir():
+        return {"ok": True, "code": "OWNERSHIP_FREEZE_NOT_APPLICABLE"}
+    capsules: list[dict[str, Any]] = []
+    for path in capsule_root.glob("run-*.json"):
+        try:
+            item = json.loads(path.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if (
+            isinstance(item, dict)
+            and item.get("phase") == "run"
+            and not item.get("closedAt")
+            and _nonempty_str(item.get("ownershipHash"))
+        ):
+            capsules.append(item)
+    if not capsules:
+        return {"ok": True, "code": "OWNERSHIP_FREEZE_NOT_APPLICABLE"}
+    capsule = sorted(capsules, key=lambda item: str(item.get("createdAt") or ""))[-1]
+    current = ownership_hash(contract)
+    if capsule.get("ownershipHash") != current:
+        return {
+            "ok": False,
+            "code": "OWNERSHIP_CHANGED_BEFORE_VERIFICATION",
+            "message": (
+                "产品范围在 Run 启动后发生变化；请先通过受控范围更新重启 Run，"
+                "系统将只失效受影响的验证。"
+            ),
+            "storedOwnershipHash": capsule.get("ownershipHash"),
+            "currentOwnershipHash": current,
+            "runId": capsule.get("runId"),
+        }
+    return {"ok": True, "code": "OWNERSHIP_FROZEN"}
 
 
 def product_tree_hash(project_root: Path | None) -> str | None:
@@ -284,6 +368,10 @@ def parse_files_manifest(raw: str | None) -> list[str]:
     ]
 
 
+class ProjectRootRequiredError(ValueError):
+    """Raised when relative verification inputs have no stable project basis."""
+
+
 def resolve_input_files(
     files: list[str], project_root: Path | None
 ) -> list[str]:
@@ -313,7 +401,15 @@ def input_files_from_args(args: argparse.Namespace) -> tuple[list[str], Path | N
     manifest = parse_files_manifest(getattr(args, "files_from", None))
     if files and manifest:
         raise ValueError("use only one of --files and --files-from")
-    return resolve_input_files(files or manifest, project_root), project_root
+    selected = files or manifest
+    if project_root is None and any(
+        not Path(raw).expanduser().is_absolute() for raw in selected
+    ):
+        raise ProjectRootRequiredError(
+            "relative verification inputs require --project so their identity "
+            "does not depend on the caller's current directory"
+        )
+    return resolve_input_files(selected, project_root), project_root
 
 
 def sha256_file(path: Path) -> str:
@@ -1674,8 +1770,8 @@ def decide_can_reuse(
         )
         and (
             not _nonempty_str(requested_command)
-            or str(candidate.get("command") or "").strip()
-            == str(requested_command).strip()
+            or canonical_command(str(candidate.get("command") or ""))
+            == canonical_command(str(requested_command))
         )
     ]
     entry = (
@@ -1823,7 +1919,7 @@ def decide_can_reuse(
             }
 
     if requested_command is not None and str(requested_command).strip():
-        if str(command).strip() != str(requested_command).strip():
+        if canonical_command(str(command)) != canonical_command(str(requested_command)):
             return {
                 "ok": True,
                 "reuse": False,
@@ -2053,10 +2149,29 @@ def cmd_can_reuse(args: argparse.Namespace) -> int:
     verbose = bool(getattr(args, "verbose", False))
     verification = args.verification
     change_dir = resolve_path(args.change_dir)
+    ownership_check = frozen_ownership_check(change_dir)
+    if not ownership_check.get("ok"):
+        return emit_error(
+            str(ownership_check.get("message")),
+            as_json=as_json,
+            error_code=str(ownership_check.get("code")),
+            extra={
+                key: value
+                for key, value in ownership_check.items()
+                if key not in {"ok", "code", "message"}
+            },
+        )
     try:
         files, project_root = input_files_from_args(args)
+    except ProjectRootRequiredError as exc:
+        return emit_error(
+            str(exc),
+            as_json=as_json,
+            error_code="PROJECT_ROOT_REQUIRED",
+        )
     except (OSError, ValueError) as exc:
         return emit_error(f"can-reuse failed: {exc}", as_json=as_json)
+    explicit_files = list(files)
     target = resolve_verification_target(verification, project_root)
     if target is None:
         return emit_error(
@@ -2085,7 +2200,22 @@ def cmd_can_reuse(args: argparse.Namespace) -> int:
                 compact_fn=_compact_can_reuse_payload,
             )
             return 0
-        files = resolve_input_files(resolved_files, project_root)
+        profile_files = resolve_input_files(resolved_files, project_root)
+        if explicit_files:
+            _explicit_hash, explicit_names = compute_inputs_hash(
+                explicit_files, project_root=project_root
+            )
+            _profile_hash, profile_names = compute_inputs_hash(
+                profile_files, project_root=project_root
+            )
+            if explicit_names != profile_names:
+                return emit_error(
+                    "PROFILE_INPUT_FILES_CONFLICT: --files does not match the "
+                    "declared build-profile input set",
+                    as_json=as_json,
+                    error_code="PROFILE_INPUT_FILES_CONFLICT",
+                )
+        files = profile_files
     if not files:
         return emit_error(
             "can-reuse requires --files or a non-empty --profile-input file set",
@@ -2097,10 +2227,20 @@ def cmd_can_reuse(args: argparse.Namespace) -> int:
             verification=verification,
             files=files,
             requested_scope=getattr(args, "scope", None),
-            requested_command=getattr(args, "command", None),
-            requested_toolchain_hash=getattr(args, "toolchain_hash", None),
+            requested_command=(
+                canonical_command(str(getattr(args, "command", "")))
+                if _nonempty_str(getattr(args, "command", None))
+                else None
+            ),
+            requested_toolchain_hash=(
+                getattr(args, "toolchain_hash", None)
+                or default_toolchain_hash(project_root)
+            ),
             requested_profile_hash=getattr(args, "profile_hash", None),
-            requested_environment_hash=getattr(args, "environment_hash", None),
+            requested_environment_hash=(
+                getattr(args, "environment_hash", None)
+                or default_environment_hash(project_root)
+            ),
             requested_db_schema_hash=getattr(args, "db_schema_hash", None),
             requested_product_tree_hash=(
                 getattr(args, "product_tree_hash", None) or product_tree_hash(project_root)
@@ -2137,6 +2277,18 @@ def cmd_record(args: argparse.Namespace) -> int:
     as_json = bool(args.json)
     verbose = bool(getattr(args, "verbose", False))
     change_dir = resolve_path(args.change_dir)
+    ownership_check = frozen_ownership_check(change_dir)
+    if not ownership_check.get("ok"):
+        return emit_error(
+            str(ownership_check.get("message")),
+            as_json=as_json,
+            error_code=str(ownership_check.get("code")),
+            extra={
+                key: value
+                for key, value in ownership_check.items()
+                if key not in {"ok", "code", "message"}
+            },
+        )
     verification = args.verification
     contract_v2 = _contract_is_v2(change_dir)
     migration_receipt: dict[str, Any] | None = None
@@ -2144,6 +2296,7 @@ def cmd_record(args: argparse.Namespace) -> int:
         files, project_root = input_files_from_args(args)
     except (OSError, ValueError) as exc:
         return emit_error(f"record failed: {exc}", as_json=as_json)
+    explicit_files = list(files)
     target = resolve_verification_target(verification, project_root)
     if target is None:
         return emit_error(
@@ -2160,7 +2313,22 @@ def cmd_record(args: argparse.Namespace) -> int:
         resolved_files, err = expand_profile_input_files(project_root, profile_input)
         if err:
             return emit_error(f"record failed: {err}", as_json=as_json)
-        files = resolve_input_files(resolved_files, project_root)
+        profile_files = resolve_input_files(resolved_files, project_root)
+        if explicit_files:
+            _explicit_hash, explicit_names = compute_inputs_hash(
+                explicit_files, project_root=project_root
+            )
+            _profile_hash, profile_names = compute_inputs_hash(
+                profile_files, project_root=project_root
+            )
+            if explicit_names != profile_names:
+                return emit_error(
+                    "PROFILE_INPUT_FILES_CONFLICT: --files does not match the "
+                    "declared build-profile input set",
+                    as_json=as_json,
+                    error_code="PROFILE_INPUT_FILES_CONFLICT",
+                )
+        files = profile_files
     if not files:
         return emit_error(
             "record requires --files or a non-empty --profile-input file set",
@@ -2226,7 +2394,12 @@ def cmd_record(args: argparse.Namespace) -> int:
         entry.update(
             {
                 "status": status,
-                "command": args.command,
+                "command": canonical_command(args.command),
+                "runnerCommand": (
+                    str(getattr(args, "runner_command", None)).strip()
+                    if _nonempty_str(getattr(args, "runner_command", None))
+                    else str(args.command).strip()
+                ),
                 "evidence": args.evidence,
                 "exitCode": args.exit_code,
                 "durationMs": args.duration_ms,
@@ -2306,6 +2479,10 @@ def cmd_record(args: argparse.Namespace) -> int:
             ("dbSchemaHash", "db_schema_hash"),
         ):
             val = getattr(args, attr, None)
+            if field == "toolchainHash" and not _nonempty_str(val):
+                val = default_toolchain_hash(project_root)
+            elif field == "environmentHash" and not _nonempty_str(val):
+                val = default_environment_hash(project_root)
             if _nonempty_str(val):
                 entry[field] = str(val).strip()
         entry["commandSetHash"] = command_set_hash(args.command)
@@ -2658,6 +2835,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_record.add_argument("--verification", required=True)
     p_record.add_argument("--status", required=True)
     p_record.add_argument("--command", required=True)
+    p_record.add_argument(
+        "--runner-command",
+        default=None,
+        help="actual launcher command; stored as execution metadata, not target identity",
+    )
     p_record.add_argument("--exit-code", type=int, required=True)
     p_record.add_argument("--duration-ms", type=int, required=True)
     p_record_files = p_record.add_mutually_exclusive_group()

package/harness/bundles/java/codex/scripts/harness_plan_finalize.py

@@ -30,6 +30,18 @@ if hasattr(sys.stderr, "reconfigure"):
 
 SCHEMA_VERSION = 1
 _LINK = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
+_BACKTICK = re.compile(r"`([^`\r\n]+)`")
+_CODE_PATH_SUFFIXES = {
+    ".c", ".cc", ".cpp", ".cs", ".css", ".go", ".h", ".hpp", ".html",
+    ".java", ".js", ".jsx", ".kt", ".kts", ".mjs", ".php", ".py", ".rb",
+    ".rs", ".scss", ".sh", ".svelte", ".swift", ".ts", ".tsx", ".vue",
+}
+_BUILD_FILE_NAMES = {
+    "build.gradle", "build.gradle.kts", "cargo.toml", "composer.json", "go.mod",
+    "gradle.properties", "package-lock.json", "package.json", "pnpm-lock.yaml",
+    "pom.xml", "pyproject.toml", "requirements.txt", "settings.gradle",
+    "settings.gradle.kts", "tsconfig.json", "yarn.lock",
+}
 
 # C8: valid ownerPhase values (lifecycle phases that can own tasks).
 VALID_OWNER_PHASES = {"plan", "run", "test", "review", "submit"}
@@ -615,6 +627,71 @@ def validate_staging(staging: Path, change_name: str) -> dict[str, Any]:
     }
 
 
+def validate_product_ownership(change_dir: Path, staging: Path) -> dict[str, Any]:
+    """Ensure Plan declares stable prefix ownership for explicit code/test/build paths."""
+    context_path = change_dir / "meta" / "change-context.json"
+    if not context_path.is_file():
+        return {"ok": True, "code": "PLAN_PRODUCT_PATHS_LEGACY_UNDECLARED"}
+    try:
+        context = json.loads(context_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result_error("PLAN_CHANGE_CONTEXT_INVALID", str(exc))
+    ownership = context.get("ownership") if isinstance(context, dict) else None
+    raw_paths = ownership.get("productPaths") if isinstance(ownership, dict) else None
+    product_paths = [
+        str(item).strip().replace("\\", "/").removeprefix("./")
+        for item in raw_paths or []
+        if isinstance(item, str) and item.strip()
+    ]
+    unsupported = sorted(path for path in product_paths if any(char in path for char in "*?[]"))
+    if unsupported:
+        result = _result_error(
+            "PLAN_PRODUCT_PATHS_GLOB_UNSUPPORTED",
+            "productPaths 只接受精确文件或目录前缀，不支持通配：" + ", ".join(unsupported),
+        )
+        result["unsupportedPaths"] = unsupported
+        return result
+
+    planned_paths: set[str] = set()
+    for document in sorted(staging.rglob("*.md")):
+        text = document.read_text(encoding="utf-8-sig")
+        for raw in _BACKTICK.findall(text):
+            candidate = raw.strip().strip("'\"").replace("\\", "/")
+            if not candidate or " " in candidate or "://" in candidate or "<" in candidate:
+                continue
+            candidate = re.sub(r":\d+(?::\d+)?$", "", candidate)
+            candidate = candidate.removeprefix("./").strip("/.,;，；")
+            if not candidate or candidate.startswith("../") or candidate.startswith(".harness/"):
+                continue
+            pure = PurePosixPath(candidate)
+            if pure.name.lower() in _BUILD_FILE_NAMES or pure.suffix.lower() in _CODE_PATH_SUFFIXES:
+                planned_paths.add(candidate)
+
+    def covered(path: str) -> bool:
+        return any(
+            path == owned.rstrip("/")
+            or path.startswith(owned.rstrip("/") + "/")
+            for owned in product_paths
+            if owned.rstrip("/")
+        )
+
+    missing = sorted(path for path in planned_paths if not covered(path))
+    if missing:
+        result = _result_error(
+            "PLAN_PRODUCT_PATHS_INCOMPLETE",
+            "productPaths 未覆盖计划明确引用的产品文件：" + ", ".join(missing),
+        )
+        result["missingPaths"] = missing
+        result["recoveryAction"] = "在 Plan 阶段补充精确文件或目录前缀后重新 finalize。"
+        return result
+    return {
+        "ok": True,
+        "code": "PLAN_PRODUCT_PATHS_COMPLETE",
+        "plannedPaths": sorted(planned_paths),
+        "productPaths": product_paths,
+    }
+
+
 def _terminal_exists(change_dir: Path, run_id: str, attempt: int) -> bool:
     try:
         events = harness_events.load_events(harness_events.events_path(change_dir))
@@ -1125,6 +1202,9 @@ def finalize_plan(
     validation = validate_staging(staging, change_name)
     if not validation["ok"]:
         return validation
+    ownership_validation = validate_product_ownership(change_dir, staging)
+    if not ownership_validation["ok"]:
+        return ownership_validation
     start_validation = _validate_plan_start(change_dir, run_id, attempt)
     if not start_validation["ok"]:
         return start_validation

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "cursor",
-  "coreHash": "44594ca0f316c6fa"
+  "coreHash": "ea74ea84e6cc3617"
 }

package/harness/bundles/java/cursor/README.md

@@ -278,7 +278,7 @@ harness-skills/
 | **submit 步骤 4** | 提交前必须展示四项：实际 staged 文件列表、diff stat、commit message、是否 push |
 | **submit push 前** | `git fetch` 后检查远程是否有新提交；有则**不得直接 pull 后 push**，必须 pull/rebase + 重新 compile/test |
 | **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 阶段 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） |
 
@@ -339,9 +339,9 @@ harness-skills/
 
 > **harness-review 是参考性审查阶段**：默认只生成参考性审查报告和按需 fixback，不影响后续 submit、archive。如果用户选择处理 fixback，回到 `/harness-run --fixback`，再执行 `/harness-test` 和 `/harness-review`；如果团队希望 review RED 阻塞提交，可在 `.harness/config/harness-test-config.md` 中设置 `review.strict-review-gate: true`。
 
-> **submit 与 archive 的时序**：主目录模式流程为 `run → test → review(advisory) → submit(含 push) → archive`；worktree 模式流程为 `run → test → review → submit(本地 commit + 自动 --no-ff 合并 + push 主分支) → archive`。`/harness-merge` 为 submit 的别名触发词。archive 优先读 ledger `mergeFinalHash`。
+> **阶段顺序以计划为准**：Plan 会把本次 `plannedPhases` 写入上下文，后续阶段只消费该计划，不再假定 test、review、submit 或 merge 必经。快速流程默认可用 `plan → run → archive`；需要完整验证、评审或提交时再把对应阶段加入计划。无 Git、无 upstream、仅本地提交或主动跳过 submit 都不妨碍事实封存；只有“发布候选”需要额外满足发布策略。
 
-> **verification-ledger 驱动跨阶段复用**：每个变更目录维护 `.harness/changes/<change-name>/evidence/verification-ledger.json`，记录 compile/unitTest/apiTest 的结果+证据+diffHash+作用范围。run/test/submit 执行验证前先读 ledger，满足复用条件（diffHash 一致、module/profile 一致、范围更严格、有证据、无行为性 post-test 修改）则跳过重跑并标记 🔁REUSED；post-test 小改动按 7 类分类，非行为性清理可复用 API 测试。详见 `protocols/ledger-protocol.md`。
+> **verification-ledger 驱动跨阶段复用**：先通过共享状态目录解析器定位变更，再读写其 `evidence/verification-ledger.json`，其中记录 compile/unitTest/apiTest 的结果、证据、diffHash 和作用范围。run/test/submit 执行验证前先读 ledger，满足复用条件（diffHash 一致、module/profile 一致、范围更严格、有证据、无行为性 post-test 修改）则跳过重跑并标记 🔁REUSED；post-test 小改动按 7 类分类，非行为性清理可复用 API 测试。详见 `protocols/ledger-protocol.md`。
 
 ## 外部方法论吸收（已内化）
 

package/harness/bundles/java/cursor/contracts/workflow-policy.json

@@ -34,7 +34,7 @@
   "riskTiers": {
     "fast": {
       "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"],
+      "defaultPhases": ["plan", "run", "archive"],
       "requiredValidations": ["unitTest"],
       "conditionalStages": ["review", "package", "apidoc"],
       "upgradeTriggers": ["api-change", "security", "migration", "concurrency", "breaking-contract"]

package/harness/bundles/java/cursor/harness-apidoc/SKILL.md

@@ -3,7 +3,7 @@ name: harness-apidoc
 description: 从 Java 后端代码生成结构化前端 API 文档（Controller/VO/ErrorCode）。仅当用户显式调用
   /harness-apidoc 时使用，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=44594ca0f316c6fa; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=ea74ea84e6cc3617; overlay=java; agent=cursor; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose

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

@@ -3,50 +3,38 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到 .harness/archive/，含归档元数据。仅当用户显式调用
   /harness-archive 时使用；不得被其他阶段 skill 自动接续触发。
 ---
-<!-- generated by harness_deploy.py; core=44594ca0f316c6fa; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=ea74ea84e6cc3617; overlay=java; agent=cursor; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
 
-将 `.harness/changes/<change-name>/` 的所有产出移入 `.harness/archive/YYYY-MM-DD-<change-name>/`，生成归档元数据和可视化最终报告，释放工作区。
+把变更事实安全封存、生成确定性 ZIP，并在已连接 Hunter Platform 时上传保存。归档结局、发布资格、Git 远端和平台上传分别建模，互不冒充前置条件。
 
 ## When to Use
 
 仅当用户显式调用 `/harness-archive` 时执行。submit/merge 完成后**不自动**进入本阶段；用户口头说"归档/收尾"而未调用本 skill 时，先确认。
 
-前置：submit 已推送、test/review 报告已就绪（或已明确标记跳过/未运行）。变更闭环最后一站，归档后从工作区移除 `.harness/changes/<change-name>/`。
-
-跳过场景：
-
-- 变更尚未 submit 推送（归档前 commit 必须已 push）。
-- 仍存在未结清的 test/review 验证（除非已明确标记 CONDITIONAL_OK）。
+前置只看本次 `plannedPhases` 与用户选择的生命周期结局。Submit、Test 或 Review 未在计划中时记录为“未执行”，不得临时补跑；无 Git、无 upstream、仅本地 commit 都允许归档和平台上传，只是不能声明为发布候选。
 
 自动调用边界：
 
 - 归档涉及移动/删除原变更目录，**禁止被其他 skill 自动调用**；只接受用户显式 `/harness-archive` 调用。
-- `harness_archive.py auto-gate` 只影响**本次显式调用内**是否需要归档确认对话：返回 `ARCHIVE_AUTO_GATE_SATISFIED`（Submit 或 Merge 已终态，archive-boundary snapshot 存在且全部归档门禁满足）时可跳过 AskQuestion 直接归档；其他情况仍须确认。auto-gate 不构成跨阶段自动触发的授权。
+- `harness_archive.py auto-gate` 只影响**本次显式调用内**是否需要归档确认对话：实际计划中的最后阶段已终态、archive-boundary/content snapshot 存在且保存门禁满足时可跳过确认。auto-gate 不构成跨阶段自动触发的授权。
 
 ## 前置条件
 
-- commit 已 push（`git log @{u}..HEAD` 输出为空）
-- **最终 hash 来源**：worktree 模式（`meta/worktree.json` requested=true）下读 ledger 的 `mergeFinalHash`（由 `/harness-submit` 合并段写入）；主目录模式读 submit 的 `final pushed hash`。当前 `git rev-parse HEAD` 须一致
-- test 报告存在或标记"跳过"；review 报告存在或标记"未运行 review"（review 不阻塞归档）
-- **最小必备集（H-4 / `harness_archive.py status` blockers）**：
-  - `plans/*-plan.md`
-  - 非空 `events.ndjson`
-  - `evidence/verification-ledger.json`
-  - 至少一个 test 或 review 报告/证据
-  - 缺失任一项 → `archivable=false`；可从 `.harness/cache/change-snapshots/<change>/` 恢复正式层后再重试
+- **最终产品身份**：Git 项目优先使用 Submit 最终收据/当前 HEAD；提交前验证而内容未变化时由 `certify-local` 自动重绑定 commit。非 Git 项目使用确定性内容清单与产品树散列，并记录 `sourceControl=none`。
+- **正常完成**按 `plannedPhases` 检查已规划阶段；被省略阶段记录 `NOT_RUN` / `NOT_APPLICABLE`。**结束未完成变更**只要求足以识别和安全封存变更的最小设计、事件与内容清单，不要求补齐测试、评审或提交。
+- 所有 events、ledger、reports、receipts 和 upload state 都通过 state layout 解析器读取；split-v1 的权威状态位于 `.harness/state/changes/<change>`，禁止复制到旧目录。
 - **产品候选验证**：
   - 有远端 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 证据，不重复执行测试。
-  - `release-candidate` 默认要求候选验证通过；仅封存未完成事实时显式使用 `--intent record-only`，归档结果必须为 `releaseEligible=false`，不得用于发布。
+  - `release-candidate` 要求候选验证通过；正常本地完成或结束未完成变更使用 `--intent record-only`，固定 `releaseEligible=false`，但仍生成 ZIP 并上传平台。
 
 ## Inputs
 
-- `$ARGUMENTS`：变更名（可选，留空时 Glob `.harness/changes/*/plans/*-plan.md` 自动检测，排除 `.harness/archive/`）
-- 相关文件：`.harness/changes/<change-name>/logs/execution-log.md`、`.harness/changes/<change-name>/events.ndjson`、`evidence/verification-ledger.json`、各阶段 reports/
+- `$ARGUMENTS`：变更名（可选）；必须由 `harness_change.py resolve` 解析 contract/state 双层目录，禁止按 mtime 或固定旧路径猜测。
 
 ## 统一读取协议
 
@@ -78,29 +66,29 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
    - `../protocols/sensitive-info-protocol.md`
    - `../protocols/evidence-based-reporting-protocol.md`
    - `../protocols/report-pipeline-protocol.md`
-4. 解析 `$ARGUMENTS`：留空时 Glob 自动检测未归档变更，排除 `.harness/archive/`。
+4. 用 `harness_change.py resolve [--change] --json` 解析 `$ARGUMENTS`；多个 active change 时让用户选择。
 
 ### Phase 1：确认归档对象（扫描未归档变更）
 
-用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（排除 `.harness/archive/`），展示变更概要。
+使用 resolver 返回的 active changes 展示变更概要；同时读取 `plannedPhases`、已完成阶段、Git 能力、平台连接和待上传 ZIP 状态。
 
 - **Read `checklist.md`** — 归档前检查项
 - 发现多个未归档变更 → 让用户选择或终止
 
 ### Phase 2：确认归档 / 自动门禁
 
-先运行 `harness_archive.py auto-gate --change-dir ".harness/changes/<change-name>" --intent <intent> --json`。
+先运行 `harness_archive.py auto-gate --change-dir "<executionRoot>" --intent <intent> --json`。
 
 - `autoArchiveAllowed=true`：记录 gate receipt，直接进入 Phase 3；无需 AskQuestion。
-- 否则：blocking user confirmation 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
+- 否则用中文提供：①正常完成并归档（本地验证、不可发布）；②作为发布候选归档；③结束未完成变更；④取消。选择③后继续选择“主动废弃”或“被其他方案替代”，并填写中文原因。不要把无 upstream 显示为阻止保存。
 
 - **Read `reference.md`** — 确认对话框的内容格式
 
 ### Phase 3：执行归档
 
-1. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --intent release-candidate --json` 前置检查。无 CI 项目若已有完整全量 ledger，先运行 `certify-local`；若用户明确只封存事实，则 status/finalize 均使用 `--intent record-only`。
+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. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent <release-candidate|record-only> --json`；读 JSON（cleanup、事件、移动、collect、render、validate、manifest 比对、archive-meta、ZIP package、上传与服务端 knowledge status）。finalize 内部负责且仅负责一次 `phase.start` / `phase.end`，调用者不得重复追加。**本地不再执行知识维护，也不写 maintenance-outbox**；服务端在归档 ZIP 持久保存并解包后 ingest。**finalize 失败或 validate 报错时不删除原目录**。
+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 和回执。
    - **归档包上传**：始终先生成一个确定性 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。
@@ -137,7 +125,7 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 ### 二、归档前确认或自动门禁
 
-`auto-gate` 只有在 Submit/Merge 终态、`meta/state-snapshot.json` 含 archive-boundary base、且 `status.archivable=true` 时才允许无确认执行。未满足时 blocking user confirmation；用户拒绝 → 终止，不执行任何操作。
+`auto-gate` 只有在实际计划最后阶段终态、边界快照存在且 `status.archivable=true` 时才允许无确认执行。未满足时按 Phase 2 的四个中文选项确认；用户取消则不执行移动。
 
 ### 三、文件移动只用内置工具或 PowerShell
 
@@ -151,12 +139,12 @@ description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档
 
 归档前后生成 `evidence/archive-manifest-before.json` / `archive-manifest-after.json`（path/size/sha256），before/after 不一致时**不得删除原目录**。复杂 PowerShell 写入 `scripts/*.ps1` 后 `-File` 执行，禁止内联 `$` / `$_` / `@{}`。详见 `reference.md`。
 
-### 六、归档前确认四项（缺一不可）
+### 六、归档前确认四项
 
-- commit 已 push（`git log @{u}..HEAD` 输出为空）
-- **final hash 来源**：worktree 模式（requested=true）下读 ledger `mergeFinalHash`（submit 合并段）；否则读 submit 日志 `final pushed hash`。当前 HEAD 须一致
-- test 报告存在，或标记"跳过"/"未运行测试"
-- review 报告：存在则作 📝ADVISORY 归档材料；不存在标记"📝ADVISORY：未运行 review"（review 不阻塞归档）
+- 生命周期结局与中文原因已确认；正常完成、主动废弃、被其他方案替代不得混写
+- Git 项目记录当前 HEAD 与 upstream 状态；无 upstream 只影响发布资格，不阻止保存。非 Git 项目记录内容身份
+- Test/Review 只按 `plannedPhases` 核对；未规划或提前结束时如实标记未执行
+- 平台连接与 Git remote 分开检查；无 Git remote 仍生成 ZIP，并在平台已连接时上传
 
 ### 七、verification-ledger 汇总状态
 

package/harness/bundles/java/cursor/harness-archive/checklist.md

@@ -37,19 +37,15 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 - [ ] 未在调用 finalize 前手工追加 archive 阶段边界
 - [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
-- [ ] **最小必备集 blockers**（`harness_archive.py status`）：
-  - [ ] `plans/*-plan.md` 存在
-  - [ ] `events.ndjson` 存在且非空
-  - [ ] `evidence/verification-ledger.json` 存在
-  - [ ] 至少一个 test 或 review 报告/证据
-  - [ ] 若缺失：优先从 `.harness/cache/change-snapshots/<change>/` 恢复，禁止空壳归档
+- [ ] 已确认 `closure`：正常完成 / 主动废弃 / 被其他方案替代；后两者有中文 `closure-reason`
+- [ ] 正常完成按 `plannedPhases` 核对；提前结束只要求可识别变更与安全封存的最小材料
 - [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
 - [ ] `events.ndjson` 存在；执行日志允许由 finalize 从事件流重新渲染（旧 archive 才兼容根目录 `execution-log.md`）
 - [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）
 - [ ] 准备生成 `summary-data.json`（业务目标、阶段状态、验证、产物、维护者结论）
-- [ ] git status 无未提交的重要变更（归档应对应已提交的代码）
-- [ ] **commit 已 push**：`powershell.exe -Command "git -C '<项目路径>' log @{u}..HEAD --oneline"` 输出为空（无未推送提交）
-- [ ] **最终 hash 一致**：worktree 模式（requested=true）下读 `evidence/verification-ledger.json` 的 `mergeFinalHash`（submit 合并段写入），否则从 events/ledger 读取 `final pushed hash`，与当前 `git rev-parse HEAD` 比对
+- [ ] Git 项目记录 dirty/HEAD/upstream；无 upstream 或仅本地 commit 允许归档，但 `releaseEligible=false`
+- [ ] 非 Git 项目生成确定性内容清单与产品树散列，并记录 `sourceControl=none`
+- [ ] 最终产品身份来自 Submit 收据或当前内容；提交前候选只允许在验证输入未变化时由 `certify-local` 自动重绑定
 - [ ] **test/review 报告状态确认**：
   - ✅ `.harness/changes/<change-name>/tests/test-report-*.md` 存在 → 归档正常
   - 🟡 不存在 → 必须在 archive-meta.md 和 final-summary.html 中标记"跳过测试"或"未运行测试"，不得伪造通过率
@@ -63,7 +59,7 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 - [ ] `.harness/archive/YYYY-MM-DD-<change-name>/` 目录存在（通过 Glob 实际扫描确认）
 - [ ] 所有子目录（plans/, tests/, reviews/, sqls/）已完整移入（通过 Glob 实际扫描确认，不仅看预期路径）
 - [ ] before/after manifest 校验通过（排除 `logs/execution-log.md`——归档追加结束记录预期 sha256 变化；其他 moved 文件 sha256 必须一致，missing/mismatch=0）
-- [ ] 如需 archive-meta.md，已在 finalize 前创建且 frontmatter 字段完整；finalize 后未再改动归档文件
+- [ ] archive-meta.md 由 finalize 自动生成且字段完整；调用者未手写或补改
 - [ ] summary-data.json 已生成，且为合法 JSON
 - [ ] final-summary.html 已由 `templates/render-summary.mjs` 渲染生成
 - [ ] **final-summary.html 真实性检查**：

package/harness/bundles/java/cursor/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=44594ca0f316c6fa; overlay=java; agent=cursor; do not edit -->
+<!-- generated by harness_deploy.py; core=ea74ea84e6cc3617; overlay=java; agent=cursor; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose