okstra 0.201.3 → 0.204.0

package/runtime/prompts/profiles/feature-analysis.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "1.0",
+  "id": "feature-analysis",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "analyser",
+      "dutyId": "analysis-worker",
+      "min": 2,
+      "recommended": 3,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "dynamic",
+      "roleId": "verifier",
+      "dutyId": "reverification-worker",
+      "sourceRoleIds": [
+        "analyser"
+      ],
+      "activation": "per-selected-source"
+    }
+  ]
+}

package/runtime/prompts/profiles/feature-analysis.md

@@ -1,25 +1,5 @@
 # Feature Analysis Profile
 
-```yaml
-roles:
-  - role: analyser
-    min: 2
-    recommended: 3
-    max: 5
-    duty: analysis-worker
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-  - role: verifier
-    min: 0
-    recommended: 0
-    max: 0
-    duty: reverification-worker
-    dynamic: true
-```
-
 - Purpose: analyse a confirmed feature target's behavior, rules, state changes, external calls, and test coverage scope without designing or changing an implementation
 - Required workers:
   - claude

package/runtime/prompts/profiles/final-verification.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "1.0",
+  "id": "final-verification",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "verifier",
+      "dutyId": "acceptance-verifier",
+      "min": 2,
+      "recommended": 2,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "critic",
+      "dutyId": "acceptance-critic",
+      "min": 0,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    }
+  ]
+}

package/runtime/prompts/profiles/final-verification.md

@@ -1,24 +1,5 @@
 # Final Verification Profile
 
-```yaml
-roles:
-  - role: verifier
-    min: 2
-    recommended: 2
-    max: 5
-    duty: acceptance-verifier
-  - role: critic
-    min: 0
-    recommended: 1
-    max: 1
-    duty: acceptance-critic
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-```
-
 - Purpose: judge the delivered implementation on three axes before final acceptance — does it cover every requirement (under-delivery), does it carry work no requirement asked for (over-delivery), and does it actually do what it claims (defects, and tests that verify nothing). Whether the run followed okstra's own procedure is not one of the axes: the runtime and `validators/validate-run.py` own that, and a finding about it is not an acceptance judgement
 - Required workers:
   - claude
@@ -49,8 +30,8 @@ roles:
 - Pre-verification entry gate (resolved & enforced by `okstra render-bundle` prep — the lead does NOT recompute it):
   - the verification target (scope / worktree / base / stages / source reports / diff stat) is injected as the `VERIFICATION_TARGET` block. The lead MUST treat it as authoritative and MUST NOT re-pick a target from the brief.
   - **whole-task scope** (`--stage auto`, default): prep has already verified every Stage Map stage is `status:done` in `consumers.jsonl`, every done stage's `head_commit` is an ancestor of the task worktree HEAD (all stage branches merged), and the worktree is clean outside `.okstra/`. If any check failed the run never started (PrepareError); a started whole-task run is therefore a fully-merged, clean target.
