okstra 0.130.4 → 0.131.1

package/README.md

@@ -172,7 +172,6 @@ Use these slash commands inside a Claude Code session:
 | `/okstra-usage` | Show the current project's recent run coverage, raw and billable-equivalent tokens, known USD cost, CPU time, and wall-clock time grouped by task type (default: last 30 days) |
 | `/okstra-schedule-gen` | Generate a work schedule for an entire task group. Stages are sourced from each non-done task's `implementation-planning` final-report **Stage Map**; you pick which stages to include, and the final file is written only after an independent verifier subagent confirms the draft covers exactly the selected stages |
 | `/okstra-container-build` | Deploy a verified task's code as a local Docker Compose group and monitor per-container logs (subcommands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
-| `/okstra-graphify` | Build and query a knowledge graph over the project's own `.okstra/` memory—final reports, `decisions/*.md`, and `glossary.md`—with scope restricted to `.okstra/` and output under `.okstra/graph/` (subcommands: `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `/okstra-manager` | Coordinate cross-project okstra tasks through manager-owned plans, assignments, one-way project sync snapshots, status, and child launch context packets |
 | `/okstra-pr-gen` | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (subcommands: `template` / `branches` / `gen`). Global skill—needs a Git repo, not a registered okstra project |
 | `/okstra-user-response` | Answer a task's open clarification questions in-session and write the response sidecar. Each answer is dispositioned as `answer` or `reframe`; a `reframe` is carried into the next run as a re-scoped brief |

package/docs/architecture.md

@@ -150,9 +150,9 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - Runtime selection and worker-provider assignment remain independent. Milestone 1 keeps `claude-execution-prompt.md`, existing manifest role labels, model defaults, and worker rosters for compatibility; provider registry and front-door separation are later milestones.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
 - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — in-session entry point that **starts an okstra task in the current Claude session**. Calls `prepare_task_bundle` directly.
-- Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-graphify/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, and `skills/okstra-user-response/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, `.okstra` knowledge graphs, PR description generation, and clarification-response submission. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
+- Twelve skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, and `skills/okstra-user-response/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, PR description generation, and clarification-response submission. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
 - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
-- Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-graphify`, `okstra-pr-gen`, `okstra-user-response`).
+- Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the twelve user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-pr-gen`, `okstra-user-response`).
 - Installation location: `~/.claude/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`.
 - Release procedure: [`../../RELEASING.md`](../RELEASING.md) — npm publish flow and release-please / manual fallback.
 

package/docs/cli.md

@@ -668,7 +668,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra codex-run <args…>` | Codex lead-adapter dry-run entry point. Accepts the same arguments as `render-bundle` but owns `--render-only --lead-runtime codex`. It prepares the task bundle and prints the prompt for the Codex lead without dispatching workers |
 | `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers codex,antigravity,report-writer]` | Read a run manifest prepared by `codex-run` and execute the Codex-side supported worker subset. Without `--workers`, unsupported roster members such as `claude` are skipped; explicitly requesting one fails. The report writer requires opt-in with `--enable-codex-report-writer --report-writer-codex-model <model>`. On success, it automatically performs token-usage substitution, HTML view rendering, follow-up task-stub generation, and run validation |
 | `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down tmux-pane workers. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
-| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step; every step is idempotent so re-running after a fix is safe. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) the Codex lead adapter runs automatically after its report-writer completes, so a Claude-led and a Codex-led run finalize identically. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the four steps individually |
+| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step, then prints a per-step `[ok]` / `[FAIL]` / `[skip]` summary on stderr so the outcome is legible without parsing the JSON payload. Every step is idempotent, so re-running after a fix is safe — but `--only <step>` (repeatable) reruns just the named steps in contractual order, which matters because `validate-run` is the step that usually fails and retrying it otherwise repeats the three steps before it at full token and wall-clock cost. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) the Codex lead adapter runs automatically after its report-writer completes, so a Claude-led and a Codex-led run finalize identically. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the four steps individually |
 | `okstra render-views <final-report.md>` | The Phase 7 `render-views` step, runnable on its own: deterministically create a human-facing self-contained sibling `*.html` view from one final-report Markdown file after token substitution. The source Markdown is unchanged. The Node delegation wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies form-control placement, absence of external URLs, stale source digests, and Response ID parity |
 | `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
 | `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, and improvement-discovery. Downstream phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |

package/docs/for-ai/README.md

@@ -27,7 +27,6 @@ This directory is a compressed manual for an AI to quickly select and precisely
 | Store or search conversations/decisions/preferences/requirements in the global Memory Book | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
 | Manage the implementation-task worktree-based docker compose user-test environment | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
 | Answer the unresolved clarification questions an okstra run left behind in-session and record the approval gate | `okstra-user-response` | [`skills/okstra-user-response.md`](skills/okstra-user-response.md) |
-| Build and query a knowledge graph over the project's own `.okstra` memory (reports, decision records, glossary) | `okstra-graphify` | [`skills/okstra-graphify.md`](skills/okstra-graphify.md) |
 | Register a PR body template or generate a PR description from a branch diff (global, git repository) | `okstra-pr-gen` | [`skills/okstra-pr-gen.md`](skills/okstra-pr-gen.md) |
 
 ## Shared Execution Rules
@@ -62,5 +61,4 @@ The public skills listed in this AI manual are the following 13:
 - `okstra-schedule-gen`
 - `okstra-container-build`
 - `okstra-user-response`
-- `okstra-graphify`
 - `okstra-pr-gen`

package/docs/for-ai/skills/okstra-run.md

@@ -170,7 +170,18 @@ render-bundle calls `prepare_task_bundle()` in render-only mode to prepare the m
 
 ## conformance waiver
 
