@hunter-harness/workflow-harness 0.2.55 → 0.2.56

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

@@ -11,6 +11,7 @@ import os
 import re
 import tempfile
 import sys
+import uuid
 from pathlib import Path
 from typing import Any
 
@@ -19,6 +20,7 @@ if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
 from harness_paths import resolve_state_dir_for_contract
+import harness_events as he
 
 
 SCHEMA_VERSION = 1
@@ -96,6 +98,171 @@ def _all_batches(change_dir: Path) -> list[dict[str, Any]]:
     return batches
 
 
+def _session_path(change_dir: Path) -> Path:
+    return _state_root(change_dir) / "runtime" / "fixback-session.json"
+
+
+def _next_step(batch: dict[str, Any]) -> str:
+    issues = [item for item in batch.get("issues", []) if isinstance(item, dict)]
+    if not issues:
+        return "add-issues"
+    if any(item.get("status") != "RESOLVED" for item in issues):
+        return "resolve-issues"
+    receipts = batch.get("receipts") if isinstance(batch.get("receipts"), dict) else {}
+    if not receipts.get("affected"):
+        return "verify-affected"
+    if not receipts.get("review"):
+        return "review"
+    return "close"
+
+
+def resume_batch(
+    change_dir: Path,
+    *,
+    batch_id: str | None,
+    product_identity: str | None,
+    root_cause: str | None,
+    run_id: str | None,
+    attempt: int | None,
+) -> dict[str, Any]:
+    """Open once or resume the active Fixback session with a stable run identity."""
+    opened = [item for item in _all_batches(change_dir) if item.get("status") == "OPEN"]
+    resumed = bool(opened)
+    if opened:
+        batch = sorted(opened, key=lambda item: str(item.get("openedAt") or ""))[0]
+    else:
+        if not batch_id or not product_identity or not root_cause:
+            raise ValueError(
+                "FIXBACK_RESUME_INPUT_REQUIRED: new sessions require batch-id, "
+                "product-identity and root-cause"
+            )
+        batch = open_batch(
+            change_dir,
+            batch_id=batch_id,
+            product_identity=product_identity,
+            root_cause=root_cause,
+        )
+    session_path = _session_path(change_dir)
+    existing: dict[str, Any] = {}
+    if session_path.is_file():
+        try:
+            loaded = json.loads(session_path.read_text(encoding="utf-8-sig"))
+            existing = loaded if isinstance(loaded, dict) else {}
+        except (OSError, json.JSONDecodeError):
+            existing = {}
+    same_open_session = (
+        existing.get("status") == "ACTIVE"
+        and existing.get("batchId") == batch.get("batchId")
+    )
+    effective_run_id = (
+        str(existing.get("runId"))
+        if same_open_session and existing.get("runId")
+        else str(run_id or "fixback-" + uuid.uuid4().hex)
+    )
+    effective_attempt = (
+        int(existing.get("attempt"))
+        if same_open_session and isinstance(existing.get("attempt"), int)
+        else max(1, int(attempt or 1))
+    )
+    next_step = _next_step(batch)
+    session = {
+        "schemaVersion": 1,
+        "status": "ACTIVE",
+        "batchId": batch.get("batchId"),
+        "runId": effective_run_id,
+        "attempt": effective_attempt,
+        "nextStep": next_step,
+        "updatedAt": now_iso(),
+    }
+    _write_json(session_path, session)
+    he.append_event(
+        change_dir,
+        phase="run",
+        type_="decision",
+        note=(
+            "已恢复现有修复批次，将从未完成步骤继续。"
+            if resumed
+            else "已创建修复批次，将按问题逐项执行 RED/GREEN。"
+        ),
+        run_id=effective_run_id,
+    )
+    return {
+        "ok": True,
+        "code": "FIXBACK_RESUMED" if resumed else "FIXBACK_OPENED",
+        "resumed": resumed,
+        "batchId": batch.get("batchId"),
+        "runId": effective_run_id,
+        "attempt": effective_attempt,
+        "nextStep": next_step,
+        "requiredVerifications": batch.get("requiredVerifications", []),
+        "changedFiles": batch.get("changedFiles", []),
+        "sessionPath": str(session_path),
+    }
+
+
+def invalidate_affected_evidence(
+    change_dir: Path,
+    *,
+    changed_files: list[str],
+    batch_id: str,
+) -> dict[str, Any]:
+    """Invalidate only verification targets whose declared inputs were changed."""
+    normalized = {
+        str(path).replace("\\", "/").lstrip("./")
+        for path in changed_files
+        if str(path).strip()
+    }
+    ledger_path = _state_root(change_dir) / "evidence" / "verification-ledger.json"
+    if not normalized or not ledger_path.is_file():
+        return {"ok": True, "targetIds": [], "validations": []}
+    try:
+        ledger = json.loads(ledger_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        return {"ok": False, "code": "FIXBACK_LEDGER_INVALID"}
+    if not isinstance(ledger, dict):
+        return {"ok": False, "code": "FIXBACK_LEDGER_INVALID"}
+
+    def affected(entry: dict[str, Any]) -> bool:
+        inputs = entry.get("inputsFiles")
+        if not isinstance(inputs, list):
+            return False
+        input_set = {
+            str(path).replace("\\", "/").lstrip("./")
+            for path in inputs
+            if str(path).strip()
+        }
+        return bool(normalized & input_set)
+
+    invalidation = {
+        "code": "FIXBACK_AFFECTED_INPUT_CHANGED",
+        "batchId": batch_id,
+        "changedFiles": sorted(normalized),
+        "invalidatedAt": now_iso(),
+    }
+    target_ids: list[str] = []
+    targets = ledger.get("verificationTargets")
+    if isinstance(targets, dict):
+        for target_id, target in targets.items():
+            if isinstance(target, dict) and affected(target):
+                target["reusable"] = False
+                target["invalidation"] = dict(invalidation)
+                target_ids.append(str(target_id))
+    validation_names: list[str] = []
+    validations = ledger.get("validations")
+    if isinstance(validations, dict):
+        for name, entry in validations.items():
+            if isinstance(entry, dict) and affected(entry):
+                entry["reusable"] = False
+                entry["invalidation"] = dict(invalidation)
+                validation_names.append(str(name))
+    _write_json(ledger_path, ledger)
+    return {
+        "ok": True,
+        "targetIds": sorted(target_ids),
+        "validations": sorted(validation_names),
+    }
+
+
 def _required_verifications(issues: list[dict[str, Any]]) -> list[str]:
     required = {"affected", "review"}
     for issue in issues:
@@ -506,6 +673,11 @@ def resolve_issue(
         }
     )
     batch["updatedAt"] = resolved_at
