okstra 0.115.0 → 0.116.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.115.0",
+  "version": "0.116.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.115.0",
-  "builtAt": "2026-07-09T15:25:58.950Z",
+  "package": "0.116.0",
+  "builtAt": "2026-07-09T17:28:22.971Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/launch.template.md

@@ -85,3 +85,37 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 - Source path: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 - If the source path above is empty, no prior clarification response was attached to this run.
 - If the source path is set, a copy is staged at `{{INSTRUCTION_SET_RELATIVE_PATH}}/clarification-response.md`. Read it before running workers; reconcile each `C-*` row in section 1 (`## 1. Clarification Items`) of the prior report against new evidence and record the outcome in the conditional `## 0. Clarification Response Carried In From Previous Run` section of this run's final report (render that heading only when carry-in is non-empty — the validator fails empty Section 0 stubs).
+
+### Incremental re-verification (implementation-planning clarification re-runs only)
+
+The **default is full re-verification**. Only narrow this re-run to the impacted stages when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`; on any doubt, stay full. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
+
+1. **Resolve the impacted stage set (safety condition C2 — your discretionary judgement).** For each answered `C-*` row you reconciled in §1, decide which **Stage Map stage numbers** (from the prior plan's `## 5.5 Stage Map`) the answer touches. Rules:
+   - Pass ONLY stage numbers that appear in that Stage Map. Never invent or guess a stage number — a number absent from the graph must never enter `--impacted` (it would leak into `reverify_stages`).
+   - If you cannot map a touched item to a real stage with confidence, leave the impacted set **EMPTY** — an empty set forces `mode == "full"`. Widening to full is always the safe choice; guessing is not.
+   - If any answer overturns the selected Option, restructures the stages, or changes the recommended approach (rather than a localized detail), also leave the impacted set **EMPTY**.
+2. **Resolve the two base SHAs (safety condition C1 — code-unchanged, decided by the CLI, not by you).**
+   - Current base SHA: `{{EXECUTOR_WORKTREE_BASE_REF}}` (this run's resolved worktree base commit).
+   - Prior base SHA: read the prior run's active-run-context at `runs/implementation-planning/state/active-run-context-implementation-planning-<prev-seq>.json`, field `executorWorktree.baseRef` (a resolved commit SHA). The run-manifest does NOT carry this field — use the active-run-context. If that file or field cannot be located, treat the run as **full** and skip the rest of this procedure.
+3. **Call the CLI** (it is pure — same inputs always yield the same decision):
+   ```
+   okstra incremental-scope \
+     --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --cur-base-sha {{EXECUTOR_WORKTREE_BASE_REF}} \
+     --prev-base-sha <prior baseRef from step 2> \
+     --impacted <csv of impacted stage numbers, empty for full>
+   ```
+   The CLI reads the plan's dependency graph from the top-level `## 5.5 Stage Map` (`implementationPlanning.stageMap`), which is authoritative for the impacted stage numbers — there is no per-option stage graph. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}`. Instruct the report-writer to record this JSON verbatim into this run's data.json as `implementationPlanning.incrementalDecision` (keys `mode`, `reverifyStages`, `carryStages`, `reason`) — the renderer turns it into the `### 0.1 Incremental Re-Verification Scope` audit block, and the validator fails an `incremental`-mode run whose Section 0 omits that block.
+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").
+6. **Merge carried-forward verdicts.** In `incremental` mode, after this run's report-writer authors its data.json, instruct it to merge the prior plan-item verdicts for `carry_stages` into it:
+   ```
+   okstra incremental-carry \
+     --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --cur-data <this run's data.json> \
+     --prev-seq <prev-seq> \
+     --out <this run's data.json>
+   ```
+   A non-zero exit (`CarryError` — schema drift between the two runs) means the carry is unsafe: fall back to **full** — discard the incremental result and re-verify every stage. Note: `verdictCard` / `finalVerdict` are NEVER carried — this run re-computes them from the re-verified plus carried plan items.
+
+   **Carry completeness (BLOCKING).** In incremental mode, this run's `planItems` MUST contain every plan-item id from the re-verified stages, each carried forward with its updated verdict. If re-verification concludes a plan item should be REMOVED, that is a signal the answer's blast radius is NOT local — abandon incremental and re-route to a FULL re-verification. The carry merge only ever ADDS prior items whose id is absent from this run; it cannot distinguish a legitimate deletion from an untouched carry, so it would resurrect a stale verdict.

package/runtime/prompts/lead/convergence.md

@@ -66,6 +66,8 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
 
 **Convergence scope.** Convergence operates on sections 1–5 of the worker output (the common core, see `team-contract` "Worker Output Contract"). Section 6 ("Specialization Lens") is additive worker-specific depth and MUST NOT be fed into the consensus grouping, the verification queue, or the round-N reverify prompts. Carry Section 6 forward into the final report verbatim through the report-writer worker — do not let it inflate `unique` counts or trigger spurious `verification-error` statuses.
 
+**Incremental re-verification scope (implementation-planning clarification re-runs).** When the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), only findings the lead attributes to a stage in `reverify_stages` enter the verification queue. Findings and plan-item verdicts carried forward for `carry_stages` are NOT re-queued — they skip the re-verification rounds entirely and are merged verbatim into this run's data.json via `okstra incremental-carry`. When the decision is `mode == "full"` (the default), every finding enters the queue as usual.
+
 1. In the "Findings" section of each worker's results, identify individual items by number (F-001, F-002, ...) and parse the ticket identifier attached to each item:
    - For table-form findings, read the `Ticket ID` column.
    - For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.