-Offer a waiver to the user only when Tier 3 conformance is genuinely impossible in the environment during implementation. A waiver requires user approval and a verbatim reason. Neither the AI lead nor a worker creates a self-exemption.
+Classify the entry before offering a waiver. If `requires` contains `db`,
+`http`, or `external`, do not offer a waiver: Okstra still attempts the command,
+but any non-PASS or unavailable outcome is an external advisory with a
+user-owned rerun method. If `requires=[]`, fail closed as a declaration or
+contract defect and do not offer a waiver. Offer the waiver only when
+`requires=[io]` and that blocking local conformance command is genuinely
+impossible to run in the environment. A waiver requires user approval and a
+verbatim reason. Neither the AI lead nor a worker creates a self-exemption.
+The resulting blocking/advisory policy is enforced by
+`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
+`validators/validate-run.py::_validate_conformance`; the picker restriction is
+defined by `skills/okstra-run/SKILL.md` Step 5.1.
 
 When chosen, add it to `render-bundle` only.
 
@@ -232,7 +243,7 @@ For a single-element chain, the end of Step 6 is the end of the run. Step 7 belo
 
 When `task-type == implementation` and the render-args `chain-stages` CSV has 2 or more elements, the current session acts as the orchestrator and runs the stages as an unattended chain in dependency order. Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`. For each stage `N` in the queue, in order:
 
-1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
+1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
 2. As in Step 6, become Claude lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
 3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.

package/docs/for-ai/skills/okstra-setup.md

@@ -99,7 +99,10 @@ Optional settings:
 
 - `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
 - `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
-- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns the Tier 3 conformance script uses.
+- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns
+  Okstra uses to attempt Tier 3 automatically; real DB/API verification remains
+  a user-owned advisory when the environment is unavailable or the result is
+  non-PASS.
 - PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
 - final report language: `okstra config set report-language <en|ko|auto> --scope project`
 

package/docs/project-structure-overview.md

@@ -51,7 +51,7 @@ okstra/
 │   ├── okstra_ctl/                  orchestration core
 │   ├── okstra_project/              project root / project.json resolver
 │   ├── okstra_token_usage/          token usage + cost accounting
-│   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe + graphify / networkx (okstra-graphify skill)
+│   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe (final-report rendering)
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
 ├── skills/                          Claude Code skills (13); `_fragments/` holds shared marker blocks
@@ -249,6 +249,7 @@ Important modules:
 | `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
 | `md_table.py` | Markdown pipe-table escape/split SSOT — the `mdcell` filter (`escape_pipes`) and the `\|`-aware `split_pipe_row`; shared by the renderer, HTML view, and validators |
 | `qa_commands.py` | QA command deny-list validation for plans |
+| `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance` |
 | `pr_template.py` | PR body template resolution for release-handoff |
 | `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report data.json → Markdown → Report View Model → self-contained HTML pipeline |
 | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
@@ -294,10 +295,11 @@ Important modules:
 | `convergence_store.py`, `convergence_migration.py` | atomic JSON persistence plus legacy/new-engine seed decisions; valid terminal finals are reused, while invalid state requires byte-preserving archival before restart |
 | `convergence.py` | `okstra convergence` internal CLI orchestration for `seed`, `plan-round`, `apply-round`, `apply-critic-gaps`, `finalize`, `validate`, and `example`; it composes the reducer, store, and migration policy without duplicating their decisions |
 | `plan_items.py`, `plan_items_cli.py` | deterministic extraction of the report-writer data.json `P-*` plan-item queue plus the `okstra plan-items extract` / `validate` adapter |
+| `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
+| `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
 | `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
 | `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar written by `okstra-wrapper-status.py` (the heartbeat writer) |
 | `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
-| `graphify_cmd.py` | scope wrapper for the okstra-graphify skill — `resolve_scope` + `assemble` + `okstra graphify` subcommand dispatch. Forces the corpus to `.okstra` and outputs to `.okstra/graph/` |
 
 > `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.
 
@@ -381,7 +383,6 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 | `okstra-usage` | yes | Read-only project usage snapshot — aggregate recent run coverage, tokens, known cost, CPU, and wall-clock time by task type (default: 30 days) |
 | `okstra-schedule-gen` | yes | Generate task-group schedule |
 | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
-| `okstra-graphify` | yes | Knowledge graph over the project's own `.okstra/` memory — final reports, `decisions/*.md`, `glossary.md`; scope restricted to `.okstra/`, output under `.okstra/graph/` (sub-commands `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |
 | `okstra-manager` | yes | Coordinate cross-project okstra tasks through manager-owned plans, assignments, sync snapshots, status, and child launch context packets |
 | `okstra-setup` | yes | Install/check runtime and register project |
@@ -586,4 +587,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-07-21 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mjs`, `src/lib/skill-catalog.mjs`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-07-22 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mjs`, `src/lib/skill-catalog.mjs`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/docs/task-process/implementation-planning.md

@@ -99,6 +99,19 @@ If there is no detected surface and no manual test input that changes the interf
 
 `manual-user-test` does not have to fully fix the execution method at planning time. If there is a safe default procedure even before seeing the actual diff, proceed with `provisional` and `ifStillOpen: follow-up`, and the implementation report finally owns the `implementation.manualUserTest` aligned to the actual change. Conversely, use `blocked` only when the stage cannot be safely completed without an acceptance method that only the user can provide.
 
+Tier 3 entries keep the following ownership and gate boundary. Planning records
+the executable check and prerequisites, but a live external verification stays
+with the user when Okstra cannot prove it in-session.
+
+| Entry policy | PASS | FAIL / MISSING / unavailable |
+|---|---|---|
+| `requires` contains `db`, `http`, or `external` | Evidence recorded | Advisory; user rerun method recorded; run continues |
+| `requires=[]` or `requires=[io]` | Evidence recorded | Blocking |
+
+These outcomes are enforced by
+`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
+`validators/validate-run.py::_validate_conformance`.
+
 Phase 7 deterministically creates a `design-prep-requests/` document filled with an AI proposal for each `provisional`/`blocked` item. When the user or wizard approves, edits, rejects, or holds the draft, only after confirmation does it append a new revision sidecar under `design-prep-inputs/`. This response does not modify the approved planning report.
 
 Plan approval and design-preparation status are independent gates. If plan-body verification passed, the plan itself can be approved even when there is a `blocked` item. The actual `implementation` preflight resolves only the items of the selected stage, and unrelated stages keep proceeding.

package/docs/task-process/implementation.md

@@ -86,6 +86,18 @@ Right after stage selection, before worktree provisioning and appending `status:
 
 `manual-user-test` input uses the same flexible status. The planning draft is a seed for implementation to concretize the verification method against the actual diff, and the SSOT of the final execution method is the implementation report's `implementation.manualUserTest`. final-verification does not directly execute the planning sidecar.
 