-    - **whole-task is a mutating phase, not a read-only one.** On entry, whole-task mode auto-merges (with `--no-ff`) the done stages not yet merged into the task branch to create an integration commit. The stage worktrees are NOT removed on entry: they are reclaimed after the verdict, by the Phase 7 `teardown-stages` step, and only when the verdict clears the work for release (`accepted`, or `conditional-accept` with no condition blocking release). A `blocked` verdict therefore leaves every stage worktree in place, so the rework it routes to can start immediately. The stage branches are kept as the reviewable stack (the target of `okstra handoff local-checkout --stage <N>`). If a merge conflict occurs it reports the conflicting files and aborts (the user resolves them manually and retries). A stage worktree with uncommitted changes remaining is preserved. Therefore the "fully-merged, clean target" the entry gate above refers to is the state after this auto-integration step completes, and whole-task final-verification must be treated as a mutating phase that creates the integration commit.
-  - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification: it MUST NOT recommend plain `release-handoff`, but MAY recommend `release-handoff(stage-group)` when the verdict is `accepted` — the stage becomes PR-eligible for a stage-group handoff.
+    - **whole-task mutates only when it has to.** When one stage branch already contains every other done stage's commit — the usual shape of a linear plan, since each stage branches from its predecessor's done commit — that branch IS the whole task, and verification runs in that stage's worktree with no merge at all (`stage_targets.containing_stage`). Only when the stage graph has several tips does entry auto-merge (with `--no-ff`) the done stages into the task branch to create an integration commit; that case is the mutating one. The stage worktrees are NOT removed on entry: they are reclaimed after the verdict, by the Phase 7 `teardown-stages` step, and only when the verdict clears the work for release (`accepted`, or `conditional-accept` with no condition blocking release). A `blocked` verdict therefore leaves every stage worktree in place, so the rework it routes to can start immediately. The stage branches are kept as the reviewable stack (the target of `okstra handoff local-checkout --stage <N>`). If a merge conflict occurs it reports the conflicting files and aborts (the user resolves them manually and retries). A stage worktree with uncommitted changes remaining is preserved. Therefore the "fully-merged, clean target" the entry gate above refers to is the state after this auto-integration step completes, and whole-task final-verification must be treated as a mutating phase that creates the integration commit.
+  - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification of one stage, and that is exactly the unit release-handoff ships: an `accepted` verdict here makes the stage PR-eligible, so `release-handoff` is the routing target. It says nothing about any other stage.
   - the lead still captures `git status --short` from the injected worktree to confirm the analysis ran against the delivered work-tree state; an unexpected divergence (dirty tree outside `.okstra/`, missing worktree) is a `tool-failure`, not a silent proceed.
 - Worker verification procedure:
   - **Target confirmation:** analyse the injected target and nothing else. Read `verification-target.md` for the stage/report mapping and the complete diff stat. Prepare fixed that target and `validators/validate-run.py` `_validate_verification_target_match` re-checks the report against its digest, so the procedure to follow here is simply: if the worktree you can see does not match the injected target, record a `tool-failure` — never reselect a target.
@@ -84,7 +65,7 @@ roles:
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command touched during this run MUST be listed with its exact command line and one honest status — `executed` (ran; carries its exit code) / `advisory` (external Tier 3 did not PASS; carries observed/expected results and remains user-owned) / `env-unavailable` (should run but cannot in this environment — missing replica DB, container, or service; carries the reason, never a faked pass) / `not-configured` (no such qa-command tier) / `rejected` (a mutating/denied token — skipped, carries the denied token). A check that could not run locally is recorded as `env-unavailable` or `advisory` according to the external QA policy — never silently dropped and never reported as `executed` with an invented exit code. Mutating-command prohibition is the shared read-only boundary (see Non-goals); it is not restated per row.
   - **Could-not-verify roll-up (§5.8.9)**: the template mechanically aggregates every not-confirmed check into one scannable list — `gap` requirement-coverage rows, `advisory` / `not-configured` / `env-unavailable` / `rejected` command rows, and `blocked` manual tests. You do not hand-author it, but you MUST give those rows their honest status so nothing unverified hides across sections: a check silently recorded as `executed`/`covered` will not surface in the roll-up. This is okstra's answer to "say what could not be verified this run."
-  - **Routing recommendation**: `finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value of the enum below, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. The seven allowed targets are `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, and `done`. Both `release-handoff` forms are allowed ONLY when the verdict is release-ready — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false`. Plain `release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a release-ready `single-stage` run routes to `release-handoff(stage-group)` (or `implementation` / `done`) instead. `done` ends the lifecycle here. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target`, a verdict that is not release-ready routed to either `release-handoff` form (naming the condition ids that block it), and a `single-stage` report whose routing cites plain `release-handoff`.
+  - **Routing recommendation**: `finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value of the enum below, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. The eight allowed targets are `release-handoff`, `release-handoff(stage-group)`, `final-verification`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, and `done`. `final-verification` re-runs this phase on the same head and is for exactly one situation: every remaining blocker is an environment or configuration fault whose cause this report already names — a `qaCommands` entry pointing at a path that no longer exists, a missing credential, a stale fixture — so nothing in the code, the plan, or the selected direction is being re-decided. Name the repair in the `rationale`. When any blocker needs a code, plan, or direction change, route to the phase that owns that change instead; routing a defect you have not diagnosed back into this phase re-runs the verification that already failed. Both `release-handoff` forms are allowed ONLY when the verdict is release-ready — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false`. Either verification scope may route there: release-handoff opens one PR per stage, so a release-ready `single-stage` run is the evidence for that stage's PR, and `release-handoff(stage-group)` is only a scope qualifier that projects onto the same phase. `done` ends the lifecycle here. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target` and a verdict that is not release-ready routed to either `release-handoff` form (naming the condition ids that block it).
   - **Verified-row recording** (single-stage scope only): when the verdict is release-ready, the lead MUST run `okstra handoff record-verified --plan-run-root <plan-run-root> --stage <N> --report-path <final-report.md path> --data-json <final-report data.json path>` and quote the command + exit code in the report. The helper checks the latest verification manifest, task/stage identity, report pointer, prepared target, and recorded implementation commit. It records the captured commit and original verdict, including conditional acceptance conditions. A missing target or mismatched commit requires re-verification. Recording happens before final validation; eligibility is granted only after that verification passes validation. **Enforced:** `okstra_ctl.handoff_verification` validates the evidence, and `validators/validate-run.py` `_validate_verified_row_recorded` requires a `verified` row matching this report, captured commit, and verdict.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 1. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff

