@hunter-harness/workflow-harness 0.2.54 → 0.2.56

package/harness/bundles/java/codebuddy/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:
@@ -1160,6 +1256,8 @@ _DYNAMIC_OWN_DIRS = ("events.ndjson", "logs", "evidence", "reports", "runtime",
 
 def _matches_ownership_path(rel: str, declared: Any) -> bool:
     scope = str(declared).replace("\\", "/").strip("/")
+    if scope.endswith("/**"):
+        scope = scope[:-3].rstrip("/")
     if not scope:
         return False
     normalized = rel.replace("\\", "/").strip("/")
@@ -1672,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 = (
@@ -1821,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,
@@ -2051,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(
@@ -2083,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",
@@ -2095,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)
@@ -2135,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
@@ -2142,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(
@@ -2158,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",
@@ -2224,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,
@@ -2304,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)
@@ -2656,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/codebuddy/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
@@ -1155,6 +1235,7 @@ def finalize_plan(
                 "artifactsHash": validation["artifactsHash"],
                 "files": validation["files"],
                 "receiptPath": str(receipt_path),
+                "artifactRef": "meta/plan-finalization.json",
             }
 
     lock_path.parent.mkdir(parents=True, exist_ok=True)
@@ -1253,6 +1334,7 @@ def finalize_plan(
             "artifactsHash": validation["artifactsHash"],
             "files": validation["files"],
             "receiptPath": str(receipt_path),
+            "artifactRef": "meta/plan-finalization.json",
             "executionLogPath": str(harness_events.execution_log_path(change_dir)),
         }
     except OSError as exc:

package/harness/bundles/java/codebuddy/scripts/harness_test_guard.py

@@ -1593,18 +1593,15 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
             [],
             error=str(exc),
         )
-    if (
+    profile_changed = bool(
         isinstance(snapshot.get("profileFingerprint"), str)
         and snapshot["profileFingerprint"] != current_profile_fingerprint
-    ):
-        return _result(False, action, "PROFILE_CHANGED", [])
+    )
     baseline_commit = _snapshot_baseline_commit(
         project_root,
         change_root,
         snapshot,
     )
-    profile_changed = False
-
     before_entries = snapshot.get("files")
     if not isinstance(before_entries, list):
         return _result(False, action, "SNAPSHOT_INVALID", [])
@@ -1682,11 +1679,21 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
             return result
 
     recorded = [rel for rel, _ in touched]
-    reconciliation = _reconcile_close_manifest(
-        project_root,
-        change_root,
-        set(recorded),
-        baseline_commit,
+    reconciliation = (
+        {
+            "ok": True,
+            "code": "PROFILE_REBASED_MANIFEST_PRESERVED",
+            "removedCurrentTouches": 0,
+            "deletedEntries": 0,
+            "preservedForeignEntries": 0,
+        }
+        if profile_changed
+        else _reconcile_close_manifest(
+            project_root,
+            change_root,
+            set(recorded),
+            baseline_commit,
+        )
     )
     if not reconciliation.get("ok"):
         return _result(
@@ -1696,40 +1703,26 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
             list(reconciliation.get("files") or []),
         )
 
-    # Cross-check (retro §5.10): if the manifest has active entries for this
-    # change but close computed recordedCount=0, the snapshot/manifest/diff
-    # are inconsistent. Fail closed instead of silently returning success.
-    manifest_path = _manifest_path(change_root)
-    if manifest_path is not None and manifest_path.is_file():
-        try:
-            manifest = _read_json(manifest_path)
-        except (OSError, json.JSONDecodeError):
-            manifest = None
-        if isinstance(manifest, dict):
-            manifest_files = manifest.get("files")
-            if isinstance(manifest_files, list):
-                is_v2 = manifest.get("schemaVersion") == 2
-                change_id = change_root.name
-                active_entries = [
-                    f for f in manifest_files
-                    if isinstance(f, dict)
-                    and f.get("reason") in ("tdd-created", "test-updated", "stale-test-repair")
-                    and (
-                        not is_v2
-                        or f.get("introducedBy") == change_id
-                        or change_id in (f.get("touchedBy") or [])
-                    )
-                ]
-                if active_entries and not recorded:
-                    return _result(
-                        False,
-                        action,
-                        "MANIFEST_DIFF_HASH_MISMATCH",
-                        [],
-                        manifestEntries=len(active_entries),
-                        recordedCount=0,
-                        detail="manifest has active entries but close computed 0 recorded tests",
-                    )
+    # A manifest is change-wide and intentionally survives phase boundaries.
+    # Therefore pre-existing entries with no new diff are consistent and must
+    # not force a test-guard reset. When the build profile changes mid-phase,
+    # retain the diff result and rebaseline the reusable snapshot atomically.
+    if profile_changed:
+        snapshot.update(
+            {
+                "profileFingerprint": current_profile_fingerprint,
+                "capturedAt": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                "files": [
+                    {
+                        "path": rel,
+                        "sha256": digest,
+                        "ignored": _is_ignored(project_root, rel),
+                    }
+                    for rel, digest in sorted(current.items())
+                ],
+            }
+        )
+        _write_json(snapshot_path, snapshot)
 
     return _result(
         True,

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "java",
   "agent": "codex",
-  "coreHash": "832bb85cf65732cb"
+  "coreHash": "70bd5c265ab41b9b"
 }

package/harness/bundles/java/codex/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/codex/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/codex/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=832bb85cf65732cb; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=70bd5c265ab41b9b; overlay=java; agent=codex; do not edit -->
 # harness-apidoc — 前端接口文档（Java overlay）
 
 ## Purpose