briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/cli/provenance_commands.py

@@ -0,0 +1,100 @@
+"""Provenance projection CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from multi_agent_brief.orchestrator.runtime_state import RuntimeStateError
+from multi_agent_brief.provenance.builder import (
+    build_provenance_workspace,
+    show_provenance_workspace,
+    validate_provenance_workspace,
+)
+from multi_agent_brief.provenance.model import ProvenanceError
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    provenance_parser = subparsers.add_parser(
+        "provenance",
+        help="Build and inspect deterministic workspace provenance projections.",
+    )
+    actions = provenance_parser.add_subparsers(dest="provenance_action", required=True)
+
+    build_parser = actions.add_parser(
+        "build",
+        help="Build output/intermediate/provenance_graph.json from existing control files.",
+    )
+    build_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    build_parser.add_argument("--repo-workdir", help="Repository or packaged contract base.")
+    build_parser.add_argument("--strict", action="store_true", help="Fail when provenance warnings exist.")
+    build_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+    show_parser = actions.add_parser(
+        "show",
+        help="Show provenance graph summary.",
+    )
+    show_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    show_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+    validate_parser = actions.add_parser(
+        "validate",
+        help="Validate output/intermediate/provenance_graph.json.",
+    )
+    validate_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    validate_parser.add_argument("--strict", action="store_true", help="Fail when provenance warnings exist.")
+    validate_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+
+def handle(args: argparse.Namespace) -> int:
+    try:
+        if args.provenance_action == "build":
+            state = build_provenance_workspace(
+                workspace=args.workspace,
+                repo_workdir=getattr(args, "repo_workdir", None),
+                strict=getattr(args, "strict", False),
+            )
+            _print_state("provenance build", state, as_json=getattr(args, "json", False))
+            return 0 if state.get("ok") else 1
+
+        if args.provenance_action == "show":
+            state = show_provenance_workspace(workspace=args.workspace)
+            _print_state("provenance show", state, as_json=getattr(args, "json", False))
+            return 0 if state.get("ok") else 1
+
+        if args.provenance_action == "validate":
+            state = validate_provenance_workspace(
+                workspace=args.workspace,
+                strict=getattr(args, "strict", False),
+            )
+            _print_state("provenance validate", state, as_json=getattr(args, "json", False))
+            return 0 if state.get("ok") else 1
+    except (ProvenanceError, RuntimeStateError) as exc:
+        _print_error(exc, as_json=getattr(args, "json", False))
+        return 1
+    return 1
+
+
+def _print_state(label: str, state: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(state, ensure_ascii=False, indent=2, sort_keys=True))
+        return
+    validation = state.get("validation") or {}
+    summary = (state.get("provenance_graph") or {}).get("summary") or state.get("summary") or {}
+    print(f"[{label}] ok: {state.get('ok')}")
+    print(f"[{label}] graph: {state.get('provenance_graph_path')}")
+    print(f"[{label}] nodes: {summary.get('node_count', validation.get('node_count', 0))}")
+    print(f"[{label}] edges: {summary.get('edge_count', validation.get('edge_count', 0))}")
+    print(f"[{label}] warnings: {summary.get('warning_count', validation.get('warning_count', 0))}")
+    print(f"[{label}] errors: {summary.get('error_count', validation.get('error_count', 0))}")
+    for error in validation.get("errors") or []:
+        print(f"  - {error}")
+
+
+def _print_error(exc: Exception, *, as_json: bool) -> None:
+    payload = exc.to_dict() if hasattr(exc, "to_dict") else {"ok": False, "error": str(exc)}
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+    else:
+        print(f"[provenance] {exc}")

multi_agent_brief/cli/release_commands.py

@@ -0,0 +1,68 @@
+"""Release readiness check CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from multi_agent_brief.orchestrator.runtime_state.errors import RuntimeStateError
+from multi_agent_brief.product.release_approval import (
+    ReleaseApprovalError,
+    check_release_readiness,
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "release",
+        help="Check internal review readiness without authorizing public release.",
+    )
+    actions = parser.add_subparsers(dest="release_action", required=True)
+    check_parser = actions.add_parser("check", help="Write a release readiness report.")
+    check_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    check_parser.add_argument("--mode", required=True, help="Release mode, for example ir_draft.")
+    check_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+
+def handle(args: argparse.Namespace) -> int:
+    action = getattr(args, "release_action", "")
+    try:
+        if action == "check":
+            result = check_release_readiness(workspace=args.workspace, mode=args.mode)
+            payload = dict(result.payload)
+            payload["ok"] = payload.get("status") == "pass"
+            payload["report_path"] = "output/intermediate/release_readiness_report.json"
+            _print_payload("release check", payload, as_json=getattr(args, "json", False))
+            return 0 if payload["ok"] else 1
+    except (ReleaseApprovalError, RuntimeStateError, OSError, json.JSONDecodeError) as exc:
+        payload = {"ok": False, "error": str(exc)}
+        _print_payload("release check", payload, as_json=getattr(args, "json", False))
+        return 1
+    raise AssertionError(f"Unhandled release action: {action}")
+
+
+def _print_payload(label: str, payload: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+        return
+    print(label)
+    for key in (
+        "ok",
+        "mode",
+        "status",
+        "approval_required",
+        "missing_roles",
+        "blockers",
+        "branding_context",
+        "authorization",
+        "next_step",
+        "report_path",
+    ):
+        if key not in payload:
+            continue
+        value = payload[key]
+        if isinstance(value, (dict, list)):
+            print(f"{key}: {json.dumps(value, ensure_ascii=False, sort_keys=True)}")
+        else:
+            print(f"{key}: {value}")

multi_agent_brief/cli/repair_commands.py

@@ -0,0 +1,169 @@
+"""Repair routing CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from multi_agent_brief.orchestrator.runtime_state import (
+    RuntimeStateError,
+    complete_repair_transaction,
+    start_repair_transaction,
+)
+from multi_agent_brief.repair.router import route_repair
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    repair_parser = subparsers.add_parser(
+        "repair",
+        help="Route and execute deterministic owner-stage repair transactions.",
+    )
+    actions = repair_parser.add_subparsers(dest="repair_action", required=True)
+    route_parser = actions.add_parser(
+        "route",
+        help="Show allowed repair owner/artifacts for the current workspace issue.",
+    )
+    route_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    route_parser.add_argument(
+        "--route-index",
+        type=int,
+        help="0-based route index to inspect explicitly.",
+    )
+    route_parser.add_argument(
+        "--finding-id",
+        help="Finding ID to inspect explicitly.",
+    )
+    route_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    start_parser = actions.add_parser(
+        "start",
+        help="Start the deterministic owner-stage repair transaction for the current route.",
+    )
+    start_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    start_parser.add_argument(
+        "--repo-workdir",
+        help="Repository or packaged contract base (default: auto-detect).",
+    )
+    start_parser.add_argument(
+        "--actor",
+        default="orchestrator",
+        choices=("cli", "orchestrator", "runtime", "system"),
+        help="Actor recorded in event_log.jsonl.",
+    )
+    start_parser.add_argument(
+        "--route-index",
+        type=int,
+        help="0-based route index from `repair route --json` to start explicitly.",
+    )
+    start_parser.add_argument(
+        "--finding-id",
+        help="Finding ID from `repair route --json` to start explicitly.",
+    )
+    start_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    complete_parser = actions.add_parser(
+        "complete",
+        help="Complete the active owner-stage repair transaction.",
+    )
+    complete_parser.add_argument("--workspace", required=True, help="Path to workspace directory.")
+    complete_parser.add_argument("--reason", required=True, help="Short repair completion reason summary.")
+    complete_parser.add_argument(
+        "--repo-workdir",
+        help="Repository or packaged contract base (default: auto-detect).",
+    )
+    complete_parser.add_argument(
+        "--actor",
+        default="orchestrator",
+        choices=("cli", "orchestrator", "runtime", "system"),
+        help="Actor recorded in event_log.jsonl.",
+    )
+    complete_parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+
+
+def handle(args: argparse.Namespace) -> int:
+    try:
+        if args.repair_action == "route":
+            payload = route_repair(
+                workspace=args.workspace,
+                route_index=getattr(args, "route_index", None),
+                finding_id=getattr(args, "finding_id", None),
+            )
+            if getattr(args, "json", False):
+                print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+            else:
+                _print_route(payload)
+            return 0 if payload.get("ok") else 1
+        if args.repair_action == "start":
+            payload = start_repair_transaction(
+                workspace=args.workspace,
+                repo_workdir=getattr(args, "repo_workdir", None),
+                actor=getattr(args, "actor", "orchestrator"),
+                route_index=getattr(args, "route_index", None),
+                finding_id=getattr(args, "finding_id", None),
+            )
+            if getattr(args, "json", False):
+                print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+            else:
+                _print_repair_state("repair start", payload)
+            return 0
+        if args.repair_action == "complete":
+            payload = complete_repair_transaction(
+                workspace=args.workspace,
+                reason=args.reason,
+                repo_workdir=getattr(args, "repo_workdir", None),
+                actor=getattr(args, "actor", "orchestrator"),
+            )
+            if getattr(args, "json", False):
+                print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+            else:
+                _print_repair_state("repair complete", payload)
+            return 0
+    except RuntimeStateError as exc:
+        if getattr(args, "json", False):
+            print(json.dumps(exc.to_dict(), ensure_ascii=False, indent=2, sort_keys=True))
+        else:
+            print(f"[repair] {exc}")
+        return 1
+    return 1
+
+
+def _print_route(payload: dict[str, Any]) -> None:
+    if not payload.get("ok"):
+        print(f"[repair route] Error: {payload.get('message') or payload.get('error')}")
+        return
+    print(f"[repair route] owner: {payload.get('repair_owner')}")
+    print(f"[repair route] must_rerun_from: {payload.get('must_rerun_from') or 'none'}")
+    print(f"[repair route] reason: {payload.get('reason')}")
+    if payload.get("default_selected") is True:
+        source = payload.get("source") if isinstance(payload.get("source"), dict) else {}
+        finding_id = source.get("finding_id") or source.get("finding_type") or "selected route"
+        print(
+            f"[repair route] default: {finding_id} -> {payload.get('repair_owner')} "
+            f"-> {', '.join(payload.get('allowed_artifacts') or []) or 'none'}"
+        )
+    print("[repair route] allowed_artifacts:")
+    for artifact in payload.get("allowed_artifacts") or []:
+        print(f"  - {artifact}")
+    blocked = payload.get("blocked_direct_edits") or []
+    if blocked:
+        print("[repair route] blocked_direct_edits:")
+        for artifact in blocked:
+            print(f"  - {artifact}")
+
+
+def _print_repair_state(label: str, payload: dict[str, Any]) -> None:
+    workflow = payload.get("workflow_state") or {}
+    repair = payload.get("repair") or workflow.get("active_repair") or {}
+    print(f"[{label}] current_stage: {workflow.get('current_stage')}")
+    print(f"[{label}] repair_owner: {repair.get('repair_owner')}")
+    print(f"[{label}] must_rerun_from: {repair.get('must_rerun_from') or repair.get('next_stage') or 'none'}")
+    allowed = repair.get("allowed_artifacts") or []
+    if allowed:
+        print(f"[{label}] allowed_artifacts:")
+        for artifact in allowed:
+            print(f"  - {artifact}")
+    effect = repair.get("run_integrity_effect")
+    if isinstance(effect, dict) and effect.get("reference_eligible") is False:
+        print(f"[{label}] reference_eligible: false")
+        reason = effect.get("reason")
+        if reason:
+            print(f"[{label}] run_integrity_note: {reason}")

multi_agent_brief/cli/run_commands.py

@@ -0,0 +1,292 @@
+"""run / start / handoff / prepare — runtime handoff launcher commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from multi_agent_brief.orchestrator.handoff import (
+    RUNTIME_RECIPE_FAST_RERUN,
+    VALID_RUNTIMES,
+    VALID_RUNTIME_RECIPES,
+    build_handoff,
+    legacy_runtime_alias_warning,
+    render_handoff_cli,
+    write_handoff_and_state,
+)
+from multi_agent_brief.orchestrator.fact_layer_import import require_fast_rerun_handoff_ready
+from multi_agent_brief.orchestrator_contract import resolve_repo_workdir
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register run, start, handoff, and prepare subparsers."""
+
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run a workspace through the selected agent runtime handoff.",
+    )
+    run_parser.add_argument(
+        "--workspace", help="Path to workspace directory."
+    )
+    run_parser.add_argument(
+        "--config",
+        help="Path to workspace config.yaml (convenience alias for --workspace).",
+    )
+    run_parser.add_argument(
+        "--runtime",
+        default="auto",
+        choices=list(VALID_RUNTIMES),
+        help="Target runtime for handoff (default: auto, resolves to hermes; manual is a legacy alias for operator).",
+    )
+    run_parser.add_argument(
+        "--recipe",
+        default="full",
+        choices=list(VALID_RUNTIME_RECIPES),
+        help="Runtime handoff recipe: full or fast-rerun (guidance only, not a Python pipeline).",
+    )
+    run_parser.add_argument(
+        "--repo-workdir",
+        help="Repository workdir (default: auto-detect source repo).",
+    )
+    run_parser.add_argument(
+        "--venv", help="Virtual env path (default: auto-detect)."
+    )
+    run_parser.add_argument(
+        "--skip-doctor", action="store_true", help="Skip doctor check."
+    )
+    prepare_parser = subparsers.add_parser(
+        "prepare",
+        help="[legacy] Replaced by 'briefloop run'.",
+    )
+    prepare_parser.add_argument(
+        "--config", required=True, help="Path to config.yaml in the workspace."
+    )
+    prepare_parser.add_argument("--input", help="Override input directory.")
+    prepare_parser.add_argument("--output", help="Override output directory.")
+
+    start_parser = subparsers.add_parser(
+        "start",
+        help="Alias for run: create runtime handoff for the current agent.",
+    )
+    start_parser.add_argument(
+        "--workspace", help="Path to workspace directory."
+    )
+    start_parser.add_argument(
+        "--runtime",
+        default="auto",
+        choices=list(VALID_RUNTIMES),
+        help="Target runtime for handoff (default: auto, resolves to hermes; manual is a legacy alias for operator).",
+    )
+    start_parser.add_argument(
+        "--recipe",
+        default="full",
+        choices=list(VALID_RUNTIME_RECIPES),
+        help="Runtime handoff recipe: full or fast-rerun (guidance only, not a Python pipeline).",
+    )
+    start_parser.add_argument(
+        "--repo-workdir",
+        help="Repository workdir (default: auto-detect source repo).",
+    )
+    start_parser.add_argument(
+        "--venv", help="Virtual env path (default: auto-detect)."
+    )
+    start_parser.add_argument(
+        "--skip-doctor", action="store_true", help="Skip doctor check."
+    )
+    handoff_parser = subparsers.add_parser(
+        "handoff",
+        help="Generate a runtime handoff artifact from a workspace config.",
+    )
+    handoff_parser.add_argument(
+        "--config", required=True, help="Path to workspace config.yaml."
+    )
+    handoff_parser.add_argument(
+        "--runtime",
+        default="auto",
+        choices=list(VALID_RUNTIMES),
+        help="Target runtime for handoff (default: auto, resolves to hermes; manual is a legacy alias for operator).",
+    )
+    handoff_parser.add_argument(
+        "--recipe",
+        default="full",
+        choices=list(VALID_RUNTIME_RECIPES),
+        help="Runtime handoff recipe: full or fast-rerun (guidance only, not a Python pipeline).",
+    )
+    handoff_parser.add_argument(
+        "--repo-workdir",
+        help="Repository workdir (default: auto-detect source repo).",
+    )
+    handoff_parser.add_argument(
+        "--venv", help="Virtual env path (default: auto-detect)."
+    )
+    handoff_parser.add_argument(
+        "--skip-doctor", action="store_true", help="Skip doctor check."
+    )
+
+def handle(args: argparse.Namespace) -> int:
+    """Dispatch run / start / handoff / prepare commands."""
+    if args.command == "prepare":
+        return _run_prepare(args)
+    if args.command == "handoff":
+        return _run_handoff(args)
+    # run and start both use the launcher
+    return _run_launcher(args)
+
+
+def _resolve_workspace(args: argparse.Namespace) -> Path | None:
+    """Resolve workspace path from --workspace, --config, or CWD auto-detect."""
+    workspace = getattr(args, "workspace", None)
+    config_path = getattr(args, "config", None)
+
+    if config_path and not workspace:
+        cp = Path(config_path).resolve()
+        if cp.is_file():
+            workspace = str(cp.parent)
+        elif cp.is_dir():
+            workspace = str(cp)
+
+    if not workspace:
+        cwd = Path.cwd()
+        if (cwd / "config.yaml").exists() and (cwd / "user.md").exists():
+            workspace = str(cwd)
+
+    if not workspace:
+        return None
+
+    ws_path = Path(workspace).resolve()
+    if not (ws_path / "config.yaml").exists():
+        return None
+    return ws_path
+
+
+def _run_launcher(args: argparse.Namespace) -> int:
+    """run — standard runtime handoff launcher."""
+    prefix = (
+        "[start]" if getattr(args, "command", None) == "start" else "[run]"
+    )
+
+    workspace_path = _resolve_workspace(args)
+    if workspace_path is None:
+        print(f"{prefix} No workspace found.")
+        print()
+        print("For a real workspace:")
+        print("  briefloop onboard")
+        print("  briefloop init <workspace> --from-onboarding onboarding.json")
+        print()
+        print("For a demo only:")
+        print("  briefloop init <workspace> --demo")
+        return 1
+
+    try:
+        repo_workdir = resolve_repo_workdir(
+            getattr(args, "repo_workdir", None),
+            workspace=workspace_path,
+        )
+    except ValueError as exc:
+        print(f"{prefix} {exc}")
+        return 1
+
+    recipe = getattr(args, "recipe", "full")
+    if recipe == RUNTIME_RECIPE_FAST_RERUN:
+        try:
+            require_fast_rerun_handoff_ready(workspace_path)
+        except ValueError as exc:
+            print(f"{prefix} {exc}")
+            return 1
+
+    try:
+        handoff = build_handoff(
+            workspace=workspace_path,
+            repo_workdir=repo_workdir,
+            runtime=args.runtime,
+            recipe=recipe,
+            venv=getattr(args, "venv", None),
+            run_doctor=not getattr(args, "skip_doctor", False),
+        )
+    except ValueError as exc:
+        print(f"{prefix} {exc}")
+        return 1
+    _print_runtime_alias_warning(prefix, getattr(args, "runtime", ""))
+
+    written = write_handoff_and_state(
+        handoff=handoff,
+        workspace=workspace_path,
+        repo_workdir=repo_workdir,
+        prefix=prefix,
+    )
+    if written is None:
+        return 1
+    md_path, json_path = written
+    print(render_handoff_cli(handoff))
+    print(f"{prefix} Handoff written: {md_path}")
+    print(f"{prefix} Handoff JSON:  {json_path}")
+    return 0
+
+
+def _run_prepare(args: argparse.Namespace) -> int:
+    """[legacy] prepare — replaced by the runtime handoff launcher."""
+    print(
+        "[legacy] prepare has been replaced by:"
+        " briefloop run --workspace <workspace>"
+    )
+    return 1
+
+
+def _run_handoff(args: argparse.Namespace) -> int:
+    """handoff — generate runtime handoff from workspace config."""
+    config_path = Path(args.config).resolve()
+    if not config_path.exists():
+        print(f"[error] config.yaml not found: {config_path}")
+        return 1
+    workspace = config_path.parent
+    try:
+        repo_workdir = resolve_repo_workdir(
+            getattr(args, "repo_workdir", None),
+            workspace=workspace,
+        )
+    except ValueError as exc:
+        print(f"[handoff] {exc}")
+        return 1
+
+    recipe = getattr(args, "recipe", "full")
+    if recipe == RUNTIME_RECIPE_FAST_RERUN:
+        try:
+            require_fast_rerun_handoff_ready(workspace)
+        except ValueError as exc:
+            print(f"[handoff] {exc}")
+            return 1
+
+    try:
+        handoff = build_handoff(
+            workspace=workspace,
+            repo_workdir=repo_workdir,
+            runtime=args.runtime,
+            recipe=recipe,
+            venv=getattr(args, "venv", None),
+            run_doctor=not getattr(args, "skip_doctor", False),
+        )
+    except ValueError as exc:
+        print(f"[handoff] {exc}")
+        return 1
+    _print_runtime_alias_warning("[handoff]", getattr(args, "runtime", ""))
+
+    written = write_handoff_and_state(
+        handoff=handoff,
+        workspace=workspace,
+        repo_workdir=repo_workdir,
+        prefix="[handoff]",
+    )
+    if written is None:
+        return 1
+    md_path, json_path = written
+    print(render_handoff_cli(handoff))
+    print(f"[handoff] Written: {md_path}")
+    print(f"[handoff] JSON:   {json_path}")
+    return 0
+
+
+def _print_runtime_alias_warning(prefix: str, runtime: str) -> None:
+    warning = legacy_runtime_alias_warning(runtime)
+    if warning:
+        print(f"{prefix} WARNING: {warning}", file=sys.stderr)