okstra 0.186.7 → 0.187.0

package/runtime/bin/okstra-render-report-views.py

@@ -28,25 +28,10 @@ import re
 import sys
 from pathlib import Path
 
-REPO_ROOT = Path(__file__).resolve().parents[1]
-SCRIPTS_DIR = REPO_ROOT / "scripts"
-HOME_LIB = (
-    Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
-    / "lib"
-    / "python"
-)
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
 
-# Prefer dev sources when present, fall back to install. Without this
-# order, a stale install (~/.okstra/lib/python/okstra_ctl) without the
-# report_views module shadows the in-repo copy during development.
-if (SCRIPTS_DIR / "okstra_ctl" / "report_views.py").is_file():
-    if str(SCRIPTS_DIR) in sys.path:
-        sys.path.remove(str(SCRIPTS_DIR))
-    sys.path.insert(0, str(SCRIPTS_DIR))
-    if HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
-        sys.path.append(str(HOME_LIB))
-elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
-    sys.path.insert(0, str(HOME_LIB))
+prefer_colocated_modules(__file__, "okstra_ctl/report_views.py")
 
 from okstra_ctl.clarification_items import STRUCTURED_REPORT_VERSIONS  # noqa: E402
 from okstra_ctl.report_views import infer_run_meta, render_html_view  # noqa: E402
@@ -56,6 +41,7 @@ from okstra_ctl.final_report_paths import (  # noqa: E402
 )
 
 
+REPO_ROOT = Path(__file__).resolve().parents[1]
 _OKSTRA_HOME = Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
 # Search order:
 #   1) dev tree (`<repo>/templates/reports`) — wins when this script runs from
@@ -168,8 +154,29 @@ def _elapsed_ms(report_path, task_type: str, seq: str) -> int | None:
     return wall_clock_ms(state) or None if isinstance(state, dict) else None
 
 