package/runtime/prompts/profiles/forbidden-actions.json

@@ -75,13 +75,14 @@
   ],
   "release-handoff": [
     "entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited",
-    "local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` run by the lead. The single exception is the merge commits `okstra handoff assemble` itself creates on the collector branch — the lead never merges by hand.",
+    "local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` / `git rebase --onto` / `git cherry-pick` / `git commit --amend` run by the lead. The single exception is the merge commits `okstra handoff pr-plan` itself creates on a `merge-base` branch — the lead never merges by hand. Rewriting a stage branch breaks the PR stack that sits on it.",
     "any git push variant that rewrites remote history, regardless of intent or whether the user said \"force it\": `git push --force`, `git push --force-with-lease`, `git push -f`, `git push +<refspec>`, or any other history-rewriting invocation",
-    "pushing directly to a base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the PR base in this run. The only permitted push target is the current feature branch.",
+    "pushing directly to a release base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the release base in this run. The only permitted push targets are the branches `okstra handoff pr-plan` listed for this run (each stage `head_branch`, and any `merge-base` branch).",
     "bypassing repo safeguards: `--no-verify` / `-n` on `git push`, bypassing GPG signing, disabling safeguards via equivalent flags, or any hook bypass.",
     "release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.",
     "source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.",
-    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local checkout`; pushing when the user picked `skip`; switching the PR base branch silently after the user already chose one.",
+    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local checkout`; pushing when the user picked `skip`; switching the release base branch silently after the user already chose one; opening a PR for a stage outside `HANDOFF_STAGES`.",
+    "squash-merging, or instructing anyone to squash-merge, a stage PR — and `gh pr merge` in any form. A squash replaces the commits the next stage's PR base points at, so the stack breaks; the PR body states merge-commit-or-rebase and the lead never merges.",
     "retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.",
     "worker dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Okstra lead.",
     "silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim."

package/runtime/prompts/profiles/implementation-option-selection.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "1.0",
+  "id": "implementation-option-selection",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "designer",
+      "dutyId": "direction-selection-worker",
+      "min": 3,
+      "recommended": 3,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "dynamic",
+      "roleId": "verifier",
+      "dutyId": "reverification-worker",
+      "sourceRoleIds": [
+        "designer"
+      ],
+      "activation": "per-selected-source"
+    }
+  ]
+}

package/runtime/prompts/profiles/implementation-option-selection.md

@@ -1,25 +1,5 @@
 # Implementation Option Selection Profile
 
-```yaml
-roles:
-  - role: designer
-    min: 3
-    recommended: 3
-    max: 5
-    duty: direction-selection-worker
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-  - role: verifier
-    min: 0
-    recommended: 0
-    max: 0
-    duty: reverification-worker
-    dynamic: true
-```
-
 - Purpose: compare feasible implementation directions before planning, preserving a read-only record of the evidence and trade-offs that selects the direction to plan
 - Required workers:
   - claude

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

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": "1.0",
+  "id": "implementation-planning",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "planner",
+      "dutyId": "planning-worker",
+      "min": 2,
+      "recommended": 2,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "critic",
+      "dutyId": "scope-critic",
+      "min": 0,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "dynamic",
+      "roleId": "verifier",
+      "dutyId": "reverification-worker",
+      "sourceRoleIds": [
+        "critic",
+        "planner"
+      ],
+      "activation": "per-selected-source"
+    }
+  ]
+}

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

