okstra 0.102.3 → 0.103.0

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -0,0 +1,271 @@
+"""Artifact-derived implementation phase outcome reconciliation."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .consumers import read_stage_consumer_state
+from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
+
+
+@dataclass(frozen=True)
+class ImplementationOutcome:
+    completed: bool
+    stages: list[int] = field(default_factory=list)
+    head_commit: str = ""
+    report_path: str = ""
+    next_recommended_phase: str = ""
+    reason: str = ""
+
+
+def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
+    task_root = Path(task_root)
+    manifest = _load_json(task_root / "task-manifest.json")
+    workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+    if workflow.get("currentPhase") != "implementation":
+        return ImplementationOutcome(completed=False, reason="current phase is not implementation")
+
+    plan_run_root = task_root / "runs" / "implementation-planning"
+    if not plan_run_root.is_dir():
+        return ImplementationOutcome(completed=False, reason="implementation-planning run root missing")
+
+    stage_map = _load_stage_map(task_root, manifest)
+    if not stage_map:
+        return ImplementationOutcome(completed=False, reason="stage map unavailable")
+
+    consumers = read_stage_consumer_state(plan_run_root, recover_from_carry=True)
+    required_stages = {stage["stage_number"] for stage in stage_map}
+    if not required_stages or not required_stages.issubset(consumers.done_stages):
+        return ImplementationOutcome(completed=False, reason="not all stages are done")
+
+    carries = [_load_carry(task_root, stage) for stage in sorted(required_stages)]
+    if any(carry is None for carry in carries):
+        return ImplementationOutcome(completed=False, reason="carry sidecar missing")
+    if any(not _carry_passed(carry) for carry in carries if carry is not None):
+        return ImplementationOutcome(completed=False, reason="carry sidecar is not pass-grade")
+
+    latest_stage = max(required_stages)
+    latest_done = consumers.done_by_stage.get(latest_stage) or {}
+    latest_carry = carries[-1] or {}
+    return ImplementationOutcome(
+        completed=True,
+        stages=sorted(required_stages),
+        head_commit=str(latest_done.get("head_commit") or "") or _carry_head_commit(latest_carry),
+        report_path=_latest_implementation_report(task_root),
+        next_recommended_phase=DEFAULT_NEXT_PHASE["implementation"],
+        reason="all implementation stages have pass-grade carry and done rows",
+    )
+
+
+def reconcile_implementation_outcome(project_root: Path, task_root: Path) -> bool:
+    project_root = Path(project_root)
+    task_root = Path(task_root)
+    outcome = derive_implementation_outcome(task_root)
+    if not outcome.completed:
+        return False
+
+    manifest_path = task_root / "task-manifest.json"
+    manifest = _load_json(manifest_path)
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, dict):
+        workflow = {}
+        manifest["workflow"] = workflow
+
+    changed = _promote_workflow(workflow, outcome)
+    phase_outcome = manifest.get("phaseOutcome")
+    if not isinstance(phase_outcome, dict):
+        phase_outcome = {}
+        manifest["phaseOutcome"] = phase_outcome
+
+    contract = manifest.get("contractValidation")
+    contract_status = contract.get("status", "") if isinstance(contract, dict) else ""
+    implementation = {
+        "state": "completed",
+        "source": "implementation-carry",
+        "stages": outcome.stages,
+        "headCommit": outcome.head_commit,
+        "reportPath": outcome.report_path,
+        "contractValidationStatus": contract_status,
+        "reason": outcome.reason,
+    }
+    if phase_outcome.get("implementation") != implementation:
+        phase_outcome["implementation"] = implementation
+        changed = True
+
+    if changed:
+        _write_json(manifest_path, manifest)
+    return changed or _update_task_catalog(project_root, manifest)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    plan_path = _source_plan_path(task_root, manifest)
+    if not plan_path.is_file():
+        return []
+    from .run import PrepareError, _load_parsed_stage_map, _stage_map_reject_detail
+
+    try:
+        stages, errs = _load_parsed_stage_map(plan_path.read_text(encoding="utf-8"))
+    except PrepareError:
+        return []
+    if _stage_map_reject_detail(stages, errs) is not None:
+        return []
+    return [
+        {
+            "stage_number": stage.stage_number,
+            "title": stage.title,
+            "depends_on": list(stage.depends_on),
+            "step_count": stage.step_count,
+        }
+        for stage in stages
+    ]
+
+
+def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
+    carry_dir = task_root / "runs" / "implementation" / "carry"
+    for carry_path in sorted(carry_dir.glob("stage-*.json")):
+        value = _load_json(carry_path).get("sourcePlanPath")
+        if isinstance(value, str) and value:
+            return _resolve_relative(task_root, value)
+
+    latest = manifest.get("latestReportPath")
+    if isinstance(latest, str) and "implementation-planning" in latest:
+        return _resolve_relative(task_root, latest)
+
+    reports = task_root / "runs" / "implementation-planning" / "reports"
+    candidates = sorted(reports.glob("final-report-implementation-planning-*.md"))
+    return candidates[-1] if candidates else Path()
+
+
+def _resolve_relative(task_root: Path, value: str) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    project_root = _project_root_from_task_root(task_root)
+    project_relative = project_root / path
+    if project_relative.exists():
+        return project_relative
+    task_relative = task_root / path
+    if task_relative.exists():
+        return task_relative
+    return project_relative
+
+
+def _project_root_from_task_root(task_root: Path) -> Path:
+    parts = task_root.resolve().parts
+    if ".okstra" not in parts:
+        return task_root.resolve()
+    return Path(*parts[: parts.index(".okstra")])
+
+
+def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
+    data = _load_json(task_root / "runs" / "implementation" / "carry" / f"stage-{stage}.json")
+    return data or None
+
+
+def _carry_passed(carry: dict[str, Any]) -> bool:
+    status = str(carry.get("status") or "").lower()
+    if status in {"fail", "failed", "blocked", "error", "aborted"}:
+        return False
+    conformance = carry.get("conformance")
+    if isinstance(conformance, dict):
+        overall = str(conformance.get("overall") or "").upper()
+        if overall and overall != "PASS":
+            return False
+    unverified = carry.get("unverified")
+    return not (isinstance(unverified, list) and unverified)
+
+
+def _carry_head_commit(carry: dict[str, Any]) -> str:
+    stage_range = carry.get("stageCommitRange")
+    if isinstance(stage_range, dict) and stage_range.get("head"):
+        return str(stage_range["head"])
+    for key in ("head_sha", "head_commit", "head"):
+        value = carry.get(key)
+        if value:
+            return str(value)
+    commits = carry.get("commits")
+    if isinstance(commits, list) and commits:
+        last = commits[-1]
+        if isinstance(last, dict) and last.get("sha"):
+            return str(last["sha"])
+    return ""
+
+
+def _latest_implementation_report(task_root: Path) -> str:
+    reports = sorted(
+        (task_root / "runs" / "implementation").glob(
+            "stage-*/reports/final-report-implementation-*.md"
+        )
+    )
+    if not reports:
+        return ""
+    project_root = _project_root_from_task_root(task_root)
+    try:
+        return str(reports[-1].relative_to(project_root))
+    except ValueError:
+        return str(reports[-1])
+
+
+def _promote_workflow(workflow: dict[str, Any], outcome: ImplementationOutcome) -> bool:
+    before = json.dumps(workflow, sort_keys=True, ensure_ascii=False)
+    phase_states = workflow.get("phaseStates")
+    if not isinstance(phase_states, dict):
+        phase_states = {}
+        workflow["phaseStates"] = phase_states
+    for phase in PHASE_SEQUENCE:
+        phase_states.setdefault(phase, "not-started")
+    workflow["currentPhase"] = "implementation"
+    workflow["currentPhaseState"] = "completed"
+    phase_states["implementation"] = "completed"
+    workflow["lastCompletedPhase"] = "implementation"
+    workflow["nextRecommendedPhase"] = outcome.next_recommended_phase
+    after = json.dumps(workflow, sort_keys=True, ensure_ascii=False)
+    return before != after
+
+
+def _update_task_catalog(project_root: Path, manifest: dict[str, Any]) -> bool:
+    catalog_path = project_root / ".okstra" / "discovery" / "task-catalog.json"
+    catalog = _load_json(catalog_path)
+    tasks = catalog.get("tasks")
+    if not isinstance(tasks, list):
+        return False
+    task_key = manifest.get("taskKey")
+    workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+    outcome = manifest.get("phaseOutcome") if isinstance(manifest.get("phaseOutcome"), dict) else {}
+    for entry in tasks:
+        if not isinstance(entry, dict) or entry.get("taskKey") != task_key:
+            continue
+        before = json.dumps(entry, sort_keys=True, ensure_ascii=False)
+        entry["currentPhase"] = workflow.get("currentPhase", "")
+        entry["currentPhaseState"] = workflow.get("currentPhaseState", "")
+        entry["lastCompletedPhase"] = workflow.get("lastCompletedPhase", "")
+        entry["nextRecommendedPhase"] = workflow.get("nextRecommendedPhase", "")
+        entry["latestReportPath"] = manifest.get("latestReportPath", "")
+        entry["latestRunStatus"] = manifest.get("latestRunStatus", entry.get("latestRunStatus", ""))
+        entry["currentStatus"] = manifest.get("currentStatus", entry.get("currentStatus", ""))
+        entry["phaseOutcome"] = outcome
+        if before == json.dumps(entry, sort_keys=True, ensure_ascii=False):
+            return False
+        _write_json(catalog_path, catalog)
+        return True
+    return False
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )

package/runtime/python/okstra_ctl/manager_cli.py

@@ -0,0 +1,231 @@
+"""CLI entrypoint for okstra manager."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from okstra_project.dirs import okstra_home
+
+from .manager_launch import build_launch_packet
+from .manager_store import (
+    ManagerError,
+    append_directive,
+    assign_child,
+    create_task,
+    create_task_group,
+    discover_projects,
+    init_manager,
+    link_project,
+)
+from .manager_sync import status_task, sync_task
+
+
+def _emit(payload: dict | list[dict], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return
+    print(json.dumps(payload, ensure_ascii=False))
+
+
+def _normalize_global_flags(argv: list[str] | None) -> list[str]:
+    values = list(argv or [])
+    out: list[str] = []
+    json_seen = False
+    for value in values:
+        if value == "--json":
+            json_seen = True
+            continue
+        out.append(value)
+    return (["--json"] if json_seen else []) + out
+
+
+def _parse_child_specs(values: list[str], task_group: str, default_task_id: str) -> list[dict]:
+    specs: list[dict] = []
+    for value in values:
+        parts = value.split(":")
+        if len(parts) == 1:
+            specs.append({"projectId": parts[0], "taskId": default_task_id})
+            continue
+        if len(parts) == 2:
+            specs.append({"projectId": parts[0], "taskId": parts[1]})
+            continue
+        if len(parts) == 3:
+            project_id, embedded_task_group, child_task_id = parts
+            if embedded_task_group != task_group:
+                raise ManagerError(
+                    f"task-group mismatch for --task {value!r}: expected {task_group!r}, got {embedded_task_group!r}"
+                )
+            specs.append({"projectId": project_id, "taskId": child_task_id})
+            continue
+        raise ManagerError(
+            f"invalid --task {value!r}: expected project-id, project-id:task-id, or project-id:task-group:task-id"
+        )
+    return specs
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra manager")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--workspace-root", default="")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init")
+    init.add_argument("--manager-id", required=True)
+
+    sub.add_parser("discover-projects")
+
+    new = sub.add_parser("new")
+    new_sub = new.add_subparsers(dest="new_command", required=True)
+
+    project = new_sub.add_parser("project")
+    project.add_argument("--manager-id", required=True)
+    project.add_argument("--project-id", required=True)
+    project.add_argument("--project-root", required=True)
+    project.add_argument("--role", default="")
+    project.add_argument("--tag", action="append", default=[])
+
+    group = new_sub.add_parser("task-group")
+    group.add_argument("--manager-id", required=True)
+    group.add_argument("--task-group", required=True)
+
+    task_new = new_sub.add_parser("task")
+    task_new.add_argument("--manager-id", required=True)
+    task_new.add_argument("--task-group", required=True)
+    task_new.add_argument("--task-id", required=True)
+    task_new.add_argument("--task", action="append", default=[])
+    task_new.add_argument("--objective", default="")
+    task_new.add_argument("--common-brief", default="")
+    task_new.add_argument("--progress-mode", choices=["manual", "auto"], default="manual")
+
+    task = sub.add_parser("task")
+    task_sub = task.add_subparsers(dest="task_command", required=True)
+
+    for name in ("status", "sync"):
+        command = task_sub.add_parser(name)
+        command.add_argument("--manager-id", required=True)
+        command.add_argument("--task-group", required=True)
+        command.add_argument("--task-id", required=True)
+
+    assign = task_sub.add_parser("assign")
+    assign.add_argument("--manager-id", required=True)
+    assign.add_argument("--task-group", required=True)
+    assign.add_argument("--task-id", required=True)
+    assign.add_argument("--project-id", required=True)
+    assign.add_argument("--child-task-id", default=None)
+    assign.add_argument("--role", default="")
+    assign.add_argument("--tag", action="append", default=[])
+    assign.add_argument("--assignment", default="")
+
+    note = task_sub.add_parser("note")
+    note.add_argument("--manager-id", required=True)
+    note.add_argument("--task-group", required=True)
+    note.add_argument("--task-id", required=True)
+    note.add_argument("--scope", choices=["shared", "project"], required=True)
+    note.add_argument("--project-id", default="")
+    note.add_argument("--body", required=True)
+
+    run = task_sub.add_parser("run")
+    run.add_argument("--manager-id", required=True)
+    run.add_argument("--project-id", required=True)
+    run.add_argument("--task-group", required=True)
+    run.add_argument("--task-id", required=True)
+    run.add_argument("--child-task-id", default=None)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(_normalize_global_flags(argv if argv is not None else sys.argv[1:]))
+    home = okstra_home()
+    try:
+        if args.command == "init":
+            _emit(init_manager(home, args.manager_id), args.json)
+        elif args.command == "discover-projects":
+            _emit(discover_projects(home), args.json)
+        elif args.command == "new" and args.new_command == "project":
+            _emit(
+                link_project(
+                    home,
+                    args.manager_id,
+                    args.project_id,
+                    Path(args.project_root),
+                    role=args.role,
+                    tags=args.tag,
+                ),
+                args.json,
+            )
+        elif args.command == "new" and args.new_command == "task-group":
+            _emit(create_task_group(home, args.manager_id, args.task_group), args.json)
+        elif args.command == "new" and args.new_command == "task":
+            _emit(
+                create_task(
+                    home,
+                    args.manager_id,
+                    args.task_group,
+                    args.task_id,
+                    _parse_child_specs(args.task, args.task_group, args.task_id),
+                    objective=args.objective,
+                    common_brief_path=args.common_brief,
+                    progress_mode=args.progress_mode,
+                ),
+                args.json,
+            )
+        elif args.command == "task" and args.task_command == "assign":
+            _emit(
+                assign_child(
+                    home,
+                    args.manager_id,
+                    args.task_group,
+                    args.task_id,
+                    args.project_id,
+                    role=args.role,
+                    tags=args.tag,
+                    assignment=args.assignment,
+                    child_task_id=args.child_task_id,
+                ),
+                args.json,
+            )
+        elif args.command == "task" and args.task_command == "note":
+            _emit(
+                append_directive(
+                    home,
+                    args.manager_id,
+                    args.task_group,
+                    args.task_id,
+                    scope=args.scope,
+                    project_id=args.project_id,
+                    body=args.body,
+                ),
+                args.json,
+            )
+        elif args.command == "task" and args.task_command == "sync":
+            _emit(sync_task(home, args.manager_id, args.task_group, args.task_id), args.json)
+        elif args.command == "task" and args.task_command == "status":
+            _emit(status_task(home, args.manager_id, args.task_group, args.task_id), args.json)
+        elif args.command == "task" and args.task_command == "run":
+            _emit(
+                build_launch_packet(
+                    home,
+                    args.manager_id,
+                    args.task_group,
+                    args.task_id,
+                    args.project_id,
+                    child_task_id=args.child_task_id,
+                    env=os.environ,
+                ),
+                args.json,
+            )
+        else:
+            parser.print_help()
+            return 2
+        return 0
+    except ManagerError as exc:
+        print(f"okstra manager: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))