package/runtime/prompts/lead/report-writer.md

@@ -281,7 +281,7 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 
 **Reader-facing prose MUST NOT cite a bare brief/worker-internal ID that this report never surfaces** — `RC-*` (reporter confirmations, defined in the brief), `RF-*` / `F-*` (findings, defined in worker-results) have no anchor in the final report, so a reader hits an opaque token with nothing to click. Either expand it inline (`the confirmed version target 1.27.47→1.27.48`) or, for an audit trail, namespace it (`claude:F-005`). **Enforced:** `_validate_no_opaque_id_references` fails a bare `RC-*` / `RF-*` / non-namespaced `F-*` appearing in `verdictCard` / `finalVerdict` / `rationale` / `clarificationItems[].statement`. (The renderer anchors + links in-report IDs of any digit width, so a surfaced `RC-4`-style id does resolve.) Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
 
-0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub.
+0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub. When the lead ran `okstra incremental-scope` for this re-run, record its JSON verbatim into `implementationPlanning.incrementalDecision` (`mode`, `reverifyStages`, `carryStages`, `reason`); the renderer emits the `### 0.1 Incremental Re-Verification Scope` audit block from it, and the validator fails an `incremental`-mode run whose Section 0 omits that block. In `incremental` mode this run's `planItems` MUST carry every plan-item id from the re-verified stages forward with its updated verdict; if re-verification concludes a plan item should be REMOVED, that is a signal the answer's blast radius is not local — do not drop it here, tell the lead to abandon incremental and re-route to a FULL re-verification, because the carry merge only adds prior items and would resurrect the removed item's stale verdict.
 1. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- 합의 미달 항목 없음.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.
 2. **Final Verdict** — `Direction` ∈ `continue-investigation` / `begin-implementation` / `approve` / `reject` / `hold`. **Verdict Token** is `not-applicable` for every task-type except `final-verification` — see "Final-verification verdict token contract" below for that case.
 3. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.

package/runtime/prompts/profiles/implementation-planning.md