@@ -1,34 +1,11 @@
 # Implementation Planning Profile
 
+Keep `commandOrObservation` executable when the checklist calls for a command. Put explanations and existing-helper citations in the checklist's `check` text, outside the command. Do not append prose after a semicolon. The plan-item renderer separates legacy `existing helper: <file>:<lines>` suffixes, and `verification-target` supplies the same executable command to every verifier.
+
 Validation commands are executable inputs: preserve their newlines, quotes, and code bodies. Use frozen dependency installation (`npm ci`, `pnpm install --frozen-lockfile`, or the package manager's equivalent). Name QA scripts with absolute task-artifact paths when a command runs from a stage worktree; `.okstra/tasks/...` relative to that worktree does not point to the project task. `stage_validation_executability_errors` enforces command restrictions at planning validation, implementation entry, and report preflight, including advisory plan-body runs.
 
 Plan for the actual worktree layout before approval. Shared documentation directories can be links to the main checkout. Choose a build command compatible with those links (for example, an installed Next.js version may provide `next build --webpack`); verify the available option rather than assuming it. Do not plan for a verifier to move links or repair its environment. Compare negative-case assertions with the brief and the script body: a requirement to cache existing assets does not establish that missing assets should be cached. Record any changed expectation in a new plan revision; preserve the earlier approved plan.
 
-```yaml
-roles:
-  - role: planner
-    min: 2
-    recommended: 2
-    max: 5
-    duty: planning-worker
-  - role: critic
-    min: 0
-    recommended: 1
-    max: 1
-    duty: scope-critic
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-  - role: verifier
-    min: 0
-    recommended: 0
-    max: 0
-    duty: reverification-worker
-    dynamic: true
-```
-
 - Purpose: turn an upstream-selected direction into an executable plan; legacy reruns may retain candidate comparison
 - Required workers:
   - claude
@@ -69,8 +46,8 @@ roles:
   - flag any requirement that is ambiguous, contradictory, or missing success criteria — register each one as a row in the report's `## 1. Clarification Items` table with `Blocks=approval` instead of guessing
   - read `<PROJECT_ROOT>/.okstra/glossary.md` and `<PROJECT_ROOT>/.okstra/decisions/` titles if present. Absent okstra memory files are the normal state — do not error. Treat the brief's `terminology:*` resolutions from `requirements-discovery` (if any) as authoritative; if missing, resolve any remaining fuzzy term as a `Blocks=approval` clarification row.
   - **Stage Ledger (read before drafting the Stage Map):** when this task already has a plan on disk, the analysis packet carries a `## Stage Ledger` JSON block listing every stage with its `status` (`done` / `active` / `ready` / `blocked`), `dependsOn`, and done commit. It states what exists, not what to plan. Two rules follow from it:
-    - A stage whose `status` is `done` is already implemented and will not be executed again. Carry its plan body forward as written; do not rewrite its steps, and do not fold its work into a new stage.
-    - Every stage number in the ledger is taken. A new stage takes the next number after the highest one listed; numbers are never reused or reordered. **Not yet machine-enforced** — the validator for this rule lands with the plan-amendment feature.
+    - A stage whose `status` is `done` is already implemented and will not be executed again. Declare it in this report's `stages[]` and `stageMap[]` with its plan body copied forward as written; do not rewrite its steps, and do not fold its work into a new stage. Its plan items are `observed`, not `in-scope` (`okstra_ctl.plan_items.stage_scope_bucket`), so re-declaring it adds no verification load. A carried body is also not re-judged: the planning conformance gate skips a stage the consumer ledger records as `done`, and report assembly issues no design-prep request for one (`okstra_ctl.design_prep.materialize_design_prep_requests`). A rule that widened since that stage shipped cannot be satisfied by a body you are forbidden to rewrite.
+    - Every stage number in the ledger is taken. This report declares every one of them — rows run `1..N` with no gap — and a new stage takes the next number after the highest one listed; numbers are never reused or reordered. A report that declares only its new stages satisfies neither rule and is refused twice over. **Enforced:** `okstra_ctl.stage_map._validate_stage_numbers` rejects the gap in every published plan it parses, so `okstra prepare` refuses the implementation run (`okstra_ctl.run._parse_stage_map_into_ctx`) and the Stage Ledger of every later run reads as `unreadable`; `validators/validate-implementation-plan-stages.py` check **S2** reports the same defect at authoring time. Cancelling a stage you no longer want is not yet expressible — that lands with the plan-amendment feature — so an unstarted stage you drop still keeps its number and body here.
     - The ledger answers two questions from two sources, and the block names both. `sourcePlan` is the plan the completed stages were actually built against; `latestPlan` is the plan the `stages` list came from and is therefore the numbering authority. When they differ, the completed work followed the former and the highest taken number comes from the latter.
     - A `planDivergence` entry means one of two things: the two plans disagree about a stage that is already `done` — the same number naming different work, or a completed stage the latest plan no longer declares — or the plan the completed stages were built against could not be read at all, so that comparison never ran. Both block the same way: do not pick one of the two plans yourself; register it as a `Blocks=approval` clarification row and assign no new stage number until it is resolved. Completed stages built against an *earlier* plan are not a divergence — that is the normal shape of an amended plan and the ledger folds it silently.
     - The block is absent ONLY on a task's first planning run. Its absence then means there is no prior plan, not that no stage is done. When the ledger could not be read, the packet names the source and reason. Continue planning to repair unambiguous dependency notation in the new report, retaining every stage number and title and every completed stage body. Record the original and corrected values with their source. Do not overwrite the prior report or select an older plan. Assign no new stage number until the corrected Stage Map validates; unresolved dependency meaning remains a blocker. The preparation behavior is covered by `tests/run/test_stage_ledger_prepare.py`; preservation of author intent remains a review guideline.
@@ -110,7 +87,7 @@ roles:
   - 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 / plan item) 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 kind `a` (path/symbol mismatch) — and `f` on `P-Req-*` items. `P-Var-*` items are excepted from the kind-`a` exception: a variation-point defect takes a majority. Rollback ordering (`d`) is advisory and never blocks the gate — a rollback is executed by a human, not by okstra's workers or verifiers. 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.
