@hunter-harness/workflow-harness 0.2.13 → 0.2.15

package/harness/bundles/general/codebuddy/scripts/harness_archive.py

@@ -683,6 +683,34 @@ def check_status(
             else:
                 blockers.append(tier_issue)
 
+    # --- artifact preflight (retro §5.31) ---
+    # Classify artifact events before destructive finalize: informational (OK),
+    # canonicalizable (same-change repo-relative path, warning), or blocking
+    # (cross-change/absolute/escaping path, fail closed).
+    try:
+        preflight = artifact_preflight(change_dir)
+    except Exception as exc:  # noqa: BLE001 — preflight must not crash status
+        preflight = {"ok": False, "items": [], "blocking": [], "error": str(exc)}
+    checks["artifact_preflight"] = preflight
+    for item in preflight.get("blocking") or []:
+        blockers.append({
+            "code": "artifact-path-blocking",
+            "message": (
+                f"artifact event {item.get('eventId', '')} path "
+                f"{item.get('path', '')}: {item.get('reason', 'blocking')}"
+            ),
+        })
+    for item in preflight.get("items") or []:
+        if item.get("category") == "canonicalizable":
+            warnings.append({
+                "code": "artifact-path-canonicalizable",
+                "message": (
+                    f"artifact event {item.get('eventId', '')} path "
+                    f"{item.get('path', '')} is repo-relative; "
+                    f"canonical={item.get('canonicalPath', '')}"
+                ),
+            })
+
     archivable = len(blockers) == 0
     return {
         "ok": True,
@@ -2799,6 +2827,130 @@ def _html_escape(text: str) -> str:
 # ---------------------------------------------------------------------------
 
 
+def validate_report_adequacy(summary: dict[str, Any]) -> dict[str, Any]:
+    """Validate that final summary is factually complete (retro §5.32).
+
+    The archive validator must not return all-green when the summary is
+    factually incomplete. This gate checks independent sources (git facts,
+    typed metrics, stage status) rather than comparing the summary against
+    a lossy projection of itself.
+    """
+    issues: list[dict[str, str]] = []
+
+    git_facts = summary.get("gitFacts") or {}
+    if isinstance(git_facts, dict):
+        base = str(git_facts.get("baseCommit") or "").strip()
+        final = str(git_facts.get("finalCommit") or "").strip()
+        files_changed = int(git_facts.get("filesChanged") or 0)
+        # base != final but diff=0 → factually incomplete.
+        if base and final and base != final and files_changed == 0:
+            issues.append({
+                "code": "DIFF_ZERO_WITH_NONEMPTY_COMMIT",
+                "severity": "error",
+                "message": f"final commit {final} differs from base {base} but filesChanged=0",
+            })
+
+    # Typed metrics missing despite test report artifacts present.
+    verification = summary.get("verification") or {}
+    if isinstance(verification, dict):
+        unit = verification.get("unitTests") or {}
+        api = verification.get("apiTests") or {}
+        artifacts = summary.get("artifacts") or []
+        has_test_report = any(
+            isinstance(a, dict) and "test" in str(a.get("path") or "").lower()
+            for a in artifacts
+        ) if isinstance(artifacts, list) else False
+        unit_pass = int(unit.get("passed") or 0) if isinstance(unit, dict) else 0
+        api_status = str(api.get("status") or "") if isinstance(api, dict) else ""
+        if has_test_report and unit_pass == 0 and api_status in {"", "not_available"}:
+            issues.append({
+                "code": "TYPED_METRICS_MISSING",
+                "severity": "error",
+                "message": "test report artifacts present but unitTests/apiTests typed metrics are empty",
+            })
+
+    # stageStatus contradicts event reducer.
+    stage = summary.get("stageStatus") or {}
+    stage_from_events = summary.get("stageStatusFromEvents") or {}
+    if isinstance(stage, dict) and isinstance(stage_from_events, dict):
+        for phase, status in stage.items():
+            event_status = stage_from_events.get(phase)
+            if event_status is not None and str(status) != str(event_status):
+                issues.append({
+                    "code": "STAGE_STATUS_CONTRADICTION",
+                    "severity": "error",
+                    "message": f"stageStatus.{phase}={status} but event reducer says {event_status}",
+                })
+
+    return {"ok": not issues, "issues": issues}
+
+
+def artifact_preflight(change_dir: Path) -> dict[str, Any]:
+    """Classify artifact events before destructive finalize (retro §5.31).
+
+    Returns per-artifact classification: informational (no path, OK),
+    canonicalizable (same-change repo-relative path, auto-normalize), or
+    blocking (cross-change/absolute/escaping path, fail closed).
+    """
+    change_dir = change_dir.resolve()
+    events_p = change_dir / "events.ndjson"
+    items: list[dict[str, Any]] = []
+    blocking: list[dict[str, Any]] = []
+    if not events_p.is_file():
+        return {"ok": True, "items": [], "blocking": []}
+    change_id = change_dir.name
+    for line in events_p.read_text(encoding="utf-8").splitlines():
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict) or event.get("type") != "artifact":
+            continue
+        path = str(event.get("path") or "").strip()
+        kind = str(event.get("kind") or "").strip()
+        event_id = str(event.get("id") or "")
+        if not path:
+            items.append({
+                "eventId": event_id,
+                "category": "informational",
+                "kind": kind or "informational",
+                "note": str(event.get("note") or "")[:80],
+            })
+            continue
+        # Check for escaping/cross-change paths.
+        parts = path.replace("\\", "/").split("/")
+        if ".." in parts or path.startswith("/") or re.match(r"^[A-Za-z]:", path):
+            item = {
+                "eventId": event_id,
+                "category": "blocking",
+                "path": path,
+                "reason": "absolute or escaping path",
+            }
+            items.append(item)
+            blocking.append(item)
+            continue
+        # Same-change repo-relative path: canonicalizable.
+        prefix = f".harness/changes/{change_id}/"
+        if path.startswith(prefix):
+            canonical = path[len(prefix):]
+            items.append({
+                "eventId": event_id,
+                "category": "canonicalizable",
+                "path": path,
+                "canonicalPath": canonical,
+                "correction": f"append correction --target-event-id {event_id} --target-field path --new-value-json \"{canonical}\"",
+            })
+            continue
+        # Change-relative path: OK.
+        items.append({
+            "eventId": event_id,
+            "category": "file-backed",
+            "path": path,
+            "exists": (change_dir / path).is_file(),
+        })
+    return {"ok": not blocking, "items": items, "blocking": blocking}
+
+
 def run_knowledge_poststeps(project_root: Path) -> dict[str, Any]:
     results: dict[str, Any] = {"ran": False, "steps": [], "warnings": []}
     if not KNOWLEDGE_SCRIPT.is_file():
@@ -3107,6 +3259,36 @@ def cmd_finalize(
             note="review missing on full tier (allowed by user)",
         )
 
+    # --- 2c. artifact preflight (retro §5.31) ---
+    # Classify artifact events before freeze: blocking paths must fail closed
+    # before the staged operation commits a phase.end.
+    try:
+        preflight = artifact_preflight(work_dir)
+    except Exception as exc:  # noqa: BLE001 — preflight must not crash finalize
+        preflight = {"ok": False, "items": [], "blocking": [], "error": str(exc)}
+    payload["steps"]["artifact_preflight"] = {
+        "ok": bool(preflight.get("ok")),
+        "blockingCount": len(preflight.get("blocking") or []),
+        "itemsCount": len(preflight.get("items") or []),
+    }
+    if preflight.get("blocking"):
+        payload["error"] = (
+            f"artifact preflight blocking: "
+            f"{len(preflight['blocking'])} path(s) cannot be archived"
+        )
+        payload["issues"] = [
+            {
+                "code": "ARTIFACT_PATH_BLOCKING",
+                "severity": "error",
+                "message": f"{item.get('path', '')}: {item.get('reason', 'blocking')}",
+            }
+            for item in preflight["blocking"]
+        ]
+        _restore_finalize_failure()
+        payload["warnings"] = warnings
+        payload["ok"] = False
+        return 1, payload
+
     # --- 3. candidate phase.end + freeze cutoff (RET-19 freeze-first) ---
     # This terminal exists only inside the isolated operation staging tree. It
     # becomes authoritative atomically at publish; validation failure discards
@@ -3169,6 +3351,28 @@ def cmd_finalize(
         payload["ok"] = False
         return 1, payload
 
+    # --- 5b. report adequacy (retro §5.32) ---
+    # Validate that the summary is factually complete: no diff=0 with non-empty
+    # commit, no missing typed metrics despite test reports, no stageStatus
+    # contradictions. Fail closed rather than archiving an incomplete summary.
+    adequacy_result = validate_report_adequacy(summary)
+    payload["steps"]["report_adequacy"] = adequacy_result
+    summary.setdefault("reportPipeline", {})["reportAdequacy"] = {
+        "ok": bool(adequacy_result.get("ok")),
+        "issues": adequacy_result.get("issues") or [],
+    }
+    try:
+        write_json(summary_path, summary)
+    except OSError as exc:
+        warnings.append(f"could not write reportAdequacy: {exc}")
+    if not adequacy_result.get("ok"):
+        payload["issues"] = adequacy_result.get("issues") or []
+        payload["error"] = "report adequacy failed; staged operation discarded"
+        _restore_finalize_failure()
+        payload["warnings"] = warnings
+        payload["ok"] = False
+        return 1, payload
+
     # --- 6. render (Node, else Python fallback) ---
     render_result = render_final_summary(work_dir, summary_path)
     payload["steps"]["render"] = render_result

package/harness/bundles/general/codebuddy/scripts/harness_change.py

@@ -224,6 +224,60 @@ def _layout_fields(project_root: Path, change_id: str) -> dict[str, Any]:
     }
 
 
+def read_concurrency_mode(project_root: Path) -> str:
+    """Return the configured concurrency mode (retro §5.2).
+
+    Defaults to ``single-active`` when no config declares a mode. Supported
+    values: ``single-active`` (default, blocks a second active Change),
+    ``isolated-multi-active`` (allows multiple active Changes but all
+    Change-scoped commands require ``--change``).
+    """
+    cfg = project_root / ".harness" / "config.json"
+    if cfg.is_file():
+        try:
+            data = json.loads(cfg.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                mode = data.get("concurrencyMode")
+                if isinstance(mode, str) and mode in {
+                    "single-active",
+                    "isolated-multi-active",
+                }:
+                    return mode
+        except (OSError, json.JSONDecodeError):
+            pass
+    return "single-active"
+
+
+def check_concurrency_block(
+    project_root: Path, change_id: str
+) -> dict[str, Any] | None:
+    """Return a blocking payload when a second active Change is forbidden.
+
+    Returns ``None`` when the begin may proceed. In ``single-active`` mode a
+    second active Change (any other than ``change_id``) blocks begin; in
+    ``isolated-multi-active`` mode multiple active Changes are allowed.
+    """
+    mode = read_concurrency_mode(project_root)
+    if mode == "isolated-multi-active":
+        return None
+    active = list_active_changes(project_root)
+    others = [entry for entry in active if entry.get("changeId") != change_id]
+    if not others:
+        return None
+    return {
+        "ok": False,
+        "code": "SINGLE_ACTIVE_BLOCKED",
+        "message": (
+            "single-active concurrency mode: another active Change exists; "
+            "use portfolio/decompose to sequence multiple Changes, or switch "
+            "to isolated-multi-active after ensuring full Change-scoped isolation"
+        ),
+        "concurrencyMode": mode,
+        "activeChanges": active,
+        "blockingChanges": others,
+    }
+
+
 def resolve_change(
     project_root: Path,
     change_id: str | None,
@@ -536,7 +590,9 @@ def lease_port(
         }
         for port in range(start, end + 1):
             if port not in used:
+                lease_id = str(uuid.uuid4())
                 entry = {
+                    "leaseId": lease_id,
                     "changeId": change_id,
                     "runId": run_id,
                     "pid": os.getpid(),
@@ -549,7 +605,7 @@ def lease_port(
                 leases.append(entry)
                 registry["leases"] = leases
                 _write_json(registry_path, registry)
-                return {"ok": True, "code": "PORT_LEASED", "port": port, "lease": entry}
+                return {"ok": True, "code": "PORT_LEASED", "port": port, "leaseId": lease_id, "lease": entry}
     return {
         "ok": False,
         "code": "PORT_RANGE_EXHAUSTED",
@@ -562,7 +618,16 @@ def release_port(
     *,
     change_id: str,
     run_id: str,
+    port: int | None = None,
+    lease_id: str | None = None,
 ) -> dict[str, Any]:
+    """Release port leases by subset (retro §5.16).
+
+    - `--lease-id`: release only the matching leaseId.
+    - `--port`: release only the matching port (must match changeId+runId).
+    - Neither: release all leases matching (changeId, runId) — does NOT require
+      all leases under changeId to have the same runId.
+    """
     registry_path = project_root / PORTS_REL / "registry.json"
     if not registry_path.is_file():
         return {"ok": True, "code": "PORT_LEASE_ABSENT", "changeId": change_id}
@@ -574,27 +639,84 @@ def release_port(
         leases = registry.get("leases") if isinstance(registry, dict) else None
         if not isinstance(leases, list):
             return {"ok": False, "code": "PORT_REGISTRY_INVALID", "message": "leases is not a list"}
-        owned = [
-            item for item in leases
-            if isinstance(item, dict) and str(item.get("changeId")) == change_id
-        ]
-        if not owned:
+
+        # Select the subset to release based on lease_id, port, or (changeId, runId)
+        if lease_id is not None:
+            to_release = [
+                item for item in leases
+                if isinstance(item, dict) and str(item.get("leaseId")) == lease_id
+            ]
+            # Validate that the lease belongs to this change
+            for item in to_release:
+                if str(item.get("changeId")) != change_id:
+                    return {
+                        "ok": False,
+                        "code": "PORT_LEASE_OWNER_MISMATCH",
+                        "message": "leaseId does not belong to this change",
+                        "holder": item,
+                    }
+        elif port is not None:
+            to_release = [
+                item for item in leases
+                if isinstance(item, dict)
+                and item.get("port") == port
+                and str(item.get("changeId")) == change_id
+            ]
+            # Validate runId matches
+            for item in to_release:
+                if str(item.get("runId")) != run_id:
+                    return {
+                        "ok": False,
+                        "code": "PORT_LEASE_OWNER_MISMATCH",
+                        "message": f"port {port} owned by different runId",
+                        "holder": item,
+                        "conflictingOwners": [
+                            {"runId": str(i.get("runId")), "port": i.get("port")}
+                            for i in leases
+                            if isinstance(i, dict)
+                            and i.get("port") == port
+                            and str(i.get("changeId")) == change_id
+                        ],
+                    }
+        else:
+            # Release all matching (changeId, runId) — subset release
+            to_release = [
+                item for item in leases
+                if isinstance(item, dict)
+                and str(item.get("changeId")) == change_id
+                and str(item.get("runId")) == run_id
+            ]
+
+        if not to_release:
+            # Check if there are other leases under this changeId (different runId)
+            other_owned = [
+                item for item in leases
+                if isinstance(item, dict)
+                and str(item.get("changeId")) == change_id
+                and str(item.get("runId")) != run_id
+            ]
+            if other_owned:
+                return {
+                    "ok": False,
+                    "code": "PORT_LEASE_OWNER_MISMATCH",
+                    "message": "no matching leases for this runId; other runIds exist under this changeId",
+                    "conflictingOwners": [
+                        {"runId": str(i.get("runId")), "port": i.get("port"), "leaseId": i.get("leaseId")}
+                        for i in other_owned
+                    ],
+                }
             return {"ok": True, "code": "PORT_LEASE_ABSENT", "changeId": change_id}
-        if any(str(item.get("runId")) != run_id for item in owned):
-            return {
-                "ok": False,
-                "code": "PORT_LEASE_OWNER_MISMATCH",
-                "message": "run id does not match port lease owner",
-                "holder": owned[0],
-            }
-        released_ports = [item.get("port") for item in owned]
-        registry["leases"] = [item for item in leases if item not in owned]
+
+        released_ports = [item.get("port") for item in to_release]
+        released_ids = [item.get("leaseId") for item in to_release]
+        registry["leases"] = [item for item in leases if item not in to_release]
         _write_json(registry_path, registry)
         return {
             "ok": True,
             "code": "PORT_LEASE_RELEASED",
             "changeId": change_id,
             "ports": released_ports,
+            "leaseIds": released_ids,
         }
 
 
@@ -794,7 +916,13 @@ def cmd_lease_port(args: argparse.Namespace) -> int:
 
 def cmd_release_port(args: argparse.Namespace) -> int:
     project = resolve_main_project_root()
-    payload = release_port(project, change_id=args.change, run_id=args.run_id)
+    payload = release_port(
+        project,
+        change_id=args.change,
+        run_id=args.run_id,
+        port=getattr(args, "port", None),
+        lease_id=getattr(args, "lease_id", None),
+    )
     if payload.get("ok"):
         emit(payload, as_json=bool(args.json))
         return 0
@@ -827,6 +955,161 @@ def cmd_integration_lock(args: argparse.Namespace) -> int:
     )
 
 
+def _ensure_change_identity(change_dir: Path) -> dict[str, str]:
+    """Ensure meta/change-identity.json exists with a stable UUID (retro §5.5).
+
+    Returns the identity dict with changeUuid and changeName.
+    """
+    identity_path = change_dir / "meta" / "change-identity.json"
+    if identity_path.is_file():
+        try:
+            data = json.loads(identity_path.read_text(encoding="utf-8-sig"))
+            if isinstance(data, dict) and data.get("changeUuid"):
+                return data
+        except (OSError, json.JSONDecodeError):
+            pass
+    # Generate new identity
+    identity = {
+        "schemaVersion": 1,
+        "changeUuid": str(uuid.uuid4()),
+        "changeName": change_dir.name,
+        "createdAt": now_iso(),
+    }
+    identity_path.parent.mkdir(parents=True, exist_ok=True)
+    identity_path.write_text(
+        json.dumps(identity, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    return identity
+
+
+def cmd_rename(args: argparse.Namespace) -> int:
+    """Rename a change atomically: directory, pointers, worktree, identity (retro §5.5).
+
+    Appends a change.rename event; does not rewrite history.
+    """
+    project = resolve_main_project_root()
+    changes_root = project / ".harness" / "changes"
+    old_dir = changes_root / args.change
+    new_dir = changes_root / args.to
+
+    if not old_dir.is_dir():
+        return emit_error(
+            "CHANGE_NOT_FOUND",
+            f"change directory not found: {old_dir}",
+            as_json=bool(args.json),
+        )
+    if new_dir.exists():
+        return emit_error(
+            "CHANGE_ALREADY_EXISTS",
+            f"target change directory already exists: {new_dir}",
+            as_json=bool(args.json),
+        )
+
+    # Ensure identity exists before rename
+    identity = _ensure_change_identity(old_dir)
+    old_uuid = identity.get("changeUuid", "")
+
+    # Rename directory
+    import shutil
+    shutil.move(str(old_dir), str(new_dir))
+
+    # Update knowledge-context.json.changeId if present
+    kc_path = new_dir / "meta" / "knowledge-context.json"
+    if kc_path.is_file():
+        try:
+            kc = json.loads(kc_path.read_text(encoding="utf-8-sig"))
+            if isinstance(kc, dict):
+                kc["changeId"] = args.to
+                kc["changeUuid"] = old_uuid
+                kc_path.write_text(
+                    json.dumps(kc, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8",
+                    newline="\n",
+                )
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    # Update worktree.json path/branch if present
+    wt_path = new_dir / "meta" / "worktree.json"
+    if wt_path.is_file():
+        try:
+            wt = json.loads(wt_path.read_text(encoding="utf-8-sig"))
+            if isinstance(wt, dict):
+                old_name = args.change
+                new_name = args.to
+                # Update path and branch if they contain old name
+                if isinstance(wt.get("path"), str) and old_name in wt["path"]:
+                    wt["path"] = wt["path"].replace(old_name, new_name)
+                if isinstance(wt.get("branch"), str) and old_name in wt["branch"]:
+                    wt["branch"] = wt["branch"].replace(old_name, new_name)
+                wt_path.write_text(
+                    json.dumps(wt, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8",
+                    newline="\n",
+                )
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    # Update change-identity.json.changeName
+    identity_path = new_dir / "meta" / "change-identity.json"
+    if identity_path.is_file():
+        try:
+            ident = json.loads(identity_path.read_text(encoding="utf-8-sig"))
+            if isinstance(ident, dict):
+                ident["changeName"] = args.to
+                ident["renamedFrom"] = args.change
+                identity_path.write_text(
+                    json.dumps(ident, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8",
+                    newline="\n",
+                )
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    # Append change.rename event (does not rewrite history)
+    try:
+        import harness_events
+        harness_events.append_event(
+            new_dir,
+            phase="plan",
+            type_="change.rename",
+            renamed_from=args.change,
+            renamed_to=args.to,
+            change_uuid=old_uuid,
+            note=f"change renamed from {args.change} to {args.to}",
+        )
+    except Exception:
+        pass  # event append failure should not block rename
+
+    payload = {
+        "ok": True,
+        "code": "RENAMED",
+        "changeUuid": old_uuid,
+        "renamedFrom": args.change,
+        "renamedTo": args.to,
+        "changeDir": str(new_dir),
+    }
+    emit(payload, as_json=bool(args.json))
+    return 0
+
+
+def cmd_ensure_identity(args: argparse.Namespace) -> int:
+    """Ensure meta/change-identity.json exists with a stable UUID (retro §5.5)."""
+    project = resolve_main_project_root()
+    change_dir = project / ".harness" / "changes" / args.change
+    if not change_dir.is_dir():
+        return emit_error(
+            "CHANGE_NOT_FOUND",
+            f"change directory not found: {change_dir}",
+            as_json=bool(args.json),
+        )
+    identity = _ensure_change_identity(change_dir)
+    emit(identity, as_json=bool(args.json))
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="harness_change.py")
     parser.add_argument("--json", action="store_true")
@@ -869,6 +1152,8 @@ def build_parser() -> argparse.ArgumentParser:
     p_port_release = sub.add_parser("release-port", parents=[shared])
     p_port_release.add_argument("--change", required=True)
     p_port_release.add_argument("--run-id", required=True)
+    p_port_release.add_argument("--port", type=int, default=None)
+    p_port_release.add_argument("--lease-id", default=None)
     p_port_release.set_defaults(func=cmd_release_port)
 
     p_lock = sub.add_parser("integration-lock", parents=[shared])
@@ -877,6 +1162,15 @@ def build_parser() -> argparse.ArgumentParser:
     p_lock.add_argument("--ttl-seconds", type=int, default=3600)
     p_lock.set_defaults(func=cmd_integration_lock)
 
+    p_rename = sub.add_parser("rename", parents=[shared])
+    p_rename.add_argument("--change", required=True)
+    p_rename.add_argument("--to", required=True)
+    p_rename.set_defaults(func=cmd_rename)
+
+    p_identity = sub.add_parser("ensure-identity", parents=[shared])
+    p_identity.add_argument("--change", required=True)
+    p_identity.set_defaults(func=cmd_ensure_identity)
+
     return parser