okstra 0.223.0 → 0.224.0

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

@@ -6,12 +6,15 @@ from pathlib import Path
 from collections.abc import Mapping
 from typing import Any, Optional
 
-from okstra_ctl import next_phase
+from okstra_ctl import next_phase, worktree_registry
+from okstra_ctl.consumers import latest_done_by_stage, read_consumers
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.paths import RunRef
 from okstra_ctl.group_context import (
     QUEUE_DONE,
     QUEUE_IN_PROGRESS,
     QUEUE_NOT_STARTED,
+    group_briefs,
     group_context_file,
     group_queue,
     is_group_context_file,
@@ -79,15 +82,18 @@ def _validate_base_ref(ref: str, project_root: Path) -> str:
     ref = (ref or "").strip()
     if not ref:
         raise WizardError("base ref is empty")
-    main_wt = _git_main_worktree(project_root)
+    if not _ref_resolves(_git_main_worktree(project_root), ref):
+        raise WizardError(f"base ref not found in repository: {ref}")
+    return ref
+
+
+def _ref_resolves(main_wt: Path, ref: str) -> bool:
     rc = subprocess.call(
         ["git", "-C", str(main_wt), "rev-parse",
          "--verify", "--quiet", f"{ref}^{{commit}}"],
         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
     )
-    if rc != 0:
-        raise WizardError(f"base ref not found in repository: {ref}")
-    return ref
+    return rc == 0
 
 
 # --- builders ---
@@ -605,8 +611,12 @@ def _build_task_type(state: WizardState) -> Prompt:
     brief_phase = _brief_recommended_task_type(state) if fresh_task else ""
     recommended = (revision_requested or state.task_type
                    or _recommended_task_type(state, manifest))
+    # Only a recommendation okstra recorded is taken without asking: the pointer,
+    # a revision request, or the brief's own entry phase.
+    auto_value = recommended
     if not recommended and not workflow:
         recommended = state.requested_task_type or brief_phase or TASK_TYPE_VALUES[0]
+        auto_value = recommended if recommended in (state.requested_task_type, brief_phase) else ""
     if brief_phase and recommended == brief_phase:
         recommended_suffix = t["options"].get("_BRIEF_SUFFIX", recommended_suffix)
     pointer = next_phase.promote(workflow.get("nextRecommendedPhase"))
@@ -638,7 +648,8 @@ def _build_task_type(state: WizardState) -> Prompt:
     options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
     return Prompt(step=S_TASK_TYPE, kind="pick",
                   label=t["label"], options=options,
-                  echo_template=t["echo_template"])
+                  echo_template=t["echo_template"],
+                  auto_value=auto_value)
 
 
 def _carry_in_existing_brief(state: WizardState) -> str:
@@ -835,28 +846,100 @@ def _build_brief_carry(state: WizardState) -> Prompt:
     )
 
 
