@hunter-harness/workflow-harness 0.2.85 → 0.2.86

package/harness/bundles/java/codex/harness-plan/reference.md

@@ -351,7 +351,8 @@ status: approved
 | `.harness/changes/<change>/plans/<change>-plan.md` | ✅（派生） | ✅ |
 | `.harness/changes/<change>/plans/<change>-implementation-detail.md` | ✅（派生） | ✅ |
 | `.harness/changes/<change>/plans/<change>-test-scenarios.md` | ✅（派生） | ✅ |
-| `.harness/changes/<change>/meta/gate-policy.json` | ✅ | ✅ |
+| `.harness/changes/<change>/meta/gate-policy.json` | ✅（**classify 写，非发布产物**） | ✅ |
+| `.harness/changes/<change>/meta/plan-profile.json` | ✅（派生） | — |
 | `.harness/changes/<change>/meta/worktree.json` | ✅ | ✅ |
 | `.harness/changes/<change>/meta/implementation-checkpoints.json` | ✅ | ✅ |
 | `.harness/changes/<change>/meta/scenario-manifest.json` | ✅ | ✅ |
@@ -363,6 +364,25 @@ status: approved
 
 legacy 的 `plan-finalization.json.files` 必须完整列出 design、plan、implementation-detail、test-scenarios、gate-policy、worktree 六项标准输入。`verify` 对缺项、重复项、越界路径以及 symlink/junction/reparse point 一律 fail-closed；不得通过删减收据文件集后重算哈希来绕过完整性检查。
 
+### 两套分类模型的边界（别把它们当同一件事）
+
+| | Python `tier` | TS `mode` |
+|---|---|---|
+| 取值 | `fast` / `standard` / `full` | `quick` / `standard` / `assurance` |
+| 写到哪 | `meta/gate-policy.json`（`schemaVersion:1`，camelCase） | `meta/plan-profile.json`（artifact 包装体，snake_case） |
+| 谁写 | `harness_gate.py classify`（阶段 0.5 由 bootstrap-plan 调起） | `hunter-harness plan finalize`（阶段 8 发布） |
+| 地位 | **门禁权威**：驱动 `requiredGateDag`、`requiredValidationsByPhase`，run/test 开门读它 | **派生视图**：供展示与下游只读消费，门禁不读 |
+| 输入 | 计划文档的「风险等级」正则 + capabilityGates 信号 | 自然输入里手填的 `risk_signals` |
+
+**两者不共用文件名。** v2 发布对 `binding.ownership_paths` 逐个原子覆盖，若派生视图占用 `meta/gate-policy.json`，阶段 8 会把 classify 写的那份换成包装体，之后 `gate begin --phase run` 直接 `POLICY_LOAD_FAILED`——`harness_gate.effective_workflow_policy` 读 `schemaVersion` 拿不到就 raise。
+
+**为什么派生视图目前不能当权威**（将来要接通就得先解决这两条）：
+
+1. `plan evidence-pack` 对 `risk_signals` **不做任何推断**——不读 git diff、不扫路径、不解析 frontmatter，值完全来自自然输入里手填的那个数组。拿它当门禁权威等于让 agent 自声明低风险来跳门禁。
+2. 命令里的 `capabilities` 是写死的（`is_git:true, has_remote:true, uses_worktree:false`），用户在阶段 0.6 通过 `configure-plan` 选的阶段计划被完全忽略，`planned_phases` 退化成 mode 的纯函数。
+
+`meta/implementation-checkpoints.json` 的情况不同：v2 包装体里的 `content.foundation_gate` 信息是够的，所以门禁在**只读侧**解包（`checkpoint_status` 同时认 `checkpoints[]`、顶层 `foundationGate` 与 v2 包装体三种形状），不改文件名。注意写回路径（`gate checkpoint approve`）仍然操作原始文档——用归一化结构覆盖会破坏 v2 产物的哈希绑定。
+
 ### 阶段 8 v2 路径（结构化证据包流程，新 change 优先）
 
 阶段 8 v2 标准三步流（证据包自举，阶段 14 起可用）：
@@ -422,13 +442,22 @@ npx hunter-harness plan finalize --input .harness/changes/<cn>/meta/plan-evidenc
 | `context` | project_id/run_id/branch_name/attempt（复用 plan-run-id 与 attempt） | 0.5 |
 | `expected_baseline` | 首次发布 `{state:"absent", manifest_hash:null, generation:0}` | 8 |
 