+Tier 3 conformance uses the same ownership boundary during execution and
+verification.
+
+| Entry policy | PASS | FAIL / MISSING / unavailable |
+|---|---|---|
+| `requires` contains `db`, `http`, or `external` | Evidence recorded | Advisory; user rerun method recorded; run continues |
+| `requires=[]` or `requires=[io]` | Evidence recorded | Blocking |
+
+These outcomes are enforced by
+`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
+`validators/validate-run.py::_validate_conformance`.
+
 ## 4. executor and verifier
 
 ```mermaid
@@ -99,7 +111,10 @@ flowchart TD
     CV --> QA[Independent QA rerun]
     XV --> QA
     Gem --> QA
-    QA --> Verdict[PASS / CONCERNS / FAIL]
+    QA --> External{External Tier 3<br/>non-PASS?}
+    External -->|yes| Advisory[ADVISORY<br/>user-owned rerun]
+    External -->|no| Verdict[PASS / CONCERNS / FAIL]
+    Advisory --> Report
     Verdict --> Report[Final report preserves dissent]
 ```
 
@@ -162,7 +177,7 @@ flowchart TD
     Impl[implementation] --> Allowed[local edit/write/build/test/git add/git commit]
     Impl -. forbidden .-> Push[git push]
     Impl -. forbidden .-> Publish[publish/release/deploy]
-    Impl -. forbidden .-> RealDB[real DB migration or non-local datastore write]
+    Impl -. forbidden .-> RealDB[source migration or<br/>shared/staging/prod datastore write]
     Impl -. forbidden .-> VerifierWrite[verifier edit/write]
     Impl -. forbidden .-> Scope[silent scope expansion]
     Impl -. forbidden .-> Acceptance[declaring final acceptance]

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.130.4",
-  "builtAt": "2026-07-21T15:17:32.560Z",
+  "package": "0.131.1",
+  "builtAt": "2026-07-22T05:33:21.666Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -93,6 +93,13 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` and `verdictCard.direction` MUST byte-match `finalVerdict.verdictToken` / `.direction`; `validators/validate-run.py` diffs both and fails the run on divergence. `verdictCard.nextStep` names the same action as `finalVerdict.nextStep` and `recommendedNextSteps[0].text` but is written as the actionable command the reader runs (e.g. `/okstra-run task-key=… task-type=release-handoff`) where the other two are prose — it is deliberately not a byte copy. Duplicating the compared values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
 - **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
+- **External QA advisory.** A Tier 3 entry requiring `db`, `http`, or
+  `external` may be non-PASS without changing approval or final verdict. Render
+  its command log row as `tier: 3`, `status: advisory`, keep the observed and
+  expected result in `statusReason`, add a `Residual Risk` row owned by `user`,
+  and add the exact rerun command to `recommendedNextSteps`. Never turn this
+  advisory alone into a clarification, Acceptance Blocker, conditional
+  acceptance condition, or blocked routing.
 - **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 Additional Material Request`, no `5.2 User Confirmation Questions` — clarifications go under the unified `clarificationItems[]` array.
 - **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).

package/runtime/bin/lib/okstra/usage.sh

@@ -58,10 +58,10 @@ optional arguments:
                        \`implementation-option:\` line with <name>. When omitted, the implementation run
                        falls back to the plan's \`Recommended Option\`.
   --qa-waiver <stageKey>:<reason>
-                       Stage conformance gate 우회(사용자 확인형). Only meaningful with
-                       --task-type=implementation. prepare-time 에 task-level conformance 매니페스트의
-                       해당 stageKey entry.waiver 를 채운다(reason 은 사용자 지시 원문 그대로 기록).
-                       lead/worker 가 스스로 면제할 수 없으며 사용자가 명시할 때만 사용한다.
+                       User-recorded waiver for a blocking local io conformance gate.
+                       Only meaningful with --task-type=implementation; prepare records
+                       the verbatim reason in the matching manifest entry.
+                       External DB/HTTP/service QA is advisory and normally needs no waiver.
   --no-plan-verification
                        Disable the Phase 6 plan-body verification round that runs after the report-writer
                        authors the implementation-planning draft. Default: enabled. Only meaningful with

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -329,7 +329,7 @@ If only one worker result is usable: reduced-confidence synthesis. If evidence i
 
 After the Report writer worker draft is reviewed (or after the lead-authored fallback completes), **if** `task_type == "implementation-planning"` **and** `task-manifest.json` `convergence.planBodyVerification.enabled == true` (default), the lead MUST run one additional verification round on the consolidated plan body before declaring Phase 6 complete and entering Phase 7.
 
-This is a Phase 6 sub-step — it does NOT introduce a new top-level lifecycle phase; the lead operating-phase model (Phase 1 Intake → Phase 7 Persist, labels in the "Quick Reference" table above as the single source of truth) is preserved. `okstra-inspect status` exposes it as a `planVerification` sub-field of the implementation-planning phase, not a separate lifecycle phase identifier.
+This is a Phase 6 sub-step — it does NOT introduce a new top-level lifecycle phase; the lead operating-phase model (Phase 1 Intake → Phase 7 Persist, labels in the "Quick Reference" table above as the single source of truth) is preserved. The round's outcome is read from the final report's `### 5.5.9 Plan Body Verification` section and `implementationPlanning.planBodyVerification` in its data.json — it is not a separate lifecycle phase identifier.
 
 **REQUIRED RESOURCE:** Read [plan-body-verification](./plan-body-verification.md) for the round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` / `P-Req-*` / `P-Prep-*`), verdict semantics (`AGREE` / `DISAGREE(a-f)` / `SUPPLEMENT`), classification rules, gate-result resolution, and the state-file schema at `runs/<task-type>/state/plan-body-verification.json`.
 
@@ -354,7 +354,7 @@ Lead's responsibilities in this sub-step (in order):
 4. Write `runs/<task-type>/state/plan-body-verification.json` (schema in the plan-body-verification contract).
 5. Populate `### 5.5.9 Plan Body Verification` in the final-report file (template at `templates/reports/final-report.template.md` §5.5.9 — Round count, Gate result, per-item verdict tables grouped under each plan item's `subject`, Dissent log).
 6. For every `majority-disagree` plan item, append a row to `## 1. Clarification Items` with `Blocks=approval` and the 1:1 ID match in the verdict table's `Classification` column (`majority-disagree → C-<N>`). Do NOT create a parallel `Open Questions` block — see `prompts/profiles/implementation-planning.md` self-review step 6 for the orphan-on-either-side contract.