-def _checked_out_canonical_ref(project_root: Path) -> str:
-    """The main worktree's branch when it is one of the listed base refs, else ''.
+def _checked_out_branch(main_wt: Path) -> str:
+    """The main worktree's branch, or '' when HEAD is detached.
 
     Projects differ in their integration branch (main vs preprod), and nothing in
     okstra records it; the branch the user keeps checked out is the observed hint.
     """
-    try:
-        main_wt = _git_main_worktree(project_root)
-    except WizardError:
-        return ""
     result = subprocess.run(
         ["git", "-C", str(main_wt), "symbolic-ref", "--quiet", "--short", "HEAD"],
         capture_output=True, text=True,
     )
-    branch = result.stdout.strip() if result.returncode == 0 else ""
-    return branch if branch in CANONICAL_BASE_REFS else ""
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def _recorded_stage_branches(state: WizardState, task_id: str) -> list[str]:
+    """A task's stage branches, top of the stack first: PR heads, then done stages.
+
+    release-handoff `record-pr` writes a `pr` row per stage PR; a task that never
+    reached handoff only has `done` rows, whose branch lives in the worktree
+    registry's stage row (kept after the stage is released).
+    """
+    key = f"{state.project_id}:{state.task_group}:{task_id}"
+    task_root = find_task_root(Path(state.project_root), key)
+    if task_root is None:
+        return []
+    rows = read_consumers(RunRef.from_task_root(task_root, "implementation-planning").run_dir)
+    prs = [row for row in rows if row.get("status") == "pr" and row.get("branch")]
+    prs.sort(key=lambda row: max(row.get("stages") or [0]), reverse=True)
+    branches = [str(row["branch"]) for row in prs]
+    for stage in sorted(latest_done_by_stage(rows), reverse=True):
+        stage_row = worktree_registry.get_stage_row(
+            state.project_id, state.task_group, task_id, stage) or {}
+        if stage_row.get("branch"):
+            branches.append(str(stage_row["branch"]))
+    return branches
+
+
+def _predecessor_base_ref(state: WizardState, main_wt: Path) -> tuple[str, bool]:
+    """(branch, succession) from the nearest earlier task in the group's start order.
+
+    A follow-up task in a group usually builds on the previous task's unmerged
+    stage branches. `succession` is True when okstra records that this task
+    follows that one: it is the next row in the start order (what the
+    predecessor's closeout named as `nextInGroup`), or this task's brief waits
+    for that ticket in its Related Task Graph.
+    """
+    if not (state.project_root and state.task_group and state.task_id):
+        return "", False
+    project_root = Path(state.project_root)
+    queue = _group_start_order(project_root, state.task_group)
+    brief = _project_relative_path(Path(state.brief_path), project_root) if state.brief_path else ""
+    current = next(
+        (index for index, row in enumerate(queue)
+         if row.task_id == state.task_id or (brief and row.brief == brief)),
+        None,
+    )
+    if current is None:
+        return "", False
+    waits: set[str] = set()
+    for item in group_briefs(project_root, state.task_group):
+        waits.update(item["waits_for"].get(queue[current].ticket_id, set()))
+    for index in range(current - 1, -1, -1):
+        row = queue[index]
+        branch = next(
+            (b for b in _recorded_stage_branches(state, row.task_id) if _ref_resolves(main_wt, b)),
+            "",
+        )
+        if branch:
+            return branch, index == current - 1 or row.ticket_id in waits
+    return "", False
+
+
+def _base_ref_candidates(state: WizardState) -> tuple[list[str], str]:
+    """(refs in display order, recommended ref or '')."""
+    try:
+        main_wt = _git_main_worktree(Path(state.project_root))
+    except WizardError:
+        return list(CANONICAL_BASE_REFS), ""
+    predecessor, succession = _predecessor_base_ref(state, main_wt)
+    checked_out = _checked_out_branch(main_wt)
+    derived = [predecessor] if predecessor else []
+    if (checked_out and checked_out not in CANONICAL_BASE_REFS
+            and checked_out not in derived and _ref_resolves(main_wt, checked_out)):
+        derived.append(checked_out)
+    if succession:
+        recommended = predecessor
+    else:
+        recommended = checked_out if checked_out in CANONICAL_BASE_REFS else ""
+    refs = derived + [r for r in CANONICAL_BASE_REFS if r not in derived]
+    return sorted(refs, key=lambda r: r != recommended), recommended
 
 
 def _build_base_ref_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "base_ref_pick")
-    recommended = _checked_out_canonical_ref(Path(state.project_root))
-    refs = sorted(CANONICAL_BASE_REFS, key=lambda r: r != recommended)
+    refs, recommended = _base_ref_candidates(state)
     options = [_opt(r, recommended=r == recommended) for r in refs]
     for value, label in _static_options(t):
         options.append(_opt(value=value, label=label))

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

@@ -120,6 +120,9 @@ class _OptionalCachedPickSpec:
     # 추천 옵션 라벨·echo 뒤에 덧붙일 동적 안내(예: 함께 첨부될 사이드카 개수).
     # (state, 추천 relpath) -> note. 미설정 picker 는 영향 없음.
     recommend_note: Optional[Callable[["WizardState", str], str]] = None
+    # Whether the wizard takes the suggestion without asking. A previous directive
+    # is an instruction written for another run, so reusing it stays a question.
+    auto_take_suggestion: bool = True
 
 
 def _build_optional_cached_pick(state: WizardState, spec: _OptionalCachedPickSpec) -> Prompt:
@@ -137,10 +140,17 @@ def _build_optional_cached_pick(state: WizardState, spec: _OptionalCachedPickSpe
     setattr(state, spec.cache_attr, suggestion)
     options.append(_opt(PICK_SKIP, t["options"][PICK_SKIP]))
     options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
+    if not suggestion:
+        auto_value = PICK_SKIP
+    elif spec.auto_take_suggestion:
+        auto_value = spec.recommend_token
+    else:
+        auto_value = ""
     return Prompt(
         step=spec.step, kind="pick",
         label=t["label"], options=options,
         echo_template=t["echo_template"],
+        auto_value=auto_value,
     )
 
 
@@ -199,6 +209,7 @@ _DIRECTIVE_PICK_SPEC = _OptionalCachedPickSpec(
     cache_attr="last_directive_cached", target_attr="directive",
     pending_attr="directive_pending_text",
     recommend_note=_directive_context_note,
+    auto_take_suggestion=False,
 )
 
 

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

@@ -276,6 +276,7 @@ def _build_approved_plan_pick(state: WizardState) -> Prompt:
         step=S_APPROVED_PLAN_PICK, kind="pick",
         label=label, options=options,
         echo_template=t["echo_template"],
+        auto_value=PICK_USE_DEFAULT if default is not None else "",
     )
 
 
@@ -341,9 +342,22 @@ def _build_approve_plan_confirm(state: WizardState) -> Prompt:
             for k, v in options_map.items()
         ],
         echo_template=t["echo_template"],
+        auto_value="yes" if _already_approved(state) else "",
     )
 
 
+def _already_approved(state: WizardState) -> bool:
+    """An approved plan with no exported approval sidecar leaves nothing to decide."""
+    if state.html_approval_sidecar or not state.approve_plan_candidate:
+        return False
+    try:
+        _, fully_approved = _classify_approved_plan(
+            state.approve_plan_candidate, Path(state.project_root))
+    except (PrepareError, WizardError):
+        return False
+    return fully_approved
+
+
 def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str]:
     allowed = ("yes_apply", "yes", "no") if state.html_approval_sidecar else ("yes", "no")
     if value not in allowed:

package/runtime/python/okstra_ctl/worktree/rebase.py

@@ -67,6 +67,13 @@ def rebase_stage_branch(
         raise RuntimeError(
             f"cannot rebase {branch}: recorded base {old} is not an ancestor"
         )
+    # A branch rebased by hand already sits linearly on the new base; replaying
+    # old..head would reapply the new base's own commits and conflict. A merge
+    # of the new base still goes through the rebase, which flattens it.
+    if is_ancestor(project_root, new, head) and not _checked_git(
+        project_root, "rev-list", "--merges", f"{new}..{head}"
+    ):
+        return head
     with _stage_worktree(project_root, branch) as holder:
         for state in ["rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD"]:
             path = Path(_checked_git(holder, "rev-parse", "--git-path", state))
@@ -103,6 +110,9 @@ def _apply_rebase(holder: Path, branch: str, old: str, new: str) -> str:
                 f"rebase failed for {branch}; recovery worktree: {holder}; {detail}; abort: {abort.stderr}"
             )
         raise RuntimeError(
-            f"rebase failed for {branch}; original branch restored: {detail}"
+            f"rebase failed for {branch}; original branch restored: {detail}\n"
+            f"To resolve: in the worktree holding {branch}, run "
+            f"`git rebase --onto {new} {old}`, resolve the conflicts, then re-run "
+            "the same prepare command; it records the new base without rebasing again."
         )
     return _checked_git(holder, "rev-parse", "HEAD")

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

@@ -9557,7 +9557,8 @@
               "block": {"type": "string", "enum": ["execution", "record"]},
               "stageScope": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
               "contentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of subject+payload+block+stageScope for the current extract."},
-              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "contentHash at the last apply-verdicts. Matching hashes keep a pre-self-fix verdict."},
+              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Body hash at the last apply-verdicts; insufficient on its own for runtime verdict reuse."},
+              "verifiedReviewHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Runtime fingerprint of the judged body, declared evidence closure, contract, roster and detailed votes."},
               "id": {
                 "type": "string",
                 "minLength": 1
@@ -9597,6 +9598,7 @@
                   "additionalProperties": false,
                   "properties": {
                     "claimKind": {"description": "Set only on DISAGREE. `fact` claims are settled by reproduction, `judgement` by quorum.", "enum": ["fact", "judgement", null]},
+                    "dependencies": {"type": "object", "required": ["complete", "itemIds", "paths"], "additionalProperties": false, "properties": {"complete": {"type": "boolean"}, "itemIds": {"type": "array", "items": {"type": "string", "minLength": 1}}, "paths": {"type": "array", "items": {"type": "string", "minLength": 1}}}},
                     "reproduction": {"description": "Set only on a `fact` claim. The probe okstra runs; see okstra_ctl/claim_reproduction.py.", "type": ["object", "null"]},
                     "reproductionResult": {"description": "Written by okstra, not by the worker.", "enum": ["reproduced", "not-reproduced", "not-runnable", null]},
                     "worker": {

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

@@ -9849,7 +9849,8 @@
               "block": {"type": "string", "enum": ["execution", "record"]},
               "stageScope": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "integer", "minimum": 1}},
               "contentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of subject+payload+block+stageScope for the current extract."},
-              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "contentHash at the last apply-verdicts. Matching hashes keep a pre-self-fix verdict."},
+              "verifiedContentHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Body hash at the last apply-verdicts; insufficient on its own for runtime verdict reuse."},
+              "verifiedReviewHash": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Runtime fingerprint of the judged body, declared evidence closure, contract, roster and detailed votes."},
               "id": {
                 "type": "string",
                 "minLength": 1
@@ -9896,6 +9897,7 @@
                   "additionalProperties": false,
                   "properties": {
                     "claimKind": {"description": "Set only on DISAGREE. `fact` claims are settled by reproduction, `judgement` by quorum.", "enum": ["fact", "judgement", null]},
+                    "dependencies": {"type": "object", "required": ["complete", "itemIds", "paths"], "additionalProperties": false, "properties": {"complete": {"type": "boolean"}, "itemIds": {"type": "array", "items": {"type": "string", "minLength": 1}}, "paths": {"type": "array", "items": {"type": "string", "minLength": 1}}}},
                     "reproduction": {"description": "Set only on a `fact` claim. The probe okstra runs; see okstra_ctl/claim_reproduction.py.", "type": ["object", "null"]},
                     "reproductionResult": {"description": "Written by okstra, not by the worker.", "enum": ["reproduced", "not-reproduced", "not-runnable", null]},
                     "worker": {

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -87,8 +87,8 @@ okstra pr gen --base <base> --template <template>
 To describe a branch other than the checkout — a stage branch whose worktree is gone — add
 `--head <branch>`; nothing is checked out.
 
-Read the fixed `Base`, `Head`, `Current branch`, `Template name`, `Commits`, `Diff stat`,
-`Template`, and `Drafting rules` sections. Then fill the template by following every item of
+Read the fixed `Base`, `Head`, `Current branch`, `Upstream`, `Merge base`, `Template name`,
+`Commits`, `Diff stat`, `Template`, and `Drafting rules` sections. Then fill the template by following every item of
 `Drafting rules`: it says how to read the full diff, when to stop, how to fill sections and
 checkboxes, how to open the new-behavior section, and which identifiers the title and body may
 carry. release-handoff drafts its PR bodies from the same rules.

package/runtime/templates/pr/drafting-rules.md

@@ -1,8 +1,15 @@
-1. Read the full diff — it is the source of truth: `git diff <Base>...<Head>`, using the `Base` and
-   `Head` values above. Read a large diff in sections.
+1. Read the full diff — it is the source of truth: `git diff <Merge base> <Head>`, pasting the
+   `Merge base` and `Head` values above literally. `Merge base` already folds in the base's upstream,
+   so changes the remote base has merged are excluded. Read a large diff in sections.
 2. If `Commits` or `Diff stat` above is `-`, there is nothing to describe: stop and say so.
-3. Fill the template from the diff and the commits. Describe only what actually changed. Strip HTML
-   comments; keep the template's sections as the structure.
+3. Fill the template from the diff and the commits. Describe only the net change from the merge base
+   to the head, as a reviewer sees it on the PR. Strip HTML comments; keep the template's sections as
+   the structure.
+   - "Current behavior" is the behavior at the merge base, never at an intermediate commit of the branch.
+   - A problem one commit of the branch introduced and a later commit fixed is not a change: leave it
+     out, or describe only the final state. Never present it as a pre-existing bug the PR fixes.
+   - A commit subject is not evidence of a change the diff does not show.
+   - The drafting session's conversation, the last commit alone, and earlier PR drafts are not sources.
 4. Mark a checklist box `[x]` only when the diff supports it (tests touched → the tests box, docs
    touched → the docs box).
 5. Open the new-behavior section — `What is the new behavior` in the default template, or the section