@hunter-harness/workflow-harness 0.2.13 → 0.2.15

package/harness/bundles/java/claude-code/scripts/harness_events.py

@@ -50,6 +50,7 @@ EVENT_TYPES = frozenset(
         "issue.resolve",
         "decision",
         "correction",
+        "change.rename",
     }
 )
 
@@ -94,6 +95,9 @@ OPTIONAL_FIELDS = (
     "orchestration_active_ms",
     "wall_clock_ms",
     "user_wait_ms",
+    "renamed_from",
+    "renamed_to",
+    "change_uuid",
 )
 
 _PROVENANCE_FIELDS = frozenset(
@@ -144,6 +148,10 @@ _EVENT_ALLOWED_FIELDS = {
         }
     )
     | _PROVENANCE_FIELDS,
+    "change.rename": frozenset(
+        {"renamed_from", "renamed_to", "change_uuid", "note"}
+    )
+    | _PROVENANCE_FIELDS,
 }
 _EVENT_REQUIRED_FIELDS = {
     "issue": ("severity",),
@@ -506,6 +514,87 @@ def new_event_id(existing: list[dict[str, Any]] | None = None) -> str:
     return f"evt-{uuid.uuid4().hex}"
 
 
+def append_event(
+    change_dir: Path,
+    *,
+    phase: str,
+    type_: str,
+    note: str = "",
+    kind: str | None = None,
+    path: str | None = None,
+    run_id: str | None = None,
+    executor_tool: str | None = None,
+    renamed_from: str | None = None,
+    renamed_to: str | None = None,
+    change_uuid: str | None = None,
+) -> dict[str, Any]:
+    """Programmatic append API (retro §5.31 C5/T16).
+
+    Validates and appends an event without going through argparse. Returns
+    a payload dict with ``ok``/``code``/``event``.
+    """
+    args = argparse.Namespace(
+        change_dir=str(change_dir),
+        phase=phase,
+        type=type_,
+        note=note,
+        kind=kind,
+        path=path,
+        run_id=run_id,
+        executor_tool=executor_tool,
+        command=None,
+        exit_code=None,
+        duration_ms=None,
+        status=None,
+        name=None,
+        code=None,
+        severity=None,
+        message=None,
+        decision=None,
+        reason=None,
+        issue_id=None,
+        scope=None,
+        target_event_id=None,
+        target_field=None,
+        old_value_hash=None,
+        new_value_json=None,
+        renamed_from=renamed_from,
+        renamed_to=renamed_to,
+        change_uuid=change_uuid,
+        attempt=None,
+        executor_agent=None,
+        executor_model=None,
+        handoff_from_tool=None,
+        handoff_reason=None,
+        trace_id=None,
+        span_id=None,
+        parent_span_id=None,
+        runner_ms=None,
+        orchestration_active_ms=None,
+        wall_clock_ms=None,
+        user_wait_ms=None,
+        legacy_lenient=False,
+        json=True,
+    )
+    as_json = True
+    if type_ not in EVENT_TYPES:
+        return {"ok": False, "code": "EVENT_TYPE_INVALID", "message": f"unsupported type: {type_}"}
+    validation = validate_append_event(args)
+    if validation:
+        error_code, message = validation
+        return {"ok": False, "code": error_code, "message": message}
+    archived = archived_change_dir(change_dir)
+    if archived is not None:
+        return {"ok": False, "code": "ARCHIVED_CHANGE_IMMUTABLE", "message": str(archived)}
+    events_path_obj = events_path(change_dir)
+    lock_path = events_path_obj.with_name(events_path_obj.name + ".lock")
+    existing = []
+    event = build_event(args, existing)
+    with event_file_lock(lock_path):
+        atomic_append_line(events_path_obj, json.dumps(event, ensure_ascii=False))
+    return {"ok": True, "event": event, "events_path": str(events_path_obj), "rendered": False}
+
+
 def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dict[str, Any]:
     event: dict[str, Any] = {
         "schema_version": SCHEMA_VERSION,
@@ -588,8 +677,31 @@ def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
         except json.JSONDecodeError as exc:
             return (
                 "CORRECTION_VALUE_INVALID_JSON",
-                f"CORRECTION_VALUE_INVALID_JSON: {exc.msg}",
+                f"CORRECTION_VALUE_INVALID_JSON: {exc}",
+            )
+    # Retro §5.31: artifact events must distinguish file-backed from
+    # informational. file-backed requires a change-relative path; informational
+    # (preview/summary) must not masquerade as a file artifact. Legacy kind
+    # values (ledger, report, etc.) are treated as file-backed aliases.
+    if event_type == "artifact":
+        kind = str(getattr(args, "kind", "") or "").strip()
+        path = str(getattr(args, "path", "") or "").strip()
+        is_informational = kind == "informational"
+        if kind == "file-backed" and not path:
+            return (
+                "ARTIFACT_PATH_REQUIRED",
+                "ARTIFACT_PATH_REQUIRED: file-backed artifact requires --path",
+            )
+        # If kind is explicitly informational, path is optional. If kind is
+        # absent and path is absent, reject (can't infer file-backed without path).
+        if not kind and not path:
+            return (
+                "ARTIFACT_PATH_REQUIRED",
+                "ARTIFACT_PATH_REQUIRED: artifact without --kind or --path is ambiguous; "
+                "use --kind informational for previews or --path for file artifacts",
             )
+        # If no kind is provided, infer from path presence: a path implies
+        # file-backed, absence implies informational (legacy compatibility).
     return None
 
 

package/harness/bundles/java/claude-code/scripts/harness_gate.py

@@ -329,6 +329,12 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[
 
     Returns ``(missing_fields, degraded_ok)`` where ``degraded_ok`` is True only when
     the entry is a valid DEGRADED NOT_RUN record with no other missing fields.
+
+    Retro §5.14: ``status=OK``/``status=NOT_RUN``/``status=FAIL`` in the
+    missing list is a *status value* hint, not a field-completeness defect.
+    Callers consuming this under ``phase_status=FAIL`` must filter out
+    ``status=*`` entries from the missing list before treating them as
+    blocking problems.
     """
     missing: list[str] = []
     degraded = is_degraded_ledger_entry(entry)
@@ -341,7 +347,7 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[
                 missing.append("inputsFiles(non-empty)")
         elif field == "status":
             if value != "OK" and not degraded:
-                missing.append("status=OK")
+                missing.append(f"status={value}")
         elif not (isinstance(value, str) and value.strip()):
             missing.append(field)
         elif field == "coverage" and str(value).strip() not in hl.COVERAGE_RANK:
@@ -357,8 +363,16 @@ def validate_ledger_for_phase_close(
     policy: dict[str, Any],
     *,
     execution_root: Path | None = None,
+    phase_status: str = "OK",
 ) -> dict[str, Any]:
-    """Validate ledger v2 fields required for phase close (UT-026)."""
+    """Validate ledger v2 fields required for phase close (UT-026).
+
+    Retro §5.14: ``phase_status`` separates phase outcome from promotion gate.
+    ``phase_status=OK`` (default) requires all required validations to be OK;
+    ``phase_status=FAIL`` validates field completeness and identity but allows
+    individual validation status to be FAIL/NOT_RUN, so a failing phase can
+    close honestly without polluting evidence or blocking lease release.
+    """
     required = policy.get("requiredValidations", {}).get(phase, [])
     if not required:
         return {"ok": True, "code": "LEDGER_NOT_REQUIRED", "phase": phase}
@@ -443,6 +457,7 @@ def validate_ledger_for_phase_close(
 
     problems: list[dict[str, Any]] = []
     degraded: list[str] = []
+    fail_status: list[str] = []
     for verification in required:
         entry = validations.get(verification)
         if not isinstance(entry, dict):
@@ -455,6 +470,12 @@ def validate_ledger_for_phase_close(
             )
             continue
         missing, is_degraded = validate_ledger_entry_v2(entry, verification)
+        # Retro §5.14: under phase_status=FAIL/WARN, status value hints
+        # (status=FAIL, status=NOT_RUN) are acceptable; only real field-
+        # completeness defects block close. Under phase_status=OK, status
+        # value hints are blocking.
+        if phase_status.upper() in {"FAIL", "WARN"}:
+            missing = [m for m in missing if not m.startswith("status=")]
         if missing:
             code = (
                 "MISSING_V2_FIELDS"
@@ -476,8 +497,21 @@ def validate_ledger_for_phase_close(
                     "code": code,
                 }
             )
-        elif is_degraded:
+            continue
+        if is_degraded:
             degraded.append(verification)
+            continue
+        # Under phase_status=FAIL/WARN, a FAIL/NOT_RUN status is acceptable.
+        entry_status = str(entry.get("status") or "").upper()
+        if entry_status in {"FAIL", "NOT_RUN"}:
+            if phase_status.upper() in {"FAIL", "WARN"}:
+                fail_status.append(verification)
+            else:
+                problems.append({
+                    "verification": verification,
+                    "missing": [f"status={entry_status}"],
+                    "code": "VALIDATION_NOT_OK",
+                })
 
     if problems:
         return {
@@ -489,6 +523,16 @@ def validate_ledger_for_phase_close(
             "ledgerPath": str(ledger_path) if ledger_path else None,
             "detail": "natural-language override is not permitted",
         }
+    if fail_status:
+        return {
+            "ok": True,
+            "code": "LEDGER_OK_FAIL",
+            "phase": phase,
+            "validated": required,
+            "failed": fail_status,
+            "degraded": degraded,
+            "ledgerPath": str(ledger_path) if ledger_path else None,
+        }
     if degraded:
         return {
             "ok": True,
@@ -1169,6 +1213,14 @@ 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"])
+    concurrency_block = hc.check_concurrency_block(project, resolved["changeId"])
+    if concurrency_block is not None:
+        return emit_error(
+            str(concurrency_block.get("code", "CONCURRENCY_BLOCKED")),
+            str(concurrency_block.get("message", "concurrency mode blocked begin")),
+            as_json=as_json,
+            extra={k: v for k, v in concurrency_block.items() if k not in {"ok", "message"}},
+        )
     blocked = foundation_gate_blocks(getattr(args, "task", None), change_dir)
     if blocked:
         return emit_error(
@@ -1407,7 +1459,8 @@ def cmd_close(args: argparse.Namespace) -> int:
             return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
 
     ledger_result = validate_ledger_for_phase_close(
-        change_dir, args.phase, policy, execution_root=execution_root
+        change_dir, args.phase, policy, execution_root=execution_root,
+        phase_status=args.status,
     )
     if not ledger_result.get("ok") and args.phase in {"run", "test", "package"}:
         return emit_error(

package/harness/bundles/java/claude-code/scripts/harness_integration.py

@@ -84,6 +84,12 @@ class TargetMovedError(IntegrationError):
     code = "TARGET_MOVED"
 
 
+class RemoteProbeFailedError(IntegrationError):
+    """Remote probe failed (network/auth/process error), not target moved (retro §5.28)."""
+
+    code = "REMOTE_PROBE_FAILED"
+
+
 class LedgerSyncError(IntegrationError):
     code = "LEDGER_SYNC_PENDING"
 
@@ -139,6 +145,52 @@ class GitRunner:
             return None
         return proc.stdout.strip()
 
+    def remote_probe(self, cwd: Path, *args: str) -> dict[str, Any]:
+        """Typed remote probe result (retro §5.28).
+
+        Returns:
+            {
+                "exitCode": int,
+                "stdoutHash": str | None,   # first whitespace-delimited token
+                "redactedStderr": str,       # stderr with credentials redacted
+                "category": "ok" | "target-moved" | "probe-failed" | "auth-failed",
+            }
+
+        `category` distinguishes:
+        - `ok`: exit=0, hash available
+        - `target-moved`: only meaningful when caller compares hash to expected
+        - `probe-failed`: exit!=0, network/process error (allow bounded retry)
+        - `auth-failed`: exit!=0, stderr contains auth/credential indicators
+
+        `None` must never enter the "found head" field; callers must branch on
+        `exitCode` before comparing hashes.
+        """
+        proc = self.run(cwd, *args, check=False)
+        stderr = (proc.stderr or "").strip()
+        # Redact potential credentials in stderr (URLs with user:pass@, tokens)
+        redacted = re.sub(
+            r"(https?|ssh)://[^\s]+@[^\s]+", r"\1://***@***", stderr
+        )
+        redacted = re.sub(r"(token|password|secret|key)\s*[:=]\s*\S+", r"\1=***", redacted, flags=re.I)
+        stdout_hash: str | None = None
+        if proc.returncode == 0:
+            stdout = (proc.stdout or "").strip()
+            if stdout:
+                stdout_hash = stdout.split()[0]
+        # Classify category
+        if proc.returncode == 0:
+            category = "ok"
+        elif re.search(r"auth|credential|permission|forbidden|unauthorized", stderr, re.I):
+            category = "auth-failed"
+        else:
+            category = "probe-failed"
+        return {
+            "exitCode": proc.returncode,
+            "stdoutHash": stdout_hash,
+            "redactedStderr": redacted,
+            "category": category,
+        }
+
 
 def _sanitize(value: str) -> str:
     return re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-") or "txn"
@@ -422,6 +474,9 @@ class IntegrationTransaction:
         else:
             result = hl.record_integration_hashes(
                 ledger_path,
+                change_dir=(
+                    self.project_root / ".harness" / "changes" / self.change_id
+                ),
                 repository_id=str(journal["repositoryId"]),
                 merge_final_hash=merge_commit,
                 ci_expected_head=merge_commit,
@@ -760,16 +815,21 @@ class IntegrationTransaction:
                     f"{expected_local}, found {current_target}"
                 )
             if journal.get("remoteTargetHead"):
-                remote_line = self.runner.text(
+                # Use typed remote probe (retro §5.28): distinguish probe failure
+                # (network/auth/process) from genuine target movement. `None`
+                # must never enter the "found head" field.
+                probe = self.runner.remote_probe(
                     self.project_root, "ls-remote", "origin", self.target_branch
                 )
-                current_remote = (
-                    remote_line.split()[0]
-                    if remote_line and remote_line.split()
-                    else None
-                )
                 expected_remote = journal.get("remoteTargetHead")
-                if current_remote != expected_remote:
+                if probe["exitCode"] != 0:
+                    # Probe failed: network/auth/process error, not target moved.
+                    raise RemoteProbeFailedError(
+                        f"remote probe failed (exit={probe['exitCode']}, "
+                        f"category={probe['category']}): {probe['redactedStderr']}"
+                    )
+                current_remote = probe["stdoutHash"]
+                if current_remote is not None and current_remote != expected_remote:
                     raise TargetMovedError(
                         f"remote {self.target_branch} moved: expected "
                         f"{expected_remote}, found {current_remote}"

package/harness/bundles/java/claude-code/scripts/harness_ledger.py

@@ -621,12 +621,13 @@ def validate_ledger_identity(ledger: dict[str, Any]) -> list[str]:
 def record_integration_hashes(
     ledger_path: Path,
     *,
+    change_dir: Path | None = None,
     repository_id: str,
     merge_final_hash: str,
     ci_expected_head: str,
     remote_head: str,
 ) -> dict[str, Any]:
-    """Atomically attach post-push identity to an existing ledger v3."""
+    """Atomically attach post-push hashes using the change contract's ledger rules."""
     path = Path(ledger_path).resolve()
     if not path.is_file():
         return {"ok": False, "code": "LEDGER_MISSING", "ledgerPath": str(path)}
@@ -637,15 +638,26 @@ def record_integration_hashes(
             "ok": False, "code": "LEDGER_INVALID", "ledgerPath": str(path),
             "message": str(exc),
         }
+    legacy_contract = False
+    if change_dir is not None:
+        resolved_change_dir = Path(change_dir).resolve()
+        if ledger.get("changeName") != resolved_change_dir.name:
+            return {
+                "ok": False,
+                "code": "LEDGER_CHANGE_MISMATCH",
+                "ledgerPath": str(path),
+            }
+        legacy_contract = not _contract_is_v2(resolved_change_dir)
+
     missing = validate_ledger_identity(ledger)
-    if missing:
+    if missing and not legacy_contract:
         return {
             "ok": False,
             "code": "LEDGER_IDENTITY_INVALID",
             "ledgerPath": str(path),
             "missing": missing,
         }
-    if ledger.get("repositoryId") != repository_id:
+    if not missing and ledger.get("repositoryId") != repository_id:
         return {
             "ok": False,
             "code": "LEDGER_REPOSITORY_MISMATCH",

package/harness/bundles/java/claude-code/scripts/harness_plan_finalize.py

@@ -177,6 +177,82 @@ def _terminal_exists(change_dir: Path, run_id: str, attempt: int) -> bool:
     )
 
 
+def _read_design_capabilities(staging: Path, change_name: str) -> list[str]:
+    """Read capabilities from design frontmatter (retro §5.4)."""
+    design_path = staging / "spec" / f"{change_name}-design.md"
+    if not design_path.is_file():
+        return []
+    try:
+        text = design_path.read_text(encoding="utf-8-sig")
+    except OSError:
+        return []
+    frontmatter = _frontmatter(text)
+    if not frontmatter:
+        return []
+    raw = frontmatter.get("capabilities") or ""
+    if not raw:
+        return []
+    # capabilities may be comma-separated or YAML list
+    if raw.startswith("["):
+        try:
+            parsed = json.loads(raw)
+            if isinstance(parsed, list):
+                return [str(c) for c in parsed if isinstance(c, str)]
+        except json.JSONDecodeError:
+            pass
+    return [c.strip() for c in raw.split(",") if c.strip()]
+
+
+def _reclassify_gate_policy(
+    staging: Path,
+    change_name: str,
+) -> dict[str, Any]:
+    """Reclassify gate policy based on approved design capabilities (retro §5.4).
+
+    Reads design frontmatter `capabilities`, invokes harness_gate.py classify
+    to recompute the gate DAG, and updates staging/meta/gate-policy.json.
+    Returns {"ok": bool, "capabilities": [...], "drift": bool}.
+    """
+    capabilities = _read_design_capabilities(staging, change_name)
+    if not capabilities:
+        return {"ok": True, "capabilities": [], "drift": False, "updated": False}
+
+    gate_policy_path = staging / "meta" / "gate-policy.json"
+    try:
+        existing = json.loads(gate_policy_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError):
+        existing = {}
+
+    existing_caps = set(existing.get("capabilities") or [])
+    design_caps = set(capabilities)
+    drift = existing_caps != design_caps
+
+    if drift:
+        # Update gate-policy.json with design capabilities
+        existing["capabilities"] = sorted(design_caps)
+        try:
+            gate_policy_path.write_text(
+                json.dumps(existing, ensure_ascii=False, indent=2) + "\n",
+                encoding="utf-8",
+                newline="\n",
+            )
+        except OSError as exc:
+            return {
+                "ok": False,
+                "error": f"failed to update gate-policy.json: {exc}",
+                "capabilities": capabilities,
+                "drift": True,
+                "updated": False,
+            }
+
+    return {
+        "ok": True,
+        "capabilities": sorted(design_caps),
+        "drift": drift,
+        "updated": drift,
+    }
+
+
 def _append_terminal(change_dir: Path, run_id: str, attempt: int) -> tuple[int, str]:
     stdout = io.StringIO()
     stderr = io.StringIO()
@@ -214,6 +290,15 @@ def finalize_plan(
 ) -> dict[str, Any]:
     change_dir = change_dir.resolve()
     staging = staging.resolve()
+
+    # C2 (retro §5.4): reclassify gate policy based on approved design capabilities.
+    # This updates staging/meta/gate-policy.json before validation, so the hash
+    # reflects the final gate policy. Drift between design capabilities and
+    # gate-policy capabilities is resolved in favor of the approved design.
+    reclassify = _reclassify_gate_policy(staging, change_name)
+    if not reclassify.get("ok"):
+        return _result_error("CAPABILITY_GATE_DRIFT", reclassify.get("error", "reclassify failed"))
+
     validation = validate_staging(staging, change_name)
     if not validation["ok"]:
         return validation