+_CLI_EPILOG = r"""A thin spawn shim over `scripts/okstra-render-report-views.py` (installed
+at `$HOME/.okstra/bin/okstra-render-report-views.py`). Resolves the final-
+report data and Markdown pair, then writes a single sibling:
+
+  <stem>.html       — single-file self-contained human view; schema v2 is
+                       always generated, while v1/quick remains conditional
+
+Usage:
+  okstra render-views <path-to-final-report.data.json|path-to-final-report.md>
+      [--task-key <key>] [--task-type <type>] [--seq <NNN>]
+      [--source-report <project-relative-path>]
+
+Schema v2 data is rendered directly into its task-specific HTML view and is
+always generated. Schema v1 and quick reports keep the legacy conditional
+Markdown view. Optional flags override inferred report metadata.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra render-views",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Render the self-contained HTML view of an okstra final-report."
     )
     parser.add_argument("report_path", type=Path)

package/runtime/bin/okstra-report-translate.py

@@ -29,24 +29,10 @@ import os
 import sys
 from pathlib import Path
 
-REPO_ROOT = Path(__file__).resolve().parents[1]
-SCRIPTS_DIR = REPO_ROOT / "scripts"
-HOME_LIB = (
-    Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
-    / "lib"
-    / "python"
-)
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
 
-# Prefer dev sources when present, fall back to install — a stale install
-# without this module would otherwise shadow the in-repo copy.
-if (SCRIPTS_DIR / "okstra_ctl" / "report_translation.py").is_file():
-    if str(SCRIPTS_DIR) in sys.path:
-        sys.path.remove(str(SCRIPTS_DIR))
-    sys.path.insert(0, str(SCRIPTS_DIR))
-    if HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
-        sys.path.append(str(HOME_LIB))
-elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
-    sys.path.insert(0, str(HOME_LIB))
+prefer_colocated_modules(__file__, "okstra_ctl/report_translation.py")
 
 from okstra_ctl.report_translation import (  # noqa: E402
     HANGUL_PROSE_LIMIT,
@@ -353,9 +339,35 @@ def cmd_check_source(args: argparse.Namespace) -> int:
     return 0
 
 
+_CLI_EPILOG = r"""A thin spawn shim over `scripts/okstra-report-translate.py` (installed at
+`$HOME/.okstra/bin/okstra-report-translate.py`).
+
+The final-report data.json is authored in English and stays the SSOT. When the
+resolved report language is not English, Phase 7 dispatches a translator that
+writes a sidecar beside the report; `render-views` overlays it so only the
+human HTML is localized.
+
+Usage:
+  okstra report-translate extract <path-to-final-report.data.json>
+  okstra report-translate source --run-manifest <path>
+  okstra report-translate write --run-manifest <path> --source-digest <sha256> --translations <markdown>
+  okstra report-translate check-data --run-manifest <path>
+      Write <stem>.translation-source.json — every pointer the report holds a
+      translatable string at, paired with its English text. The translator
+      fills in the values, so a sidecar cannot cite a path the report lacks.
+
+  okstra report-translate check <path-to-final-report.i18n.<lang>.json>
+      Resolve every pointer in a filled sidecar against the report it names
+      and report what is still English. Exits non-zero on a pointer that
+      resolves nowhere — the translator's own gate before it returns.
+"""
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        prog="okstra-report-translate.py",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra report-translate",
         description="Build and verify the final-report translation sidecar.",
     )
     sub = parser.add_subparsers(dest="op", required=True)

package/runtime/bin/okstra-spawn-followups.py

@@ -49,6 +49,9 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
+
+prefer_colocated_modules(__file__, "okstra_ctl/next_phase.py")
 
 from okstra_ctl import next_phase  # noqa: E402
 from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
@@ -251,6 +254,7 @@ def _spawn_one(
 
 def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra spawn-followups",
         description="Spawn follow-up task stubs from a final-report data.json.",
     )
     parser.add_argument(

package/runtime/bin/okstra-token-usage.py

@@ -12,6 +12,9 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+from okstra_bootstrap import prefer_colocated_modules  # noqa: E402
+
+prefer_colocated_modules(__file__, "okstra_token_usage/cli.py")
 
 from okstra_token_usage.cli import main  # noqa: E402
 # Re-exports for callers that access attributes off this module directly.

package/runtime/bin/okstra.sh

@@ -254,6 +254,7 @@ done
 [[ -n "${STAGE-}" ]] && PY_ARGS+=(--stage "$STAGE")
 [[ -n "${STAGES-}" ]] && PY_ARGS+=(--stages "$STAGES")
 [[ -n "${QA_WAIVER-}" ]] && PY_ARGS+=(--qa-waiver "$QA_WAIVER")
+[[ -n "${TERMINAL_BACKEND-}" ]] && PY_ARGS+=(--terminal-backend "$TERMINAL_BACKEND")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$PLAN_VERIFICATION_ENABLED" == "false" ]] && PY_ARGS+=(--no-plan-verification)
 
@@ -285,8 +286,9 @@ if [[ -z "$LAUNCH_JSON" ]]; then
   exit 1
 fi
 
-# Note: per-session --settings injection was removed. okstra-ctl prepare
-# provisions <PROJECT_ROOT>/.claude/settings.local.json as a symlink to
+# Note: per-session --settings injection was removed. `okstra setup` and the
+# prepare path (okstra_ctl/seeding.py) provision
+# <PROJECT_ROOT>/.claude/settings.local.json as a symlink to
 # ~/.okstra/templates/settings.local.json, which Claude Code auto-loads
 # whenever it runs inside that project — no CLI flag required.
 execute_launch_plan \

package/runtime/bin/okstra_bootstrap.py

@@ -0,0 +1,58 @@
+"""진입 스크립트가 자기와 같은 배치의 모듈 트리를 import 하게 만든다.
+
+okstra 의 파이썬 진입 스크립트는 두 배치 중 하나에 놓인다.
+
+* 레포 체크아웃 — `scripts/okstra-*.py` 옆에 `scripts/okstra_ctl/` 이 있다.
+* 설치본 — `~/.okstra/bin/okstra-*.py` 의 짝은 `~/.okstra/lib/python/` 이다.
+
+짝을 `sys.path` **맨 앞**에 두어야 하는 이유는 상속된 `PYTHONPATH` 다.
+`okstra <cmd>` 는 자식 프로세스에 npm 패키지의 `runtime/python` 을 먼저 담은
+`PYTHONPATH` 를 물려준다(`src/lib/paths.mts` 의 `buildPythonpath`). 짝을 뒤에
+붙이면 설치본 스크립트가 npm 패키지 쪽 모듈을 import 하게 되고, 설치본과 npm
+패키지의 버전이 어긋나 있으면 그 스크립트는 import 에서 죽는다. 실행되는
+스크립트와 그 스크립트가 읽는 모듈은 항상 같은 버전이어야 한다.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def _home_lib() -> Path:
+    home = Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
+    return home / "lib" / "python"
+
+
+def _prepend(path: Path) -> None:
+    text = str(path)
+    if text in sys.path:
+        sys.path.remove(text)
+    sys.path.insert(0, text)
+
+
+def _append(path: Path) -> None:
+    text = str(path)
+    if path.is_dir() and text not in sys.path:
+        sys.path.append(text)
+
+
+def prefer_colocated_modules(entry_file: str, probe: str) -> None:
+    """`entry_file` 의 짝이 되는 모듈 트리를 `sys.path` 맨 앞에 둔다.
+
+    `probe` 는 그 트리 안에 있어야 하는 파일의 상대 경로다
+    (예: `okstra_ctl/report_views.py`). 디렉터리 존재만 보면 그 스크립트가
+    필요로 하는 새 모듈이 아직 없는 낡은 설치본도 후보로 뽑히므로, 실제로
+    쓰는 파일이 있는 쪽을 고른다. 어느 쪽에도 없으면 설치본을 앞에 둔다 —
+    빠진 모듈은 상속된 경로에서 채워질 수 있고, 채워지지 않으면 ImportError
+    로 드러난다.
+    """
+    entry_dir = Path(entry_file).resolve().parent
+    home_lib = _home_lib()
+    if (entry_dir / probe).is_file():
+        primary, fallback = entry_dir, home_lib
+    else:
+        primary, fallback = home_lib, entry_dir
+    if primary.is_dir():
+        _prepend(primary)
+    _append(fallback)