-  - **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand it from the current snapshot, which no longer holds it (a `done` stage is not in this run's narrative), so that path has no answer that works. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
+  - **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand plan-item verdicts from the current snapshot, which no longer holds them (a `done` stage's plan items are `observed`, so they are never dispatched or scored in this run), so that path has no answer that works. The stage's own row is still declared in the narrative — that is the numbering rule above, not a re-verification. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
   - **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --cur-narrative ... --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
 {{INCLUDE:_coverage-critic.md}}
 - Non-goals:
@@ -178,7 +155,7 @@ roles:
       - **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step. Stage completion records the commit in the consumer ledger without creating or moving git tags.
       - **Never read an `.okstra/` artifact back out of a git object.** `.okstra/**` is gitignored and never committed — the executor aborts a commit that stages an ignored path and the verifier reports a committed `.okstra` path as a branch defect — so `git cat-file -e <tag>:.okstra/…`, `git show <tag>:.okstra/…`, and every variant of that read can never resolve, at any tag, in any stage. A later stage that needs a QA artifact reads it from the working tree or receives it through the carry sidecar / verifier result; do not design a stage contract around one being reachable from a tag. Validator S12 rejects the read.
     - **Per-stage conformance declaration (mandatory one line, in the stage section — same placement freedom as `TDD exemption:`):** the stage MUST carry exactly one of:
-      - `Conformance tests: stage-<N> — <task_root>/qa/scripts/stage-<N>.<ext> (requires=[db|io|http|external,...])` — declare that a Tier3 verification script will prove this stage's upstream requirements (brief / requirements-discovery / error-analysis / improvement-discovery → this stage's `Acceptance`) hold against **real** DB rows, real endpoints, or the real external API — NOT mocks. This phase emits the line and the `requires` set only. Do NOT write `<task_root>/qa/scripts/stage-<N>.*` and do NOT add a `runCommand` or `conformance-manifest.json` entry here — the matching `implementation` stage run creates the script file and the manifest `runCommand`. A plan that declares tests with no script file on disk is valid at this gate. The data.json `conformanceTests` value carries only the remainder after the `Conformance tests: stage-<N> — ` prefix — never the `stage-<N> — ` label itself (report assembly strips a leftover label at publication, and the implementation entry gate rejects one).
+      - `Conformance tests: stage-<N> — <task_root>/qa/scripts/stage-<N>.<ext> (requires=[db|io|http|external,...])` — declare that a Tier3 verification script will prove this stage's upstream requirements (brief / requirements-discovery / error-analysis / improvement-discovery → this stage's `Acceptance`) hold against **real** DB rows, real endpoints, or the real external API — NOT mocks. This phase emits the line and the `requires` set only. Do NOT write `<task_root>/qa/scripts/stage-<N>.*` and do NOT add a `runCommand` or `conformance-manifest.json` entry here — the matching `implementation` stage run creates the script file and the manifest `runCommand`. A plan that declares tests with no script file on disk is valid at this gate. The data.json `conformanceTests` value carries only the remainder after the `Conformance tests: stage-<N> — ` prefix — never the `stage-<N> — ` label itself (report assembly strips a leftover label at publication, and the implementation entry gate rejects one). The `requires` set MUST cover every surface the stage's own `stepwiseExecution[].plannedPaths` touch — a controller is `http`, a repository or query is `db` — because the implementation run's diff-surface check demands them after the work is done, when the approved plan can no longer change (2026-09-22, dev-10860: `requires=[io]` over a planned `catalog.controller.ts`). **Enforced at planning:** `validators/validate-run.py` `_validate_planning_conformance_declared` runs the implementation gate's surface patterns over those paths (`okstra_ctl.conformance.declared_stage_surface_gaps`) and fails the planning run on a missing surface. A stage the consumer ledger records as `done` is skipped — its body is carried, not authored, and cannot be corrected here.
       - `Conformance exemption: <reason>` — only for stages that touch no db/io/http/external surface, or where unit tests fully cover the increment. Exemption stays a planning declaration; do not move it to implementation. (If the eventual `implementation` diff actually touches one of those surfaces, `validate-run.py`'s diff-surface cross-check is BLOCKING — an exemption cannot hide a real db/io/http/external change.) **Enforced at planning:** `validators/validate-run.py` `_validate_planning_conformance_declared` runs the same surface patterns over the exempted stage's `stepwiseExecution[].plannedPaths` (`okstra_ctl.conformance.exempt_stage_surface_conflicts`) and fails the planning run — a plan that exempts a stage while planning a `*repository*` / `*.controller.*` / `*migration*` path is corrected here, where the plan is still editable, not after the implementation is done (observed 2026-09-09, dev-10784 Stage 2).
       - **External QA outcome guideline:** after satisfying the S11 declaration above, a line whose `requires` contains
         `db`, `http`, or `external` should name those capabilities here so the later `runCommand` can be written against them.

package/runtime/prompts/profiles/implementation.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "1.0",
+  "id": "implementation",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "implementer",
+      "dutyId": "implementation-executor",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "static",
+      "roleId": "verifier",
+      "dutyId": "implementation-verifier",
+      "min": 2,
+      "recommended": 2,
+      "max": 3
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    }
+  ]
+}