-7. Conditionally render the top-of-report `- [ ] Approved` marker line: present iff gate ∈ {passed, passed-with-dissent}, absent iff gate ∈ {blocked-by-disagreement, aborted-non-result}. `validators/validate-run.py` `validate_phase_boundary` enforces this correspondence. Manually flipping a blocked gate to passing in order to render the marker is a contract violation.
+7. Publish the YAML frontmatter `approved:` field as `false`. There is no in-body `- [ ] Approved` marker line — approval lives only in the frontmatter (see [plan-body-verification](./plan-body-verification.md) §"Round protocol" step 9). The user may flip it to `true` only when the gate is `passed` or `passed-with-dissent`. **Enforced:** `validators/validate-run.py` `validate_phase_boundary` fails a report shipping `approved: true` under `blocked-by-disagreement` / `aborted-non-result`, and run-prep (`scripts/okstra_ctl/run.py` `_validate_approved_plan`) fail-closes the same case. Manually flipping a blocked gate to passing is a contract violation.
 
 If `convergence.planBodyVerification.enabled == false` (set by `--no-plan-verification` or by `okstra config set plan-verification off`), the entire sub-step is skipped and the top-of-report Approval marker is rendered unconditionally (legacy behaviour). This opt-out is intended for fast iteration only and is not recommended for handoff-ready plans.
 

package/runtime/prompts/lead/plan-body-verification.md

@@ -138,6 +138,8 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
 1. Lead runs `okstra plan-items extract --data <data.json> --output <state>/plan-items-....json`, places the persisted `items[]` verbatim in every verifier prompt with the compact `subject` and lossless `payload`, then runs `okstra plan-items validate --data <data.json> --items <state>/plan-items-....json`. Dispatch only after that exact-match validation succeeds.
 2. For each analyser worker in the roster (`claude`, `codex`, and `antigravity` if opted in), lead constructs a reverify prompt using the template in §"Plan-body reverify prompt" below.
 3. Dispatch uses the same wrapper infrastructure as finding convergence. The `--role-slug` is `<role>-plan-verify-r<N>`. Result file path: `runs/<task-type>/worker-results/<role-slug>-plan-verify-r<N>-implementation-planning-<seq>.md`.
+   **Verdict provenance (BLOCKING).** Every verdict recorded in `planItems[].verdicts[]` MUST trace back to a dispatch that actually returned a result file at the path above. The whole gate — classification, self-fix eligibility, promotion, `gateBlockedBy` — is computed from these votes, so an unbacked vote lets the round be skipped while the gate still reads `passed`. **Enforced:** `validators/validate-run.py` `_validate_plan_body_verdict_provenance` fails any `verdicts[].worker` with no matching `<worker>-plan-verify-r<N>-<task-type>-<seq>.md` result file. Recording a `verification-error` for a dispatch that produced no result is the correct way to represent a failed worker — inventing an `AGREE` is a contract violation.
+
 4. After all dispatches return, lead aggregates verdicts per `P-*` item across workers and classifies each:
    - `full-consensus` — all participating analysers `AGREE` (SUPPLEMENT counts as agree on the item itself).
    - `partial-consensus` — majority `AGREE`, dissenting `DISAGREE` recorded.
@@ -150,13 +152,20 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
    - all dispatches non-result → `aborted-non-result`
    - any `partial-consensus` / `dissent-isolated` / `needs-reverify` present, no `majority-disagree` → `passed-with-dissent`
    - all items `full-consensus` → `passed`
+
+   **Record the cause, not just the outcome.** The gate value names the outcome; `planBodyVerification.gateBlockedBy` (array) names every input that blocked it — `majority-disagree`, `coverage-gap`, `non-result`. Two independent inputs can block: a `majority-disagree` plan item, and a Requirement Coverage `gap` / `blocked C-NNN` row (`prompts/profiles/implementation-planning.md` §"Requirement Coverage"). A coverage-only block still renders as `blocked-by-disagreement` because that is the only blocking non-abort value, so **without `gateBlockedBy` the report asserts a worker disagreement that never happened** and the reader hunts for a dissent that does not exist. Leave the array empty for a passing gate. **Enforced:** `validators/validate-run.py` `_validate_gate_blocked_by` cross-checks the declared causes against the recorded verdicts and coverage rows, and fails a passing gate that has a blocking coverage row — the coverage rule was prose-only before.
+
+   **A coverage row citing this run's own `C-NNN` is not an independent blocker.** When a coverage row's `blocked C-NNN` points at a clarification that step 8 below promoted from a `majority-disagree` item in *this same run*, that blocker is already counted once as the plan item. Counting it again as a coverage gap makes the run block on a clarification it just authored, and the row carries into the next run as a fresh blocker — the Requirement Coverage ↔ Clarification cycle. Such rows are excluded from `coverage-gap`. **Enforced:** `validators/validate-run.py` `_independent_coverage_blockers`.
 6. Lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below) and populates `### 5.5.9 Plan Body Verification` in the final report's data.json (`implementationPlanning.planBodyVerification`, schema `schemas/final-report-v1.0.schema.json`; template at `templates/reports/final-report.template.md`). The §5.5.9 body is **grouped by plan item**: `planItems[]`, each carrying its `id`, its plain-language `subject` (rendered as the item heading), an optional `sourceSection`, an optional `clarificationId` (the `C-<N>` this item blocks on when `majority-disagree`), and a `verdicts[]` list (`worker / verdict / breakageKind / note`) — one verdict row per worker under that item. The renderer prints three fixed legends (gate values, verdict tokens, breakage kinds a–f) so the reader can decode every cell without opening this spec. The older flat `#### Verdict details` table (`Plan item / Worker / …`, one row per plan-item × worker pair) is superseded by the grouped layout — it hid *what* each vote was about behind a bare `P-*` ID; the subject heading is the fix. The validator's `Plan Body Verification` + `Gate result:` substring checks still gate this section.
 7. **Self-fix loop (up to `selfFixMaxRounds`, targeting planner-fixable defects).** After aggregation, while at least one `majority-disagree` item has a majority of its `DISAGREE` verdicts at `fixability == planner-fixable`, lead runs self-fix rounds **before** promoting anything to the user:
