okstra 0.219.0 → 0.220.0

package/runtime/python/okstra_ctl/stage_done.py

@@ -0,0 +1,183 @@
+"""`okstra stage-done` — settle a passing implementation stage: carry sidecar, then `done` row.
+
+Both writes were lead hand-work. The `done` row needed a python call to `append_consumer`,
+which Claude Code auto mode blocks, and the carry path in `_implementation-deliverable.md`
+(`runs/<impl-task-key>/carry/stage-<N>.json`) read as the staged run directory: measured
+2026-10-17 (figma-plugin dev-11377 run 002), the lead wrote
+`runs/implementation/stage-1/carry/stage-1.json`, validate-run looked for the flat
+`runs/implementation/carry/stage-1.json`, and the `done` row kept the wrong `carry_path`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_project import ResolverError, StateError, resolve_project_root
+
+from .consumers import (
+    FAILED_CARRY_STATUSES,
+    append_consumer,
+    carry_head_commit,
+    read_consumers,
+)
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from .paths import RunRef
+from .stage_reopen import resolve_planned_stage
+
+_REPORT_LABEL_RE = re.compile(r"^final-report-(?P<label>[a-z-]+-\d+)\.")
+
+
+def _read_carry(carry_file: Path, stage: int) -> dict:
+    try:
+        carry = load_owned_object(carry_file, artifact="implementation stage carry")
+    except (JsonBoundaryError, OSError) as exc:
+        raise StateError(
+            f"--carry must name the executor's `### Stage Carry Evidence` JSON saved under "
+            f"this run's .okstra tree: {exc}", stage="carry") from exc
+    recorded = carry.get("stage", carry.get("stageNumber"))
+    if isinstance(recorded, int) and recorded != stage:
+        raise StateError(f"--carry records stage {recorded}, not {stage}", stage="carry")
+    if str(carry.get("status") or "").lower() in FAILED_CARRY_STATUSES:
+        raise StateError(
+            f"--carry records status {carry['status']!r}; a failed stage is recorded with "
+            "`okstra stage-fail`", stage="carry")
+    if not carry_head_commit(carry):
+        raise StateError("--carry names no head commit (stageCommitRange.head)", stage="carry")
+    return carry
+
+
+def _supersede(target: Path, rows: list[dict], stage: int) -> Path:
+    """Move the sidecar of the run that first settled a reopened stage aside, unchanged."""
+    settled = [r for r in rows if r.get("stage") == stage and r.get("status") == "done"]
+    if not settled:
+        raise StateError(
+            f"{target} exists but stage {stage} was never settled — one stage holds one "
+            "sidecar; inspect it before replacing it by hand", stage="carry")
+    match = _REPORT_LABEL_RE.match(Path(str(settled[-1].get("report_path") or "")).name)
+    if not match:
+        raise StateError(
+            f"cannot name the superseded sidecar: the earlier done row's report_path "
+            f"{settled[-1].get('report_path')!r} is not a final-report path", stage="carry")
+    moved = target.parent / "superseded" / f"stage-{stage}-from-{match['label']}.json"
+    if moved.exists():
+        raise StateError(f"{moved} already exists", stage="carry")
+    moved.parent.mkdir(parents=True, exist_ok=True)
+    target.rename(moved)
+    return moved
+
+
+def done_stage(
+    project_root: Path, task_key: str, stage: int, carry_file: Path, report: Path,
+) -> dict:
+    """Write the stage's carry sidecar at its canonical path and append the `done` row."""
+    identity, plan_run_root = resolve_planned_stage(project_root, task_key, stage)
+    carry = _read_carry(carry_file, stage)
+    head = carry_head_commit(carry)
+    report = report if report.is_absolute() else project_root / report
+    try:
+        report_rel = report.relative_to(RunRef.from_report_path(report).run_dir).as_posix()
+    except ValueError as exc:
+        raise StateError(f"--report is not a final-report path: {report}", stage="report") from exc
+
+    rows = read_consumers(plan_run_root)
+    last = [r for r in rows if r.get("stage") == stage and r.get("status") in ("done", "failed")]
+    if last and last[-1].get("status") == "done" and last[-1].get("head_commit") != head:
+        raise StateError(
+            f"stage {stage} is already done at {last[-1].get('head_commit')}; withdraw it with "
+            "`okstra stage-reopen` before settling another head", stage="consumers")
+
+    task_root = Path(identity["taskRoot"])
+    target = RunRef.from_task_root(task_root, "implementation").carry(stage)
+    superseded = None
+    if target.exists():
+        existing = load_owned_object(target, artifact="implementation stage carry")
+        if carry_head_commit(existing) != head:
+            superseded = _supersede(target, rows, stage)
+    if not target.exists():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        write_owned_object_atomic(target, carry, artifact="implementation stage carry")
+    carry_rel = target.relative_to(task_root).as_posix()
+    append_consumer(
+        plan_run_root,
+        impl_task_key=identity["taskKey"],
+        stage=stage,
+        status="done",
+        head_commit=head,
+        carry_path=carry_rel,
+        report_path=report_rel,
+        completed_at=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    )
+    return {
+        "taskKey": identity["taskKey"],
+        "stage": stage,
+        "headCommit": head,
+        "carryPath": str(target),
+        "supersededCarryPath": str(superseded) if superseded else "",
+        "reportPath": report_rel,
+        "consumersPath": str(plan_run_root / "consumers.jsonl"),
+    }
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra stage-done <task-key> --stage <N> --carry <carry.json> --report <final-report path>
+
+Settles an implementation stage whose synthesised verdict is not FAIL. Writes the
+executor's `### Stage Carry Evidence` JSON (saved by the lead under the run's
+.okstra tree, with the post-fix head after a lead minor fix) to the stage's
+canonical sidecar `runs/implementation/carry/stage-<N>.json`, then appends the
+`done` row with that carry path, the report path relative to its run directory,
+the carry's head and the completion time. A reopened stage's previous sidecar
+is moved to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json` first.
+Refuses a carry for another stage, a failed carry, and a stage already done at
+another head. Re-running with the same carry writes nothing new.
+
+Output: JSON { ok, taskKey, stage, headCommit, carryPath, supersededCarryPath,
+reportPath, consumersPath }. Exit 1 on a refusal, 2 when
+PROJECT_ROOT cannot be resolved.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Settle a passing implementation stage (carry sidecar + done row).",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra stage-done")
+    parser.add_argument("task_key", metavar="task-key",
+                        help="project-id:task-group:task-id")
+    parser.add_argument("--stage", type=int, required=True,
+                        help="the Stage Map number this run implemented")
+    parser.add_argument("--carry", type=Path, required=True,
+                        help="the Stage Carry Evidence JSON saved under the run's .okstra tree")
+    parser.add_argument("--report", type=Path, required=True,
+                        help="this run's final-report path")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    args = parser.parse_args(argv)
+
+    def emit(payload: dict) -> None:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    try:
+        resolved = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        emit({"ok": False, "stage": "resolve", "reason": str(exc)})
+        return 2
+    try:
+        settled = done_stage(Path(resolved), args.task_key, args.stage,
+                             args.carry, args.report)
+    except StateError as exc:
+        emit({"ok": False, "stage": getattr(exc, "stage", None) or "stage-done",
+              "reason": str(exc)})
+        return 1
+    emit({"ok": True, **settled})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/stage_fail.py

@@ -0,0 +1,114 @@
+"""`okstra stage-fail` — FAIL 로 끝난 implementation run 의 stage 에 `failed` 행을 남긴다.
+
+종합 verdict 가 FAIL 이면 리드는 carry sidecar 대신 `failed` 행을 써야 한다
+(`_implementation-deliverable.md` §"Lead post-stage persistence"). 그 행을 쓰는 명령이
+없어 리드가 `append_consumer` 를 python 으로 직접 불렀고, Claude Code auto-mode 가 그
+호출을 막아 사용자가 손으로 실행해야 했다 — 실측(2026-10-17, figma-plugin dev-11377).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from okstra_project import ResolverError, StateError, resolve_project_root
+
+from .consumers import append_consumer, last_lifecycle_status_by_stage, read_consumers
+from .stage_reopen import resolve_planned_stage
+
+
+def fail_stage(
+    project_root: Path, task_key: str, stage: int, head_commit: str, report_path: str,
+    reason: str,
+) -> dict:
+    """아직 `done` 이 아닌 stage 에 `failed` 행을 붙인다."""
+    for flag, value in (("--head-commit", head_commit), ("--report", report_path),
+                        ("--reason", reason)):
+        if not value.strip():
+            raise StateError(f"{flag} is required", stage=flag.lstrip("-"))
+    identity, plan_run_root = resolve_planned_stage(project_root, task_key, stage)
+    recorded = last_lifecycle_status_by_stage(read_consumers(plan_run_root)).get(stage)
+    if recorded == "done":
+        raise StateError(
+            f"stage {stage} is recorded 'done' — withdraw a settled stage with "
+            "`okstra stage-reopen`, which records the done head it withdraws",
+            stage="consumers",
+        )
+    append_consumer(
+        plan_run_root,
+        impl_task_key=identity["taskKey"],
+        stage=stage,
+        status="failed",
+        head_commit=head_commit.strip(),
+        report_path=report_path.strip(),
+        reason=reason.strip(),
+    )
+    return {
+        "taskKey": identity["taskKey"],
+        "stage": stage,
+        "headCommit": head_commit.strip(),
+        "reportPath": report_path.strip(),
+        "reason": reason.strip(),
+        "consumersPath": str(plan_run_root / "consumers.jsonl"),
+    }
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra stage-fail <task-key> --stage <N> --head-commit <sha> --report <path> --reason "<why>"
+
+Appends the `failed` row an implementation run writes when its synthesised verdict
+is FAIL, or when it ends with no verifier result: dependents stay blocked, the
+stage's worktree occupancy is released, and `/okstra-run` offers the stage for a
+fix run that reuses its worktree and branch. --report is this run's final-report
+path as the `done` row would record it. Refuses a stage that is not in the latest
+Stage Map, is cancelled, or is already `done` (use `okstra stage-reopen`).
+Appending the same row twice writes it once.
+
+Output: JSON { ok, taskKey, stage, headCommit, reportPath, reason, consumersPath }.
+Exit 1 on a refusal, 2 when PROJECT_ROOT cannot be resolved.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Record a FAIL-ended implementation stage as failed.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra stage-fail")
+    parser.add_argument("task_key", metavar="task-key",
+                        help="project-id:task-group:task-id")
+    parser.add_argument("--stage", type=int, required=True,
+                        help="the Stage Map number this run implemented")
+    parser.add_argument("--head-commit", required=True,
+                        help="the stage worktree HEAD at the end of this run")
+    parser.add_argument("--report", required=True,
+                        help="this run's final-report path, as a done row records it")
+    parser.add_argument("--reason", required=True,
+                        help="why the stage failed; recorded on the row")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    args = parser.parse_args(argv)
+
+    def emit(payload: dict) -> None:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    try:
+        resolved = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        emit({"ok": False, "stage": "resolve", "reason": str(exc)})
+        return 2
+    try:
+        failed = fail_stage(Path(resolved), args.task_key, args.stage,
+                            args.head_commit, args.report, args.reason)
+    except StateError as exc:
+        emit({"ok": False, "stage": getattr(exc, "stage", None) or "stage-fail",
+              "reason": str(exc)})
+        return 1
+    emit({"ok": True, **failed})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -283,8 +283,14 @@ def _teardown_all(project_id, task_group, task_id, task_wt: str,
 
 def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, str] | None:
     """clean stage worktree 를 물리 제거. dirty/실패면 (outcome, detail), 성공이면 None."""
-    from .worktree import is_dirty_excluding_okstra, remove_worktree_force
-
+    from .worktree import (
+        is_dirty_excluding_okstra,
+        nested_worktree_excludes,
+        remove_worktree_force,
+    )
+
+    if nested_worktree_excludes(wt):
+        return ("skipped", "nested worktrees remain — preserved")
     if is_dirty_excluding_okstra(wt):
         return ("skipped", "dirty — 미커밋 변경 보존")
     rm = remove_worktree_force(task_wt, wt)
@@ -293,6 +299,35 @@ def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, st
     return None
 
 
+def reclaim_completed_stage(
+    project_root: Path, project_id: str, task_group: str, task_id: str,
+    stage: int, expected_head: str, done: dict | None, status: str,
+) -> tuple[str, str]:
+    from . import worktree_registry
+    from .worktree import main_worktree_path
+
+    row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage)
+    if not row:
+        return "skipped", "stage worktree is not registered"
+    if status != "done" or row.get("status") == "active":
+        return "skipped", "stage is unfinished or active"
+    if not expected_head or (done or {}).get("head_commit") != expected_head:
+        return "skipped", "completion commit does not match this report"
+    tip = _git(project_root, "rev-parse", "--verify", f"refs/heads/{row['branch']}")
+    if tip.returncode or tip.stdout.strip() != expected_head:
+        return "skipped", "stage branch moved after completion"
+    wt = Path(row["worktree_path"])
+    if wt.resolve() == main_worktree_path(project_root).resolve():
+        return "skipped", "main worktree is preserved"
+    if wt.exists():
+        current = _git(wt, "symbolic-ref", "--short", "HEAD")
+        if current.returncode or current.stdout.strip() != row["branch"]:
+            return "skipped", "worktree no longer holds the registered stage branch"
+    return _teardown_stage(
+        project_id, task_group, task_id, str(project_root), stage, row, expected_head,
+    )
+
+
 def _unmerged_branch_tip_warning(task_wt: str, stage_n: int, branch: str,
                                  verified_head: str = "") -> str:
     """Warn text when the stage branch tip is not an ancestor of the commit

package/runtime/python/okstra_ctl/stage_rebase.py

@@ -0,0 +1,189 @@
+"""선행 기준이 이동한 단계 브랜치를 의존 순서로 재배치한다."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import consumers, worktree_registry
+from .stage_targets import (
+    StageWorktreeIdentity,
+    order_stage_closure,
+    resolve_stage_base_commit,
+)
+from .worktree import is_ancestor
+from .worktree.rebase import _checked_git, rebase_stage_branch
+
+
+def _rebase_completed_stage(
+    project_root: Path,
+    plan_run_root: Path,
+    identity: StageWorktreeIdentity,
+    row: dict,
+    done_row: dict,
+    base: str,
+) -> dict:
+    number, branch = row["stage"], row["branch"]
+    tip = _checked_git(project_root, "rev-parse", f"refs/heads/{branch}")
+    if tip != done_row.get("head_commit"):
+        raise RuntimeError(
+            f"stage {number} branch moved beyond its done commit; reconcile it before rebasing"
+        )
+    head = rebase_stage_branch(project_root, branch, row["base_ref"], base)
+    worktree_registry.update_stage_base(
+        identity.project_id,
+        identity.task_group,
+        identity.task_id,
+        number,
+        expected_base=row["base_ref"],
+        base_ref=base,
+    )
+    consumers.append_consumer(
+        plan_run_root,
+        impl_task_key=done_row["impl_task_key"],
+        stage=number,
+        status="done",
+        force_reappend=True,
+        head_commit=head,
+        replaced_commit=tip,
+        reconciled=True,
+        reconcile_reason="dependency-rebase",
+        report_path=done_row.get("report_path", ""),
+    )
+    return {**done_row, "head_commit": head}
+
+
+def _refresh_predecessor_head(
+    root: Path,
+    plan: Path,
+    row: dict,
+    done_row: dict,
+    active: bool,
+) -> dict:
+    tip = _checked_git(root, "rev-parse", f"refs/heads/{row['branch']}")
+    previous = done_row["head_commit"]
+    if tip == previous:
+        return done_row
+    if active or not is_ancestor(root, previous, tip):
+        raise RuntimeError(
+            f"predecessor stage {row['stage']} is active or rewritten; finish or reconcile it first"
+        )
+    consumers.append_consumer(
+        plan,
+        impl_task_key=done_row["impl_task_key"],
+        stage=row["stage"],
+        status="done",
+        force_reappend=True,
+        head_commit=tip,
+        replaced_commit=previous,
+        reconciled=True,
+        reconcile_reason="predecessor-advance",
+        report_path=done_row.get("report_path", ""),
+    )
+    return {**done_row, "head_commit": tip}
+
+
+def synchronize_stage_stack(
+    *,
+    project_root: Path,
+    plan_run_root: Path,
+    stage_map: list[dict],
+    identity: StageWorktreeIdentity,
+) -> list[int]:
+    """호출자가 task-key provision 잠금을 잡은 상태에서 실행한다."""
+    rows = consumers.read_consumers(plan_run_root)
+    done = consumers.latest_done_by_stage(rows)
+    statuses = consumers.last_lifecycle_status_by_stage(rows)
+    anchor = (
+        worktree_registry.get_implementation_base(
+            identity.project_id,
+            identity.task_group,
+            identity.task_id,
+        )
+        or ""
+    )
+    graph = [(s["stage_number"], s.get("depends_on") or []) for s in stage_map]
+    order = order_stage_closure(graph, {n for n, _ in graph}, set())
+    if len(order) != len(graph):
+        raise RuntimeError("cannot synchronize a cyclic Stage Map")
+    by_number = {s["stage_number"]: s for s in stage_map}
+    predecessors = {dep for _, deps in graph for dep in deps}
+    changed = []
+    for number in order:
+        row = worktree_registry.get_stage_row(
+            identity.project_id,
+            identity.task_group,
+            identity.task_id,
+            number,
+        )
+        stage = by_number[number]
+        if not row or number not in done or stage.get("cancelled"):
+            continue
+        active = statuses.get(number) == "started" or row.get("status") == "active"
+        if _synchronize_recorded_stage(
+            project_root,
+            plan_run_root,
+            identity,
+            stage,
+            row,
+            done,
+            anchor,
+            active,
+            number in predecessors,
+        ):
+            changed.append(number)
+    return changed
+
+
+def _synchronize_recorded_stage(
+    root: Path,
+    plan: Path,
+    identity: StageWorktreeIdentity,
+    stage: dict,
+    row: dict,
+    done: dict[int, dict],
+    anchor: str,
+    active: bool,
+    predecessor: bool,
+) -> bool:
+    number = stage["stage_number"]
+    previous = done[number]["head_commit"]
+    if predecessor:
+        done[number] = _refresh_predecessor_head(root, plan, row, done[number], active)
+    if stage.get("depends_on"):
+        done[number] = _synchronize_dependent(
+            root,
+            plan,
+            identity,
+            stage,
+            row,
+            done,
+            anchor,
+            active,
+        )
+    return previous != done[number]["head_commit"]
+
+
+def _synchronize_dependent(
+    root: Path,
+    plan: Path,
+    identity: StageWorktreeIdentity,
+    stage: dict,
+    row: dict,
+    done: dict[int, dict],
+    anchor: str,
+    active: bool,
+) -> dict:
+    number = stage["stage_number"]
+    base = resolve_stage_base_commit(
+        stage,
+        list(done.values()),
+        anchor,
+        project_root=root,
+        plan_run_root=plan,
+        identity=identity,
+    )
+    if row["base_ref"] == base:
+        return done[number]
+    if active:
+        raise RuntimeError(f"cannot rebase active stage {number}; finish its run first")
+    return _rebase_completed_stage(root, plan, identity, row, done[number], base)

package/runtime/python/okstra_ctl/stage_reopen.py

@@ -31,16 +31,10 @@ from .paths import RunRef
 from .stage_map import StageMapError, load_latest_plan_stage_map
 
 
-def reopen_stage(
-    project_root: Path, task_key: str, stage: int, reason: str, evidence: str = "",
-) -> dict:
-    """마지막 행이 `done` 인 stage 에 `failed` 행을 붙이고 그 근거를 돌려준다."""
-    if not reason.strip():
-        raise StateError("--reason is required: say why the stage is reopened",
-                         stage="reason")
+def resolve_planned_stage(project_root: Path, task_key: str, stage: int) -> tuple[dict, Path]:
+    """task identity 와 plan run root 를 돌려준다. 최신 Stage Map 에 없거나 취소된 stage 는 거절한다."""
     identity = resolve_task_identity(project_root, task_key)
     task_root = Path(identity["taskRoot"])
-    plan_run_root = RunRef.from_task_root(task_root, "implementation-planning").run_dir
     try:
         stage_map = load_latest_plan_stage_map(task_root)
     except StageMapError as exc:
@@ -50,7 +44,17 @@ def reopen_stage(
         raise StateError(f"stage {stage} is not in this task's Stage Map", stage="stage-map")
     if any(row.get("stage_number") == stage and row.get("cancelled") for row in rows):
         raise StateError(f"stage {stage} is cancelled in the latest plan", stage="stage-map")
+    return identity, RunRef.from_task_root(task_root, "implementation-planning").run_dir
+
 
+def reopen_stage(
+    project_root: Path, task_key: str, stage: int, reason: str, evidence: str = "",
+) -> dict:
+    """마지막 행이 `done` 인 stage 에 `failed` 행을 붙이고 그 근거를 돌려준다."""
+    if not reason.strip():
+        raise StateError("--reason is required: say why the stage is reopened",
+                         stage="reason")
+    identity, plan_run_root = resolve_planned_stage(project_root, task_key, stage)
     consumers = read_consumers(plan_run_root)
     recorded = last_lifecycle_status_by_stage(consumers).get(stage)
     if recorded != "done":