@@ -43,6 +43,7 @@
 - Cross-verification mode:
   - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / option) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode".
   - §5.5.9 plan-body verification runs with an **adversarial posture** (`prompts/lead/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kinds `a` (path/symbol mismatch) / `d` (rollback order) — and `f` on `P-Req-*` items. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
+  - **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
 {{INCLUDE:_coverage-critic.md}}
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -0,0 +1,70 @@
+"""Merge carried-forward plan-item verdicts from the prior run into the
+current incremental re-run's data.json. Plan items the current run did not
+re-verify keep their prior verdict, tagged so the report shows they are
+carried forward and unchanged.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+class CarryError(Exception):
+    """Carry merge refused — schema drift or structural mismatch."""
+
+
+def merge_carried_forward(prev: dict, cur: dict, prev_seq: str = "previous") -> dict:
+    if prev.get("schemaVersion") != cur.get("schemaVersion"):
+        raise CarryError(
+            f"schemaVersion drift {prev.get('schemaVersion')!r} != {cur.get('schemaVersion')!r}; "
+            "cannot carry forward — caller must fall back to full"
+        )
+    prev_pbv = prev.get("implementationPlanning", {}).get("planBodyVerification", {})
+    cur_ip = cur.setdefault("implementationPlanning", {})
+    cur_pbv = cur_ip.setdefault("planBodyVerification", {})
+    cur_items = cur_pbv.setdefault("planItems", [])
+    reverified_ids = {i["id"] for i in cur_items}
+    for item in prev_pbv.get("planItems", []):
+        if item["id"] in reverified_ids:
+            continue
+        carried = dict(item)
+        carried["carriedForwardFromSeq"] = str(prev_seq)
+        cur_items.append(carried)
+    cur_items.sort(key=lambda i: i["id"])
+    return cur
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(prog="okstra incremental-carry")
+    ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
+    ap.add_argument("--cur-data", required=True, help="current incremental re-run data.json")
+    ap.add_argument("--prev-seq", required=True, help="prior run seq, tagged onto carried items")
+    ap.add_argument("--out", required=True, help="path to write the merged data.json")
+    args = ap.parse_args(argv)
+
+    prev = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+    cur = json.loads(Path(args.cur_data).read_text(encoding="utf-8"))
+    try:
+        merged = merge_carried_forward(prev, cur, prev_seq=args.prev_seq)
+    except CarryError as exc:
+        print(f"carry refused: {exc}", file=sys.stderr)
+        return 1
+
+    Path(args.out).write_text(
+        json.dumps(merged, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    carried = sum(
+        1
+        for i in merged.get("implementationPlanning", {})
+        .get("planBodyVerification", {})
+        .get("planItems", [])
+        if i.get("carriedForwardFromSeq") == str(args.prev_seq)
+    )
+    print(f"merged {carried} carried-forward plan item(s) from seq {args.prev_seq} -> {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -0,0 +1,89 @@
+"""Decide whether an implementation-planning clarification re-run can be
+incremental, and if so which stages to re-verify vs carry forward.
+
+Deterministic half of the incremental-reverification feature: the lead
+prompt supplies the impacted-stage set (its discretionary C2 judgement) and
+the base SHAs; everything here is pure so the same inputs always yield the
+same decision. See docs/superpowers/specs/2026-07-09-incremental-clarification-reverification-design.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from okstra_ctl.stage_targets import downstream_stage_closure
+
+CUTOFF_RATIO = 0.5
+
+
+@dataclass
+class IncrementalDecision:
+    mode: str  # "incremental" | "full"
+    reverify_stages: list[int]
+    carry_stages: list[int]
+    reason: str
+
+
+def _parse_depends_on(cell: str) -> list[int]:
+    text = (cell or "").strip()
+    if not text or text == "(none)":
+        return []
+    return [int(tok.strip()) for tok in text.split(",") if tok.strip()]
+
+
+def parse_stage_graph(data: dict) -> list[tuple[int, list[int]]]:
+    stage_map = data.get("implementationPlanning", {}).get("stageMap", [])
+    return [(int(row["stage"]), _parse_depends_on(row.get("dependsOn", ""))) for row in stage_map]
+
+
+def decide_scope(
+    *,
+    stages: list[tuple[int, list[int]]],
+    impacted_stages: set[int],
+    prev_base_sha: str,
+    cur_base_sha: str,
+    cutoff_ratio: float = CUTOFF_RATIO,
+) -> IncrementalDecision:
+    if not prev_base_sha or prev_base_sha != cur_base_sha:
+        return IncrementalDecision(
+            "full", [], [],
+            f"base-ref changed ({prev_base_sha!r} -> {cur_base_sha!r}); prior analysis invalid",
+        )
+    if not impacted_stages:
+        return IncrementalDecision("full", [], [], "no impacted stages resolved; falling back to full")
+    all_stages = {num for num, _ in stages}
+    closure = downstream_stage_closure(stages, set(impacted_stages))
+    if len(closure) * 2 > len(all_stages):
+        return IncrementalDecision(
+            "full", [], [],
+            f"closure {len(closure)}/{len(all_stages)} exceeds {int(cutoff_ratio * 100)}% cutoff",
+        )
+    reverify = sorted(closure)
+    carry = sorted(all_stages - closure)
+    return IncrementalDecision("incremental", reverify, carry, f"closure {reverify} within cutoff")
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(prog="okstra incremental-scope")
+    ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
+    ap.add_argument("--cur-base-sha", required=True)
+    ap.add_argument("--prev-base-sha", required=True)
+    ap.add_argument("--impacted", default="", help="comma-separated impacted stage numbers")
+    args = ap.parse_args(argv)
+
+    data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+    stages = parse_stage_graph(data)
+    impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
+    decision = decide_scope(
+        stages=stages, impacted_stages=impacted,
+        prev_base_sha=args.prev_base_sha, cur_base_sha=args.cur_base_sha,
+    )
+    print(json.dumps(asdict(decision), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/stage_targets.py

@@ -306,6 +306,32 @@ def order_stage_closure(
     return out
 
 
+def downstream_stage_closure(
+    stages: list[tuple[int, list[int]]],
+    seed: set[int],
+) -> set[int]:
+    """Stages that (transitively) depend on any stage in ``seed``, plus ``seed``.
+
+    ``stages`` mirrors ``order_stage_closure``: ``(stage_number, [depends_on_numbers])``.
+    ``order_stage_closure`` walks dependencies (upstream); this walks dependents
+    (downstream) — the reverse edge — so an answered clarification that changes a
+    seed stage re-verifies everything built on top of it.
+    """
+    dependents: dict[int, list[int]] = {}
+    for num, deps in stages:
+        for dep in deps:
+            dependents.setdefault(dep, []).append(num)
+    result = set(seed)
+    queue = list(seed)
+    while queue:
+        cur = queue.pop()
+        for child in dependents.get(cur, []):
+            if child not in result:
+                result.add(child)
+                queue.append(child)
+    return result
+
+
 def commit_is_ancestor(project_root: Path, ancestor: str, descendant: str) -> bool:
     """True iff ``ancestor`` is an ancestor of ``descendant`` in git history."""
     from .worktree import is_ancestor

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

@@ -445,6 +445,24 @@
         "skippedAdrCandidates": {
           "type": "array",
           "items": { "$ref": "#/$defs/SkippedAdrCandidate" }
+        },
+        "incrementalDecision": {
+          "type": "object",
+          "description": "Verbatim `okstra incremental-scope` output for a clarification re-run. Present only when this implementation-planning run scoped itself against a prior run; drives the Section 0 incremental audit block.",
+          "required": ["mode", "reverifyStages", "carryStages", "reason"],
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "type": "string", "enum": ["incremental", "full"] },
+            "reverifyStages": {
+              "type": "array",
+              "items": { "type": "integer" }
+            },
+            "carryStages": {
+              "type": "array",
+              "items": { "type": "integer" }
+            },
+            "reason": { "type": "string", "minLength": 1 }
+          }
         }
       }
     },
@@ -1500,6 +1518,7 @@
               "id": { "type": "string", "minLength": 1 },
               "subject": { "type": "string", "minLength": 1 },
               "sourceSection": { "type": "string" },
+              "carriedForwardFromSeq": { "type": "string" },
               "clarificationId": {
                 "anyOf": [
                   { "type": "null" },

package/runtime/templates/reports/final-report.template.md

@@ -43,6 +43,19 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {{ t("sectionIntro.clarificationCarryIn") }}
 
 - Source file: `{{ clarificationCarryIn.sourceFile }}`
+{% if implementationPlanning and implementationPlanning.incrementalDecision %}
+{% set incrementalDecision = implementationPlanning.incrementalDecision %}
+### 0.1 Incremental Re-Verification Scope
+
+- Decision mode: `{{ incrementalDecision.mode }}`
+- Reason: {{ incrementalDecision.reason }}
+{% if incrementalDecision.mode == 'incremental' %}
+- Re-verified stages: {% for s in incrementalDecision.reverifyStages %}`stage-{{ s }}`{% if not loop.last %}, {% endif %}{% else %}(none){% endfor +%}
+- Carried-forward stages: {% for s in incrementalDecision.carryStages %}`stage-{{ s }}` carried-forward (unchanged){% if not loop.last %}, {% endif %}{% else %}(none){% endfor +%}
+
+Carried-forward plan items retain their prior verdicts verbatim; each such item carries a `carriedForwardFromSeq` tag pointing at the run it was verified in.
+{% endif %}
+{% endif %}
 
 {% endif %}
 ## Summary of the Problem or Verification Target

package/runtime/validators/validate-run.py

@@ -744,6 +744,14 @@ _EMPTY_CARRY_IN_SOURCE_RE = re.compile(
     re.MULTILINE,
 )
 
+# Section 0 incremental audit sub-block. When the data.json records an
+# `implementationPlanning.incrementalDecision` with `mode == "incremental"`,
+# the rendered report MUST expose the decision so a reader can audit which
+# stages were re-verified vs carried forward unchanged.
+_INCREMENTAL_AUDIT_HEADING_RE = re.compile(
+    r"^###[ \t]+0\.1[ \t]+Incremental Re-Verification Scope\b", re.MULTILINE
+)
+
 # Deprecated section headings removed by the report-format readability
 # pass. Each entry is (regex, human-readable remedy). The regexes are
 # line-anchored to avoid false positives from inline references in prose
@@ -971,6 +979,44 @@ def _validate_conformance(report_path: Path, failures: list[str],
             )
 
 
+def _check_incremental_audit_block(
+    report_path: Path, content: str, failures: list[str]
+) -> None:
+    """Enforce the Section 0 incremental audit block.
+
+    When the data.json records an `implementationPlanning.incrementalDecision`
+    with `mode == "incremental"`, the rendered markdown MUST carry the
+    `### 0.1 Incremental Re-Verification Scope` block naming the re-verified
+    and carried-forward stages — otherwise the narrowed re-run is silently
+    un-auditable. Non-incremental (`full`) runs and reports without the
+    decision are exempt, so this never conflicts with the empty-Section-0
+    stub rule (that fires only when NO carry-in was provided at all).
+    """
+    data = _load_final_report_data(report_path)
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return
+    decision = planning.get("incrementalDecision")
+    if not isinstance(decision, dict) or decision.get("mode") != "incremental":
+        return
+    if _INCREMENTAL_AUDIT_HEADING_RE.search(content) is None:
+        failures.append(
+            "final report data.json records an `incremental`-mode "
+            "implementationPlanning.incrementalDecision, but the markdown is "
+            "missing the `### 0.1 Incremental Re-Verification Scope` audit "
+            "block under Section 0. Re-render from the data.json so the "
+            "re-verified / carried-forward stages are visible."
+        )
+        return
+    for needle in ("Re-verified stages", "Carried-forward stages"):
+        if needle not in content:
+            failures.append(
+                f"final report's Section 0 incremental audit block is missing "
+                f"the `{needle}` line — an `incremental`-mode run must list "
+                "both the re-verified and the carried-forward stages."
+            )
+
+
 def validate_report(
     report_path: Path,
     required_agent_status_entries: list[str],
@@ -1064,6 +1110,10 @@ def validate_report(
             "and body — do NOT emit a placeholder stub."
         )
 
+    # Incremental audit block — an `incremental`-mode re-run must expose its
+    # scope decision in Section 0 so the narrowed re-verification is auditable.
+    _check_incremental_audit_block(report_path, content, failures)
+
     # Deprecated section headings — pre-1.0 hard removal.
     for pattern, remedy in _DEPRECATED_FINAL_REPORT_PATTERNS:
         if pattern.search(content) is not None:

package/src/cli-registry.mjs

@@ -305,6 +305,20 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Append run error events to the run error log"],
   },
+  {
+    name: "incremental-scope",
+    module: "./commands/execute/incremental-scope.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Decide re-verify vs carry-forward scope for a clarification re-run"],
+  },
+  {
+    name: "incremental-carry",
+    module: "./commands/execute/incremental-carry.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Merge carried-forward plan-item verdicts into an incremental re-run"],
+  },
   {
     name: "memory",
     module: "./commands/memory/memory.mjs",

package/src/commands/execute/incremental-carry.mjs

@@ -0,0 +1,20 @@
+import { runInstalledScript } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra incremental-carry — merge carried-forward plan-item verdicts into an incremental re-run's data.json
+
+Wraps the python helper (\`okstra-incremental-carry.py\`) installed under
+\`~/.okstra/bin/\` so the report-writer worker calls \`okstra incremental-carry\`
+instead of emitting a \`python3 "$HOME/..."\` invocation (which breaks
+\`Bash(okstra:*)\` permission matching and prompts on every call).
+
+Usage:
+  okstra incremental-carry --prev-data <path> --cur-data <path> \\
+    --prev-seq <str> [--carry-stages <csv>] --out <path>
+
+Writes the merged data.json to --out. Exits non-zero on schema drift
+(\`CarryError\`) so the caller's shell can fall back to a full re-run.
+`;
+
+export async function run(args) {
+  return runInstalledScript({ scriptName: "okstra-incremental-carry.py", args, usage: USAGE });
+}

package/src/commands/execute/incremental-scope.mjs

@@ -0,0 +1,20 @@
+import { runInstalledScript } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra incremental-scope — decide the re-verify vs carry-forward scope for a clarification re-run
+
+Wraps the python helper (\`okstra-incremental-scope.py\`) installed under
+\`~/.okstra/bin/\` so the lead prompt calls \`okstra incremental-scope\`
+instead of emitting a \`python3 "$HOME/..."\` invocation (which breaks
+\`Bash(okstra:*)\` permission matching and prompts on every call).
+
+Usage:
+  okstra incremental-scope --prev-data <path> --cur-base-sha <sha> \\
+    --prev-base-sha <sha> [--impacted <csv>] [--option <name>]
+
+Prints a JSON decision {mode, reverify_stages, carry_stages, reason} to stdout.
+All arguments are forwarded verbatim to the python helper.
+`;
+
+export async function run(args) {
+  return runInstalledScript({ scriptName: "okstra-incremental-scope.py", args, usage: USAGE });
+}