okstra 0.109.0 → 0.111.0

package/runtime/prompts/profiles/_implementation-diff-review.md

@@ -0,0 +1,43 @@
+<!--
+Post-write counterpart to _coding-conventions-preflight.md. The preflight gate
+runs BEFORE the first Edit/Write and loads the conventions; THIS gate runs AFTER
+the edits are written and BEFORE the executor's final commit, sweeping the actual
+diff against those same conventions with an exhaustive file×rule matrix. It is a
+prevention pass owned by the executor — it fixes findings in place, so the same
+defects do not reach the verifier's Static design gate or post-merge PR review.
+
+Same delivery paths as the other executor gates (see _implementation-executor.md
+"Pre-implementation context exploration"):
+  - Claude executor reads this file directly after its last Edit / Write.
+  - codex / antigravity executor cannot read this path (outside the CLI sandbox),
+    so the lead appends this file's body into the persisted executor prompt at
+    dispatch time (see codex_dispatch.py `_implementation_executor_tail`).
+The `Pre-commit diff review sweep` heading below is the literal string the CLI
+wrapper's "Executor post-write gate forwarding check" greps for in the persisted
+prompt (agents/workers/_cli-wrapper-template.md → Prompt Composition).
+-->
+
+# Pre-commit diff review sweep (BLOCKING — before the executor's final commit)
+
+Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, untruthful names, and unreadable functions all pass a green pipeline. This sweep is what keeps them out of the diff. Run it once, after the last `Edit` / `Write` of the stage, before the final commit. Fix every finding in place (you are the executor — you may edit); this is a prevention pass, not a report you hand off.
+
+Do not scan holistically and stop when it "looks fine". Work the matrix exhaustively — the failure mode this gate exists to prevent is a real defect surviving because you eyeballed the diff instead of enumerating it.
+
+## Method — enumerate the diff, then walk every (file × applicable-rule) cell
+
+1. **List every changed file:** `git diff --name-only <stage-base>..HEAD`. That list is your worklist — cover it to the end; no sampling.
+2. **Classify each file and select its rule set** from the conventions the preflight already loaded (do NOT re-derive the rules here — read them from the routed pack):
+   - any source file → `clean-code.md`: truthful + standalone names, plain-English summary test, single-purpose ≤50-line functions, DRY (incl. scattered domain literals + documented forks), no magic numbers, shallow nesting, comments explain why.
+   - test file (`*.spec.*` / `*.test.*` / `test_*.py` / `*_test.go` …) → `clean-code.md` "Testing discipline": no self-mocking of the SUT, behavioral (outcome) assertions not interaction-only, no tautological delegation assertion.
+   - port / adapter / domain file, when the hexagonal overlay is loaded → `architectures/hexagonal.md`: no business logic in a port body, adapter methods are I/O only (no post-fetch filtering on domain state, no `findValid*`/`findActive*` names hiding a rule), domain objects declared under the domain boundary.
+   A file can hold several roles — apply every rule set that fits it.
+3. **Decide clean-or-finding for each cell.** Read the full file when a rule needs context (never judge a port/adapter/domain or a naming rule from the hunk alone).
+4. **Fix each finding in place** before the commit. When a readability finding is real, the fix is a named helper or named intermediate value — sketch the cleaner shape (a few lines) in your audit note, then apply it. When the fix is genuinely out of this stage's scope, record it as an `Out-of-plan` note instead of silently leaving it.
+
+## Coverage footer (BLOCKING deliverable)
+
+End your audit-sidecar entry for this sweep with a one-line `Coverage:` footer naming each file you examined and the rule set(s) you applied to it — e.g. `Coverage: users.service.ts [names, plain-english], users.repository.adapter.ts [hexagonal, names], users.service.spec.ts [testing-discipline]`. The footer is how the completion self-check and any reviewer confirm nothing in the diff was skipped. A sweep with no footer is an unfinished sweep.
+
+## Graceful degradation
+
+When the routed coding-preflight pack is unreadable (codex / antigravity runtime, or the files are absent), do NOT skip the sweep — apply the language-agnostic principles the preflight already listed (no self-mocking, behavioral assertions, truthful/standalone names, single-purpose ≤50-line functions) plus the project's `CLAUDE.md` / `CONTRIBUTING` / lint config, and record `diff-review: resource-unavailable → applied <agnostic principles + project rules>` with the Coverage footer. Never claim a resource read that did not happen.