package/runtime/prompts/profiles/implementation.md

@@ -1,24 +1,5 @@
 # Implementation Profile
 
-```yaml
-roles:
-  - role: implementer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: implementation-executor
-  - role: verifier
-    min: 2
-    recommended: 2
-    max: 3
-    duty: implementation-verifier
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-```
-
 - Purpose: realise the approved `implementation-planning` deliverable as actual source changes, with cross-model verification, while keeping the run reversible
 - **Run-level fixed cost:** the verifier set, Phase 5.5 convergence, and the Phase 6 report-writer run exactly once per implementation run, over this run's single stage diff — never once per step.
 - **Fix run (profile carries a "Fix-Run Carry" block):** the executor's scope is the carried blocking findings plus the previous routing recommendation — it MUST NOT re-execute plan steps the previous run completed. Verifiers apply the "Fix-run incremental scope" section of `_implementation-verifier.md`; the report writer applies "Fix-run incremental authoring" in `report-writer.md`. The full validation-command re-run is NOT reduced.
@@ -53,7 +34,7 @@ roles:
   - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — canonical `<base>` for every `git diff` / `git log` in this run. Independent stages start from the common anchor (the task-key worktree HEAD, fixed once at first stage entry); dependent stages start from the predecessor done commit or the verified merged task worktree head.
   - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
   - Treat the working-tree path as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. cwd-sensitive Bash commands MUST be prefixed `cd {{EXECUTOR_WORKTREE_PATH}} && ` in the same Bash invocation (never `bash -lc "..."` wrappers — see executor sidecar for full rules).
