okstra 0.219.1 → 0.220.1

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_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":

package/runtime/python/okstra_ctl/wizard/engine.py

@@ -96,7 +96,7 @@ def _build_group_prompt(state: WizardState, group_id: str) -> Prompt:
 
 
 def _is_lone_choice_pick(prompt: Prompt) -> bool:
-    """고를 것이 한 줄뿐인 단일 선택 픽인가.
+    """고를 것이 한 줄뿐인 픽인가 — 단일 선택이든 체크박스든.
 
     호스트 선택기는 옵션 2개 미만을 받지 않아(`nativeLimits` `minOptions`) 이런
     화면은 번호 1개짜리 목록으로 내려간다 — 사용자는 고를 것이 없는 목록에서
@@ -106,7 +106,6 @@ def _is_lone_choice_pick(prompt: Prompt) -> bool:
     """
     return (
         prompt.kind == "pick"
-        and not prompt.multi
         and len(prompt.options) == 1
         and prompt.options[0].value != _ABORT_OPTION
     )

package/runtime/schemas/final-report-v3.0.schema.json

@@ -1355,6 +1355,14 @@
             "$ref": "#/$defs/LeadFixRow"
           }
         },
+        "correctionRounds": {
+          "type": "array",
+          "description": "Correction rounds run in this run after a verifier FAIL (`_implementation-deliverable.md` \"Correction round\"): each sends the executor a bounded fix and the verifiers a re-verification. `verifierResults` holds the last round's verdicts; earlier FAIL verdicts stay here. Optional so reports of tasks already in flight keep validating.",
+          "maxItems": 2,
+          "items": {
+            "$ref": "#/$defs/CorrectionRoundRow"
+          }
+        },
         "rollbackVerification": {
           "type": "array",
           "minItems": 1,
@@ -10159,6 +10167,76 @@
         }
       }
     },
+    "CorrectionRoundRow": {
+      "type": "object",
+      "description": "One correction round: the findings it fixed, the executor's commit range, and each verifier's re-verification verdict.",
+      "required": [
+        "round",
+        "findingIds",
+        "baseCommit",
+        "commit",
+        "verifierVerdicts",
+        "result"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "round": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2
+        },
+        "findingIds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "baseCommit": {
+          "description": "Stage HEAD before the round.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$"
+        },
+        "commit": {
+          "description": "Stage HEAD after the executor's fix.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$"
+        },
+        "verifierVerdicts": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "verifier",
+              "verdict"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "verifier": {
+                "type": "string",
+                "minLength": 1
+              },
+              "verdict": {
+                "enum": [
+                  "PASS",
+                  "CONCERNS",
+                  "FAIL"
+                ]
+              }
+            }
+          }
+        },
+        "result": {
+          "description": "`pass` when no re-verification verdict is FAIL.",
+          "enum": [
+            "pass",
+            "fail"
+          ]
+        }
+      }
+    },
     "LeadFixRow": {
       "type": "object",
       "description": "One lead minor fix: the verifier findings it answers, the commit that carries it, and the re-run checks that decide whether the run may settle the stage. `changedLines` has no schema maximum on purpose: an over-limit fix must still be recordable, and `_validate_lead_fixes` reports it.",

package/runtime/skills/okstra-manager/SKILL.md

@@ -29,7 +29,7 @@ okstra manager task status --manager-id <manager-id> --task-group <task-group> -
 okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
 okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
 okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
-okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>]
+okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] [--allow-completed]
 okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
 okstra manager list managers
 okstra manager list projects --manager-id <manager-id>
@@ -104,7 +104,7 @@ When the user wants to see a manager at a glance, run `okstra manager task sync
 For launching child work:
 
 1. Run `okstra manager task sync ...` if the manager snapshot must be refreshed first.
-2. Run `okstra manager task run ...`.
+2. Run `okstra manager task run ...`. It re-reads the child's state from its project, not from the snapshot. When the child is already done there (terminal next phase, or work status `done`), it refuses with the last phase and report path; tell the user that and do not add `--allow-completed` unless the user asks to run the child again.
 3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, `Run command`, every numbered `Run arg N`, and `Shell command`.
 4. Give the user the `Shell command` line verbatim and tell them to run it in a new terminal. It starts the installed launcher in the child project: the launcher fills the task type and brief from the child task manifest or asks for them, prepares the run with the manager context directive, and starts the child lead as a separate host process (`Backend` `spawn-process`).
 

package/runtime/templates/reports/html/i18n/en.json

@@ -678,6 +678,12 @@
       "lead-fix-changed-lines": "Changed lines",
       "lead-fix-result-pass": "checks pass",
       "lead-fix-result-fail": "checks still fail",
+      "correction-rounds": "Corrected within this run",
+      "correction-rounds-intro": "Verifiers rejected the change. Instead of starting a fix run, the executor fixed the confirmed findings in this run and the verifiers checked the fix again.",
+      "correction-round": "Round",
+      "correction-range": "Fix range",
+      "correction-result-pass": "re-verification passed",
+      "correction-result-fail": "re-verification failed",
       "entry-count": "{count} entries",
       "manual-user-test": "Manual user test",
       "environment": "Environment:",

package/runtime/templates/reports/html/i18n/ko.json

@@ -678,6 +678,12 @@
       "lead-fix-changed-lines": "바뀐 줄 수",
       "lead-fix-result-pass": "검사 통과",
       "lead-fix-result-fail": "검사 여전히 실패",
+      "correction-rounds": "이 run 안에서 고친 것",
+      "correction-rounds-intro": "검증자가 변경을 거부했습니다. fix run 을 새로 여는 대신 이 run 안에서 실행자가 확인된 finding 을 고치고, 검증자가 그 수정을 다시 검증했습니다.",
+      "correction-round": "라운드",
+      "correction-range": "수정 범위",
+      "correction-result-pass": "재검증 통과",
+      "correction-result-fail": "재검증 실패",
       "entry-count": "{count}개 항목",
       "manual-user-test": "수동 사용자 테스트",
       "environment": "환경:",

package/runtime/validators/validate-run.py

@@ -40,6 +40,7 @@ from okstra_ctl.phases.implementation.validation import (
     _validate_verifier_reran_independently,
     _validate_verifier_discrepancy_is_not_passed,
     _validate_verifier_fail_blocks_verdict,
+    _validate_correction_rounds,
     _validate_lead_fixes,
     _validate_verifier_command_log_is_read_only as validate_verifier_command_log_is_read_only,
     _validate_verifier_discrepancy_names_checklist_phase as validate_verifier_discrepancy_names_checklist_phase,
@@ -3187,6 +3188,7 @@ def validate_final_report_data(
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
         _validate_lead_fixes(data, failures)
         _validate_lead_fix_carry_head(data, report_path, failures)
+        _validate_correction_rounds(data, manifest, failures)
     _validate_lead_authored_report(data, report_path, failures)
     if task_type == "error-analysis":
         _validate_error_analysis_consistency(data, failures)