outcomeci-cli 0.1.0__py3-none-any.whl

outcomeci/__init__.py

@@ -0,0 +1,7 @@
+"""OutcomeCI portable workflow runtime."""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("outcomeci-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

outcomeci/cli.py

@@ -0,0 +1,140 @@
+"""OutcomeCI command-line interface."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from . import __version__
+from .config import ConfigError, compile_workflow
+from .local import advance as advance_local_outcome
+from .local import begin as begin_local_outcome
+from .local import compile_context
+from .local import continue_run as continue_local_outcome
+from .local import start as start_local_outcome
+from .local import status as local_outcome_status
+from .local import validate_artifacts
+from .outcome import run as run_outcome
+from .process import ExecutionError
+from .repository import RepositoryError, initialize, update, validate
+from .twin import TwinError, search
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="oci", description="Standup and outcome workflows for OutcomeCI")
+    root.add_argument("--version", action="version", version=f"oci {__version__}")
+    commands = root.add_subparsers(dest="command", required=True)
+    for name in ("init", "update", "validate", "status"):
+        item = commands.add_parser(name)
+        item.add_argument("--dir", type=Path, default=Path.cwd())
+        if name == "init":
+            item.add_argument("--backend", choices=("outcomeci", "filesystem"), default="outcomeci")
+    outcome = commands.add_parser("outcome")
+    outcome_commands = outcome.add_subparsers(dest="outcome_command", required=True)
+    for name in ("validate", "compile"):
+        item = outcome_commands.add_parser(name)
+        item.add_argument("config", nargs="?", type=Path, default=Path("outcome.yml"))
+        if name == "compile":
+            item.add_argument("--phase", choices=("intake", "plan", "tasks", "implementation", "pr"))
+            item.add_argument("--run")
+            item.add_argument("--workspace", type=Path, default=Path.cwd())
+    run = outcome_commands.add_parser("run")
+    run.add_argument("--claim", required=True, type=Path)
+    run.add_argument("--workspace", type=Path, default=Path("/workspace"))
+    start = outcome_commands.add_parser("start")
+    start.add_argument("intent")
+    start.add_argument("--workspace", type=Path, default=Path.cwd())
+    start.add_argument("--config", type=Path)
+    start.add_argument("--agent", choices=("codex", "claude"))
+    start.add_argument("--model")
+    continuation = outcome_commands.add_parser("continue")
+    continuation.add_argument("run_id")
+    continuation.add_argument("--approve", action="store_true")
+    continuation.add_argument("--workspace", type=Path, default=Path.cwd())
+    continuation.add_argument("--config", type=Path)
+    continuation.add_argument("--agent", choices=("codex", "claude"))
+    continuation.add_argument("--model")
+    outcome_status = outcome_commands.add_parser("status")
+    outcome_status.add_argument("run_id", nargs="?")
+    outcome_status.add_argument("--workspace", type=Path, default=Path.cwd())
+    begin_command = outcome_commands.add_parser("begin")
+    begin_command.add_argument("intent")
+    begin_command.add_argument("--workspace", type=Path, default=Path.cwd())
+    begin_command.add_argument("--config", type=Path)
+    validate_command = outcome_commands.add_parser("validate-artifacts")
+    validate_command.add_argument("--run")
+    validate_command.add_argument("--workspace", type=Path, default=Path.cwd())
+    validate_command.add_argument("--config", type=Path)
+    advance_command = outcome_commands.add_parser("advance")
+    advance_command.add_argument("--run")
+    advance_command.add_argument("--approve", action="store_true")
+    advance_command.add_argument("--workspace", type=Path, default=Path.cwd())
+    advance_command.add_argument("--config", type=Path)
+    twin = commands.add_parser("twin")
+    twin_commands = twin.add_subparsers(dest="twin_command", required=True)
+    twin_search = twin_commands.add_parser("search")
+    twin_search.add_argument("query")
+    twin_search.add_argument("--repository-id", action="append", default=[])
+    twin_search.add_argument("--limit", type=int, default=10)
+    twin_search.add_argument("--component-limit", type=int, default=20)
+    return root
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            print(json.dumps({"created": initialize(args.dir, args.backend)}, indent=2))
+        elif args.command == "update":
+            print(json.dumps({"created": update(args.dir)}, indent=2))
+        elif args.command == "validate":
+            result = validate(args.dir)
+            print(json.dumps({"valid": True, "workflow_revision": result["workflow_revision"]}, indent=2))
+        elif args.command == "status":
+            result = validate(args.dir)
+            print(json.dumps({"initialized": True, "workflow_revision": result["workflow_revision"], "path": str(args.dir.resolve())}, indent=2))
+        elif args.command == "outcome" and args.outcome_command == "validate":
+            result = compile_workflow(args.config)
+            print(json.dumps({"valid": True, "workflow_revision": result["workflow_revision"]}, indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "compile":
+            if args.run:
+                result = compile_context(args.workspace.resolve(), args.config.resolve(), args.run)
+            else:
+                result = compile_workflow(args.config)
+                if args.phase:
+                    phase = result["instructions"]["phases"].get(args.phase)
+                    if phase is None:
+                        raise ExecutionError(f"workflow has no instructions for {args.phase}")
+                    result = {**result, "instructions": {"standup": result["instructions"]["standup"], "phase": phase}}
+            print(json.dumps(result, indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "run":
+            print(json.dumps(run_outcome(args.claim, args.workspace), separators=(",", ":")))
+        elif args.command == "outcome" and args.outcome_command == "start":
+            config = args.config or args.workspace / "outcome.yml"
+            print(json.dumps(start_local_outcome(args.workspace.resolve(), config.resolve(), args.intent, agent=args.agent, model=args.model), indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "continue":
+            config = args.config or args.workspace / "outcome.yml"
+            print(json.dumps(continue_local_outcome(args.workspace.resolve(), config.resolve(), args.run_id, args.approve, agent=args.agent, model=args.model), indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "status":
+            print(json.dumps(local_outcome_status(args.workspace.resolve(), args.run_id), indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "begin":
+            config = args.config or args.workspace / "outcome.yml"
+            print(json.dumps(begin_local_outcome(args.workspace.resolve(), config.resolve(), args.intent), indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "validate-artifacts":
+            config = args.config or args.workspace / "outcome.yml"
+            print(json.dumps(validate_artifacts(args.workspace.resolve(), config.resolve(), args.run), indent=2, sort_keys=True))
+        elif args.command == "outcome" and args.outcome_command == "advance":
+            config = args.config or args.workspace / "outcome.yml"
+            print(json.dumps(advance_local_outcome(args.workspace.resolve(), config.resolve(), args.run, args.approve), indent=2, sort_keys=True))
+        elif args.command == "twin" and args.twin_command == "search":
+            print(json.dumps(search(args.query, args.repository_id, args.limit, args.component_limit), indent=2, sort_keys=True))
+        return 0
+    except (ConfigError, RepositoryError, TwinError, ExecutionError) as exc:
+        print(f"oci: {exc}", file=sys.stderr)
+        return 1 if isinstance(exc, ExecutionError) and exc.retryable else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

outcomeci/config.py

@@ -0,0 +1,142 @@
+"""Validation and deterministic compilation for outcome.yml."""
+from __future__ import annotations
+
+import hashlib
+import fnmatch
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from . import __version__
+
+PHASES = ("intake", "plan", "tasks", "implementation", "pr")
+RUNNERS = {"codex", "claude"}
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def _mapping(value: Any, path: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{path} must be a mapping")
+    return value
+
+
+def load(path: Path) -> dict[str, Any]:
+    try:
+        root = _mapping(yaml.safe_load(path.read_text(encoding="utf-8")), "document")
+    except (OSError, yaml.YAMLError) as exc:
+        raise ConfigError(f"could not read {path}: {exc}") from exc
+    if root.get("apiVersion") != "outcomeci.dev/v1alpha1":
+        raise ConfigError("apiVersion must be outcomeci.dev/v1alpha1")
+    if root.get("kind") != "OutcomeWorkflow":
+        raise ConfigError("kind must be OutcomeWorkflow")
+    metadata = _mapping(root.get("metadata"), "metadata")
+    if not isinstance(metadata.get("name"), str) or not metadata["name"].strip():
+        raise ConfigError("metadata.name is required")
+    spec = _mapping(root.get("spec"), "spec")
+    for field, choices in (("backend", {"outcomeci", "filesystem"}), ("context", {"outcomeci", "http", "filesystem"})):
+        value = _mapping(spec.get(field, {"provider": "outcomeci"}), f"spec.{field}")
+        if value.get("provider", "outcomeci") not in choices:
+            raise ConfigError(f"unsupported spec.{field}.provider")
+        if field == "context":
+            for patterns_name in ("include", "exclude"):
+                patterns = value.get(patterns_name, [])
+                if not isinstance(patterns, list) or not all(isinstance(pattern, str) and pattern.strip() for pattern in patterns):
+                    raise ConfigError(f"spec.context.{patterns_name} must be a list of non-empty glob strings")
+    instructions = _mapping(spec.get("instructions"), "spec.instructions")
+    if not isinstance(instructions.get("standup"), str):
+        raise ConfigError("spec.instructions.standup is required")
+    agents = _mapping(spec.get("agents", {}), "spec.agents")
+    default = _mapping(agents.get("default", {}), "spec.agents.default")
+    phases = _mapping(agents.get("phases", {}), "spec.agents.phases")
+    unknown = set(phases) - set(PHASES)
+    if unknown:
+        raise ConfigError(f"unknown outcome phases: {', '.join(sorted(unknown))}")
+    for name, policy in (("default", default), *phases.items()):
+        item = _mapping(policy, f"spec.agents.{name}")
+        if item.get("runner") is not None and item["runner"] not in RUNNERS:
+            raise ConfigError(f"spec.agents.{name}.runner must be codex or claude")
+        if item.get("model") is not None and not str(item["model"]).strip():
+            raise ConfigError(f"spec.agents.{name}.model must be non-empty")
+        if name != "default" and not isinstance(item.get("instructions"), str):
+            raise ConfigError(f"spec.agents.{name}.instructions is required")
+    connections = spec.get("connections", [])
+    if not isinstance(connections, list):
+        raise ConfigError("spec.connections must be a list")
+    refs: set[str] = set()
+    for index, value in enumerate(connections):
+        item = _mapping(value, f"spec.connections[{index}]")
+        ref = item.get("ref")
+        if not isinstance(ref, str) or not ref or ref in refs:
+            raise ConfigError("connection references must be unique non-empty strings")
+        refs.add(ref)
+    return root
+
+
+def _instruction(root: Path, relative: str) -> dict[str, str]:
+    path = (root / relative).resolve()
+    try:
+        path.relative_to(root.resolve())
+    except ValueError as exc:
+        raise ConfigError("instruction path escapes repository") from exc
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"could not read instruction {relative}: {exc}") from exc
+    if not content.strip():
+        raise ConfigError(f"instruction {relative} is empty")
+    return {"path": relative, "sha256": hashlib.sha256(content.encode()).hexdigest(), "content": content}
+
+
+def _excluded(relative: str, patterns: list[str]) -> bool:
+    return any(
+        fnmatch.fnmatch(relative, pattern)
+        or (pattern.endswith("/**") and (relative == pattern[:-3] or relative.startswith(pattern[:-2])))
+        for pattern in patterns
+    )
+
+
+def _filesystem_context(root: Path, context: dict[str, Any]) -> list[dict[str, Any]]:
+    includes = context.get("include", [])
+    excludes = context.get("exclude", [])
+    paths: dict[str, Path] = {}
+    for pattern in includes:
+        if pattern.endswith("/**"):
+            base = root / pattern[:-3]
+            matches = base.rglob("*") if base.is_dir() else []
+        else:
+            matches = root.glob(pattern)
+        for path in matches:
+            if not path.is_file():
+                continue
+            resolved = path.resolve()
+            try:
+                relative = resolved.relative_to(root.resolve()).as_posix()
+            except ValueError as exc:
+                raise ConfigError(f"context path escapes repository: {path}") from exc
+            if not _excluded(relative, excludes):
+                paths[relative] = resolved
+    if len(paths) > 5000:
+        raise ConfigError("filesystem context exceeds 5000 files")
+    return [
+        {"path": relative, "byte_size": path.stat().st_size, "sha256": hashlib.sha256(path.read_bytes()).hexdigest()}
+        for relative, path in sorted(paths.items())
+    ]
+
+
+def compile_workflow(path: Path) -> dict[str, Any]:
+    document = load(path)
+    spec = document["spec"]
+    resolved = {"standup": _instruction(path.parent, spec["instructions"]["standup"]), "phases": {}}
+    for phase, policy in spec.get("agents", {}).get("phases", {}).items():
+        resolved["phases"][phase] = _instruction(path.parent, policy["instructions"])
+    normalized = json.loads(json.dumps(document, sort_keys=True, separators=(",", ":")))
+    context = spec.get("context", {"provider": "outcomeci"})
+    context_files = _filesystem_context(path.parent, context) if context.get("provider") == "filesystem" else []
+    revision_input = {"workflow": normalized, "instructions": resolved, "context": {"provider": context.get("provider", "outcomeci"), "files": context_files}}
+    revision = hashlib.sha256(json.dumps(revision_input, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    return {"schema_version": "outcomeci.workflow/v1alpha1", "engine_version": "1", "engine_package_version": __version__, "workflow_revision": revision, **revision_input}

outcomeci/local.py

@@ -0,0 +1,318 @@
+"""Filesystem-backed execution of an OutcomeWorkflow with a local agent."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import compile_workflow
+from .manifest import build_manifest
+from .outcome import _expected, _select_sessions, _session_details, _transcripts, _validate_trajectory
+from .process import ExecutionError, invoke
+
+PHASES = ("intake", "plan", "tasks")
+
+
+def _id(intent: str) -> str:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S%f")
+    slug = re.sub(r"[^a-z0-9]+", "-", intent.casefold()).strip("-")[:36] or "outcome"
+    return f"{stamp}-{slug}"
+
+
+def _policy(compiled: dict[str, Any], phase: str, agent: str | None, model: str | None) -> tuple[str, str | None]:
+    agents = compiled["workflow"]["spec"].get("agents", {})
+    default = agents.get("default", {})
+    selected = agents.get("phases", {}).get(phase, {})
+    runner = agent or selected.get("runner") or default.get("runner")
+    chosen_model = model or selected.get("model") or default.get("model")
+    if runner not in {"codex", "claude"}:
+        raise ExecutionError(f"no supported agent configured for {phase}")
+    return runner, chosen_model
+
+
+def _record(root: Path, run_id: str) -> Path:
+    return root / ".outcomeci" / "outcomes" / run_id / "run.json"
+
+
+def _read(root: Path, run_id: str) -> dict[str, Any]:
+    try:
+        value = json.loads(_record(root, run_id).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ExecutionError(f"local outcome {run_id!r} was not found") from exc
+    if not isinstance(value, dict):
+        raise ExecutionError("invalid local outcome state")
+    return value
+
+
+def _write(root: Path, state: dict[str, Any]) -> None:
+    path = _record(root, state["run_id"])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    state["updated_at"] = datetime.now(timezone.utc).isoformat()
+    path.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _local_revision(root: Path) -> str | None:
+    result = subprocess.run(
+        ["git", "rev-parse", "HEAD"], cwd=root, text=True, capture_output=True, check=False
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def _interactive_session(root: Path, compiled: dict[str, Any]) -> dict[str, Any]:
+    codex_id = os.environ.get("CODEX_SESSION_ID") or os.environ.get("CODEX_THREAD_ID")
+    claude_id = os.environ.get("CLAUDE_CODE_SESSION_ID") or os.environ.get("CLAUDE_SESSION_ID")
+    if codex_id:
+        provider, session_id = "codex", codex_id
+    elif claude_id or os.environ.get("CLAUDECODE"):
+        provider, session_id = "claude", claude_id
+    else:
+        provider = compiled["workflow"]["spec"].get("agents", {}).get("default", {}).get("runner", "codex")
+        session_id = None
+    matches = _select_sessions(provider, session_id, root, None)
+    if matches and not session_id:
+        session_id = _session_details(matches[0], provider)[0]
+    return {
+        "provider": provider,
+        "session_id": session_id,
+        "byte_offset": matches[0].stat().st_size if matches else 0,
+    }
+
+
+def _execute(root: Path, config: Path, state: dict[str, Any], *, agent: str | None = None, model: str | None = None) -> dict[str, Any]:
+    compiled = compile_workflow(config)
+    if compiled["workflow"]["spec"]["backend"].get("provider") != "filesystem":
+        raise ExecutionError("local execution requires spec.backend.provider: filesystem")
+    phase = state["phase"]
+    runner, chosen_model = _policy(compiled, phase, agent, model)
+    outcome_root = root / ".outcomeci" / "outcomes" / state["run_id"]
+    repository = root.name
+    shared = compiled["instructions"]["standup"]["content"]
+    instructions = compiled["instructions"]["phases"][phase]["content"]
+    local_revision = f"filesystem:{compiled['workflow_revision']}"
+    context = {
+        "run_id": state["run_id"], "phase": phase, "intent": state["intent"],
+        "repository": {"name": repository, "checkout": str(root)},
+        "prior_phases": state.get("completed_phases", []),
+        "workflow_revision": compiled["workflow_revision"],
+        "context_files": compiled["context"]["files"],
+    }
+    intake_contract = ""
+    if phase == "intake":
+        intake_contract = f"""
+Write intake/trajectory.json with schema_version \"1\", ontology_revision_id
+\"{local_revision}\", and at least one target. The local target must use
+repository_id \"local:{repository}\", repository \"{repository}\", a non-empty
+rationale, and a candidates array following the stable role and disposition
+contract above. Use paths relative to this repository.
+"""
+    prompt = f"{shared}\n\n{instructions}\n\nThis is a filesystem-backed local Standup. Work in {root}. Write durable artifacts beneath {outcome_root}. During intake, plan, and tasks, do not modify product source files. There is no OutcomeCI Cloud or Digital Twin; inspect the local repository directly.\n{intake_contract}\n{json.dumps(context, separators=(',', ':'))}"
+    state.update({"status": "running", "agent": runner, "model": chosen_model, "workflow_revision": compiled["workflow_revision"]})
+    _write(root, state)
+    try:
+        summary = invoke(runner, chosen_model, prompt, root, 7200)
+        expected = _expected(outcome_root, [repository], phase)
+        if any(not path.is_file() or not path.read_text(encoding="utf-8").strip() for path in expected):
+            raise ExecutionError("agent did not produce the complete local outcome artifact set")
+        if phase == "intake":
+            trajectory = json.loads((outcome_root / "intake" / "trajectory.json").read_text(encoding="utf-8"))
+            _validate_trajectory(trajectory, {"intent_context": {"ontology_revision_id": local_revision}})
+        transcripts = _transcripts(runner, outcome_root, phase)
+    except (ExecutionError, OSError, json.JSONDecodeError) as exc:
+        state.update({"status": "error", "error": str(exc)})
+        _write(root, state)
+        if isinstance(exc, ExecutionError):
+            raise
+        raise ExecutionError(f"invalid local outcome artifacts: {exc}") from exc
+    state["completed_phases"] = [*state.get("completed_phases", []), phase]
+    state["status"] = "awaiting_confirmation" if phase != "tasks" else "ready_for_implementation"
+    state["summary"] = summary[-1000:]
+    state["usage_records"] = transcripts["usage_records"]
+    state.pop("error", None)
+    constitution = root / ".outcomeci" / "constitution.md"
+    manifest = build_manifest(
+        outcome_root=outcome_root,
+        artifact_base=root,
+        run_id=state["run_id"],
+        workflow_run_id=None,
+        trajectory_version=None,
+        phase=phase,
+        workflow_revision=compiled["workflow_revision"],
+        backend_provider="filesystem",
+        state_repository=None,
+        context_provider=compiled["workflow"]["spec"]["context"].get("provider", "filesystem"),
+        context_revision_id=local_revision,
+        constitution_sha256=hashlib.sha256(constitution.read_bytes()).hexdigest(),
+        repository_base_commits={repository: _local_revision(root)},
+        runner=runner,
+        model=chosen_model,
+        transcript=transcripts,
+    )
+    (outcome_root / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    _write(root, state)
+    return state
+
+
+def start(root: Path, config: Path, intent: str, *, agent: str | None = None, model: str | None = None) -> dict[str, Any]:
+    if not intent.strip():
+        raise ExecutionError("intent is required")
+    state = {"schema_version": 1, "run_id": _id(intent), "intent": intent.strip(), "phase": "intake", "status": "queued", "completed_phases": [], "created_at": datetime.now(timezone.utc).isoformat()}
+    return _execute(root, config, state, agent=agent, model=model)
+
+
+def begin(root: Path, config: Path, intent: str) -> dict[str, Any]:
+    """Create an interactive run without launching a child agent."""
+    if not intent.strip():
+        raise ExecutionError("intent is required")
+    compiled = compile_workflow(config)
+    if compiled["workflow"]["spec"]["backend"].get("provider") != "filesystem":
+        raise ExecutionError("interactive local execution requires spec.backend.provider: filesystem")
+    session = _interactive_session(root, compiled)
+    state = {
+        "schema_version": 1,
+        "run_id": _id(intent),
+        "intent": intent.strip(),
+        "phase": "intake",
+        "status": "awaiting_agent",
+        "completed_phases": [],
+        "workflow_revision": compiled["workflow_revision"],
+        "interactive_session": session,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _write(root, state)
+    return {**state, "outcome_root": str(_record(root, state["run_id"]).parent)}
+
+
+def compile_context(root: Path, config: Path, run_id: str | None) -> dict[str, Any]:
+    state = _read(root, run_id) if run_id else status(root, None)
+    if state.get("status") == "no_runs":
+        raise ExecutionError("no local outcome exists; run `oci outcome begin` first")
+    compiled = compile_workflow(config)
+    phase = state["phase"]
+    if phase not in compiled["instructions"]["phases"]:
+        raise ExecutionError(f"workflow has no instructions for {phase}")
+    runner, model = _policy(compiled, phase, state.get("interactive_session", {}).get("provider"), None)
+    context_revision = f"filesystem:{compiled['workflow_revision']}"
+    phase_contract: dict[str, Any] | None = None
+    if phase == "intake":
+        phase_contract = {
+            "artifact": "intake/trajectory.json",
+            "schema_version": "1",
+            "ontology_revision_id": context_revision,
+            "target": {
+                "repository_id": f"local:{root.name}",
+                "repository": root.name,
+                "required": ["rationale", "candidates"],
+            },
+        }
+    return {
+        "schema_version": "outcomeci.interactive-context/v1alpha1",
+        "run": state,
+        "outcome_root": str(_record(root, state["run_id"]).parent),
+        "runner": {"provider": runner, "model": model or "provider-default"},
+        "context": compiled["context"],
+        "phase_contract": phase_contract,
+        "instructions": {
+            "standup": compiled["instructions"]["standup"],
+            "phase": compiled["instructions"]["phases"][phase],
+        },
+        "workflow_revision": compiled["workflow_revision"],
+    }
+
+
+def validate_artifacts(root: Path, config: Path, run_id: str | None) -> dict[str, Any]:
+    state = _read(root, run_id) if run_id else status(root, None)
+    if state.get("status") == "no_runs":
+        raise ExecutionError("no local outcome exists")
+    compiled = compile_workflow(config)
+    phase = state["phase"]
+    repository = root.name
+    outcome_root = _record(root, state["run_id"]).parent
+    expected = _expected(outcome_root, [repository], phase)
+    missing = [str(path.relative_to(root)) for path in expected if not path.is_file() or not path.read_text(encoding="utf-8").strip()]
+    if missing:
+        raise ExecutionError(f"incomplete {phase} artifacts: {', '.join(missing)}")
+    standup = (outcome_root / "standup.md").read_text(encoding="utf-8")
+    if "# Standup:" not in standup or "**Status**: active" not in standup:
+        raise ExecutionError("agent did not produce a valid active Standup")
+    context_revision = f"filesystem:{compiled['workflow_revision']}"
+    if phase == "intake":
+        try:
+            trajectory = json.loads((outcome_root / "intake" / "trajectory.json").read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ExecutionError("intake trajectory is not valid JSON") from exc
+        _validate_trajectory(trajectory, {"intent_context": {"ontology_revision_id": context_revision}})
+    session = state.get("interactive_session", {})
+    runner, model = _policy(compiled, phase, session.get("provider"), None)
+    transcript = _transcripts(
+        runner,
+        outcome_root,
+        phase,
+        session_id=session.get("session_id"),
+        byte_offset=int(session.get("byte_offset") or 0),
+        workspace=root,
+        since=state.get("created_at"),
+    )
+    matches = _select_sessions(runner, session.get("session_id"), root, state.get("created_at"))
+    if matches:
+        session["session_id"] = session.get("session_id") or _session_details(matches[0], runner)[0]
+        session["byte_offset"] = matches[0].stat().st_size
+        state["interactive_session"] = session
+    constitution = root / ".outcomeci" / "constitution.md"
+    manifest = build_manifest(
+        outcome_root=outcome_root, artifact_base=root, run_id=state["run_id"],
+        workflow_run_id=None, trajectory_version=None, phase=phase,
+        workflow_revision=compiled["workflow_revision"], backend_provider="filesystem",
+        state_repository=None, context_provider="filesystem", context_revision_id=context_revision,
+        constitution_sha256=hashlib.sha256(constitution.read_bytes()).hexdigest(),
+        repository_base_commits={repository: _local_revision(root)}, runner=runner,
+        model=model, transcript=transcript,
+    )
+    (outcome_root / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    completed = list(state.get("completed_phases", []))
+    if phase not in completed:
+        completed.append(phase)
+    state.update({
+        "completed_phases": completed,
+        "status": "ready_for_implementation" if phase == "tasks" else "awaiting_confirmation",
+        "workflow_revision": compiled["workflow_revision"],
+    })
+    _write(root, state)
+    return {"valid": True, "run_id": state["run_id"], "phase": phase, "status": state["status"], "manifest": manifest}
+
+
+def advance(root: Path, config: Path, run_id: str | None, approve: bool) -> dict[str, Any]:
+    state = _read(root, run_id) if run_id else status(root, None)
+    if not approve:
+        raise ExecutionError("advancing requires explicit --approve")
+    if state.get("status") != "awaiting_confirmation":
+        raise ExecutionError(f"outcome cannot advance from {state.get('status')}")
+    state["phase"] = PHASES[PHASES.index(state["phase"]) + 1]
+    state["status"] = "awaiting_agent"
+    state["workflow_revision"] = compile_workflow(config)["workflow_revision"]
+    _write(root, state)
+    return {**state, "outcome_root": str(_record(root, state["run_id"]).parent)}
+
+
+def continue_run(root: Path, config: Path, run_id: str, approve: bool, *, agent: str | None = None, model: str | None = None) -> dict[str, Any]:
+    state = _read(root, run_id)
+    if state.get("status") != "awaiting_confirmation":
+        raise ExecutionError(f"outcome cannot continue from {state.get('status')}")
+    if not approve:
+        raise ExecutionError("continuation requires explicit --approve")
+    current = state["phase"]
+    state["phase"] = PHASES[PHASES.index(current) + 1]
+    state["status"] = "queued"
+    _write(root, state)
+    return _execute(root, config, state, agent=agent, model=model)
+
+
+def status(root: Path, run_id: str | None) -> dict[str, Any]:
+    if run_id:
+        return _read(root, run_id)
+    records = sorted((root / ".outcomeci" / "outcomes").glob("*/run.json"), reverse=True)
+    return _read(root, records[0].parent.name) if records else {"status": "no_runs"}

outcomeci/manifest.py

@@ -0,0 +1,52 @@
+"""Shared artifact manifest contract for local and managed outcome runs."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA_VERSION = "outcomeci.outcome-manifest/v1alpha1"
+
+
+def build_manifest(
+    *,
+    outcome_root: Path,
+    artifact_base: Path,
+    run_id: str,
+    workflow_run_id: str | None,
+    trajectory_version: int | None,
+    phase: str,
+    workflow_revision: str,
+    backend_provider: str,
+    state_repository: str | None,
+    context_provider: str,
+    context_revision_id: str | None,
+    constitution_sha256: str,
+    repository_base_commits: dict[str, str | None],
+    runner: str,
+    model: str | None,
+    transcript: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the canonical envelope without backend-specific omissions."""
+    artifacts = sorted(
+        str(path.relative_to(artifact_base))
+        for path in outcome_root.rglob("*")
+        if path.is_file() and path.name not in {"manifest.json", "run.json"}
+    )
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "run_id": run_id,
+        "odl_run_id": run_id,
+        "workflow_run_id": workflow_run_id,
+        "trajectory_version": trajectory_version,
+        "phase": phase,
+        "workflow_revision": workflow_revision,
+        "backend": {"provider": backend_provider, "state_repository": state_repository},
+        "context": {"provider": context_provider, "revision_id": context_revision_id},
+        "standup": str((outcome_root / "standup.md").relative_to(artifact_base)),
+        "constitution_sha256": constitution_sha256,
+        "repository_base_commits": repository_base_commits,
+        "runner": {"provider": runner, "model": model or "provider-default"},
+        "transcript": transcript,
+        "artifacts": artifacts,
+    }