-   - lead instructs report-writer to rewrite only those planner-fixable items for correction (NOT a full draft regeneration — patch only the plan section each `P-*` points to; procedure in [report-writer](./report-writer.md) §"Self-fix rewrite").
+   - **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect — one constant declared twice, one responsibility given two owners — and the coverage rows that cite them fail as a consequence, not independently. Lead MUST partition this round's targets into cause groups and instruct each group as **"remove this cause"**, naming the derivatives it accounts for. **Handing report-writer a bare item list is forbidden**: patched one at a time, each correction leaves the sibling sections still asserting the old value, so the next round re-finds the same family and the budget drains without converging. Record the partition in `planBodyVerification.selfFixGroups[]` (`round`, `causeSummary`, `itemIds`). One group per item is a legitimate outcome only when the items genuinely share no cause — recorded that way, it is a visible diagnosis rather than a skipped one. **Enforced:** `validators/validate-run.py` `_validate_self_fix_grouping` requires the partition, ties `selfFixRoundsApplied` to the highest recorded round, and fails any corrected item that belongs to no group.
+   - lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration; procedure in [report-writer](./report-writer.md) §"Self-fix rewrite").
    - missing or weak `P-Prep-*` contracts are repaired by adding kind-specific inline detail or an AI-prepared PREP item with a concrete proposal. Facts that require user or external authority remain `blocked` and keep their request material; never invent those facts during self-fix.
-   - lead re-runs plan-body verification (focused on the corrected items + adjacent items the rewrite touched, plus any `needs-reverify` items whose peer failed to vote last round). After re-verification, overwrite `planItems[].verdicts` with the new verdicts.
+   - **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `validators/validate-run.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
+   - lead re-runs plan-body verification (focused on the corrected items + adjacent items the rewrite touched, plus any `needs-reverify` items whose peer failed to vote last round). After re-verification, overwrite `planItems[].verdicts` with the new verdicts. **The round's verdicts MUST be transcribed into `planBodyVerification.planItems[].verdicts` in the final report's data.json before the gate is declared** — the gate is re-derived from that table, so declaring a gate over an empty one leaves it unauditable. **Enforced:** `_validate_round_recorded_verdicts`.
    - for an item whose `majority-disagree` was resolved by self-fix, record `self-fixed in round <N>: <what was fixed>` in `planItems[].selfFixNote`. A resolved item does not create a clarification.
-   - **Loop termination.** Record the round count in `planBodyVerification.selfFixRoundsApplied` and why the loop stopped in `planBodyVerification.selfFixStopReason`:
+   - **Round completion.** A round is complete only after the renderer has run on the corrected data.json and lead has reconciled instructed groups against applied corrections — every `itemIds` entry either carries a `selfFixNote` or is still recorded as broken. A round that was instructed but never rendered has not happened, and counting it inflates the budget that gates promotion.
+   - **Loop termination.** Lead — not the report-writer worker — records the round count in `planBodyVerification.selfFixRoundsApplied` at each round's end, and why the loop stopped in `planBodyVerification.selfFixStopReason`. The count must equal the highest `round` in `selfFixGroups[]`, so it is derivable from recorded work rather than self-reported:
      - `all-resolved` — no planner-fixable `majority-disagree` item remains. Exit.
      - `no-progress` — the round resolved **zero** planner-fixable items relative to the previous round. Exit even with budget left: the same rewrite would repeat. Newly *introduced* defects count against progress, so a rewrite that trades one defect for another stops the loop rather than churning.
      - `max-rounds-reached` — `selfFixRoundsApplied == selfFixMaxRounds`. Exit.
@@ -169,11 +178,22 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
    - `Kind` chosen per the standard policy (usually `decision` for option-level conflicts, `data-point` for path/symbol mismatches)
    - `Blocks=approval`
    - the item's `planItems[].clarificationId` set to that `C-<N>` (1:1 link). `validators/validate-run.py` `_validate_plan_body_clarification_matching` recomputes each item's class and fails when a majority-disagree item's `clarificationId` is missing, dangling, or points at a non-`approval` row.
-   - a `planner-fixable` item that survives the self-fix loop is still promoted, but its `Statement` MUST state "planner self-fix attempted but unresolved" and name the stop reason. `validators/validate-run.py` `_validate_self_fix_before_clarification` fails when a planner-fixable majority item is promoted while the budget is not exhausted — it requires `selfFixRoundsApplied >= 1` **and** `selfFixStopReason` in `{no-progress, max-rounds-reached}`, so neither `all-resolved` nor `not-attempted` can excuse a promotion.
+   - **A `planner-fixable` item that survives the self-fix loop is NOT promoted to the user by default.** A defect the *planner* could have fixed but did not is still a planner defect; promoting it asks the user to proofread the plan. Once the self-fix budget is exhausted, such an item is recorded as a Working Assumption in `## 5. Missing Information and Risks` — naming the defect, the assumption the implementation will proceed under, and the stop reason — and it stops blocking the gate (it folds into `passed-with-dissent`). It gets **no** `Blocks=approval` row and **no** `clarificationId`.
+   - **Exception — correctness-critical defects still block.** An item whose `DISAGREE` kinds include `a` (cited path/symbol mismatch) or `d` (rollback violates commit/dependency order), or `f` on a `P-Req-*` item, is promoted per the rules above regardless of `fixability`. These are the defects that make `implementation` produce wrong or unsafe code; `b`/`c`/`e` degrade the plan document, not the resulting code. **Enforced:** `validators/validate-run.py` `_is_dissent_downgraded` (fold) + `_is_correctness_critical` (the exception).
+   - When a correctness-critical `planner-fixable` item is promoted, its `Statement` MUST state "planner self-fix attempted but unresolved" and name the stop reason. `validators/validate-run.py` `_validate_self_fix_before_clarification` fails when a planner-fixable majority item is promoted while the budget is not exhausted — it requires `selfFixRoundsApplied >= 1` **and** `selfFixStopReason` in `{no-progress, max-rounds-reached}`, so neither `all-resolved` nor `not-attempted` can excuse a promotion.
 9. Approval lives in the report's YAML frontmatter `approved:` field — there is no in-body marker line. The user may flip it to `true` only when the Gate result is `passed` or `passed-with-dissent`. **Enforced:** run-prep (`scripts/okstra_ctl/run.py` `_validate_approved_plan`) fail-closes an `approved: true` plan whose data.json carries a blocking `gateResult` or an open/answered `Blocks: approval` clarification row, and `validators/validate-run.py` `_validate_plan_body_gate_recompute` rejects a declared `gateResult` healthier than the recorded votes.
 
 ## `plan-body-verification-<task-type>-<seq>.json` schema
 