package/runtime/prompts/profiles/_implementation-executor.md

@@ -22,9 +22,12 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 - **Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop below).** The gate body is a single source at `prompts/profiles/_coding-conventions-preflight.md` (sibling of this sidecar). Do NOT re-type that content from memory — deliver it by file so it cannot drift or be dropped:
   - **Claude executor:** Read `_coding-conventions-preflight.md` end-to-end before the first `Edit` / `Write`, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`).
   - **CLI executor (BLOCKING when the executor provider is `codex` or `antigravity`):** the executor CLI process does NOT share the lead's context, and it cannot Read this sidecar's directory — that path sits outside the CLI sandbox and the CLI only sees its stdin prompt, so a file reference never reaches it. The lead MUST physically append the **body** of `_coding-conventions-preflight.md` into the persisted executor prompt at dispatch time: Read the file from the same absolute directory you read this sidecar from, then `Write`/`cat` its body into the persisted prompt. Never hand-retype it. Enforcement: the CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
-- **Completion self-check (BLOCKING — runs BEFORE you claim the stage done).** The gate body is a single source at `prompts/profiles/_implementation-self-check.md` (sibling of this sidecar): the four-item completion gate (functions ≤50 lines, conventions applied, truthful names & why-comments, real build/test run). Do NOT re-type it from memory — deliver it by file so it cannot drift.
-  - **Claude executor:** Read `_implementation-self-check.md` end-to-end before appending the `status:"done"` row, then write one confirming line per item to your audit sidecar.
-  - **CLI executor (codex / antigravity):** the CLI process cannot Read this path (outside its sandbox). The lead appends this file's body into the persisted executor prompt at dispatch time, immediately after the preflight body (see `codex_dispatch.py` `_implementation_executor_tail`). The head-less executor honours both gates from the single prompt.
+- **Pre-commit diff review sweep (BLOCKING — runs AFTER the last `Edit` / `Write`, BEFORE the final commit).** The gate body is a single source at `prompts/profiles/_implementation-diff-review.md` (sibling of this sidecar): an exhaustive file×rule sweep of the actual diff against the conventions the preflight loaded, with fix-in-place and a `Coverage:` footer. Do NOT re-type it from memory — deliver it by file so it cannot drift.
+  - **Claude executor:** Read `_implementation-diff-review.md` end-to-end after the stage's last edit, run the sweep over `git diff <stage-base>..HEAD`, fix findings in place, and write its `Coverage:` footer to your audit sidecar before committing.
+  - **CLI executor (codex / antigravity):** the CLI process cannot Read this path (outside its sandbox). The lead appends this file's body into the persisted executor prompt at dispatch time, between the preflight body and the self-check body (see `codex_dispatch.py` `_implementation_executor_tail`). The head-less executor honours all three gates from the single prompt.
+- **Completion self-check (BLOCKING — runs BEFORE you claim the stage done).** The gate body is a single source at `prompts/profiles/_implementation-self-check.md` (sibling of this sidecar): the completion gate (diff-review Coverage footer present, functions ≤50 lines, conventions applied, truthful names & why-comments, real build/test run, cleanup). Do NOT re-type it from memory — deliver it by file so it cannot drift.
+  - **Claude executor:** Read `_implementation-self-check.md` end-to-end before appending the `status:"done"` row, then write the confirming evidence per item to your audit sidecar.
+  - **CLI executor (codex / antigravity):** the CLI process cannot Read this path (outside its sandbox). The lead appends this file's body into the persisted executor prompt at dispatch time, immediately after the diff-review body (see `codex_dispatch.py` `_implementation_executor_tail`). The head-less executor honours all three gates from the single prompt.
 - **Stage discipline transcription (when a preceding stage is `done`):** the lead MUST transcribe the `Stage discipline` rule (from this run's rendered profile — the INCLUDEd `_stage-discipline.md` body) verbatim into the dispatched CLI executor prompt, so a codex/antigravity executor honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.
 - **Non-interactive auto-execution (BLOCKING when the executor provider is `codex` or `antigravity`).** A CLI executor runs head-less (`codex exec` / antigravity equivalent) — there is no human at the keyboard. Skills loaded during the run (tdd, coding-preflight, and others) contain "get user approval", "state your plan to the user and wait", or "ask before proceeding" gates written for interactive sessions; in this run those gates are **already satisfied** by the upstream `implementation-planning` approval (the plan this stage executes was human-approved). The executor MUST NOT stop to request approval, MUST NOT end its turn after only producing a plan, and MUST carry the stage through end-to-end — RED → GREEN → refactor → per-cycle commit → `### Stage Carry Evidence`. The ONLY skill step to skip is the interactive user-approval prompt itself; every other skill rule (TDD discipline, conventions, real-IO isolation) still binds. The lead MUST transcribe this bullet verbatim into the dispatched CLI executor prompt (same reason as the preflight transcription rule above — the CLI process does not share lead context). Stopping early for approval in a head-less run is the observed empty-exit failure (exit 0, no diff): treat it as `contract-violated`.
 - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
