okstra 0.200.0 → 0.201.0

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

@@ -25,6 +25,7 @@
   ],
   "additionalProperties": false,
   "properties": {
+    "technicalVerification": {"$ref": "#/$defs/TechnicalVerification"},
     "schemaVersion": {
       "const": "3.0",
       "description": "Schema version. Renderer refuses to process unknown versions."
@@ -1664,6 +1665,86 @@
     }
   },
   "allOf": [
+    {
+      "if": {
+        "properties": {
+          "header": {
+            "properties": {
+              "taskType": {
+                "const": "technical-verification"
+              }
+            }
+          }
+        },
+        "required": [
+          "header"
+        ]
+      },
+      "then": {
+        "required": [
+          "technicalVerification"
+        ],
+        "properties": {
+          "frontmatter": {
+            "properties": {
+              "approved": {
+                "const": false
+              }
+            }
+          },
+          "implementationOptionSelection": false,
+          "implementationPlanning": false,
+          "implementation": false,
+          "finalVerification": false,
+          "releaseHandoff": false,
+          "errorAnalysis": false,
+          "requirementsDiscovery": false,
+          "improvementDiscovery": false,
+          "analysisCommon": false,
+          "projectAnalysis": false,
+          "featureAnalysis": false,
+          "changeImpactAnalysis": false,
+          "followUpTasks": {
+            "contains": {
+              "properties": {
+                "origin": {
+                  "const": "phase-continuation"
+                }
+              },
+              "required": [
+                "origin"
+              ]
+            },
+            "minContains": 1,
+            "maxContains": 1,
+            "items": {
+              "if": {
+                "properties": {
+                  "origin": {
+                    "const": "phase-continuation"
+                  }
+                },
+                "required": [
+                  "origin"
+                ]
+              },
+              "then": {
+                "properties": {
+                  "suggestedTaskType": {
+                    "const": "implementation-option-selection"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "technicalVerification": false
+        }
+      }
+    },
     {
       "description": "Frontmatter approval input matches the implementation-planning contract.",
       "if": {
@@ -2013,6 +2094,7 @@
             "properties": {
               "taskType": {
                 "enum": [
+                  "technical-verification",
                   "requirements-discovery",
                   "project-analysis",
                   "feature-analysis",
@@ -2192,6 +2274,7 @@
     }
   ],
   "oneOf": [
+    {"required": ["technicalVerification"]},
     {
       "required": [
         "requirementsDiscovery"
@@ -3079,7 +3162,8 @@
           "enum": [
             "pending-direction-selection",
             "implementation-planning",
-            "blocked"
+            "blocked",
+            "technical-verification"
           ]
         },
         "userNarrative": {
@@ -3745,6 +3829,17 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "resolutionKind": {
+          "type": "string",
+          "enum": ["user-decision", "technical-verification"],
+          "description": "Optional for historical reads; blocked report publication requires explicit classification."
+        },
+        "clarificationRefs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {"type": "string", "pattern": "^C-[0-9]{3}$"},
+          "description": "User decisions require nonempty references to actual clarification records, including answered records."
+        },
         "fact": {
           "type": "string",
           "minLength": 1
@@ -4060,7 +4155,7 @@
         },
         "stageRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "integer",
@@ -4069,7 +4164,7 @@
         },
         "stepRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "string",
@@ -4078,7 +4173,7 @@
         },
         "validationRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "string",
@@ -4087,7 +4182,7 @@
         },
         "fileRefs": {
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "uniqueItems": true,
           "items": {
             "type": "string",
@@ -4097,10 +4192,59 @@
         "status": {
           "enum": [
             "covered",
-            "not-covered"
+            "not-covered",
+            "externally-tracked"
           ]
+        },
+        "crossProjectDependencyRefs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^XP-[0-9]{3,}$"
+          }
         }
-      }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "status": {
+              "enum": [
+                "covered",
+                "not-covered"
+              ]
+            },
+            "stageRefs": {
+              "minItems": 1
+            },
+            "stepRefs": {
+              "minItems": 1
+            },
+            "validationRefs": {
+              "minItems": 1
+            },
+            "fileRefs": {
+              "minItems": 1
+            },
+            "crossProjectDependencyRefs": {
+              "maxItems": 0
+            }
+          }
+        },
+        {
+          "required": [
+            "crossProjectDependencyRefs"
+          ],
+          "properties": {
+            "status": {
+              "const": "externally-tracked"
+            },
+            "crossProjectDependencyRefs": {
+              "minItems": 1
+            }
+          }
+        }
+      ]
     },
     "SelectedDirectionCoverageSummary": {
       "type": "object",
@@ -4166,8 +4310,155 @@
         }
       }
     },
+    "TechnicalVerification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sourceReport",
+        "sourceDataSha256",
+        "scope",
+        "checks",
+        "routing"
+      ],
+      "properties": {
+        "sourceReport": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceDataSha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "scope": {
+          "const": "technical-evidence-only"
+        },
+        "checks": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "candidateId",
+              "factIndex",
+              "fact",
+              "hypothesis",
+              "procedure",
+              "confirmingSignal",
+              "rejectingSignal",
+              "status",
+              "commands",
+              "observation",
+              "limitations"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^TV-[0-9]{3}$"
+              },
+              "candidateId": {
+                "type": "string",
+                "pattern": "^IO-[0-9]{3}$"
+              },
+              "factIndex": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "fact": {
+                "type": "string",
+                "minLength": 1
+              },
+              "hypothesis": {
+                "type": "string",
+                "minLength": 1
+              },
+              "procedure": {
+                "type": "string",
+                "minLength": 1
+              },
+              "confirmingSignal": {
+                "type": "string",
+                "minLength": 1
+              },
+              "rejectingSignal": {
+                "type": "string",
+                "minLength": 1
+              },
+              "status": {
+                "enum": [
+                  "supported",
+                  "refuted",
+                  "inconclusive",
+                  "not-run"
+                ]
+              },
+              "commands": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "command",
+                    "cwd",
+                    "exitCode",
+                    "logPath"
+                  ],
+                  "properties": {
+                    "command": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "cwd": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "exitCode": {
+                      "type": "integer"
+                    },
+                    "logPath": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              },
+              "observation": {
+                "type": "string",
+                "minLength": 1
+              },
+              "limitations": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "routing": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "nextTaskType",
+            "rationale"
+          ],
+          "properties": {
+            "nextTaskType": {
+              "const": "implementation-option-selection"
+            },
+            "rationale": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
     "TaskType": {
       "enum": [
+        "technical-verification",
         "requirements-discovery",
         "improvement-discovery",
         "error-analysis",

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

@@ -15,6 +15,7 @@
     "requirementsDiscovery": {"type": "object"},
     "improvementDiscovery": {"type": "object"},
     "errorAnalysis": {"type": "object"},
+    "technicalVerification": {"type": "object"},
     "analysisCommon": {"type": "object"},
     "projectAnalysis": {"type": "object"},
     "featureAnalysis": {"type": "object"},

package/runtime/schemas/report-synthesis-packet-v1.0.schema.json

@@ -111,7 +111,7 @@
       "minItems": 1,
       "items": {
         "type": "object",
-        "required": ["label", "owner", "path", "digest", "content"],
+        "required": ["label", "owner", "path", "content"],
         "additionalProperties": false,
         "properties": {
           "label": {

package/runtime/schemas/report-writer-corrections-v1.0.schema.json

@@ -13,13 +13,14 @@
       "minLength": 1,
       "description": "Project-relative path of the narrative attempt the corrections apply to."
     },
+    "baseNarrativeSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "context": {
       "type": "string",
       "description": "Free text for the writer to read. Not normative; not validated."
     },
     "corrections": {
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "items": { "$ref": "#/$defs/Correction" }
     }
   },
@@ -30,8 +31,10 @@
       "required": ["id", "kind", "path", "reason"],
       "properties": {
         "id": { "type": "string", "pattern": "^RC-[0-9]{3}$" },
-        "kind": { "enum": ["replace", "remove", "rewrite"] },
+        "kind": { "enum": ["replace", "remove", "add", "move", "rewrite"] },
         "path": { "type": "string", "minLength": 1 },
+        "fromPath": { "type": "string", "minLength": 1 },
+        "evidenceRefs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
         "current": {},
         "replacement": {},
         "rule": { "type": "string", "minLength": 1 },
@@ -39,14 +42,38 @@
       },
       "allOf": [
         {
-          "if": { "properties": { "kind": { "const": "replace" } } },
+          "if": { "properties": { "kind": { "enum": ["replace", "add"] } } },
           "then": { "required": ["replacement"] }
         },
+        {
+          "if": { "properties": { "kind": { "const": "move" } } },
+          "then": { "required": ["fromPath"] }
+        },
         {
           "if": { "properties": { "kind": { "const": "rewrite" } } },
           "then": { "required": ["rule"] }
         }
       ]
+    },
+    "RewriteResults": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["baseNarrativeSha256", "replacements"],
+      "properties": {
+        "baseNarrativeSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "replacements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "replacement"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^RC-[0-9]{3}$" },
+              "replacement": {}
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -242,6 +242,8 @@ Output: `{ok: true, outcome: {renderArgv: ["--lead-runtime", "...", ...], render
 
 `renderArgv` is the canonical ordered `okstra render-bundle` argument list. Pass its tokens verbatim and in order. Repeated `--role-count` and `--role-model` flags are intentional. `renderArgs` is a compatibility and inspection view only; do not reconstruct an invocation from it. `orchestration` holds signals this skill acts on itself — never pass its entries to `render-bundle`.
 
+`userAuthorization`, when present, preserves the confirmation prompt actually emitted by this wizard and the relayed `proceed` response. Its `--user-authorization-json` token carries that record into the run manifest; preserve it unchanged. Do not synthesize a receipt for older confirmed states. Include the translator's disclosed provider/model and report material when citing this record in host execution requests, including `report-finalize`. The record documents task scope; it does not grant host execution privileges.
+
 Run every `outcome.persistActions[]` entry BEFORE `render-bundle`. The only supported action is:
 
 ```json
@@ -441,7 +443,7 @@ Inform the user with one short line:
 
 ## Step 7: implementation unattended chaining (orchestration.chainStages)
 
-When `task-type == implementation` and Step 5 outcome's `orchestration.chainStages` CSV has 2+ elements, the current session acts as the orchestrator and runs the stages in dependency order as an unattended chain (a single element behaves like the existing single run, so skip this section — the end of Step 6 is the end of the run).
+When `task-type == implementation` and Step 5 outcome's `orchestration.chainStages` CSV has 2+ elements, the current session acts as the orchestrator and runs the stages in dependency order as an unattended chain (a single element ends this queue after same-run recovery is complete; a separately authorized continuous task follows the continuation rule below).
 
 Queue = the topologically-sorted stage list from splitting `orchestration.chainStages` on `,` (the order Task 5 emitted by topologically sorting the dependency closure). For each stage `N` in the queue, in order:
 
@@ -464,6 +466,12 @@ Do not read the wizard state file directly. `okstra wizard outcome` exposes any
 - Each wizard run owns its own state file (one per `okstra wizard new-state-file`); two parallel skill invocations do not collide.
 - The skill must NOT call `okstra.sh` (or any other bash entrypoint) that would re-implement the orchestration. The wizard + `render-bundle` is the single authority.
 
+## Authorized continuation
+
+At a boundary, distinguish artifact recovery, the next item in the confirmed stage queue, and a new task scope. Continue `recovery.mode: same-run` with its supplied resume command. Continue a confirmed stage queue without asking for another invocation; the wizard receipt's `stageScope` records the displayed selection and prepare rejects stages outside it. For a broader continuous task, cite the user's actual instruction before moving to the recorded ready phase; do not expand a wizard receipt whose task type or inputs no longer match. Preserve approval gates, provider/material scope, and host execution permissions. If these changed or a required user decision remains unresolved, report that specific boundary.
+
+A failed report assembly is not an implementation rejection. Read each skipped step's `blockedBy` value and repair its owning input; do not dispatch workers for derivative missing-file errors. Use the existing retry budget and stop with the first unresolved cause and resume location when an unchanged input produces the same failure without progress. At successful completion inside an authorized continuous scope, report progress and continue; offer `nextCommand` as a user action only when that scope has ended or a concrete boundary prevents continuation.
+
 ## Boundary updates
 
 Follow the rendered launch prompt's "Progress, remaining work, and recommendation" guidance at each phase or implementation-stage boundary, at task completion, and before a controlled session pause or handoff. Include results, remaining work, and the recommended action with its reason. During an authorized continuous run, report the boundary and continue the queue; when the lead returns, relay its closeout without repeating an already delivered update.
@@ -483,4 +491,4 @@ Follow the rendered launch prompt's "Progress, remaining work, and recommendatio
 - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
 - Name every file you show the user as a markdown link — `[<what it is>](<path>)`, with the path inside the parentheses. That is the only form the host renders as clickable; a path in backticks is text the user has to copy out. The `report-finalize` result's `reportPaths.markdown` carries the run's report, report record, and team state already in that form. Commands stay in backticks — a link is for a file, not for something to run.
 - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
-- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. 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. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `/okstra-inspect status`.
+- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, finish after Step 6 and any same-run recovery, unless the user has already authorized continuing the task through further phases. In an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When `report-finalize` returns `recovery.mode: same-run`, continue the authorized corrections in this run and execute `recovery.resumeCommand` before closeout; preserve approvals and model choices without reopening the wizard. The command and owner issues are supplied by `report_finalize._finalize_recovery`. When the lead (or this skill, after the lead returns) reports a successfully finalized run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. 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. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed with `recovery.mode: phase-reentry` → name the cause and use `nextCommand` for the recorded earlier phase; otherwise `/okstra-inspect status`.

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

@@ -33,15 +33,36 @@ Inform the user up-front and confirm before continuing:
 
 ## Step 1: Install okstra
 
+Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present;
+otherwise use the registered host ID declared by the current harness. Use the
+existing host registry and its aliases rather than maintaining a provider-to-host
+lookup in this skill. Claude Code, Codex, Grok, Antigravity, and Kimi are examples,
+not a closed list; additional registered hosts follow the same rule.
+
+Do not infer the host from model names, worker providers, installed executables,
+or `PATH`. A GLM model running inside another harness uses that harness's host
+identity; a separately registered GLM harness uses its own registered identity.
+If neither the launcher nor the harness identifies the host, use `auto` to let
+the existing registry resolve session evidence. Report an unresolved or rejected
+identity without substituting Claude Code or claiming host setup is verified.
+When `auto` resolves successfully, carry the reported resolved host ID forward
+as the literal `<host-runtime>` value instead of detecting again at each step.
+
+Replace `<host-runtime>` with the resolved literal value before executing each
+command. Keep the same resolved host for installation, preflight, diagnostics,
+and retries, including retries against another project or npm cache directory.
+The runtime registry validates host IDs; the skill command contract is checked
+by `tests/contract/test_docs_runtime_contract.py::test_skills_declare_their_host_runtime_explicitly`.
+
 ```bash
-npx -y okstra@latest install --runtime claude-code
+npx -y okstra@latest install --runtime <host-runtime>
 ```
 
 This single command populates everything the user needs:
 
 - `~/.okstra/{lib/python, bin, version}` — python + bash runtime
-- `~/.claude/skills/<name>/SKILL.md` — all okstra skills (canonical count
-  in `~/.okstra/installed-skills.json`)
+- Host skill targets selected by the installer, including the shared Agent skill
+  home — installed targets are recorded in `~/.okstra/installed-skills.json`
 - `~/.okstra/installed-skills.json` — manifest for safe uninstall
 
 The skill should run this even if `~/.okstra/version` already exists —
@@ -53,12 +74,26 @@ Show the final summary line back to the user (`version stamp: x.y.z`).
 If install fails, surface the stderr verbatim. Do NOT try to "fix" it by
 running the legacy `okstra-install.sh` — that path is dev-only.
 
+For npm `EPERM` / `EACCES` errors under its cache directory, distinguish package
+preparation from okstra installation. npm's root-owned-files message is not
+evidence of root ownership. Inspect ownership and the session's write restrictions
+before proposing a permission change. Retry with a temporary cache directory
+writable by the current session, substituting its literal absolute path:
+
+```bash
+npx --cache <writable-cache-directory> -y okstra@latest install --runtime <host-runtime>
+```
+
+Do not run recursive `sudo chown` based only on npm's generic message. A cache
+override does not grant network access or permission to write the installation
+targets; follow the host's permission mechanism if either remains blocked.
+
 **Bash invocation rule (permission-friendly)**: after Step 1, every Bash command in this skill MUST begin with the literal token `okstra` and pass literal argument values. Do not introduce shell variables (`$PROJECT_ROOT`, `$PROJECT_ID`, ...), `$(...)` command substitution, leading `VAR=...` assignments, or wrap commands in `if`/`eval`/`||`/`&&` — any of those make the leading token non-literal, defeat the `Bash(okstra:*)` permission match, and force a confirmation prompt on every call. When a prior tool call emitted a path or value, paste the literal string into the next command. Every `okstra <subcmd>` call self-bootstraps its Python path — never run `okstra paths --shell` / `export PYTHONPATH=...`.
 
 ## Step 2: Resolve PROJECT_ROOT
 
 ```bash
-okstra preflight
+okstra preflight --runtime <host-runtime>
 ```
 
 Read the fixed `Okstra preflight`, `Project root`, `Project JSON`, `Project ID`,
@@ -68,11 +103,11 @@ Read the fixed `Okstra preflight`, `Project root`, `Project JSON`, `Project ID`,
 - `Ok: false`, `Stage: resolve` → ask the user (`AskUserQuestion`, free text) for an absolute project root and rerun as a separate Bash tool call with the literal absolute path:
 
   ```bash
-  okstra preflight --cwd /abs/path/from/user
+  okstra preflight --runtime <host-runtime> --cwd /abs/path/from/user
   ```
 
 - `Ok: false`, `Stage: project_json_missing` → proceed to Step 3 (this is the normal create path).
-- `Ok: false`, any other `Stage` (`python`, `parse`, `project_json_invalid`) → show the fixed `Reason` line to the user verbatim and follow the `Recovery` line (typically `okstra doctor` to diagnose, then `okstra ensure-installed` or re-running the Step 1 install). `Reason` is the SSOT — do not hand-enumerate stage causes.
+- `Ok: false`, any other `Stage` (`python`, `parse`, `project_json_invalid`) → show the fixed `Reason` line to the user verbatim and follow the `Recovery` line (typically `okstra doctor --runtime <host-runtime>` to diagnose, then `okstra ensure-installed --runtime <host-runtime>` or re-running the Step 1 install). `Reason` is the SSOT — do not hand-enumerate stage causes.
 
 ## Step 3: Project metadata setup
 
@@ -132,7 +167,7 @@ matching section:
 ## Step 4: Verify
 
 ```bash
-okstra doctor --runtime claude-code
+okstra doctor --runtime <host-runtime>
 ```
 
 If all checks return `OK`, the setup is complete. If any check fails, surface

package/runtime/templates/report-writer-prompt-preamble.md

@@ -6,6 +6,8 @@ This file is the audience-specific contract for `report-writer`. Read it and the
 
 Write only the report narrative Markdown at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`.
 
+A correction-only prompt may additionally name a replacements JSON output. In that mode, the supplied `apply-corrections` command owns the narrative update.
+
 The report narrative Markdown contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
 
 The following fields belong to other owners and must not appear in the narrative: `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, and `planBodyVerification`.
@@ -14,7 +16,7 @@ Do not pre-fill a future round, future gate, usage value, activity identifier, o
 
 ## Required reading
 
-Read every path listed under `## Inputs` end-to-end. Full context is available for synthesis, but read access does not transfer write ownership. Preserve supplied technical meaning and do not invent missing evidence.
+For initial synthesis, read every range in the synthesis packet's Read Index once, in order. Each range gives a zero-based UTF-8 byte offset and byte count for a bounded read. Continue at the next unread range instead of rereading the beginning. Resolve shared-text references through the definitions in the same source section; every vote, condition, dissent, and unknown field remains available. The sibling JSON stores each original frozen source for targeted checks. Read access does not transfer write ownership. Preserve supplied technical meaning and do not invent missing evidence.
 
 Write the audit sidecar before synthesis with one `- PROGRESS: <stage> <ISO-8601-UTC>` line and the required reading confirmation. Valid stages are `started`, `required-reading-complete`, `synthesis-start`, `narrative-write-start`, and `write-result-start`.
 
@@ -34,7 +36,7 @@ Follow the task-specific schema order and write the prose in English.
 
 These are the only names allowed at the top level:
 
-`Analysis Common`, `Change Impact Analysis`, `End State Coverage`, `Error Analysis`, `Feature Analysis`, `Final Verdict`, `Final Verification`, `Follow Up Tasks`, `Human Summary`, `Implementation`, `Implementation Option Selection`, `Implementation Planning`, `Improvement Discovery`, `Project Analysis`, `Rationale`, `Recommended Next Steps`, `Release Handoff`, `Requirements Discovery`, `Summary`, `Ticket Coverage`, `Verdict Card`
+`Analysis Common`, `Change Impact Analysis`, `End State Coverage`, `Error Analysis`, `Feature Analysis`, `Final Verdict`, `Final Verification`, `Follow Up Tasks`, `Human Summary`, `Implementation`, `Implementation Option Selection`, `Implementation Planning`, `Improvement Discovery`, `Project Analysis`, `Rationale`, `Recommended Next Steps`, `Release Handoff`, `Requirements Discovery`, `Summary`, `Technical Verification`, `Ticket Coverage`, `Verdict Card`
 
 The synthesis packet's Authoring Contract names which of these are **required** for this run and the exact `Verdict Token` value; those lines are read from the frozen report schema, so follow them over memory. `Verdict Token` under `Final Verdict` is pinned by task type: `not-applicable` for `requirements-discovery`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `release-handoff` and `quick`; one of `accepted`, `conditional-accept`, `blocked` for `final-verification`; one of `analysis-complete`, `analysis-partial`, `blocked` for `project-analysis`, `feature-analysis` and `change-impact-analysis`. `Human Summary`, `Verdict Card`, `Rationale`, `Summary`, `Final Verdict`, `Recommended Next Steps` and `Follow Up Tasks` are required at the top level of every narrative.
 
@@ -46,7 +48,9 @@ The pointer record names the project-relative narrative path and audit sidecar p
 
 ## Corrections
 
-A prompt whose body carries a `## Corrections` section is a corrective round. okstra has already applied that ledger to your previous attempt and validated the result against the schema and the task's semantic checks, so apply each entry exactly as written and change nothing else.
+A prompt whose body carries a `## Corrections` section is a corrective round. Its correction-only contract supplies the current values, constraints, evidence, and base narrative hash. Read those inputs; the initial-synthesis reading requirement above does not apply. Do not reopen the full synthesis packet or rewrite the complete narrative. If requested, write the specified replacements JSON file and execute the supplied `apply-corrections` command. The runtime checks the base hash, permitted replacement ids, schema, and semantic rules before updating the narrative. Write the pointer and audit sidecar under their existing contracts.
+
+Apply only the supplied correction ids and change nothing else.
 
 When the `Context` subsection or any free-form instruction in the body conflicts with the synthesis packet's Authoring Contract, the contract wins: write the contract's value and report the conflict through the Worker Error Contract's typed error log instead of following the instruction.