+**Which file is authoritative for what.** These two representations are *not* required to agree, and a lead that tries to make them match is doing unnecessary work:
+
+| | records | overwritten by a self-fix round? |
+|---|---|---|
+| `state/plan-body-verification-<task-type>-<seq>.json` | the round-by-round history, including rounds later superseded | no — it is the only place earlier rounds survive |
+| `data.json` `implementationPlanning.planBodyVerification` | the **final** state after the self-fix loop | yes — each re-verification replaces `planItems[].verdicts` |
+
+**The gate is computed from data.json.** The state file is the audit trail: after a successful self-fix loop the two legitimately differ (the sidecar shows what the first round blocked on, data.json shows the resolved result), and that difference is the record of the fix working. **Enforced:** `validators/validate-run.py` `_validate_plan_body_state_file` requires the file to exist with `schemaVersion` / `gateResult` / `planItems` once a round has run, and deliberately does not compare its `gateResult` to data.json.
+
 ```json
 {
   "schemaVersion": "1.0",
@@ -183,6 +203,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
   "gating": true,
   "verificationMode": "lightweight",
   "gateResult": "passed | passed-with-dissent | blocked-by-disagreement | aborted-non-result",
+  "gateBlockedBy": ["majority-disagree | coverage-gap | non-result"],
   "selfFixRoundsApplied": 0,
   "selfFixStopReason": "not-attempted | all-resolved | no-progress | max-rounds-reached",
   "planItems": [
@@ -333,4 +354,4 @@ Mirrors finding convergence ([convergence](./convergence.md) §"Worker failure h
 
 - A dispatch that returns terminal non-result MUST NOT be aggregated as `DISAGREE`.
 - If at least one dispatch was issued AND **all** plan-body dispatches return non-result, the Gate result is `aborted-non-result`. Record one `contract-violation` event per non-result dispatch.
-- When the gate is `aborted-non-result`, report-writer MUST keep the frontmatter `approved: false` (publishing `approved: true` under this gate result is a validator failure). A single row is added to `## 1. Clarification Items` with `Statement="plan-body verification could not run — all workers returned non-result"`, `Kind=decision`, `Blocks=approval`, allowing the user to either retry the phase or override by manually flipping the frontmatter to `approved: true` (or running `--approve` on the resume command).
+- When the gate is `aborted-non-result`, report-writer MUST keep the frontmatter `approved: false` (publishing `approved: true` under this gate result is a validator failure). A single row is added to `## 1. Clarification Items` with `Statement="plan-body verification could not run — all workers returned non-result"`, `Kind=decision`, `Blocks=approval`, allowing the user to either retry the phase or override by manually flipping the frontmatter to `approved: true` (or running `--approve` on the resume command). The row MUST name which dispatches returned no result and what re-running them requires. **Enforced:** `validators/validate-run.py` `_validate_aborted_gate_has_clarification` — `_validate_plan_body_clarification_matching` cannot cover this case because it walks `majority-disagree` items and an aborted round produces none, which is exactly how an aborted run used to reach the user with no stated blocker and stall.

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

@@ -232,7 +232,7 @@ The final-report template `templates/reports/final-report.template.md` Section 5
 
 ### Self-fix rewrite (plan-body self-fix round)
 
-When lead instructs a self-fix round (passing the target `P-*` list + the reason for each defect), correct **only the plan section** each designated planner-fixable item points to — do NOT rewrite the entire draft:
+Lead instructs a self-fix round as **cause groups**, not a flat `P-*` list (`plan-body-verification.md` §"Round protocol" step 7). Treat each group's `causeSummary` as the unit of work: remove that cause once, then confirm every derivative item it names is settled by that single correction. Correct the plan sections the group's items point to — do NOT rewrite the entire draft:
 
 - abbreviated path → replace with the full relative path from `<PROJECT_ROOT>` (File Structure / Stepwise `files`).
 - prose command → make it concrete as an executable command sequence including the working directory, arguments, and task-type.