-> ⚠️ **已知缺口：v2 派生的 `meta/scenario-manifest.json` 目前喂不了 run/test 门禁。**
-> 它是 artifact 包装体，每条场景只有 `scenario_id/coverage_dimension/execution_level/
-> evidence_requirements/risk_level/task_refs/requirement_refs`；而门禁按
-> `id/priority/requiredEvidenceKind/ownerPhase/executableTestId/testFile/testTitle`
-> 判定哪些场景需要 ledger 证据。缺 `priority` 与 `requiredEvidenceKind` 时"必需场景"会算成空集，
-> 所以门禁**明确报 `SCENARIO_MANIFEST_V2_UNSUPPORTED` 并列出 `missingFields`，绝不静默放行**。
-> 需要 ledger 证据闭环的变更，在 v2 场景契约补齐这些字段前请走 legacy 路径。
+> **场景契约与门禁的对接**（曾经的已知缺口，现已打通）
+>
+> v2 派生的 `meta/scenario-manifest.json` 是 artifact 包装体，键名与门禁消费的不同。消费端
+> （`harness_gate` 的 C9、`harness_ledger` 的三处）统一调 `harness_plan_finalize.unpack_v2_scenario_manifest`
+> 解成 legacy 形状再判定：`scenario_id→id`、`owner_phase→ownerPhase`、`required_evidence_kind→requiredEvidenceKind`
+> 、可执行三元 `executable_test_id/test_file/test_title→executableTestId/testFile/testTitle`。
+> `required_evidence_kind` 由 `priority` 派生（P0/P1→`ledger`，P2→`advisory`），写在 artifact 里，
+> 消费侧不重推。
+>
+> 因此自然输入的 `scenarios` **必须**带 `priority`（P0/P1/P2）与 `owner_phase`。缺任一项，
+> 门禁**逐场景**校验后报 `SCENARIO_MANIFEST_V2_UNSUPPORTED` 并列出 `missingFields`，绝不静默放行
+> ——逐场景而不是取键的并集：并集只要有一条场景带了 `priority` 就算通过，其余缺字段的会静默
+> 落进非必需集，"必需场景"随之缩水。
+>
+> 可执行三元是**可选**的，但要么整组给全、要么整组省略。ledger 场景全部带齐 → manifest 声明
+> `schemaVersion 2`，关门可绑结构化执行收据；否则降为 1。
 
 - **证据包**（`plan-evidence.json`）是命令推导的产物（trusted/publication/context/baseline），不得手改；任何字段变化必须改自然输入后重跑 evidence-pack。
 - **成功语义**：finalize exit 0 且 `code:"PLAN_FINALIZED"`。落盘事实 = 八 target（plans/*.md ×4 + meta/*.json ×4）+ `meta/publication-journals/<op>.json`（状态 committed）+ `meta/plan-events.ndjson`（artifact_published/phase_ended）。确定性门失败 exit 1 且 `code:"PLAN_FINALIZE_DETERMINISTIC_FAILED"` 附 findings——此时必须回到对应阶段修正规划内容，**不得**手改证据包或 staged 内容绕过。

package/harness/bundles/java/codex/harness-pull/SKILL.md

@@ -3,7 +3,7 @@ name: harness-pull
 description: 从 Hunter Platform 下拉配置/规则/架构/指令（及显式来源分支的分支文件恢复）。仅当用户显式调用
   /harness-pull 或明确说'从平台拉取/恢复'时使用；不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-pull — 从 Hunter Platform 下拉与恢复
 
 ## Purpose

package/harness/bundles/java/codex/harness-push/SKILL.md

@@ -3,7 +3,7 @@ name: harness-push
 description: 上传本地配置/规则/架构/指令（及显式归档）到 Hunter Platform。仅当用户显式调用 /harness-push
   或明确说'上传到平台'时使用；不得因存在本地修改就自动触发。
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-push — 上传到 Hunter Platform
 
 ## Purpose

package/harness/bundles/java/codex/harness-review/SKILL.md

@@ -4,7 +4,7 @@ description: 6维度代码审查（架构/安全/规范/兼容/测试/性能）
   .harness/context-index.json）和测试场景表，在隔离上下文运行。仅当用户显式调用 /harness-review 时使用；不得在
   test 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/java/codex/harness-run/SKILL.md

@@ -3,7 +3,7 @@ name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。仅当用户显式调用
   /harness-run 时使用；不得因用户提到编码/实现就自动触发，也不得被其他阶段 skill 自动接续。
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose
@@ -83,13 +83,15 @@ python <skills-root>/scripts/harness_test_runner.py exec --project . --timeout-s
 
 返回 `TEST_RUN_ALREADY_ACTIVE`（退出码 3）说明**已有构建在跑**：等它结束或用 `lock-status` 查明持有者，**不得**改用裸跑绕开锁，也不得另起一个并行构建。确认持有进程已消失时才用 `lock-reap` 回收。
 
-**长阶段租约续期**：`gate begin` 的租约默认 TTL 3600 秒，而 run 阶段常常跑得更久。租约过期不会中断执行，只会让最后的 `gate close` 报 `LEASE_ABSENT`。凡预计超过 1 小时的阶段，每完成一个变更簇就用本阶段**原 run-id** 续租一次（同 run-id 重复 claim 即刷新，不会新开 attempt）：
+**长阶段租约**：`gate begin` 的租约默认 TTL 3600 秒，而 run 阶段常常跑得更久。租约过期不会中断执行，**也不再阻断收尾**：`gate close` 发现租约过期而 run-id 仍是本阶段的，会自动用原 run-id 重取并照常关门，只在返回体的 `leaseLapsed` 里记下这个阶段跑过了 TTL。过期本身不说明所有权变了——抢占会重写租约文件把 run-id 换掉，那时报的是 `LEASE_OWNER_MISMATCH`。
+
+因此**不需要**为了长阶段定期续租。确实想让租约始终有效时，用本阶段原 run-id 刷新即可（同 run-id 重复 claim 即刷新，不会新开 attempt）：
 
 ```text
 python <skills-root>/scripts/harness_change.py claim --change <id> --phase run --run-id <本阶段 run-id> --ttl-seconds 3600 --json
 ```
 
-已经报了 `LEASE_ABSENT` 也按同一条命令恢复——错误响应的 `resumeRunId` 就是要用的 run-id；**不要**重跑 `gate begin`，那会新开 attempt 并丢失本轮 capsule。
+仍然报 `LEASE_ABSENT` 说明这个阶段**根本没有租约记录**（从未 begin，或已被释放），不是超时；先确认 `gate begin` 真的跑过。报 `LEASE_INVALID` 说明租约文件损坏，无法证明没被抢占，需人工确认无并发后再用上面的命令重取。两种情况都**不要**重跑 `gate begin`——那会新开 attempt 并丢失本轮 capsule。
 
 **执行器边界**：优先使用项目 build profile 和已有测试入口。禁止为了绕过 ESM、路径或参数问题临时生成 `.js`、`require` 脚本；需要文件式 runner 时使用项目已有入口，确需新增时遵循项目模块类型（例如 ESM 使用 `.mjs`）。runner 包装说明写入 `runnerCommand` 元数据，不得拼进账本的规范 `command`。
 
@@ -131,7 +133,7 @@ python <skills-root>/scripts/harness_change.py claim --change <id> --phase run -
 | **关门/状态** | 10 项关门检查；持久化 run-task-status；仅 run-owned P0 静态-only 导致 WARN；test-owned 待办正常移交 |
 | **Worktree** | `requested=true` 时代码只写 worktree |
 | **构建/测试** | 一律经 `harness_test_runner.py exec`；禁止裸跑 mvn/gradle/npm test；`TEST_RUN_ALREADY_ACTIVE` 表示已有构建在跑，等待而非另起 |
-| **租约** | 阶段超 1 小时按变更簇用原 run-id 续租；`LEASE_ABSENT` 用 `harness_change.py claim` 恢复，不重跑 begin |
+| **租约** | 阶段超 TTL 由 close 自动用原 run-id 重取，无需续租；`LEASE_ABSENT`（无记录）/`LEASE_INVALID`（文件损坏）才需人工 `harness_change.py claim`，一律不重跑 begin |
 | **PowerShell** | 所有 git 经 `powershell.exe -NoProfile -Command` |
 
 ### 陈旧测试安全修复与精确跟踪

package/harness/bundles/java/codex/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff 合并回主分支。仅当用户显式调用
   /harness-submit（或 /harness-merge 重入合并段）时使用；用户口头说'提交/commit/push'时必须先确认，不得自动触发。
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/java/codex/harness-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Use when the user asks to synchronize, refresh, or validate Harness
   metadata, adapters, remote knowledge ownership, instruction entrypoints,
   config origins, or CodeGraph status.
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-sync
 
 ## Purpose

package/harness/bundles/java/codex/harness-test/SKILL.md

@@ -3,7 +3,7 @@ name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
   时使用；不得在 run 结束后自动接续执行。
 ---
-<!-- generated by harness_deploy.py; core=02679a6652ba3eaa; overlay=java; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=874039c57f9d1bc4; overlay=java; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -564,18 +564,36 @@ def _lease_expired(lease: dict[str, Any]) -> bool:
     return dt.datetime.now().astimezone() >= exp_dt
 
 
-def inspect_lease(project_root: Path, change_id: str) -> dict[str, Any] | None:
-    """Return the current non-expired lease without mutating it."""
+def inspect_lease_state(project_root: Path, change_id: str) -> dict[str, Any]:
+    """Read the lease without mutating it, keeping the three failure modes apart.
+
+    ``inspect_lease`` collapses absent / expired / corrupt into ``None``, so a
+    caller cannot tell "nobody ever held this" from "the phase outlived its
+    TTL". Those need different answers: an expired lease still carries the
+    runId that proves who owns the phase, a corrupt one proves nothing, and an
+    absent one may just mean the phase already closed.
+
+    state is one of ``active`` | ``expired`` | ``absent`` | ``corrupt``. The
+    lease dict is returned for ``active`` and ``expired``; ``None`` otherwise.
+    """
     path = _lease_path(project_root, change_id)
     if not path.is_file():
-        return None
+        return {"state": "absent", "lease": None}
     try:
         lease = _read_json(path)
     except (OSError, json.JSONDecodeError):
-        return None
-    if not isinstance(lease, dict) or _lease_expired(lease):
-        return None
-    return lease
+        return {"state": "corrupt", "lease": None}
+    if not isinstance(lease, dict):
+        return {"state": "corrupt", "lease": None}
+    if _lease_expired(lease):
+        return {"state": "expired", "lease": lease}
+    return {"state": "active", "lease": lease}
+
+
+def inspect_lease(project_root: Path, change_id: str) -> dict[str, Any] | None:
+    """Return the current non-expired lease without mutating it."""
+    state = inspect_lease_state(project_root, change_id)
+    return state["lease"] if state["state"] == "active" else None
 
 
 def _claim_lease_locked(

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

@@ -21,6 +21,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 import harness_ledger as hl  # noqa: E402
+import harness_paths as hpaths  # noqa: E402
 
 
 PHASE_GRAPH = {
@@ -31,17 +32,8 @@ PHASE_GRAPH = {
     "submit": (),
 }
 
-WORKFLOW_PHASES = (
-    "plan",
-    "run",
-    "test",
-    "review",
-    "package",
-    "apidoc",
-    "submit",
-    "merge",
-    "archive",
-)
+# 唯一权威清单在 harness_paths（叶子模块，harness_phase 引的是同一个对象）。
+WORKFLOW_PHASES = hpaths.WORKFLOW_PHASES
 
 DISPLAY_TITLE_MAX_LENGTH = 80
 
@@ -270,13 +262,24 @@ def _contract(project: Path, change: str) -> tuple[Path, dict[str, Any], Path]:
 
 
 def _phase_plan(contract_root: Path) -> tuple[list[str] | None, str]:
+    """读出阶段计划；无法采信时说明原因，而不是悄悄退成 legacy。
+
+    以前这里遇到未知阶段名一律返回 (None, "legacy")：阶段计划整个失效，
+    `_allowed_next_phases` 退回硬编码的 PHASE_GRAPH，而调用方看不出发生过这件事。
+    未知阶段名不是假想问题——阶段清单少一个 merge 时，worktree 变更的
+    plannedPhases 就会带着 merge 走到这里。
+
+    未知名先过 LEGACY_PHASE_ALIASES 读时映射（阶段改名后历史 change 靠它继续可读），
+    仍然解析不了才降级，并把原因与具体阶段名带在 source 里。
+    """
     policy_path = contract_root / "meta" / "gate-policy.json"
     if not policy_path.is_file():
         return None, "legacy"
     try:
         policy = _read_json(policy_path)
     except (OSError, ValueError, json.JSONDecodeError):
-        return None, "legacy"
+        return None, "legacy:policy-unreadable"
+    unknown: list[str] = []
     for field, source in (
         ("plannedPhases", "change"),
         ("defaultPhases", "policy-default"),
@@ -285,12 +288,17 @@ def _phase_plan(contract_root: Path) -> tuple[list[str] | None, str]:
         if not isinstance(raw, list):
             continue
         phases = [str(item).strip() for item in raw if str(item).strip()]
-        if (
-            phases
-            and len(phases) == len(set(phases))
-            and all(item in WORKFLOW_PHASES for item in phases)
-        ):
-            return phases, source
+        if not phases or len(phases) != len(set(phases)):
+            continue
+        resolved = [hpaths.resolve_phase_name(item) for item in phases]
+        missing = [item for item, hit in zip(phases, resolved) if hit is None]
+        if missing:
+            unknown.extend(missing)
+            continue
+        # 映射后可能出现重复（两个旧名合并成同一个新阶段），保序去重。
+        return list(dict.fromkeys(str(item) for item in resolved)), source
+    if unknown:
+        return None, "legacy:unknown-phases=" + ",".join(dict.fromkeys(unknown))
     return None, "legacy"
 
 
@@ -405,6 +413,7 @@ def _paths(state_root: Path) -> dict[str, Path]:
         "begins": runtime / "transition-begins.ndjson",
         "current": runtime / "current-context.json",
         "lease": runtime / "context-lease.json",
+        "adoptions": runtime / "context-adoptions.ndjson",
     }
 
 
@@ -604,8 +613,14 @@ def _claim_prepared_context(
             )
         except (OSError, ValueError, json.JSONDecodeError):
             return {"ok": False, "code": "CONTEXT_CURRENT_INVALID"}
+        # 跨阶段推进必须有 receipt 证明它合法；同一个阶段换执行者不需要。
+        # 以前两者都要 receipt，于是上一阶段崩溃没能正常 close 时，接手的工具
+        # 连"继续把这个阶段干完"都做不到。并发保护不受影响：租约未过期而
+        # owner 不同，上面 CONTEXT_LEASE_HELD 已经拦下了，能走到这里只剩
+        # 「租约已过期」和「租约已被上一阶段 close 删除」两种情况。
+        adoption: dict[str, Any] | None = None
         if recovery is None and isinstance(current, dict) and (
-            current.get("executor") != executor or current.get("phase") != phase
+            current.get("phase") != phase
         ):
             valid_receipt = (
                 isinstance(latest, dict)
@@ -621,6 +636,19 @@ def _claim_prepared_context(
                     "toExecutor": executor,
                     "toPhase": phase,
                 }
+        executor_changed = (
+            isinstance(current, dict) and current.get("executor") != executor
+        )
+        if recovery is not None or executor_changed:
+            adoption = {
+                "previousExecutor": (
+                    current.get("executor") if isinstance(current, dict) else None
+                ),
+                "newExecutor": executor,
+                "reason": (
+                    "lease_expired" if recovery is not None else "same_phase_handoff"
+                ),
+            }
 
         try:
             execution_root = _execution_root(project, contract_root, state_root)
@@ -657,6 +685,20 @@ def _claim_prepared_context(
             current_context["preparationId"] = preparation_id
         _write_json_atomic(paths["lease"], lease)
         _write_json_atomic(paths["current"], current_context)
+        if adoption is not None:
+            # 接管必须留痕。过期租约本来就允许任何执行者顶替，但以前只在返回体
+            # 里挂一个 recovery，退出进程就没了——事后查"这个阶段是谁接手的"
+            # 无据可依。收据形状照 harness_archive.adopt_existing_range。
+            adoption = {
+                "schemaVersion": 1,
+                "changeName": change,
+                "phase": phase,
+                **adoption,
+                "previousOwner": recovery.get("previousOwner") if recovery else None,
+                "expiredAt": recovery.get("expiredAt") if recovery else None,
+                "adoptedAt": now.isoformat(),
+            }
+            _append_ndjson(paths["adoptions"], adoption)
         return {
             "ok": True,
             "lease": lease,
@@ -664,6 +706,7 @@ def _claim_prepared_context(
             "transitions": transitions,
             "latestTransition": latest,
             "recovery": recovery,
+            "adoption": adoption,
             "executionRoot": str(execution_root),
         }
 

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

@@ -405,6 +405,10 @@ def _default_gate_begin(**kwargs: Any) -> dict[str, Any]:
         str(kwargs["run_id"]),
         "--note",
         "开始处理评审中确认需要修改的代码问题。",
+        # 显式标记这一轮是 review fixback。以前靠 gate 嗅探 note 里有没有
+        # "fixback" 字样——而上面这条 note 一个都没有，于是 fixback 的 run 事件
+        # 从来没被打上 trigger/from_phase。
+        "--fixback",
     ]
     for option, key in (
         ("--executor-tool", "executor_tool"),