package/runtime/prompts/coding-preflight/overview.md

@@ -64,7 +64,7 @@ Per-file checks miss cross-cutting issues; each commit can be individually clean
 
 - [ ] **Domain-literal sweep:** `grep -rn` every domain enum value / predicate you added or touched in WHERE clauses, filters, or branches. The same literal at 2+ I/O sites is a *candidate* scattered decision — ask: would these sites change together when the business rule changes? Same decision → consolidate into one named constant or query builder in the domain layer and make every site reference it. Different decisions that merely share a value → leave them separate; coupling incidental duplication is worse than the repetition. (The identifier grep above does NOT catch this — sweep *values*, not just names.)
 - [ ] **Stand-alone name test for exports:** for each exported identifier, look at its siblings — can a caller pick the right one from the names alone? If a comment must explain which to use, the name fails; encode the distinguishing fact in it (e.g., the input shape: `parseRows` vs `parseRowsFromFlatItems`).
-- [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it. Enforced by `validators/detect_self_mock.py` (static); absent `qa/self-mock-*.json` sidecar BLOCKS at `validate-run.py`.
+- [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it. Enforced by `validators/detect_self_mock.py` (static) — **run by the implementation verifier, never by the author of the diff.** This sweep is the manual half and ends at your own reading; the detector run and its `qa/self-mock-*.json` sidecar are the verifier's duty (`prompts/profiles/_implementation-verifier.md` §"Self-mock detection"), and it is that sidecar's absence that BLOCKS at `validate-run.py` — on the verifier's report, not on your diff. Running the detector yourself does not pre-satisfy the gate: the sidecar is outside an executor attempt's `writePolicy.artifactPolicy.allowedPaths`, so writing it makes okstra's write audit close the attempt as `error` (`artifact-root change exceeds batch policy union`), and the verifier writes the same file again under its own duty.
 - [ ] **No documented forks:** two deliberate variants of one capability must not survive as parallel implementations with a comment explaining the delta. Re-read both bodies and check the deltas are genuinely parametric: if they reduce to a few orthogonal options, collapse into one implementation taking explicit option parameters that encode them. If encoding the delta would take more than ~3 options, or add more branching than the duplication it removes, they are two capabilities — keep two implementations with distinct honest names and delete the "variant of" framing. Either way the comment-documented fork dies. "The divergence is documented" stays a refused rationalization, and a two-capabilities verdict must come from reading the bodies, not from reluctance to refactor.
 
 ## Boundaries

package/runtime/prompts/duties/planning-worker.md

@@ -13,7 +13,7 @@ Produce an executable implementation plan without writing the implementation.
 
 ### Selected-direction responsibility
 
-When `selected-direction.json` is present, read it and the requirements ledger first. Preserve the selected direction's core mechanism, architecture boundaries, user constraints, and planning invariants. Concretize only its files, interfaces, stages, validation, and rollback. Link every file and stage back to original requirements, and link every original requirement forward to its files, stages, and checks. If current code evidence requires changing the direction, return `direction-invalidated` with evidence and stop. Direction selection remains upstream of this branch.
+When `selected-direction.json` is present, read it and the requirements ledger (the brief's `EB-` / `PB-` / `EO-` end-state sections, carried in the analysis packet's `## Task-Specific Brief Extract`) first. Preserve the selected direction's core mechanism, architecture boundaries, user constraints, and planning invariants. Concretize only its files, interfaces, stages, validation, and rollback. Link every file and stage back to original requirements, and link every original requirement forward to its files, stages, and checks. If current code evidence requires changing the direction, return `direction-invalidated` with evidence and stop. Direction selection remains upstream of this branch.
 
 ### Legacy candidate-comparison compatibility
 

package/runtime/prompts/launch.template.md

@@ -5,15 +5,29 @@
 
 ## Progress reporting (BLOCKING)
 
+**Enforced:** `validators/validate_session_conformance.py` reads the selected adapter's evidence within the run window and reports a missing checkpoint. Missing lines are advisories, not failures — by the time the validator runs the session that would have emitted the line has ended, so the finding records that the run is hard to follow, not that its work is wrong.
+
 Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows.
 
 When the run manifest declares `activityContractVersion: 1`, call `okstra agent-activity append` before each required activity boundary. Only after the structured append succeeds, emit the matching `PROGRESS:` line and the immediately following `ACTIVITY:` projection from the same fields. If the structured append fails, do not mark that boundary completed. Never reconstruct structured activity by parsing `ACTIVITY:` conversation text.
 
 For a new `implementation-planning` run, the plan-body sequence is initial verification → one planner self-fix → targeted re-verification → user gate. The initial verification is round 1, the targeted re-verification is round 2, and a second automatic self-fix is a contract violation. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop.
 
+## Asking the user (BLOCKING)
+
+Any question this run puts to the user — an approval blocker, a re-verification scope, a routing fork, a wizard step you relay — follows the same three rules. Full text in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Asking the user").
+
+1. Investigate first: read the artifacts the answer turns on. If that settles it, do not ask. If it does not, what you read is what the options are made of.
+2. Offer two or three concrete options, recommendation first with one clause saying why, each naming its outcome. The free-input escape is always last, never first.
+3. Never hand over a blank you could have filled. Naming a finding in chat and then offering only free input is the failure this rule exists for.
+
+Relaying a wizard step does not change the option set — relay every `options[]` entry unchanged and in order, and put your investigation and your recommendation in the question body.
+
+**Enforced:** `scripts/okstra_ctl/wizard.py` `Prompt.__post_init__` refuses a wizard step whose free-input option is not last. The investigate-first half is a contract on you, in the lifecycle core contract's section of the same name.
+
 ## Current Phase Boundary
 
-- Current lifecycle phase: `{{WORKFLOW_CURRENT_PHASE}}`
+- Current lifecycle phase: `{{WORKFLOW_CURRENT_PHASE}}` (step {{WORKFLOW_PHASE_POSITION}} of the lifecycle)
 - Allowed outputs in this phase:
 {{PHASE_ALLOWED_OUTPUTS}}
 - Forbidden actions in this phase:
@@ -29,12 +43,21 @@ For a new `implementation-planning` run, the plan-body sequence is initial verif
 
 After Phase 7 persistence, the last user-facing message of this run is the next command. A status dump is not a close. A prohibition (`do not start implementation`) is not a next action. This applies to every task type.
 
+**Read the pointer from the `report-finalize` result — do not re-derive it.** Its top-level `nextRecommendedPhase` object (`phase`, `status`, `rationale`) is the value every row below branches on, and the same three values are repeated on stderr as `next phase status:` / `next phase:` / `next phase rationale:`. You did not write that object and you cannot recompute it: you author your task type's routing field, and Phase 7 projects the pointer from it plus the approval state — for `implementation-planning` there is no routing field at all. If the result carries `nextRecommendedPhaseError`, say in one line that the pointer could not be read, then close on the `validate-run` row below. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead.
+
 Close with one command the user can run now. The first matching row wins:
 
-- Open `blocks: approval` rows → `/okstra-user-response` (name the `C-NNN` ids). An `accept-risk` / `select` / `answer` already recorded is not an open blocker.
-- `workflow.awaitingApproval` is true → `/okstra-run` → `implementation` or `--approve`. Do not propose another planning run.
-- Phase 7 `validate-run` failed → one line naming the blocking cause, then `/okstra-run` to re-run this phase, or `/okstra-inspect recap`.
-- Pointer `status: ready` → `/okstra-run` for that `phase`.
+- Open `blocks: approval` rows, or a `blocked-by-disagreement` gate whose approval rows carry no progress disposition → `/okstra-user-response` (name the `C-NNN` ids). An `accept-risk` / `select` / `answer` already recorded is not an open blocker. A report published with those rows open is not a failed run — the answers are the missing input, and a planning re-run without them reproduces the same block.
+
+After `implementation-planning`, stop on the rows above. No open approval blocker → `/okstra-run` → `implementation` or `--approve`. Do not propose another planning run. Do not say `/okstra-inspect`. A blocking `validate-run` failure is named in one line, then this same command; a `validate-run` advisory is named in one line and nothing else — it did not fail the run.
+
+For every other task type:
+
+- Pointer `status: ready` → `/okstra-run` for that `phase`. Quote the pointer's `rationale` — that sentence is this run's report saying why that phase comes next, and it is the analysis the user asked for.
+- Pointer `status: terminal` → the lifecycle ends here. Say the task is finished and quote the pointer's `rationale`. Do not propose a run and do not send the user to `/okstra-inspect`: the decision is already made, so there is nothing to inspect. If this run registered follow-up tasks, name them and the command that starts one.
+- Pointer `status: blocked` → the pointer's `rationale` names what is in the way and what to run. Quote it and issue that command — `/okstra-user-response` for the `C-NNN` ids it lists, or `/okstra-run` for the phase it names.
+- Pointer `status: pending` with a `rationale` → the comparison finished and the user's own choice is what comes next. Quote the `rationale` and issue the command it names. Do not re-run the phase that just completed, and do not send the user to `/okstra-inspect`: a finished phase has nothing to inspect, and re-running it discards the result the user is being asked to choose from.
+- Phase 7 `validate-run` failed → one line naming the blocking cause, then `/okstra-run` to re-run this phase. Only a failure matching the blocking allowlist (`okstra_ctl.blocking_checks`) reaches this row; every other finding was demoted to an advisory, printed as `validate-run: advisory — <finding>`, and the run passed. Name those advisories in one line and take the command from the matching pointer row above — an advisory is not a reason to re-run.
 - Otherwise → `/okstra-inspect status` for this task.
 
 Do not end the turn after the validator result. Task-qualified report paths and the same table live in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "After persistence").
@@ -43,6 +66,8 @@ Do not end the turn after the validator result. Task-qualified report paths and
 
 ## Project Root
 
+**Enforced:** emitted by `okstra_ctl.worker_prompt_headers` and required of every worker-facing prompt through `worker_prompt_policy` / `worker_prompt_contract`, so a dispatch without it fails before the worker starts.
+
 - Absolute project root: `{{PROJECT_ROOT}}`
 - All other paths in this prompt are relative to this root unless they begin with `/`.
 - When dispatching workers, you MUST include this absolute root in every worker prompt header so that workers do not depend on inherited cwd to resolve relative paths.
@@ -117,6 +142,7 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
 0. **Honour the scope the user already pinned (not a judgement — an instruction).** The wizard asks for a re-verification scope whenever this re-run is narrowable or an answered id traces to no stage, and the answer arrives as two tokens: mode `{{REVERIFY_SCOPE_MODE}}`, stages `{{REVERIFY_SCOPE_STAGES}}`. Apply it before you form your own view:
    - `auto` — the user left the decision to this procedure. Run steps 1–7 exactly as written; nothing is pinned. If the CLI returns `mode == "incremental"`, keep it; do not upgrade to full.
    - `full` — the user asked for full re-verification. Still call the CLI once (the record is the audit trail), passing `--full-reason "user requested full re-verification"` and every other CSV empty. Do not argue the user out of it with a narrower `--impacted`: the answer already weighed the cost.
+   - `carry-all` — the user said this re-run only ADDS stages: every prior stage is `done` and none is being re-opened, so there is no stage number to pin. Call the CLI once with `--carry-all-reason "user pinned carry-all: this re-run only adds stages"` and every other CSV empty. Do not substitute `--impacted` with prior stage numbers: `incremental-carry` then demands those stages from the current snapshot, which no longer holds a `done` stage. The CLI still applies the base-ref check, so a moved branch correctly degrades the decision to `full`.
    - `stages` — the user named the stages that must be re-verified. Put **every** number in `{{REVERIFY_SCOPE_STAGES}}` into `--impacted`, unioned with any stage you resolve yourself. Never drop one because your own back-trace did not reach it — the user is telling you about a blast radius the prior report failed to record, which is exactly what the back-trace cannot see. The CLI still applies the dependency closure and the cutoff on top, so a wide enough pin correctly ends in `mode == "full"`.
 1. **List the answered clarifications (a fact, not a judgement).** Collect the `C-NNN` ids you reconciled as answered in §1, and the IDs of any PREP items changed by the carried response. Pass the ids through `--answered-clarifications`; the CLI resolves which Stage Map stages each one touches by reading the prior run's own links — the `P-*` plan item that carried that `clarificationId`, and the requirement-coverage row blocked on `C-NNN` in either its `status` or its `approvalDisposition` (a `documented-deviation` row records the block in the latter). Do NOT map answers to stage numbers yourself.
    - An id that traces to no stage in the prior report does **not** force `mode == "full"` for the whole re-run. The CLI returns `mode == "unresolved"` and names the ids. Ask the user for the stage numbers those answers affect, then call the CLI again with those numbers in `--impacted`. Do not drop the unlinked id from `--answered-clarifications`. Do not treat `unresolved` as full, and do not silently narrow to the ids that did trace. An approval blocker in this shape should have failed the prior report's back-trace; naming stages is the remaining outlet.
@@ -129,6 +155,7 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
    ```
    okstra incremental-scope \
      --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} \
      --cur-base-sha {{EXECUTOR_WORKTREE_BASE_REF}} \
      --prev-base-sha <prior baseRef from step 2> \
      --impacted <csv of impacted stage numbers, empty for full> \
@@ -136,19 +163,18 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
      --answered-clarifications <csv of answered C-NNN ids, empty when none> \
      --full-reason "<empty, or what structural change forces full>"
    ```
-   The CLI reads the plan's dependency graph from the prior `implementationPlanning.stageMap`, which is authoritative for the impacted stage numbers. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}`. Instruct the report writer to record this decision in its narrative as `implementationPlanning.incrementalDecision`, using camel-case array keys `reverifyStages` and `carryStages`. Final report assembly preserves that writer-owned decision.
+   The CLI reads the plan's dependency graph from the prior `implementationPlanning.stageMap`, which is authoritative for the impacted stage numbers. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}` **and writes the same decision** to the record this run's manifest names in `incrementalDecisionPath`. You do not transcribe it: the report writer receives it through its authoring contract, and `incremental-carry` reads the same record. An `unresolved` result is a question back to you and is deliberately not recorded.
 4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
 5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `prompts/profiles/implementation-planning.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
 6. **`mode == "unresolved"`** → ask the user for stage numbers; re-enter step 3 with those numbers in `--impacted`. Do not fall back to full. Do not record `unresolved` as `incrementalDecision`. Then continue from the new `mode`.
-7. **Merge carried-forward verdicts.** In `incremental` mode, the report writer includes every `carry_stages` stage row unchanged in its narrative. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
+7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --narrative ... --state ...`, the lead runs:
    ```
    okstra incremental-carry \
      --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
      --cur-narrative <this run's report-writer narrative> \
      --state <this run's plan-body-verification state> \
      --prev-seq <prev-seq> \
-     --carry-stages <csv from incrementalDecision.carry_stages> \
-     --reverify-stages <csv from incrementalDecision.reverify_stages> \
+     --decision {{INCREMENTAL_DECISION_STATE_RELATIVE_PATH}} \
      --out-state <this run's plan-body-verification state>
    ```
    A non-zero exit means the writer changed or omitted a carried stage, the item set drifted, or the stage scopes conflict. Fall back to **full** and re-verify every stage. The command writes only the convergence-owned plan state. It never patches the writer narrative or final `data.json`. `verdictCard` / `finalVerdict` are never carried.