@@ -240,7 +240,11 @@ When lead instructs a self-fix round (passing the target `P-*` list + the reason
 - requirement-coverage mapping error → remap to a real option/stage/step or XP row.
 - missing/weak design-prep contract → fix with kind-specific inline detail or an AI-prepared PREP item carrying a concrete `aiProposal`. Do NOT invent facts requiring user/external authority — keep them `blocked` + request material.
 
-After correcting, leave `self-fixed in round <N>: <what was fixed>` in that `planItems[].selfFixNote` and set `planBodyVerification.selfFixRoundsApplied` to the number of rounds run so far. `needs-user-input` items are NEVER a correction target — they are promoted to clarification as-is.
+**Carry the correction to its contradictions (BLOCKING).** "Only the section the item points to" bounds *which defect you fix*, not *how far the fix reaches*. When a correction changes a constant, an owner, a path, or a disposition, every other statement in the plan asserting the old value is now false — find and rewrite those too, in whatever section they sit.
+
+**Enumerate before you edit.** Patching at the positions the lead named is what makes a round trade one defect for another: the correction lands, its siblings keep asserting the old value, and the next round finds a *new* contradiction the fix itself created. So for each cause group, first list every place the plan mentions that decision — grep the constant, the symbol, the path, the requirement ID across the whole plan body including rejected options, per-stage `Test case (…)` lines, `Acceptance`, `exitContract`, `stageValidation`, and the Requirement Coverage row — then reconcile each hit against the new decision and only then write. Record the enumeration in the group's supersession entry so the next round can see what was considered in scope. A patch that leaves its own contradictions standing produces the same defect class in the next round, so the loop spends its budget re-finding what the previous round created. Record each retirement in `implementationPlanning.supersessionLedger[]` exactly as the answer-carry-in rule requires (`_common-contract.md` §"Supersession").
+
+After correcting, leave `self-fixed in round <N>: <what was fixed>` in that `planItems[].selfFixNote`. Do NOT set `planBodyVerification.selfFixRoundsApplied` — the lead owns that count and records it at the round's end, so promotion eligibility does not hang on a worker's self-report. `needs-user-input` items are NEVER a correction target — they are promoted to clarification as-is.
 
 Lead may instruct several rounds (bounded by `selfFixMaxRounds`, see [plan-body-verification](./plan-body-verification.md) §"Round protocol" step 7). Each round targets only the items still broken, so a round that fixes nothing new ends the loop — correcting an item by breaking a sibling counts as no progress, not progress.
 

package/runtime/prompts/profiles/_common-contract.md

@@ -69,11 +69,12 @@ profile document.
   - if a phase requires a recommended answer, alternatives, or an evidence-check note, encode it inside the existing 4-column schema: put evidence notes in `Statement` as `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>`, and put recommendations/options in `Expected form` as `Recommended: (a) <answer> — <rationale>; Alternatives: (b) <option> (c) <option>`. The recommended answer is always the first option and MUST carry the `(a)` label; alternatives continue the same letter sequence from `(b)` (a lone alternative is `(b) <option>`, never restart at `(a)`), so the full option set reads `(a) (b) (c) …` in order and renders each as its own selectable option. Do **not** append a pick-one answer-space summary such as `(pick 1 of A / B)` or `(pick N of …)` to `<options>` — the rendered `<select>` already enforces single choice, and that annotation leaks verbatim into an option label. Do not add `Recommended`, `Evidence`, `Alternatives`, or `evidence-checked` columns, and do not break the merged record-meta cell back into separate columns.
   - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
   - if a clarification response was carried in for this run, render the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it), walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile each one against new evidence, and update its `Status` to `resolved` or `obsolete` before issuing the next decision/verdict. When no carry-in path was provided, omit the `## 0.` heading entirely — the validator fails reports that emit an empty Section 0 stub (e.g. "No prior clarification response was provided for this run.").
+  - **Supersession (BLOCKING).** Reconciling the `C-*` row is only half of incorporating an answer. An answer does not merely *add* a decision — it *invalidates* whatever the previous run wrote under the opposite assumption. Before issuing the next decision, walk the prior deliverable prose for every statement the answer makes false and **delete or rewrite it**, then record the retirement. Adding the new decision while leaving the contradicting sentence in place puts two opposite instructions for the same symbol in one document; the implementer must then guess which is live, and the next verification round correctly blocks on it. In `implementation-planning` this record is `implementationPlanning.supersessionLedger[]` — one entry per answered clarification, either `disposition: superseded` (with the retired statement, its replacement, and the sections revised) or `disposition: no-dependent-statement` (with a rationale). **Enforced:** `validators/validate-run.py` `_validate_supersession_ledger` requires an entry per answered clarification; whether the claim is *true* is what the §5.5.9 adversarial round tests.
 - Verdict Card (shared — applies to every final-report regardless of profile):
   - The top-of-report `## Verdict Card` block is mandatory in every final-report. Its `Verdict Token` and `Direction` cells MUST byte-match the corresponding cells in `## 7. Final Verdict` — the card is a non-authoritative index and divergence makes the run `contract-violated`. **Enforced:** `validators/validate-run.py` `_validate_verdict_card_consistency` (token, on the rendered markdown) and `_validate_verdict_card_fields` (direction, on data.json). The `Next Step` cell points at the SAME action as `## 7. Final Verdict` and the first item of `## 3. Recommended Next Steps`, but is written as the actionable command the reader runs (`/okstra-run task-type=release-handoff`) where §7 states it as prose — it is not a byte copy and is not compared.
 - Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 6.` / `## 2.` tables in the final-report):
   - **Worker-side item IDs (free-form but unique within the worker).** Every row item in sections 1–5 (and any optional section 6) of an analysis worker's output MUST carry an item ID that is unique within that one worker's result file. The ID convention is the worker's choice — `F-001` / `F-002` per the suggested schema, `1.1` / `1.2` / `1.3` as Codex tends to use, or any other shape — but it MUST appear as the leading column of the row (for table-form items) or as a `[<ID>]` prefix (for bullet/numbered items). Workers that emit findings without IDs make cross-worker reconciliation impossible.
-  - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. The `Source items` column (or, where the template still calls it `Supporting workers` / `Workers (position)` / `Source`, that same column) MUST list every contributing worker:item pair (e.g. `claude:F-001, codex:1.1, antigravity:F-3`) so a reviewer can trace the synthesised row back to each worker's original wording without re-reading every worker-results file. Bare worker names without item IDs (e.g. `claude, codex, antigravity`) are deprecated for these tables; the validator does not yet fail on them but the readability pass treats it as a contract violation.
+  - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. The `Source items` column (or, where the template still calls it `Supporting workers` / `Workers (position)` / `Source`, that same column) MUST list every contributing worker:item pair (e.g. `claude:F-001, codex:1.1, antigravity:F-3`) so a reviewer can trace the synthesised row back to each worker's original wording without re-reading every worker-results file. Bare worker names without item IDs (e.g. `claude, codex, antigravity`) are rejected. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.SourceItem` pins each entry to `^[a-z][a-z-]*:[A-Za-z0-9._-]+$`, and `ConsensusRow` / `PrimaryEvidenceRow` require a non-empty `sourceItems`, so a bare worker name fails schema validation.
   - **Why this matters.** A real run had `claude=F-1..F-11`, `codex=1.1..1.8`, `antigravity=F-3..F-9` — three incompatible ID schemes. When the lead synthesised `C-1..C-8`, the link from `C-3` back to "which sentence in which worker file" was lost. Source-item preservation restores that link without forcing every worker to adopt a single ID prefix, which would over-constrain worker output style.
 - Audit sidecar (shared): Reading Confirmation placement follows the audience-selected preamble named by `**Worker Preamble Path:**`. Profiles do not restate it; the main worker-results body starts at section 1.
 