+    batch["invalidation"] = invalidate_affected_evidence(
+        change_dir,
+        changed_files=[record["path"] for record in changed_records],
+        batch_id=batch_id,
+    )
     _write_json(_batch_path(change_dir, batch_id), batch)
     return issue
 
@@ -652,6 +824,13 @@ def _emit(value: dict[str, Any]) -> int:
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="harness_fixback.py")
     sub = parser.add_subparsers(dest="command", required=True)
+    resume = sub.add_parser("resume")
+    resume.add_argument("--change-dir", required=True)
+    resume.add_argument("--batch-id")
+    resume.add_argument("--product-identity")
+    resume.add_argument("--root-cause")
+    resume.add_argument("--run-id")
+    resume.add_argument("--attempt", type=int)
     opened = sub.add_parser("open")
     opened.add_argument("--change-dir", required=True)
     opened.add_argument("--batch-id", required=True)
@@ -692,7 +871,16 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     change_dir = Path(args.change_dir)
     try:
-        if args.command == "open":
+        if args.command == "resume":
+            value = resume_batch(
+                change_dir,
+                batch_id=args.batch_id,
+                product_identity=args.product_identity,
+                root_cause=args.root_cause,
+                run_id=args.run_id,
+                attempt=args.attempt,
+            )
+        elif args.command == "open":
             value = open_batch(
                 change_dir,
                 batch_id=args.batch_id,

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

@@ -693,11 +693,12 @@ def validate_ledger_for_phase_close(
         try:
             current_repository = hp.repository_identity(root)
             current_ownership = hl.ownership_hash(contract)
-            current_diff = hl.compute_ownership_diff(
+            current_diff_detail = hl.compute_ownership_diff(
                 root,
                 base=str(ledger["baseCommit"]),
                 change_dir=change_dir,
-            )["diffHash"]
+            )
+            current_diff = current_diff_detail["diffHash"]
             current_head = _git_text(root, "rev-parse", "--verify", "HEAD")
         except (OSError, ValueError, RuntimeError) as exc:
             return {
@@ -727,6 +728,18 @@ def validate_ledger_for_phase_close(
                 "storedHead": ledger.get("currentHead"),
                 "currentHead": current_head,
                 "ledgerPath": str(ledger_path) if ledger_path else None,
+                "pathSummary": {
+                    "ownedFiles": list(current_diff_detail.get("files") or [])[:20],
+                    "foreignPaths": list(current_diff_detail.get("foreignPaths") or [])[:20],
+                    "ownedFileCount": current_diff_detail.get("ownedFileCount", 0),
+                    "excludedRuntimeCount": current_diff_detail.get(
+                        "excludedRuntimeCount", 0
+                    ),
+                },
+                "recoveryAction": (
+                    "先确认新增、删除或越界路径是否属于当前变更；更新所有权后，"
+                    "只重新执行受影响的验证，再原样重试 close。"
+                ),
             }
 
     problems: list[dict[str, Any]] = []
@@ -1713,6 +1726,98 @@ def record_blocked_attempt(
     )
 
 
+def record_gate_blocked(
+    change_dir: Path,
+    *,
+    phase: str,
+    code: str,
+    message: str,
+    run_id: str | None = None,
+) -> dict[str, Any]:
+    """Persist a recoverable gate rejection without manufacturing a phase run."""
+    return append_phase_event(
+        change_dir,
+        phase=phase,
+        type_="gate.blocked",
+        status="BLOCKED",
+        note=message,
+        run_id=run_id or "blocked-" + uuid.uuid4().hex[:12],
+        code=code,
+    )
+
+
+def record_gate_recovered(
+    change_dir: Path,
+    *,
+    phase: str,
+    run_id: str,
+) -> dict[str, Any]:
+    """Close the latest unresolved gate.blocked record for this phase."""
+    blocked: dict[str, Any] | None = None
+    for event in reversed(he.load_events(he.events_path(change_dir))):
+        if event.get("phase") != phase:
+            continue
+        if event.get("type") == "gate.recovered":
+            break
+        if event.get("type") == "gate.blocked":
+            blocked = event
+            break
+    if blocked is None:
+        return {"ok": True, "skipped": True, "reason": "no-unresolved-block"}
+    return append_phase_event(
+        change_dir,
+        phase=phase,
+        type_="gate.recovered",
+        status="OK",
+        note="阶段交接已恢复，门禁现已成功启动。",
+        run_id=run_id,
+        code=str(blocked.get("code") or "GATE_BLOCKED"),
+    )
+
+
+def validate_context_for_gate_begin(
+    project: Path,
+    change_id: str,
+    phase: str,
+) -> dict[str, Any]:
+    """Require a completed Context handoff whenever modern Context state exists."""
+    view = hctx.context_view(project, change_id)
+    if not isinstance(view, dict) or not view.get("ok"):
+        return {"ok": True, "code": "CONTEXT_LEGACY_COMPATIBLE"}
+    current = view.get("current")
+    transitions = view.get("transitions")
+    begins = (view.get("attemptHistory") or {}).get("begins")
+    if not isinstance(current, dict):
+        return {"ok": True, "code": "CONTEXT_LEGACY_COMPATIBLE"}
+    current_phase = str(current.get("phase") or view.get("currentPhase") or "")
+    if current_phase != phase:
+        return {
+            "ok": False,
+            "code": "CONTEXT_HANDOFF_REQUIRED",
+            "message": "阶段交接尚未完成，门禁未启动；请先完成上下文交接。",
+            "expectedPhase": current_phase or None,
+            "requestedPhase": phase,
+        }
+    if isinstance(transitions, list) and transitions:
+        latest = transitions[-1] if isinstance(transitions[-1], dict) else {}
+        receipt_hash = latest.get("receiptHash")
+        begin_items = begins if isinstance(begins, list) else []
+        acknowledged = any(
+            isinstance(item, dict)
+            and item.get("phase") == phase
+            and item.get("receiptHash") == receipt_hash
+            for item in begin_items
+        )
+        if latest.get("toPhase") != phase or not acknowledged:
+            return {
+                "ok": False,
+                "code": "CONTEXT_BEGIN_REQUIRED",
+                "message": "阶段交接收据尚未确认，门禁未启动；请先执行上下文 begin。",
+                "requestedPhase": phase,
+            }
+    return {"ok": True, "code": "CONTEXT_READY"}
+
+
 def _phase_event_exists(change_dir: Path, phase: str, type_: str, run_id: str) -> bool:
     return any(
         event.get("phase") == phase
@@ -2065,6 +2170,32 @@ def cmd_begin(args: argparse.Namespace) -> int:
             extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
         )
     change_dir = Path(resolved["changeDir"])
+    context_check = validate_context_for_gate_begin(
+        project, str(resolved["changeId"]), args.phase
+    )
+    if not context_check.get("ok"):
+        code = str(context_check.get("code") or "CONTEXT_HANDOFF_REQUIRED")
+        message = str(
+            context_check.get("message")
+            or "阶段交接尚未完成，门禁未启动。"
+        )
+        record_gate_blocked(
+            change_dir,
+            phase=args.phase,
+            code=code,
+            message=message,
+            run_id=args.run_id or os.environ.get("HUNTER_HARNESS_RUN_ID"),
+        )
+        return emit_error(
+            code,
+            message,
+            as_json=as_json,
+            extra={
+                key: value
+                for key, value in context_check.items()
+                if key not in {"ok", "code", "message"}
+            },
+        )
     severity_mode = gate_severity_mode(project, change_dir)
     gate_warnings: list[dict[str, Any]] = []
     plan_verification: dict[str, Any] | None = None
@@ -2236,6 +2367,16 @@ def cmd_begin(args: argparse.Namespace) -> int:
                             message="test guard begin failed (downgraded to WARN)",
                         ))
                     else:
+                        record_gate_blocked(
+                            change_dir,
+                            phase=args.phase,
+                            code=str(
+                                guard_result.get("code")
+                                or "TEST_GUARD_BEGIN_FAILED"
+                            ),
+                            message="测试保护快照建立失败，已停止阶段启动。",
+                            run_id=run_id,
+                        )
                         hc.release_lease(
                             project,
                             change_id=resolved["changeId"],
@@ -2252,6 +2393,11 @@ def cmd_begin(args: argparse.Namespace) -> int:
             current_head = _git_text(execution_root, "rev-parse", "--verify", "HEAD")
             ledger, _ = hl.load_ledger(change_dir)
             base_commit = ledger.get("baseCommit") if isinstance(ledger, dict) else None
+            try:
+                begin_contract = hp.load_change_contract(change_dir)
+                begin_ownership_hash = hl.ownership_hash(begin_contract)
+            except (OSError, ValueError, json.JSONDecodeError):
+                begin_ownership_hash = None
             capsule = {
                 "schemaVersion": 1,
                 "changeId": resolved["changeId"],
@@ -2264,6 +2410,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 "repositoryId": hp.repository_identity(execution_root),
                 "baseCommit": base_commit or current_head,
                 "currentHead": current_head,
+                "ownershipHash": begin_ownership_hash,
                 "createdAt": he.now_iso(),
                 "projectionReceipt": projection,
             }
@@ -2281,6 +2428,11 @@ def cmd_begin(args: argparse.Namespace) -> int:
                 executor_agent=args.executor_agent or os.environ.get("HUNTER_HARNESS_AGENT"),
                 executor_model=args.executor_model or os.environ.get("HUNTER_HARNESS_MODEL"),
             )
+        recovery_result = record_gate_recovered(
+            change_dir,
+            phase=args.phase,
+            run_id=run_id,
+        )
     except BaseException:
         hc.release_lease(
             project, change_id=resolved["changeId"], phase=args.phase, run_id=run_id
@@ -2300,6 +2452,7 @@ def cmd_begin(args: argparse.Namespace) -> int:
         "lease": claim.get("lease"),
         "identity": identity,
         "event": event_result,
+        "gateRecovery": recovery_result,
         "testGuard": guard_result,
         "policySchemaVersion": policy.get("schemaVersion"),
         "planVerification": plan_verification,
@@ -2568,6 +2721,16 @@ def cmd_close(args: argparse.Namespace) -> int:
             status="LEDGER_VALIDATION_FAILED",
             error=ledger_result,
         )
+        record_gate_blocked(
+            change_dir,
+            phase=args.phase,
+            code=str(ledger_result.get("code") or "LEDGER_INVALID"),
+            message=(
+                "验证记录与当前变更身份不一致，已保留现场；"
+                "请按返回的路径摘要重新验证受影响范围。"
+            ),
+            run_id=run_id,
+        )
         return emit_error(
             str(ledger_result.get("code", "LEDGER_INVALID")),
             str(ledger_result.get("message", "ledger validation failed")),
@@ -2656,6 +2819,16 @@ def cmd_close(args: argparse.Namespace) -> int:
                             "updatedAt": he.now_iso(),
                         })
                         write_phase_capsule(change_dir, args.phase, run_id, capsule)