@@ -43,12 +46,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
   - **drift rule** (this section): if a file *named in the plan* has materially drifted, refuse to edit and route back to planning. This protects trust in the approved scope.
   - **out-of-plan rule** (Allowed actions section below): if a step *requires touching a file NOT in the plan list*, that is permitted with `Out-of-plan edits` justification. This handles honest scope discovery during execution.
 - confirm the test/build commands referenced in the plan still exist and run from a clean state
-- **Pre-commit review-rule sweep (BLOCKING before the executor's final commit):** inspect the run diff (`git diff <stage-base>..HEAD`) against the loaded coding conventions and project review rule packs. Fix in-place before handing to verifiers when the issue is inside this stage's scope. Minimum sweep:
-  - no new byte-identical or semantically equivalent helper stack appears in two touched services; extract a shared helper/domain module unless the approved plan explicitly justified duplication,
-  - no test asserts equality to a direct re-invocation of the collaborator/helper being delegated to; keep literal-value or observable-state assertions,
-  - no public method/repository function introduced by this run is left with zero in-scope callers unless it is part of a declared interface contract,
-  - no exported/public name hides side effects or omits the entity it acts on,
-  - no newly introduced function requires a reader to mentally name several phases that should be helper calls.
+- **Pre-commit diff review sweep (BLOCKING before the executor's final commit):** run the sweep whose body is delivered via `_implementation-diff-review.md` (see the gate-delivery bullet above) over the run diff (`git diff <stage-base>..HEAD`), and fix findings in place before handing to verifiers when the issue is inside this stage's scope. That sidecar is the single source for the sweep's file×rule matrix (DRY / self-mock / behavioral-test / hexagonal / truthful-name / plain-English rules) and its `Coverage:` footer — do not maintain a second copy of the rule list here.
 
 ## Stage execution contract (this run owns one stage)
 

package/runtime/prompts/profiles/_implementation-self-check.md

@@ -9,12 +9,18 @@ appends this file's body into the persisted executor prompt at dispatch time
 
 # Implementation self-check (BLOCKING — before you claim done)
 
-Before declaring the change complete, write one confirming line per item to your
-audit sidecar. If any item fails, fix it or surface the violation — do not claim
-done on a failing item.
+Before declaring the change complete, confirm each item below against the ACTUAL
+diff — not from memory. This is a re-derivation, not a rubber stamp: enumerate the
+changed files (`git diff --name-only <stage-base>..HEAD`) and, for the per-file
+items, write the confirming evidence per file, not one global "✓". If any item
+fails, fix it or surface the violation — do not claim done on a failing item.
 
-- functions: every new/edited function ≤50 effective lines, single purpose
+- diff-review done: the `Pre-commit diff review sweep` ran over the full diff and its `Coverage:` footer is in your audit sidecar (every changed file named with the rule set applied). No footer → the sweep is unfinished; do not claim done.
+- functions: every new/edited function ≤50 effective lines, single purpose — cite the longest function's actual line count, not "all under 50"
 - conventions: applied the routed pack + project patterns (name which ones)
 - names & comments: names say what, comments say why; no obvious-restatement comments; no truthful-name violations
-- verification: ran the actual build/test (paste the command + its result)
+- verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"
 - cleanup: no dead or commented-out code left behind
+
+Close with a `Self-check coverage:` line naming the files you verified the
+per-file items against, so the Coverage footer above and this gate reconcile.

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -818,6 +818,9 @@ def _implementation_executor_tail(
         parts.append(preflight_path.read_text(encoding="utf-8"))
     else:
         parts.append("# Coding-conventions preflight\n\nApply project-local conventions before editing.")
+    diff_review_path = profiles / "_implementation-diff-review.md"
+    if diff_review_path.is_file():
+        parts.append(diff_review_path.read_text(encoding="utf-8"))
     selfcheck_path = profiles / "_implementation-self-check.md"
     if selfcheck_path.is_file():
         parts.append(selfcheck_path.read_text(encoding="utf-8"))

package/runtime/python/okstra_ctl/consumers.py

@@ -68,6 +68,10 @@ def read_stage_consumer_state(
     if recover_from_carry:
         backfill_done_from_carry(plan_run_root)
     rows = read_consumers(plan_run_root)
+    return stage_consumer_state_from_rows(rows)
+
+
+def stage_consumer_state_from_rows(rows: List[Dict[str, Any]]) -> StageConsumerState:
     done_rows = [r for r in rows if r.get("status") == "done"]
     done_by_stage = latest_done_by_stage(rows)
     started = {

package/runtime/python/okstra_ctl/handoff.py

@@ -12,7 +12,7 @@ import subprocess
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
-from . import consumers, worktree_registry
+from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
@@ -44,28 +44,10 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
                         rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     """stage 별 PR 가능 여부와 차단 사유. 의존 폐포는 선택 집합의 속성이라
     여기서는 판정하지 않는다 (assemble 의 check_dependency_closure 가 담당)."""
-    done = consumers.latest_done_by_stage(rows)
-    verified = consumers.verified_accepted_stages(rows)
-    in_pr = consumers.pr_covered_stages(rows)
-    out = []
-    for s in stage_map:
-        n = s["stage_number"]
-        reasons = []
-        if n in in_pr:
-            reasons.append("already-in-pr")
-        else:
-            if n not in done:
-                reasons.append("not-done")
-            if n not in verified:
-                reasons.append("not-verified-accepted")
-        out.append({
-            "stage": n,
-            "depends_on": list(s["depends_on"]),
-            "eligible": not reasons,
-            "reasons": reasons,
-            "head_commit": (done.get(n) or {}).get("head_commit", ""),
-        })
-    return out
+    return stage_targets.stage_lifecycle_snapshot_from_rows(
+        stage_map,
+        rows,
+    ).handoff_eligibility()
 
 
 def latest_whole_task_fv_accepted(project_root, project_id: str,

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -66,32 +66,32 @@ def select_and_provision_implementation_stage(
     """
     del task_key  # The registry uses the split identity fields.
 
-    from .consumers import backfill_done_from_carry, read_stage_consumer_state
+    from .consumers import backfill_done_from_carry
     from . import worktree as _worktree
     from . import worktree_registry as _reg
 
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     backfill_done_from_carry(plan_run_root)
     auto_reconcile_best_effort(inp, plan_run_root)
-    consumers = read_stage_consumer_state(plan_run_root)
     reserved_stages = _reg.list_active_stage_numbers(
         inp.project_id,
         inp.task_group,
         inp.task_id,
     )
+    snapshot = stage_targets.read_stage_lifecycle_snapshot(
+        ctx_stage_map,
+        plan_run_root,
+        reserved_stages=reserved_stages,
+    )
 
     try:
-        selected = stage_targets.resolve_implementation_stage(
-            ctx_stage_map,
-            consumers.done_stages,
-            inp.stage,
-            started_stages=consumers.started_stages,
-            reserved_stages=reserved_stages,
-        )
+        selected = snapshot.resolve_implementation_stage(inp.stage)
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc
 
-    concurrent_stages = sorted(reserved_stages - consumers.done_stages - {selected})
+    concurrent_stages = snapshot.concurrent_stage_numbers(
+        selected_stage=selected,
+    )
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
@@ -133,7 +133,7 @@ def select_and_provision_implementation_stage(
     try:
         stage_base = stage_targets.resolve_stage_base_commit(
             selected_stage,
-            consumers.done_rows,
+            snapshot.done_rows,
             anchor_base_commit=anchor,
             candidate_base=head_sha,
             project_root=Path(task_worktree_path),

package/runtime/python/okstra_ctl/report_views.py

@@ -2,11 +2,17 @@
 
 Single product, single source of truth:
 
-* ``render_html(src_md, *, run_meta)`` — deterministic self-contained
-  HTML renderer for human readers. Sections §1/§3/§4 user-actionable
-  rows (those reachable from §1 ``C-*`` IDs) get embedded ``<form>``
-  controls. §5.6 / §5.7 / §5.8 deliverable sub-sections are explicitly
-  excluded from form attachment — they are read-only deliverables.
+* ``build_report_view_model(src_md, *, run_meta)`` — deterministic
+  server-side Report View Model for human readers. It carries source digest,
+  rendered body HTML, response IDs, sidecar hints, and optional approval
+  context.
+* ``render_report_view_model(model, *, css, js)`` — self-contained HTML
+  renderer over that model. Sections §1/§3/§4 user-actionable rows (those
+  reachable from §1 ``C-*`` IDs) get embedded ``<form>`` controls. §5.6 /
+  §5.7 / §5.8 deliverable sub-sections are explicitly excluded from form
+  attachment — they are read-only deliverables.
+* ``render_html(src_md, *, run_meta)`` remains a compatibility wrapper around
+  the model builder + renderer.
 
 User responses are NEVER merged back into the original report. The HTML
 serialises a ``user-response`` markdown sidecar via ``Export user
@@ -101,34 +107,56 @@ class RunMeta:
     source_report: str  # relative path of the .md the HTML is derived from
 
 
-def render_html(
+@dataclass(frozen=True)
+class ReportViewModel:
+    run_meta: RunMeta
+    title: str
+    body_html: str
+    source_digest: str
+    response_ids: tuple[str, ...]
+    sidecar_name: str
+    sidecar_dir: str
+    approval_ctx: PlanApprovalContext | None = None
+
+
+def build_report_view_model(
     src_md: str,
     *,
     run_meta: RunMeta,
-    css: str,
-    js: str,
     approval_ctx: PlanApprovalContext | None = None,
-) -> str:
-    """Return a single self-contained HTML document for ``src_md``.
-
-    ``css`` / ``js`` are inlined verbatim. No external URLs are written
-    into the document (validator enforces this — see
-    validate-report-views.py).
-    """
-    # Compute the digest over the source MD body. The validator
-    # recomputes the same digest from the current MD and compares it to
-    # the value embedded in run-meta below.
+) -> ReportViewModel:
     digest = source_digest(src_md)
     body_md = _strip_leading_frontmatter(src_md)
     body_html, toc_headings = _markdown_to_html(body_md)
     body_html = _inject_toc(body_html, toc_headings)
-    response_ids = sorted({item.row_id for item in (parse_clarification_items(body_md) or [])})
+    response_ids = tuple(
+        sorted({item.row_id for item in (parse_clarification_items(body_md) or [])})
+    )
+    return ReportViewModel(
+        run_meta=run_meta,
+        title=f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}",
+        body_html=body_html,
+        source_digest=digest,
+        response_ids=response_ids,
+        sidecar_name=f"user-response-{run_meta.task_type}-{run_meta.seq}.md",
+        sidecar_dir=f"runs/{run_meta.task_type}/user-responses/",
+        approval_ctx=approval_ctx,
+    )
 
-    title = html.escape(f"{run_meta.task_key} — {run_meta.task_type} #{run_meta.seq}")
-    response_ids_json = "[" + ",".join('"' + html.escape(rid) + '"' for rid in response_ids) + "]"
-    sidecar_name = html.escape(f"user-response-{run_meta.task_type}-{run_meta.seq}.md")
-    sidecar_dir = html.escape(f"runs/{run_meta.task_type}/user-responses/")
 
+def render_report_view_model(
+    model: ReportViewModel,
+    *,
+    css: str,
+    js: str,
+) -> str:
+    title = html.escape(model.title)
+    response_ids_json = "[" + ",".join(
+        '"' + html.escape(rid) + '"' for rid in model.response_ids
+    ) + "]"
+    sidecar_name = html.escape(model.sidecar_name)
+    sidecar_dir = html.escape(model.sidecar_dir)
+    run_meta = model.run_meta
     return (
         f"<!DOCTYPE html>\n"
         f"<html lang=\"ko\">\n"
@@ -143,8 +171,8 @@ def render_html(
         f"  <div>{title}</div>\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"</header>\n"
-        f"<main>{body_html}</main>\n"
-        f"{_plan_approval_section(approval_ctx, run_meta) if approval_ctx else ''}"
+        f"<main>{model.body_html}</main>\n"
+        f"{_plan_approval_section(model.approval_ctx, run_meta) if model.approval_ctx else ''}"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"  <p class=\"user-response-hint\">Export 클릭 시 <code>{sidecar_name}</code> 가 다운로드됩니다 — "
@@ -158,7 +186,7 @@ def render_html(
         f"\"task-type\":\"{html.escape(run_meta.task_type)}\","
         f"\"seq\":\"{html.escape(run_meta.seq)}\","
         f"\"source-report\":\"{html.escape(run_meta.source_report)}\","
-        f"\"source-sha256\":\"{digest}\","
+        f"\"source-sha256\":\"{model.source_digest}\","
         f"\"response-ids\":{response_ids_json}}}"
         f"</script>\n"
         f"<script>{js}</script>\n"
@@ -167,6 +195,28 @@ def render_html(
     )
 
 
+def render_html(
+    src_md: str,
+    *,
+    run_meta: RunMeta,
+    css: str,
+    js: str,
+    approval_ctx: PlanApprovalContext | None = None,
+) -> str:
+    """Return a single self-contained HTML document for ``src_md``.
+
+    ``css`` / ``js`` are inlined verbatim. No external URLs are written
+    into the document (validator enforces this — see
+    validate-report-views.py).
+    """
+    model = build_report_view_model(
+        src_md,
+        run_meta=run_meta,
+        approval_ctx=approval_ctx,
+    )
+    return render_report_view_model(model, css=css, js=js)
+
+
 def _markdown_to_html(
     src_md: str,
 ) -> tuple[str, list[tuple[int, str, str]]]:

package/runtime/python/okstra_ctl/stage_targets.py

@@ -38,6 +38,158 @@ class FinalVerificationTarget:
     reports: list[str]
 
 
+@dataclass(frozen=True)
+class StageLifecycle:
+    stage: int
+    depends_on: list[int]
+    done: bool
+    started: bool
+    reserved: bool
+    verified_accepted: bool
+    pr_covered: bool
+    head_commit: str
+    report_path: str
+
+    def handoff_eligibility_record(self) -> dict[str, Any]:
+        reasons: list[str] = []
+        if self.pr_covered:
+            reasons.append("already-in-pr")
+        else:
+            if not self.done:
+                reasons.append("not-done")
+            if not self.verified_accepted:
+                reasons.append("not-verified-accepted")
+        return {
+            "stage": self.stage,
+            "depends_on": list(self.depends_on),
+            "eligible": not reasons,
+            "reasons": reasons,
+            "head_commit": self.head_commit,
+        }
+
+
+@dataclass(frozen=True)
+class StageLifecycleSnapshot:
+    stage_map: list[dict[str, Any]]
+    rows: list[dict[str, Any]]
+    done_rows: list[dict[str, Any]]
+    done_by_stage: dict[int, dict[str, Any]]
+    done_stages: set[int]
+    started_stages: set[int]
+    reserved_stages: set[int]
+    verified_accepted_stages: set[int]
+    pr_covered_stages: set[int]
+    lifecycles: list[StageLifecycle]
+
+    def lifecycle_for(self, stage_number: int) -> StageLifecycle:
+        for lifecycle in self.lifecycles:
+            if lifecycle.stage == stage_number:
+                return lifecycle
+        raise StageTargetError(f"stage {stage_number} not in Stage Map")
+
+    def resolve_effective_stages(
+        self,
+        requested: str,
+        budget: int = RUN_STEP_BUDGET,
+    ) -> list[int]:
+        return resolve_effective_stages(
+            self.stage_map,
+            self.done_stages,
+            requested,
+            budget=budget,
+            started_stages=self.started_stages,
+            reserved_stages=self.reserved_stages,
+        )
+
+    def resolve_implementation_stage(self, requested: str) -> int:
+        return self.resolve_effective_stages(requested)[0]
+
+    def concurrent_stage_numbers(self, *, selected_stage: int) -> list[int]:
+        return sorted(self.reserved_stages - self.done_stages - {selected_stage})
+
+    def handoff_eligibility(self) -> list[dict[str, Any]]:
+        return [
+            lifecycle.handoff_eligibility_record()
+            for lifecycle in self.lifecycles
+        ]
+
+
+def _stage_consumer_state_from_rows(rows: list[dict[str, Any]]) -> Any:
+    from .consumers import stage_consumer_state_from_rows
+
+    return stage_consumer_state_from_rows(rows)
+
+
+def stage_lifecycle_snapshot_from_state(
+    stage_map: list[dict[str, Any]],
+    consumer_state: Any,
+    *,
+    reserved_stages: set[int] | None = None,
+) -> StageLifecycleSnapshot:
+    reserved = set(reserved_stages or set())
+    lifecycles: list[StageLifecycle] = []
+    for stage in stage_map:
+        stage_number = stage["stage_number"]
+        done_row = consumer_state.done_by_stage.get(stage_number) or {}
+        lifecycles.append(StageLifecycle(
+            stage=stage_number,
+            depends_on=list(stage.get("depends_on") or []),
+            done=stage_number in consumer_state.done_stages,
+            started=stage_number in consumer_state.started_stages,
+            reserved=stage_number in reserved,
+            verified_accepted=stage_number in (
+                consumer_state.verified_accepted_stages
+            ),
+            pr_covered=stage_number in consumer_state.pr_covered_stages,
+            head_commit=str(done_row.get("head_commit") or ""),
+            report_path=str(done_row.get("report_path") or ""),
+        ))
+    return StageLifecycleSnapshot(
+        stage_map=stage_map,
+        rows=list(consumer_state.rows),
+        done_rows=list(consumer_state.done_rows),
+        done_by_stage=dict(consumer_state.done_by_stage),
+        done_stages=set(consumer_state.done_stages),
+        started_stages=set(consumer_state.started_stages),
+        reserved_stages=reserved,
+        verified_accepted_stages=set(consumer_state.verified_accepted_stages),
+        pr_covered_stages=set(consumer_state.pr_covered_stages),
+        lifecycles=lifecycles,
+    )
+
+
+def stage_lifecycle_snapshot_from_rows(
+    stage_map: list[dict[str, Any]],
+    rows: list[dict[str, Any]],
+    *,
+    reserved_stages: set[int] | None = None,
+) -> StageLifecycleSnapshot:
+    return stage_lifecycle_snapshot_from_state(
+        stage_map,
+        _stage_consumer_state_from_rows(rows),
+        reserved_stages=reserved_stages,
+    )
+
+
+def read_stage_lifecycle_snapshot(
+    stage_map: list[dict[str, Any]],
+    plan_run_root: Path,
+    *,
+    recover_from_carry: bool = False,
+    reserved_stages: set[int] | None = None,
+) -> StageLifecycleSnapshot:
+    from .consumers import read_stage_consumer_state
+
+    return stage_lifecycle_snapshot_from_state(
+        stage_map,
+        read_stage_consumer_state(
+            plan_run_root,
+            recover_from_carry=recover_from_carry,
+        ),
+        reserved_stages=reserved_stages,
+    )
+
+
 def resolve_effective_stages(
     stages: list[dict[str, Any]],
     done_stages: set[int],

package/runtime/python/okstra_ctl/wizard.py

@@ -12,6 +12,7 @@ Public surface:
 - ``next_prompt()`` - deterministic; pure read on state.
 - ``submit()``      - validate + advance.
 - ``render_args()`` - final args for ``okstra render-bundle``.
+- ``wizard_outcome()`` - final args plus persistence actions and confirmation.
 
 The skill calls these via the ``okstra wizard`` CLI subcommand; it never
 imports this module directly.
@@ -3707,6 +3708,36 @@ def confirmation_block(state: WizardState) -> str:
     return "\n".join(lines)
 
 
+def _wizard_persist_actions(state: WizardState) -> list[dict[str, str]]:
+    if state.task_type != "release-handoff":
+        return []
+    if not state.pr_template_path:
+        return []
+    if state.pr_template_scope not in ("project", "global"):
+        return []
+    return [
+        {
+            "command": "config.set",
+            "key": "pr-template-path",
+            "scope": state.pr_template_scope,
+            "value": state.pr_template_path,
+        }
+    ]
+
+
+def wizard_outcome(state: WizardState) -> dict[str, Any]:
+    """Public outcome for callers that need launch data and follow-up writes."""
+    if state.aborted:
+        raise WizardError("wizard was aborted by the user — outcome is unavailable")
+    if state.confirmed is not True:
+        raise WizardError("wizard is not complete — outcome is unavailable")
+    return {
+        "renderArgs": render_args(state),
+        "persistActions": _wizard_persist_actions(state),
+        "confirmationText": confirmation_block(state),
+    }
+
+
 # ---- File I/O helpers (used by CLI) -------------------------------------
 
 def load_state_file(path: Path) -> WizardState:
@@ -3731,6 +3762,7 @@ def _cli(argv: list[str]) -> int:
       step  --state-file PATH (--answer VALUE | --no-submit)
       render-args --state-file PATH
       confirmation --state-file PATH
+      outcome --state-file PATH
     """
     import argparse
 
@@ -3759,6 +3791,9 @@ def _cli(argv: list[str]) -> int:
     p_conf = sub.add_parser("confirmation")
     p_conf.add_argument("--state-file", required=True)
 
+    p_outcome = sub.add_parser("outcome")
+    p_outcome.add_argument("--state-file", required=True)
+
     args = parser.parse_args(argv)
     state_path = Path(args.state_file)
 
@@ -3836,6 +3871,18 @@ def _cli(argv: list[str]) -> int:
                          ensure_ascii=False, indent=2))
         return 0
 
+    if args.cmd == "outcome":
+        state = load_state_file(state_path)
+        try:
+            out = wizard_outcome(state)
+        except WizardError as exc:
+            print(json.dumps({"ok": False, "error": str(exc)},
+                             ensure_ascii=False, indent=2))
+            return 0
+        print(json.dumps({"ok": True, "outcome": out},
+                         ensure_ascii=False, indent=2))
+        return 0
+
     return 2