package/runtime/prompts/profiles/_implementation-deliverable.md

@@ -25,13 +25,18 @@ are collected and convergence finished. Phase 1-5 do not need it.
   - **independent validation re-run results** — per plan-validation command: command line, exit code, and tail of output captured by the verifier (not the executor); any divergence from the executor's reported result MUST be called out as a `Discrepancy` line citing both sides,
   - **style / lint / type-check results** — each check-only tool the verifier ran, its exit code, and the count of new findings attributable to lines this run introduced. When no tool is configured for a touched language, record the single line `no lint/style tool configured for <language>`,
   - any fix recommendations the verifier declined to apply.
-  `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph. If any verifier issued `FAIL` on a `Discrepancy` line, the synthesised verdict MUST be `FAIL` unless lead cites a concrete reproduction-time reason (committed flaky-test record, documented environment delta) for overriding.
+  `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph. External Tier 3 advisory results are excluded from this aggregate promotion and remain user-owned follow-up evidence. If any other verifier issued `FAIL` on a `Discrepancy` line, the synthesised verdict MUST be `FAIL` unless lead cites a concrete reproduction-time reason (committed flaky-test record, documented environment delta) for overriding.
 - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
   - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
   - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
   - **Schema migrations, config-format changes, or any change with persisted state**: a **dry-run of the rollback step is mandatory**, not preferred. Record the exact rollback command and its captured exit code / stdout. If the migration tool offers no dry-run mode (`--dry-run`, `--plan`, equivalent), the executor MUST refuse to claim rollback verification and instead end the run with a routing recommendation back to `implementation-planning` for a safer rollback strategy. Skipping this step on a stateful change is treated as a `contract-violated` outcome by `final-verification`.
 - **Manual user test draft**: when this run produces a user-observable change (UI / API / CLI / artifact), write `target / environment / steps / expected result` per change into §5.7.9 (data field `implementation.manualUserTest`, `applicable=true` with `items`). Treat effective `manual-user-test` PREP content only as a seed: reconcile it with the approved plan's `Acceptance:` and this run's actual diff before writing the final steps. Environment line: if the project has a `docker-compose.yml`, use `/okstra-container-build` (which runs `okstra container up <task-id>`) then connect to the published port; otherwise the project's run command (e.g. `npm start`). When there is no user-observable change, set `applicable=false` and give a one-line `exemptionReason` instead of items. These are the steps a human (or `final-verification`) re-runs by hand, NOT the automated validation commands in `Validation evidence`; planning PREP is never a second final-verification manual-test source.
 - **Design preparation handoff**: `implementation.manualUserTest` remains the only manual-test handoff to final-verification. For each effective non-`manual-user-test` item whose `reviewAt.phase` is `final-verification` and whose question remains unresolved after inspecting the actual diff, add one common `missingInformation` row. Set `source` to `design-prep:<PREP-ID>:<assessment-fingerprint>`, put `ifStillOpen` and the unresolved question in `item`, and put the guardrails plus risk in `risk`. Do not introduce an implementation-only PREP schema.
+- **External QA advisory handoff:** for every external Tier 3 result that did
+  not PASS, preserve the exact command and observed result in validation
+  evidence and add one `recommendedNextSteps` item with environment
+  prerequisites and the expected `QA-RESULT`. This is user-owned verification;
+  do not route back or fail implementation solely for this advisory.
 - **Routing recommendation for `final-verification`**: brief note on whether the changes are ready for final-verification phase or need a new error-analysis / planning loop first.
 - **Follow-up tasks (Section 4 of the final report)**: every item discovered during this run that was *not* delivered MUST appear in the final report's `## 4. Follow-up Tasks` table with a concrete `Origin`, `New Task ID`, `Suggested task-type`, `Scope`, and `Reason / Why deferred`. Sources include: out-of-scope discoveries that the executor consciously chose not to fold into this run, verifier concerns the executor declined to fix in-place, scope-boundary items from the approved plan that turned out to need their own ticket, and any unresolved `## 1. Clarification Items` row carried over from the approved plan (`Status` ∈ `{open, answered}` at approval time). An empty section is acceptable but only when expressed as the single line `- No follow-up tasks.` — silence is treated as a contract violation. Rows with `Auto-spawn? = yes` will be materialised by `scripts/okstra-spawn-followups.py` in Phase 7; rows with `Auto-spawn? = no` MUST also appear in `Section 3. Recommended Next Steps` so the user knows to act manually.
 

package/runtime/prompts/profiles/_implementation-executor.md

@@ -39,7 +39,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 - re-read the approved plan end-to-end and parse the `## 5.5 Stage Map`. Read the **Stage** injected in the launch prompt (`Stage for this implementation run`): the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`.
   - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
   - this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
-- **Clarification answers carried in (read before the first edit):** when `instruction-set/clarification-response.md` exists, it carries the user's answers to the approved plan's `## 1. Clarification Items` rows (the planning HTML form's `# Attached User Responses`). Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change. **CLI executor (codex/antigravity):** that file sits outside the CLI sandbox, so the lead MUST transcribe its body into the dispatched executor prompt at dispatch time (same rule as the preflight / stage-discipline transcription above) — a path reference never reaches the CLI process.
+- **Clarification answers carried in (read before the first edit; inlined for CLI executors):** when `instruction-set/clarification-response.md` exists, it carries the user's answers to the approved plan's `## 1. Clarification Items` rows (the planning HTML form's `# Attached User Responses`). Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change. **CLI executor (codex/antigravity):** that file sits outside the CLI sandbox, so the lead MUST transcribe its body into the dispatched executor prompt at dispatch time (same rule as the preflight / stage-discipline transcription above) — a path reference never reaches the CLI process.
 - **Effective design preparation (runtime-resolved after stage selection):**
 
 {{DESIGN_PREP_CONTEXT}}
@@ -55,7 +55,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 ## Stage execution contract (this run owns one stage)
 
-- **Sidecar evidence writer (BLOCKING).** When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal).
+- **Sidecar evidence writer (BLOCKING).** When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
 - **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. On completion, append a `status:"done"` row with `carry_path` populated for this stage number.
 - **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.