+                    record_gate_blocked(
+                        change_dir,
+                        phase=args.phase,
+                        code=str(
+                            guard_result.get("code")
+                            or "TEST_GUARD_CLOSE_FAILED"
+                        ),
+                        message="测试保护关门失败，已保留现场并等待同一命令恢复。",
+                        run_id=run_id,
+                    )
                     return emit_error(
                         str(guard_result.get("code", "TEST_GUARD_CLOSE_FAILED")),
                         "test guard close failed",
@@ -2741,6 +2914,13 @@ def cmd_close(args: argparse.Namespace) -> int:
     )
     platform_monitor = _sync_after_phase_close(project, change_dir)
     if isinstance(context_handoff, dict) and not context_handoff.get("ok"):
+        record_gate_blocked(
+            change_dir,
+            phase=args.phase,
+            code=str(context_handoff.get("code") or "PHASE_HANDOFF_PENDING"),
+            message="阶段本地关门已完成，但上下文交接尚待恢复。",
+            run_id=run_id,
+        )
         return emit_error(
             "PHASE_HANDOFF_PENDING",
             "phase gate closed locally, but context handoff failed; retry the same close command",
@@ -2756,6 +2936,11 @@ def cmd_close(args: argparse.Namespace) -> int:
             },
         )
 
+    recovery_result = record_gate_recovered(
+        change_dir,
+        phase=args.phase,
+        run_id=run_id,
+    )
     payload = {
         "ok": True,
         "code": close_code,
@@ -2773,6 +2958,7 @@ def cmd_close(args: argparse.Namespace) -> int:
         "gateWarnings": gate_warnings,
         "contextHandoff": context_handoff,
         "platformMonitor": platform_monitor,
+        "gateRecovery": recovery_result,
     }
     emit(payload, as_json=as_json)
     return 0