-  - Lifecycle: kept after the run completes as this stage's evidence worktree. Later stages get their own stage worktrees. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` → drop the stage-key registry entry (`<task-key>#stage-<N>`). Exception: whole-task `final-verification` auto-merges every done stage and removes its worktree directory (`stage_integrate.integrate_stages`, `teardown=True`) — do not promise the user the worktree survives past that point. The stage BRANCH does survive: it is kept so the stack stays reviewable and `okstra handoff local-checkout --stage <N>` still has a target.
+  - Lifecycle: kept after the run completes as this stage's evidence worktree. Later stages get their own stage worktrees. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` → drop the stage-key registry entry (`<task-key>#stage-<N>`). Exception: whole-task `final-verification` removes the stage worktree directory after its verdict clears the work for release (`stage_integrate.integrate_stages`, `teardown=True`; it also merges the done stages into the task branch, unless one stage branch already contains them all) — do not promise the user the worktree survives past that point. The stage BRANCH does survive: it is kept so the stack stays reviewable and `okstra handoff local-checkout --stage <N>` still has a target.
 - Approval gate (phase-specific addendum to shared authority rule):
   - the pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination.
 - Forbidden actions — universal (any occurrence → terminal status `contract-violated`):

package/runtime/prompts/profiles/improvement-discovery.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "1.0",
+  "id": "improvement-discovery",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "analyser",
+      "dutyId": "discovery-worker",
+      "min": 3,
+      "recommended": 3,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "dynamic",
+      "roleId": "verifier",
+      "dutyId": "reverification-worker",
+      "sourceRoleIds": [
+        "analyser"
+      ],
+      "activation": "per-selected-source"
+    }
+  ]
+}

package/runtime/prompts/profiles/improvement-discovery.md

@@ -1,25 +1,5 @@
 # Improvement Discovery Profile
 
-```yaml
-roles:
-  - role: analyser
-    min: 3
-    recommended: 3
-    max: 5
-    duty: discovery-worker
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-  - role: verifier
-    min: 0
-    recommended: 0
-    max: 0
-    duty: reverification-worker
-    dynamic: true
-```
-
 - Purpose: scan a codebase scope through a fixed lens whitelist and surface ranked improvement candidates with multi-worker consensus classification
 - Required workers:
   - claude

package/runtime/prompts/profiles/project-analysis.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": "1.0",
+  "id": "project-analysis",
+  "roles": [
+    {
+      "mode": "static",
+      "roleId": "analyser",
+      "dutyId": "analysis-worker",
+      "min": 2,
+      "recommended": 3,
+      "max": 5
+    },
+    {
+      "mode": "static",
+      "roleId": "report-writer",
+      "dutyId": "report-writer",
+      "min": 1,
+      "recommended": 1,
+      "max": 1
+    },
+    {
+      "mode": "dynamic",
+      "roleId": "verifier",
+      "dutyId": "reverification-worker",
+      "sourceRoleIds": [
+        "analyser"
+      ],
+      "activation": "per-selected-source"
+    }
+  ]
+}

package/runtime/prompts/profiles/project-analysis.md

@@ -1,25 +1,5 @@
 # Project Analysis Profile
 
-```yaml
-roles:
-  - role: analyser
-    min: 2
-    recommended: 3
-    max: 5
-    duty: analysis-worker
-  - role: report-writer
-    min: 1
-    recommended: 1
-    max: 1
-    duty: report-writer
-  - role: verifier
-    min: 0
-    recommended: 0
-    max: 0
-    duty: reverification-worker
-    dynamic: true
-```
-
 - Purpose: map a bounded project area so later work can navigate components, dependencies, entry points, repositories, and external integrations without changing the source
 - Required workers:
   - claude

package/runtime/prompts/profiles/release-handoff.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": "1.0",
+  "id": "release-handoff",
+  "roles": []
+}