okstra 0.130.3 → 0.131.0

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

@@ -42,14 +42,35 @@ Verifier obtains the QA command set from exactly two declared sources, in order
 
 Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Then the Tier 3 stage conformance script (below) runs once. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Verifier-specific forbidden actions below).
 
-### Tier 3 — stage conformance scripts (requirement-conformance verification)
-
-Tier 3 proves the stage actually *meets the upper-level requirement* it was scoped to, by running a declared conformance script against the running state — Tiers 1·2 only prove the diff *builds and passes*. This is a real gate: its result sidecar is the input the `validate-run.py` Tier 3 gate reads, so a missing or non-PASS result BLOCKS acceptance.
+### Tier 3 — stage conformance scripts
+
+Tier 3 still attempts the declared `runCommand` against the permitted test
+environment. Classify the manifest entry by `requires`: any `db`, `http`, or
+`external` capability makes the entry external-advisory; an empty list or
+`io`-only entry stays blocking.
+
+**External QA outcome policy.** Record PASS normally. For FAIL, MISSING, no
+result, startup failure, credential/network/service absence, write the honest
+sidecar and command evidence with status `ADVISORY`. That result alone
+MUST NOT change the overall verifier verdict from PASS to CONCERNS/FAIL, trigger a fix
+cycle, or block the stage. Return the exact command, prerequisites, observed
+result, and expected result to the report writer as a user-owned follow-up.
+Enforcement: `scripts/okstra_ctl/conformance.py` (`decide_conformance_gate`)
+performs the core advisory classification/reduction;
+`validators/validate-run.py` (`_validate_conformance`) routes that status to
+warnings instead of failures; and
+`tests/contract/test_okstra_ctl_conformance.py` (`test_external_non_pass_is_advisory`),
+`tests/contract/test_validate_run_conformance.py` (`test_external_non_pass_returns_warning_not_failure`),
+and `tests/contract/test_final_report_contracts.py` (`test_external_qa_advisory_renders_without_downgrading_accepted_verdict`)
+lock the core, gate, and accepted-report behavior respectively.
+
+An `io`-only non-PASS remains BLOCKING. Manifest/schema/source-mutation defects
+also remain contract violations.
 
 - **Source.** The conformance manifest is `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token). This run's stage conformance entry is the manifest `entries[]` item whose `stageKey` equals this run's stageKey — `<task-id>-stage-<N>`, where `<N>` is the injected Stage number. Find that one entry; ignore the others (other stages are run by their own implementation runs or by final-verification).
-- **Exemption / waiver → do NOT run.** If the entry carries an `exemption` (or a user `waiver`), the verifier does NOT execute the script. It records the fact and the reason (`exemption.reason` / `waiver.reason` + `waiver.acknowledgedBy`) in the Read-only command log AND writes the result sidecar reflecting the skip. An `exemption` passes the gate outright; a `waiver` passes but is conditional (conformance left unverified by explicit user acknowledgement). No script runs in either case.
+- **Exemption / waiver → do NOT run.** If the entry carries an `exemption` (or a user `waiver`), the verifier does NOT execute the script. It records the fact and the reason (`exemption.reason` / `waiver.reason` + `waiver.acknowledgedBy`) in the Read-only command log AND writes the result sidecar reflecting the skip. An `exemption` passes outright. An external-advisory waiver is reported as `ADVISORY` with `conditional=false`; only an `io`-only blocking waiver is conditional. An empty `requires` list cannot be waived; it is declaration/contract trouble and remains BLOCKING. No script runs in either permitted waiver case.
 - **Otherwise run `runCommand` in the worktree cwd.** Execute the entry's `runCommand` verbatim from the worktree cwd. Inject env from `<PROJECT_ROOT>/.okstra/project.json`'s `qaEnv` (replica DB DSN / app base URL / env file — declared in Phase 4e). This is a **replica / test environment only** path — never run it against shared / staging / prod, identical to the DB real-execution gate principle above.
-- **Interpret the standard interface.** Parse the process exit code together with stdout: the `QA-RESULT: PASS|FAIL` marker line (if several appear, the last one wins) and the per-requirement `REQ <id>: PASS|FAIL: <reason>` lines. If no `QA-RESULT` marker is emitted, the overall result is `MISSING` — which the gate treats as BLOCKING (the script broke the contract).
+- **Interpret the standard interface.** Parse the process exit code together with stdout: the `QA-RESULT: PASS|FAIL` marker line (if several appear, the last one wins) and the per-requirement `REQ <id>: PASS|FAIL: <reason>` lines. If no `QA-RESULT` marker is emitted, the overall result is `MISSING`; classify it according to the entry's blocking or external-advisory capability policy above.
 - **Write the result sidecar (BLOCKING deliverable).** Write `<task_root>/qa/result-<stageKey>.json` as:
   ```json
   {
@@ -59,13 +80,13 @@ Tier 3 proves the stage actually *meets the upper-level requirement* it was scop
     "requirements": { "<id>": { "status": "PASS", "reason": "<from REQ line>" } }
   }
   ```
-  `overall` is exactly one of `PASS` / `FAIL` / `MISSING`. This file is the input to the `validate-run.py` Tier 3 gate — if it is absent the gate reports the stage as "never ran" and BLOCKS, so writing it is mandatory whenever the script runs (and on the exemption/waiver skip path, recording the skip outcome).
-- **Read-only command log.** Record the `runCommand` exact line + its exit code in the Read-only command log. Unlike Tiers 1·2, a conformance script MAY mutate the **replica datastore** (exercising integrated state is its whole purpose) — but only the `qaEnv` replica target, never a shared/staging/prod store. The `runCommand` itself is still subject to the same source/lockfile mutation deny-list as Tier 2 (`--fix`, `npm install` without `ci`, etc.); a denied token aborts with `contract-violated`.
+  `overall` is exactly one of `PASS` / `FAIL` / `MISSING`. Writing the honest sidecar is mandatory whenever the script runs and on the exemption/waiver skip path. A missing `io`-only sidecar blocks; a missing external-advisory sidecar is reported as `ADVISORY` rather than accepted as hidden evidence.
+- **Read-only command log.** Record the `runCommand` exact line + its exit code in the Read-only command log. Tier 3 external non-PASS evidence MUST remain visible with status `ADVISORY`. Unlike Tiers 1·2, a conformance script MAY mutate the **replica datastore** (exercising integrated state is its whole purpose) — but only the `qaEnv` replica target, never a shared/staging/prod store. The `runCommand` itself is still subject to the same source/lockfile mutation deny-list as Tier 2 (`--fix`, `npm install` without `ci`, etc.); a denied token aborts with `contract-violated`.
 - **No manifest / no entry for this stage.** If the manifest file is absent, or it has no entry whose `stageKey` matches this run's stageKey, the verifier records `conformance: no manifest entry for <stageKey>` and proceeds (forcing the *declaration* of conformance entries is the job of planning Step 11 + the `validate-run.py` diff-surface cross-check, not the verifier).
 
 ### Missing-tier handling
 
-If a tier is empty or absent, verifier records the single line `qa-command not configured: <category>` per missing category (`lint` / `format` / `typecheck` / `test`; and `db-test` **only when the diff touches DB/IO/SQL**, where a missing `db-test` is escalated to a blocking finding per the DB real-execution gate below) in the worker result and proceeds — silent omission is a contract violation. Verifier MUST NOT auto-detect or invent a command in this case; the user/operator must declare it in `project.json.qaCommands` or in the plan.
+If a tier is empty or absent, verifier records the single line `qa-command not configured: <category>` per missing category (`lint` / `format` / `typecheck` / `test`; and `db-test` **only when the diff touches DB/IO/SQL**, where a missing `db-test` is escalated to a blocking finding per the DB real-execution gate below) in the worker result and proceeds — silent omission is a contract violation. **Enforced:** `validators/validate-run.py` `_validate_missing_qa_categories_recorded` for the four unconditional categories; `db-test` is left to the DB gate below because its requirement depends on whether the diff touches DB/IO/SQL. Without the note, "the category passed" and "the category never ran" read identically in the report. Verifier MUST NOT auto-detect or invent a command in this case; the user/operator must declare it in `project.json.qaCommands` or in the plan.
 
 ### `cmd` field deny-list (Tier 2 validation)
 
@@ -73,7 +94,7 @@ The runtime AND the verifier MUST reject any `cmd` containing tokens that imply
 
 ### Discrepancy rule
 
-If the verifier's re-run result differs from what the executor reported (a passing test fails on re-run, a clean lint surfaces warnings, an exit code mismatches), the verifier MUST issue verdict `FAIL` with the divergence cited. `Claude lead` MUST NOT silently prefer the executor's evidence over a verifier's reproduced result during synthesis; if it overrides, it MUST cite a concrete reproduction-time reason (flaky-test commit-cited, environment delta documented) — handwaving is not allowed.
+Tier 3 external-advisory discrepancies are excluded from this promotion: preserve the executor/verifier divergence in the advisory evidence and user-owned follow-up without changing the verdict. For Tier 1, Tier 2, and blocking `io`-only Tier 3, if the verifier's re-run result differs from what the executor reported (a passing test fails on re-run, a clean lint surfaces warnings, an exit code mismatches), the verifier MUST issue verdict `FAIL` with the divergence cited. `Claude lead` MUST NOT silently prefer the executor's evidence over a verifier's reproduced result during synthesis; if it overrides, it MUST cite a concrete reproduction-time reason (flaky-test commit-cited, environment delta documented) — handwaving is not allowed.
 
 ### Read-only command log (per verifier)
 
@@ -132,11 +153,13 @@ carried findings is a contract violation the lead records via
 
 A mocked unit test cannot observe the SQL a query builder actually emits — `count({ col: 'FontFamily.fontFamily' })` passes a mocked suite yet throws `Unknown column` on a real database. For this class of change a green mock-only suite is therefore NOT evidence; only a run against a real (or faithful-replica) datastore is. This gate is the verifier's enforcement of that rule.
 
+**External Tier 3 de-duplication exception.** A DB/IO/SQL surface covered by an in-scope Tier 3 entry whose `requires` include `db`, `http`, or `external` is governed by the External QA outcome policy. Its non-PASS or unavailable result MUST NOT generate a second legacy db-test-not-configured or mock-only blocker solely for that same Tier 3 non-PASS or unavailable result. Tier 1 or Tier 2 failures remain blocking, and DB surfaces without declared external Tier 3 coverage remain blocking.
+
 - **Trigger.** Fires when `git diff <base>...HEAD` touches DB/IO/SQL: ORM / query-builder code (sequelize / typeorm / prisma / knex / raw SQL), `*.repository.*`, model/entity files, `migrations/**`, `*.sql`, or any changed query string.
 - **Requirement when fired.** The verifier MUST reproduce a real-DB execution: run the `db-test` tier (Tier 1 = plan `validation` db step; else Tier 2 = `project.json.qaCommands.db-test`) against a **local / replica** datastore (same engine + schema — never shared / staging / prod, consistent with the verifier forbidden-actions list) and record its exact command + exit code. A mock, an in-memory shim that does not parse real SQL, or static reasoning does NOT satisfy this.
 - **No `db-test` command available → blocking, not a passive skip.** If neither tier declares a `db-test` command, the verifier records the blocking finding `db-test not configured — DB change unverified (mock-only)` and sets the verdict to `FAIL`; it MUST NOT emit only the passive `qa-command not configured` note and pass. Recommended fix: declare a `db-test` command in `project.json.qaCommands` or the plan's validation set.
 - **Mock-only evidence → unverified.** If the diff's only DB coverage is mocked, the verifier labels the DB portion `static-analysis only …, unverified (not executed)` (never `verified`), records it as a blocking finding, and sets `FAIL`. Never downplay the real run as "too heavy / static proof suffices".
-- **Surface it at every layer.** The finding is copied verbatim into the verifier result and MUST survive into the final report's `## 6.` and Verdict Card, so the user sees the DB-unverified state continuously — it is the load-bearing reason a downstream `final-verification` cannot reach `accepted` and `release-handoff` cannot push.
+- **Surface it at every layer.** The finding is copied verbatim into the verifier result and MUST survive into the final report's `## 6.` and Verdict Card, so the user sees the DB-unverified state continuously — it is the load-bearing reason a downstream `final-verification` cannot reach `accepted` and `release-handoff` cannot push. **Enforced:** `validators/validate-run.py` `_validate_verifier_fail_blocks_verdict` fails a report whose `verdictCard.verdictToken` is `accepted` / `conditional-accept` while any `implementation.verifierResults[]` row records `verdict: FAIL` — a rejection dropped during synthesis is exactly how rejected work reached `release-handoff`.
 
 ## All-verifier-failure policy
 

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

@@ -15,6 +15,7 @@
     - test & validation suite pass status — independently re-run the read-only two-tier command set (Tier 1 = brief/approved-plan `validation`, Tier 2 = `project.json` `qaCommands`) and confirm each passes on the verified head, citing exact command + exit code
     - test correctness — delivered tests actually assert the intended behaviour: no gutted/weakened assertions, no tautological or always-passing tests, no tests exercising only mocks; new behaviour has matching coverage
     - DB / IO / SQL real-execution evidence — trigger: the diff touches DB/IO/SQL (ORM / query-builder, `*.repository.*`, model / `migrations/**` / `*.sql`, or changed query strings). Then Validation Evidence MUST cite a real (or faithful-replica) DB execution — the `db-test` command + exit code — not a mock-only suite. Rationale: a mock-only suite cannot observe the SQL actually emitted (observed failure class: `prompts/profiles/_implementation-verifier.md` §"DB / IO / SQL change — real-execution gate"). A DB-touching change whose only evidence is mocked, or for which no `db-test` ran, is an **Acceptance Blocker** (`major`+; per the Verdict vocabulary below, any blocker moves the verdict off `accepted`). This gate stops an unverified DB change from reaching `release-handoff` and being pushed.
+      - **External Tier 3 de-duplication exception.** A DB/IO/SQL surface covered by an in-scope Tier 3 entry whose `requires` include `db`, `http`, or `external` is governed by the External QA outcome policy. Its non-PASS or unavailable result MUST NOT generate a second legacy db-test-not-configured or mock-only blocker solely for that same Tier 3 non-PASS or unavailable result. Tier 1 or Tier 2 failures remain blocking, and DB surfaces without declared external Tier 3 coverage remain blocking.
     - no new defects introduced — the diff does not break previously-working behaviour and adds no new bug (logic/off-by-one, null/empty handling, resource leaks, broken error paths)
     - scope conformance — the delivered diff stays within the approved plan's scope; flag out-of-scope edits, unrelated file changes, leftover debug/commented-out code, and unintended deletions
     - project review-rule packs (when present) — search `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`; read the matching `SKILL.md` + referenced `references/*.md` and apply their rules as an acceptance overlay (record `project-review-rules: <paths read>` or `project-review-rules: none found`). This is a static review pass, not a PR-comment workflow — do NOT dispatch reviewer subagents. Because this phase verifies the **whole-task merged diff**, it is the gate that catches **cross-stage findings a per-stage `implementation` verifier structurally cannot see** (each implementation run reviews only its own stage diff): most importantly two cross-stage conditions: (a) the same helper stack / transform / domain rule duplicated across stages or services — byte-identical duplication is always an Acceptance Blocker, and semantically-equivalent transforms across services are blockers unless the approved plan explicitly justified keeping them separate; (b) an API newly orphaned because its only caller was removed in a different stage. A confirmed cross-stage duplication of this kind is an Acceptance Blocker (`major`+) that cites every `path:line` location and names the shared-module location to converge on. (Single-stage scope sees only one stage, so it cannot raise cross-stage findings — note that limitation rather than implying coverage.)
@@ -33,27 +34,41 @@
   - **Target confirmation:** verify the inline worktree, scope, base/head refs, target path, and digest against `verification-target.md` before analysis. Use the sidecar's stage/report mapping and complete diff stat; a missing sidecar, digest mismatch, dirty worktree outside `.okstra/`, or wrong head is a `tool-failure`, never a silent target reselection.
   - **Evidence:** attach file:line, exact command + exit code, log excerpt, or MCP SELECT evidence to every finding. Mark a requirement as covered only when the cited artifact demonstrates it.
   - **Tier 1 and Tier 2 read-only validation:** Tier 1 is the originating brief/approved plan `validation` set; Tier 2 is `<PROJECT_ROOT>/.okstra/project.json` `qaCommands`. Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token.
-  - **Tier 3 stage conformance:** read `<task_root>/qa/conformance-manifest.json`. In whole-task scope, run every non-exempt `entries[].runCommand` against the merged worktree; in single-stage scope, run only the matching `stageKey`. Use `qaEnv` only with a replica/test datastore, refresh `result-<stageKey>.json`, and interpret the exit code plus the last `QA-RESULT: PASS|FAIL` marker. Missing/non-PASS evidence is an acceptance-blocker recommendation. An exemption or user waiver is not executed; record its reason, and surface a waiver as a `conditional-accept` recommendation.
+  - **External QA outcome policy:** continue to attempt every in-scope Tier 3
+    command. For an entry requiring `db`, `http`, or `external`, record non-PASS
+    as a Tier 3 `advisory` command, add a user-owned Residual Risk and exact
+    Recommended Next Step, and include it in Could-Not-Verify. It
+    MUST NOT create an Acceptance Blocker, conditional acceptance condition, blocked verdict, or
+    non-release routing by itself. `io`-only non-PASS and malformed/undeclared
+    conformance contracts remain acceptance-gating.
+    Enforcement: `scripts/okstra_ctl/conformance.py` (`decide_conformance_gate`)
+    performs the core advisory classification/reduction;
+    `validators/validate-run.py` (`_validate_conformance`) routes that status to
+    warnings instead of failures; and
+    `tests/contract/test_okstra_ctl_conformance.py` (`test_external_non_pass_is_advisory`),
+    `tests/contract/test_validate_run_conformance.py` (`test_external_non_pass_returns_warning_not_failure`),
+    and `tests/contract/test_final_report_contracts.py` (`test_external_qa_advisory_renders_without_downgrading_accepted_verdict`)
+    lock the core, gate, and accepted-report behavior respectively.
   - **Manual user test:** read only the source implementation report's `implementation.manualUserTest`. Execute reproducible steps and record `pass`, `fail`, or `blocked` with observed evidence. Human-only or environment-unavailable steps remain `blocked` with the exact reason. Reaffirm an `applicable=false` exemption; do not execute planning `designPreparation` or manual-test PREP items directly.
   - **Design-preparation carry-in:** read only source implementation report `missingInformation` rows whose `source` starts with `design-prep:`. Recommend `ifStillOpen: block` as an acceptance blocker and `ifStillOpen: follow-up` as residual risk. This phase does not read planning PREP sidecars directly or mutate planning snapshots.
   - **Could-not-verify honesty:** use `not-configured`, `env-unavailable`, `rejected`, `gap`, or `blocked` as appropriate. Never convert unavailable evidence into an executed/pass claim.
   - **Source-mutation prohibition:** verification may write only assigned okstra run artifacts. Do not edit source, schema, deployment, lockfile, or configuration files; route detected defects to a later phase.
 - Required deliverable shape (final report, in addition to the standard sections):
-  - **Source Implementation Report(s)**: the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head refs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). Every analyser prompt carries the same compact target identity (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head ref:** / **Verification target path:** / **Verification target digest:**`) and reads the sidecar on demand for the complete diff stat. A worker that cannot confirm its analysis ran against that worktree's delivered diff MUST record a `tool-failure`.
+  - **Source Implementation Report(s)** (**Enforced:** `validators/validate-run.py` `_validate_verification_target_match` compares `verificationScope`, `worktreePath`, `implementationBaseRef`, `capturedHeadSha`, and the `stageReports` stage set against the digest-verified `instruction-set/verification-target.md`; a snapshot whose digest no longer checks out is ignored rather than trusted. `verificationScope` in particular gates both stage-group eligibility and release-handoff routing, so it is not the report's to restate): the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head refs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). Every analyser prompt carries the same compact target identity (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head ref:** / **Verification target path:** / **Verification target digest:**`) and reads the sidecar on demand for the complete diff stat. A worker that cannot confirm its analysis ran against that worktree's delivered diff MUST record a `tool-failure`.
   - **Verdict vocabulary**: Section 7 (`Final Verdict`) MUST include a `Verdict Token` field whose value is exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed. Each condition MUST be recorded as a row in the **Conditional Acceptance Conditions** deliverable (`id` `CA-NNN`, `condition`, `evidenceRequired`, `blocksReleaseHandoff`). The validator enforces verdict↔deliverable consistency: `accepted` ⇒ zero acceptance blockers, `blocked` ⇒ at least one, `conditional-accept` ⇒ at least one condition, and a `release-handoff` routing recommendation is allowed only when the verdict is `accepted`. **Any Acceptance Blocker therefore forces the verdict off `accepted` (to `conditional-accept` or `blocked`); the gates below cite this rule instead of restating the arithmetic.**
   - **Acceptance Blockers block** (under section 4): one row per blocker with `id`, `severity` (`critical` / `major` / `minor`), evidence (file path, log excerpt, or test output), and the recommended follow-up phase (`error-analysis` or `implementation-planning`). Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
   - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
   - **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) / `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` with the reason — 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, `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."
+  - **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**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`. `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 `single-stage` accepted run routes to `release-handoff(stage-group)` (or `implementation` / `done`); plain `release-handoff` remains whole-task-only. Enforcement: `validators/validate-run.py` rejects a `single-stage` report whose routing cites plain `release-handoff`.
-  - **Verified-row recording** (single-stage scope only): when the Verdict Token is `accepted`, 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 re-validates taskType/scope/verdict from data.json, so a non-accepted or whole-task report is rejected at the tool layer.
+  - **Verified-row recording** (single-stage scope only): when the Verdict Token is `accepted`, 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 re-validates taskType/scope/verdict from data.json, so a non-accepted or whole-task report is rejected at the tool layer. **Enforced:** `validators/validate-run.py` `_validate_verified_row_recorded` requires a `verified` row in `runs/implementation-planning/consumers.jsonl` for every accepted stage — the helper validated its own inputs but nothing checked it had ever run, leaving reports that said `accepted` while the registry said unverified, so the stage was never offered for a stage-group PR.
 - 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
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
   1. **Verdict precision** — section 7 (`Final Verdict`) includes `Verdict Token` with one of the three allowed verdict tokens; `conditional-accept` lists every condition as an actionable item.
   2. **Blocker traceability** — every blocker cites a concrete artifact (file:line, log excerpt, test exit code, MCP SELECT). Blockers without evidence are demoted to residual risk or removed.
-  3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. No silent omissions.
+  3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. A user-owned external advisory gap is the sole outcome exception: keep it as a Residual Risk with the exact rerun Recommended Next Step instead of promoting it to a blocker. No silent omissions.
   4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
   5. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
 - Cross-verification mode:

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

@@ -69,7 +69,11 @@
   - writing artifacts anywhere except `<PROJECT_ROOT>/.okstra/` — the run's `reports/` directory is the canonical location for this phase
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
 {{INCLUDE:_clarification-recommendation.md}}
-  - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision). A row with `none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above.
+  - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision). A row with `none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above. **Enforced:** `validators/validate-run.py` `_validate_clarification_evidence_note` requires the note to exist and to be either a concrete `<path>:<line>` or the `none — <reason>` form. The check proves the note exists, not that the lookup happened — a false `none` is caught by review, but it is now an attributable claim rather than a silent omission.
+  - **`Blocks=approval` admissibility (scope boundary).** Requirement Coverage has an admissibility test and Clarification rows did not, so anything at all could acquire approval-blocking force — a prose inconsistency inside a *rejected* option blocked a plan with the same weight as a business decision. A row earns `Blocks=approval` only when, **absent an answer, the `implementation` run would produce wrong or unsafe code**. Apply the test to the row's consequence, not its topic:
+    - admissible — the answer selects between behaviours the code must implement, fixes a requirement the plan would otherwise satisfy incorrectly, or resolves a safety/data-integrity question.
+    - NOT admissible → use `Blocks=none` — QA-harness or tooling scope, report notation and wording, numbering or citation-range cleanup, anything inside an option the plan does not recommend, and anything the codebase answers (which the codebase-first rule already forbids raising at all). These belong in `## 5. Missing Information and Risks` or a Working Assumption; they are recorded, not gating.
+    - A row you would answer with "the plan would still produce the same code either way" is by construction `Blocks=none`.
 - Section heading contract (BLOCKING — validator scans for these literal English substrings):
   - The final report MUST include section headings containing each of the following exact strings — this list mirrors `PLANNING_REQUIRED_SECTIONS` in `validators/validate-run.py`, which is the SSOT: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stage Map`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `Requirement Coverage`, `Plan Body Verification`, `Cross-Project Dependencies`, `Decision Drafts`. (Approval is no longer a body section — it is the YAML frontmatter `approved` field.) Three further headings are enforced elsewhere, not by that scan: `Stage Exit Contract` and `Stage Validation` are per-stage subsections checked by `validators/validate-implementation-plan-stages.py`, and `Implementation Design Preparation` is enforced and rendered by `schemas/final-report-v1.0.schema.json` plus `templates/reports/final-report.template.md` from its required data block.
   - Korean translations are allowed in parentheses (e.g. `### Recommended Option (Korean gloss)`), but the English keyword must be present verbatim in the heading line.
@@ -78,6 +82,11 @@
 - Required deliverable shape (final report, in addition to the standard sections):
   - at least two implementation options. **Each option must include**:
     - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
+      - **Two-tier change description.** Each `fileStructure` row carries `summary` **and** optional `details`, and they are not interchangeable:
+        - `summary` — one plain-language sentence a reviewer who has never opened this file can follow: what changes and why it is needed. Name behaviour and domain nouns, not identifiers. No function/type/variable names, no call chains, no line numbers, no conditional logic spelled out. **Enforced:** `schemas/final-report-v1.0.schema.json` `$defs.OptionCandidate.fileStructure.items.summary` caps it at 120 characters, so a dense identifier dump fails schema validation.
+        - `details` — the technical specifics that used to be crammed into `summary`: exact symbol names, signatures, comparison semantics, line ranges, enum members. Omit the field when there is nothing beyond the summary.
+        - Bad `summary` (identifier dump, no readable claim): `Widen the return of retrieveFontFamilyGroupWithFontVersionId to also yield the matched FontFamily (own key and enabled flag) and the matched Font.status.`
+        - Good — `summary`: `Carry enough information out of the font lookup to tell whether the matched family is switched off.` / `details`: `Add the matched FontFamily (own key + enabled) and Font.status to the return of retrieveFontFamilyGroupWithFontVersionId. Both are already in scope in the :102-104 loop and dropped at return.`
     - affected interfaces / public contracts and downstream consumers
     - estimated blast radius (units, configs, deployment manifests, data migrations)
   - trade-off matrix across options (rows = options, columns at minimum: complexity, risk, reversibility, test coverage cost, rollout cost)
@@ -100,7 +109,15 @@
     - **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,...])` — a Tier3 verification script that proves 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. When you emit this line you MUST also (a) write the script to `<task_root>/qa/scripts/stage-<N>.<ext>` and (b) add a matching entry to `<task_root>/qa/conformance-manifest.json` with fields `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (subset of `{db, io, http, external}`), `passContract`, `exemption: null`, `waiver: null`. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <reason>` line per requirement. When the verification body is a test spec, author it with the project's own test framework (devDependency) invoked via a discovery override at `<task_root>/qa/scripts/` (jest: `--config <project config> --roots <task_root>/qa/scripts`) — never hand-roll `describe`/`expect` and never widen the project's own test config; for TypeScript specs also write `<task_root>/qa/scripts/tsconfig.json` extending the project tsconfig with the runner's `types` entry so editors resolve the file.
       - `Conformance exemption: <reason>` — only for stages that touch no db/io/http/external surface, or where unit tests fully cover the increment. (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.)
-      The manifest lives at the **task level** (`<task_root>/qa/`, path token `TASK_QA_PATH`) and is shared across planning → implementation → final-verification. Layout split: executable scripts (conformance + any real-IO test) live under `<task_root>/qa/scripts/`; data sidecars (`conformance-manifest.json`, `result-*.json`) stay at the `qa/` root. This declaration is enforced at four layers: `validators/validate-implementation-plan-stages.py` check **S11** forces every stage to carry one of the two lines; at the planning boundary `validators/validate-run.py` `_validate_planning_conformance_declared` fails when a stage that declared `Conformance tests:` has no matching `-stage-<N>` entry in the shared manifest (a declaration that was never materialized); the manifest JSON structure — including each entry's `script` living under `qa/scripts/` — is enforced by `validate_conformance_manifest` (called from both the run path and validate-run); and the result gate (each script's `QA-RESULT`) is enforced by the verifier Tier3 + validate-run.
+      - **External QA outcome guideline:** after satisfying the mandatory script,
+        manifest, and S11 declarations above, an entry whose `requires` contains
+        `db`, `http`, or `external` should document the exact `runCommand`,
+        prerequisites, requirement IDs, and expected `QA-RESULT`. Okstra may start the
+        environment and run it automatically, but `FAIL`, missing evidence, or an
+        unavailable environment is a user-owned follow-up, never a plan approval or
+        later run blocker. `requires=[]` and `requires=[io]` remain blocking.
+        Remote IO should also declare `external`.
+      The manifest lives at the **task level** (`<task_root>/qa/`, path token `TASK_QA_PATH`) and is shared across planning → implementation → final-verification. Layout split: executable scripts (conformance + any real-IO test) live under `<task_root>/qa/scripts/`; data sidecars (`conformance-manifest.json`, `result-*.json`) stay at the `qa/` root. This declaration is enforced at four layers: `validators/validate-implementation-plan-stages.py` check **S11** forces every stage to carry one of the two lines; at the planning boundary `validators/validate-run.py` `_validate_planning_conformance_declared` fails when a stage that declared `Conformance tests:` has no matching `-stage-<N>` entry in the shared manifest (a declaration that was never materialized); the manifest JSON structure — including each entry's `script` living under `qa/scripts/` — is enforced by `validate_conformance_manifest` (called from both the run path and validate-run); and the result policy is evaluated by `conformance.py` and `validate-run.py`.
     - `### Stage Exit Contract` — predicted added/modified files, newly exposed identifiers/types/endpoints, downstream-usable resources.
     - `### Stage Validation` — pre / mid / post exact commands or observable outcomes for this stage only.
   - **Vertical-slice-first partition rule (1st-class):** the grouping anchor is a **thin end-to-end vertical slice** — one stage delivers a single user-observable increment, crossing whatever layers are needed (data → service → API → UI) to make that one increment work. File/module proximity is demoted to the **intra-slice grouping rule**: within a slice, keep steps touching the same file/directory/module together so the diff, PR, and rollback unit stay cohesive. **Horizontal layer-splitting is forbidden** — never carve "the DB layer" into one stage and "the service layer" into the next; that produces stages that ship no standalone user value. A stage is split ONLY when (a) a real `depends-on` data/contract dependency exists, (b) effective steps would exceed 8, or (c) it is a distinct vertical slice (a different user-value increment). Maximising the number of parallel stages is NOT a reason to split — parallelism is an emergent property of independent stages, never a partitioning goal.
@@ -128,7 +145,7 @@
     - **The reach of this gate — do not over-trust it.** What is mechanically enforced is the *form* of each source, that a `brief:` heading literally exists, that a `derived:` chain terminates without cycling, and that no stage is uncited. What is **not** enforced is whether the cited source genuinely demands the requirement. Every brief carries the same generic headings (`## Acceptance Criteria`, `## Context`, …), so attaching invented work to a real heading still parses clean. The gate's value is that it forces every item to name an origin and makes fabrication explicit and auditable — judging whether that origin actually demands the item remains a reviewer / `DISAGREE(f)` responsibility, and passing this gate is never evidence that the scope is justified.
     - **Stage citation format:** the reverse check reads each `Covered by` cell as prose, so a stage counts as cited only when its number is anchored to a `Stage` / `Stages` word on the same line. These all read: `Stage 2`; `Stage 1, Stage 2, Stage 3`; `Stages 1, 2, 3`; `Stages 1, 2, and 3`; ranges (`Stages 1-3`, `Stages 1 to 3`, `Stages 1 through 3`); and `and` / `&` conjunctions. A bare number with no `stage` word anchoring it is NOT read as a citation, so `covered by the recommended option, step 4` cites nothing. **Enforced:** `validators/validate-run.py` `_validate_stage_has_requirement` fails the plan when any Stage Map stage is cited by no coverage row.
     - Because that reader only sees prose, it cannot tell a citation from a mention: `Stage 1 (superseded by Stage 2)` still counts Stage 1 as cited, and one row citing `Stages 1-64` rubber-stamps every stage in the map. Cite the stages a requirement is actually satisfied by — not stages merely mentioned, and never a blanket range standing in for the work of checking.
-  - **Requirement Coverage (mandatory, §5.5.8):** one row per concrete requirement from the task brief / packet. Assign stable IDs `R-001`, `R-002`, ... in source order. Columns: `ID | Source | Requirement | Covered by option / stage / step | Status`. `Source` follows the three-form grammar defined in the **Scope provenance** rule above — a free-form `file:line` is not one of the three forms and is rejected. When this run's brief is a fan-out packet, the task manifest's `taskBriefPath` points at that packet file, so `brief:` cites the packet's own headings (`## Scope`, `## Evidence`, `## Requirement Provenance`) — not the headings of the upstream user brief the packet came from. For `covered`, `Covered by` must name the specific Option Candidate and Stage/Step that satisfies it, not just "recommended option". **Enforced:** `validators/validate-run.py` `_validate_requirement_coverage_covered_by` fails a `covered` row whose `coveredBy` is bare "recommended option", names no Option/Stage/Step anchor, or cites a Stage number absent from the Stage Map (whether the cited step *actually satisfies* the requirement remains a worker `DISAGREE(f)` judgment). `Status` is one of `covered`, `gap`, `blocked C-NNN`, or `documented-deviation`. A deviation records the concrete alternative in `coveredBy`, non-empty unique `decisionRefs` (`C-NNN` clarification IDs and/or `D-NNNN` decision-draft numbers), and `approvalDisposition: accepted|blocked C-NNN`. `accepted` is valid only when a referenced clarification is user-confirmed (`answered|resolved` with non-empty `userInput`); `blocked C-NNN` is valid only when that same-report clarification is `open` and `Blocks=approval`. **Enforced:** schema `$defs.ImplementationRequirementCoverageRow` plus `validators/validate-run.py` `_validate_requirement_deviations`; the exact `P-Req-*` queue still comes from `scripts/okstra_ctl/plan_items.py`. If any row is `gap`, plain `blocked C-NNN`, or a deviation whose approval disposition is blocked, the Plan Body Verification gate MUST NOT be `passed` / `passed-with-dissent`; add a matching `Blocks=approval` row for the blocker and keep `approved: false`.
+  - **Requirement Coverage (mandatory, §5.5.8):** one row per concrete requirement from the task brief / packet. Assign stable IDs `R-001`, `R-002`, ... in source order. Columns: `ID | Source | Requirement | Covered by option / stage / step | Status`. `Source` follows the three-form grammar defined in the **Scope provenance** rule above — a free-form `file:line` is not one of the three forms and is rejected. When this run's brief is a fan-out packet, the task manifest's `taskBriefPath` points at that packet file, so `brief:` cites the packet's own headings (`## Scope`, `## Evidence`, `## Requirement Provenance`) — not the headings of the upstream user brief the packet came from. For `covered`, `Covered by` must name the specific Option Candidate and Stage/Step that satisfies it, not just "recommended option". **Enforced:** `validators/validate-run.py` `_validate_requirement_coverage_covered_by` fails a `covered` row whose `coveredBy` is bare "recommended option", names no Option/Stage/Step anchor, or cites a Stage number absent from the Stage Map (whether the cited step *actually satisfies* the requirement remains a worker `DISAGREE(f)` judgment). `Status` is one of `covered`, `gap`, `blocked C-NNN`, or `documented-deviation`. A deviation records the concrete alternative in `coveredBy`, non-empty unique `decisionRefs` (`C-NNN` clarification IDs and/or `D-NNNN` decision-draft numbers), and `approvalDisposition: accepted|blocked C-NNN`. `accepted` is valid only when a referenced clarification is user-confirmed (`answered|resolved` with non-empty `userInput`); `blocked C-NNN` is valid only when that same-report clarification is `open` and `Blocks=approval`. **Enforced:** schema `$defs.ImplementationRequirementCoverageRow` plus `validators/validate-run.py` `_validate_requirement_deviations`; the exact `P-Req-*` queue still comes from `scripts/okstra_ctl/plan_items.py`. If any row is `gap`, plain `blocked C-NNN`, or a deviation whose approval disposition is blocked, the Plan Body Verification gate MUST NOT be `passed` / `passed-with-dissent`; add a matching `Blocks=approval` row for the blocker and keep `approved: false`, and record `coverage-gap` in `planBodyVerification.gateBlockedBy` so the blocking value does not silently read as a worker disagreement. **Exception — no double counting:** a row whose `blocked C-NNN` cites a clarification that *this same run's* §5.5.9 round promoted from a `majority-disagree` item is not an independent blocker; that blocker is already counted as the plan item, and re-counting it makes the run block on a clarification it just authored and carries the row into the next run as a fresh blocker. **Enforced:** `validators/validate-run.py` `_validate_gate_blocked_by` (fails a passing gate with a blocking coverage row) and `_independent_coverage_blockers` (the same-run exclusion).
   - **Review-rule compliance plan:** when a project-local review rule pack is found, each Option Candidate MUST include the design implication of those rules in its File Structure / interfaces / blast-radius notes. For any helper or data transform used by more than one changed service, the plan must either place it in a shared module or explicitly justify why duplication is intentional. For any test step, the plan must state the observable behavior being asserted, not the internal collaborator call being pinned. For any exported/public method added or renamed, the step must carry the intended noun/side-effect semantics so implementation names can be reviewed before code is written.
   - the YAML frontmatter MUST include the line `approved: false` (report-writer always emits the unflipped value). The user authorises the next `implementation` run by flipping it to `approved: true` (manual edit or `--approve` CLI). Do NOT recreate any `User Approval Request` body block — the validator fails reports that contain one (see `validators/validate-run.py` deprecated patterns).
   - the YAML frontmatter MUST include the line `implementation-option:` directly under `approved:` (report-writer always emits it with an **empty value**). The user selects which Option Candidate the next `implementation` run executes by filling this line with that option's name (manual edit or `--implementation-option <name>` CLI). When left empty, the `implementation` run falls back to the `Recommended Option`.
@@ -142,7 +159,7 @@
     ```
 
     An `AGREE` note records the counterexample considered and its exclusion reason. If the judgement needs unavailable external material, record `verification-error`, not `DISAGREE`. **Enforced:** `validators/validate-run.py` `_validate_plan_item_extraction_completeness` compares the exact deterministic set, independently rejecting missing, unexpected, and duplicate plan-item IDs, including `P-Prep-*`.
-  - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (Option Candidates / Trade-off Matrix / Recommended Option / Stage Map and per-stage sections / Dependency / Validation Checklist / Rollback / Requirement Coverage) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `prompts/lead/plan-body-verification.md`. The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. **Enforced:** `validators/validate-run.py` `_validate_plan_body_gate_recompute` re-derives the gate from `planItems[].verdicts` and fails when the declared `gateResult` claims a healthier outcome than the recorded votes support; `_validate_plan_item_extraction_completeness` fails when any plan-body deliverable category is under-extracted into `planItems`, so a dropped item can no longer dodge the gate. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture"). Among the majority-disagree items, those that are majority-`planner-fixable` go through one report-writer self-fix pass before being promoted to a user clarification (`prompts/lead/plan-body-verification.md` "Self-fix round"). Only items not resolved by self-fix, or that are majority-`needs-user-input`, become `Blocks=approval` clarifications. `validators/validate-run.py` `_validate_self_fix_before_clarification` fails a planner-fixable majority item promoted without a self-fix as `contract-violated`.
+  - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (Option Candidates / Trade-off Matrix / Recommended Option / Stage Map and per-stage sections / Dependency / Validation Checklist / Rollback / Requirement Coverage) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `prompts/lead/plan-body-verification.md`. The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. **Enforced:** `validators/validate-run.py` `_validate_plan_body_gate_recompute` re-derives the gate from `planItems[].verdicts` and fails when the declared `gateResult` claims a healthier outcome than the recorded votes support; `_validate_plan_item_extraction_completeness` fails when any plan-body deliverable category is under-extracted into `planItems`, so a dropped item can no longer dodge the gate. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture"). Among the majority-disagree items, those that are majority-`planner-fixable` go through report-writer self-fix rounds (`prompts/lead/plan-body-verification.md` "Self-fix round"). A `planner-fixable` item that survives the budget is **not** promoted to the user — it becomes a Working Assumption in `## 5. Missing Information and Risks` and folds into `passed-with-dissent`, because a defect the planner could have fixed is not a user decision. Only majority-`needs-user-input` items, and correctness-critical defects (`DISAGREE` kinds `a` / `d`, or `f` on `P-Req-*`) regardless of fixability, become `Blocks=approval` clarifications. `validators/validate-run.py` `_validate_self_fix_before_clarification` fails a planner-fixable majority item promoted without a self-fix as `contract-violated`.
   - **Decision-record evaluation (sole owner)**: this phase is the **single owner** of decision-record evaluation in the okstra lifecycle. The brief never evaluates or drafts decision records — it only forwards `adr-candidate:*` signals. Every `adr-candidate:*` entry inherited from the brief's `Open Questions` is a mandatory evaluation target. In addition, evaluate every decision the recommended option introduces against the three criteria:
     1. **Hard to reverse** — would changing the decision later cost meaningfully more than deciding now?
     2. **Surprising without context** — would a future reader, seeing only the code, wonder "why was it built this way?"?

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -830,9 +830,40 @@ def _implementation_executor_tail(
     selfcheck_path = profiles / "_implementation-self-check.md"
     if selfcheck_path.is_file():
         parts.append(selfcheck_path.read_text(encoding="utf-8"))
+    parts.extend(_clarification_response_section(manifest, active_context, project_root))
     return "\n\n".join(parts)
 
 
+def _clarification_response_section(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    project_root: Path,
+) -> list[str]:
+    """The user's answers, inlined for a CLI executor.
+
+    A CLI worker runs in its own process and receives only the prompt text, so
+    a path reference never reaches it. Passing the clarification response as a
+    path meant the executor implemented the pre-answer plan while the report
+    described the answers as carried in — the user answered and nothing
+    downstream acted on it.
+    """
+    relative = _instruction_path(manifest, active_context, "clarificationResponsePath")
+    if not relative:
+        return []
+    path = _resolve_project_path(project_root, relative)
+    if not path.is_file():
+        return []
+    body = path.read_text(encoding="utf-8").strip()
+    if not body:
+        return []
+    return [
+        "# Clarification answers carried in (authoritative)\n\n"
+        "The user answered these before this run. Where an answer conflicts "
+        "with the approved plan text, the answer wins — implement the answer "
+        f"and say so in your result.\n\nSource: `{relative}`\n\n{body}"
+    ]
+
+
 def _resolve_report_language(
     project_root: Path,
     manifest: Mapping[str, Any],

package/runtime/python/okstra_ctl/conformance.py

@@ -16,6 +16,23 @@ from dataclasses import dataclass
 
 # diff 가 건드린 표면과 대조할 capability 태그 화이트리스트.
 CAPABILITY_WHITELIST: tuple[str, ...] = ("db", "io", "http", "external")
+EXTERNAL_ADVISORY_CAPABILITIES: frozenset[str] = frozenset(
+    {"db", "http", "external"}
+)
+
+
+def is_advisory_conformance_entry(entry: object) -> bool:
+    """Return whether one entry depends on user-owned external QA."""
+    if not isinstance(entry, dict):
+        return False
+    requires = entry.get("requires")
+    if not isinstance(requires, list):
+        return False
+    return bool(
+        EXTERNAL_ADVISORY_CAPABILITIES.intersection(
+            capability for capability in requires if isinstance(capability, str)
+        )
+    )
 
 
 def _check_nonempty_str(value: object, path: str, errors: list[str]) -> bool:
@@ -138,9 +155,9 @@ def parse_qa_result(stdout: str) -> QaResult:
 @dataclass
 class ConformanceVerdict:
     stage_key: str
-    status: str        # "PASS" | "BLOCKING" | "WAIVED" | "EXEMPT"
-    ok: bool           # 진행 허용 여부 (PASS/WAIVED/EXEMPT 면 True)
-    conditional: bool  # WAIVED 일 때만 True — conformance 미검증(사용자 확인)
+    status: str        # "PASS" | "ADVISORY" | "BLOCKING" | "WAIVED" | "EXEMPT"
+    ok: bool           # True when the gate permits progress.
+    conditional: bool  # True only for a user-confirmed blocking-entry waiver.
     message: str
 
 
@@ -152,21 +169,24 @@ def _waiver_covers_entry(waiver: dict, entry: dict) -> bool:
     요구하는 모든 capability(`requires`)가 scope 안에 들어올 때만 entry 가 완전히
     가려진다. scope 밖 capability 를 entry 가 건드리면 waiver 가 덮지 못하므로
     결과로 정상 게이트해야 한다(예: `db` 만 waive 한 run 에서 `http` 는 계속 게이트)."""
+    requires = entry.get("requires")
+    required = {c for c in requires if isinstance(c, str)} if isinstance(requires, list) else set()
+    if not required:
+        return False
     scope = waiver.get("scope")
     if not isinstance(scope, list) or not scope:
         return True
-    requires = entry.get("requires")
-    required = {c for c in requires if isinstance(c, str)} if isinstance(requires, list) else set()
     return required.issubset({c for c in scope if isinstance(c, str)})
 
 
 def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
-    """단일 stage entry + 실행 결과(`QaResult | None`)로 게이트 판정.
+    """Determine the gate verdict from one stage entry and its result.
 
-    우선순위: exemption → (entry 를 덮는) waiver → 결과 평가. 미실행/MISSING/FAIL
-    은 BLOCKING. 면제·waiver 의 형태 검증은 `validate_conformance_manifest` 가
-    이미 보장한다. capability-scoped waiver 는 scope 가 entry.requires 를 전부
-    덮을 때만 적용되고, 그렇지 않으면 결과로 정상 게이트한다(`_waiver_covers_entry`).
+    Precedence is exemption, advisory waiver, blocking waiver, then result
+    evaluation. A PASS result passes. For unexecuted, missing, or failed results,
+    external-capability entries are ADVISORY with user-owned follow-up; all other
+    entries are BLOCKING. Manifest validation already guarantees valid exemption
+    and waiver shapes.
     """
     key = entry.get("stageKey", "<unknown>")
     exemption = entry.get("exemption")
@@ -175,8 +195,15 @@ def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
             key, "EXEMPT", True, False,
             f"conformance exempted: {exemption.get('reason', '')}",
         )
+    advisory = is_advisory_conformance_entry(entry)
     waiver = entry.get("waiver")
-    if waiver and _waiver_covers_entry(waiver, entry):
+    if advisory and waiver and _waiver_covers_entry(waiver, entry):
+        return ConformanceVerdict(
+            key, "ADVISORY", True, False,
+            f"external conformance not run by user waiver: "
+            f"{waiver.get('reason', '')}",
+        )
+    if not advisory and waiver and _waiver_covers_entry(waiver, entry):
         return ConformanceVerdict(
             key, "WAIVED", True, True,
             f"conformance waived by {waiver.get('acknowledgedBy', '?')}: "
@@ -185,6 +212,17 @@ def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
     overall = getattr(result, "overall", None)  # None when result is None → "never ran"
     if overall == "PASS":
         return ConformanceVerdict(key, "PASS", True, False, "conformance PASS")
+    if advisory:
+        if overall is None:
+            reason = "external conformance did not run"
+        elif overall == "MISSING":
+            reason = "external conformance emitted no QA-RESULT marker"
+        else:
+            reason = f"external conformance {overall}"
+        return ConformanceVerdict(
+            key, "ADVISORY", True, False,
+            f"{reason} (user-owned follow-up; non-blocking)",
+        )
     if overall is None:
         return ConformanceVerdict(
             key, "BLOCKING", False, False,

package/runtime/python/okstra_ctl/report_finalize.py

@@ -292,12 +292,18 @@ def run_finalize(
     ctx: FinalizeContext,
     *,
     before_step: Callable[[str], None] | None = None,
+    only: Sequence[str] | None = None,
 ) -> dict[str, Any]:
     """Run the Phase 7 steps in order, stopping at the first non-zero exit.
 
     ``before_step`` fires immediately before each step is spawned, letting an
     adapter settle state the step will read (the Codex adapter marks the report
     writer `completed` before `validate-run` inspects team-state).
+
+    ``only`` restricts the run to the named steps, preserving contractual
+    order. The last step (`validate-run`) is the one that usually fails, and
+    re-running the whole sequence to retry it repeats three idempotent steps
+    at full token and wall-clock cost.
     """
     steps: list[dict[str, Any]] = []
     try:
@@ -305,6 +311,17 @@ def run_finalize(
     except FinalizeError as exc:
         return {"ok": False, "reason": str(exc), "steps": steps}
 
+    if only:
+        selected = set(only)
+        unknown = sorted(selected - set(STEP_ORDER))
+        if unknown:
+            return {
+                "ok": False,
+                "reason": f"unknown finalize step(s): {', '.join(unknown)}",
+                "steps": steps,
+            }
+        commands = [(name, cmd) for name, cmd in commands if name in selected]
+
     for name, command in commands:
         if before_step is not None:
             before_step(name)
@@ -374,9 +391,34 @@ def _parser() -> argparse.ArgumentParser:
         default="",
         help="defaults to the run manifest's teamStatePath",
     )
+    parser.add_argument(
+        "--only",
+        action="append",
+        default=[],
+        choices=list(STEP_ORDER),
+        help=(
+            "run only these steps (repeatable, contractual order preserved). "
+            "Use `--only validate-run` to retry the step that usually fails "
+            "without repeating the three idempotent ones before it."
+        ),
+    )
     return parser
 
 
+def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
+    """One human-readable line per step, so the outcome is legible without
+    parsing the JSON payload."""
+    lines = []
+    for step in result.get("steps") or []:
+        code = step.get("exitCode")
+        mark = "ok  " if code == 0 else "FAIL"
+        lines.append(f"  [{mark}] {step.get('name')} (exit {code})")
+    for name in STEP_ORDER:
+        if not any(s.get("name") == name for s in (result.get("steps") or [])):
+            lines.append(f"  [skip] {name}")
+    return lines
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
@@ -384,10 +426,19 @@ def main(argv: Sequence[str] | None = None) -> int:
     except FinalizeError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
-    result = run_finalize(ctx)
+    result = run_finalize(ctx, only=args.only or None)
     print(json.dumps(result, indent=2, ensure_ascii=False))
+    print("finalize steps:", file=sys.stderr)
+    for line in _step_summary_lines(result):
+        print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
+        if result.get("steps"):
+            print(
+                "retry just the failing step with "
+                f"`--only {result['steps'][-1].get('name')}`",
+                file=sys.stderr,
+            )
         return 1
     return 0
 

package/runtime/python/okstra_ctl/report_views.py

@@ -513,6 +513,7 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
     )
 
     narrow_cols = _narrow_columns(header_cells, rows)
+    path_cols = _path_columns(header_cells)
     # `User input` carries the embedded form widget (textarea / select /
     # input) which needs all the horizontal space it can get; its
     # markdown plain text is empty or a short placeholder so the auto
@@ -523,7 +524,7 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
     head = (
         "<thead><tr>"
         + "".join(
-            f"<th{_col_class(idx, narrow_cols)}>{_inline(c)}</th>"
+            f"<th{_col_class(idx, narrow_cols, path_cols)}>{_inline(c)}</th>"
             for idx, c in enumerate(header_cells)
         )
         + "</tr></thead>"
@@ -562,7 +563,7 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
                     )
                 else:
                     cells_html.append(
-                        f"<td{_col_class(idx, narrow_cols)}>{_inline(cell)}</td>"
+                        f"<td{_col_class(idx, narrow_cols, path_cols)}>{_inline(cell)}</td>"
                     )
             body_rows.append(
                 f'<tr id="{html.escape(meta.row_id.lower())}" '
@@ -579,7 +580,7 @@ def _emit_table(lines: list[str], start: int, section_path: list[str]) -> tuple[
             body_rows.append(
                 tr_open
                 + "".join(
-                    f"<td{_col_class(idx, narrow_cols)}>{_inline(c)}</td>"
+                    f"<td{_col_class(idx, narrow_cols, path_cols)}>{_inline(c)}</td>"
                     for idx, c in enumerate(row)
                 )
                 + "</tr>"
@@ -921,8 +922,30 @@ def _narrow_columns(
     return narrow
 
 
-def _col_class(col_idx: int, narrow_cols: set[int]) -> str:
-    return ' class="td-narrow"' if col_idx in narrow_cols else ""
+def _col_class(col_idx: int, narrow_cols: set[int], path_cols: set[int]) -> str:
+    if col_idx in narrow_cols:
+        return ' class="td-narrow"'
+    if col_idx in path_cols:
+        return ' class="td-path"'
+    return ""
+
+
+# A repo-relative path has no spaces, so `overflow-wrap: anywhere` puts its
+# min-content width at one character and the auto table layout hands the
+# column almost nothing while a prose neighbour takes the rest — the path
+# then renders one or two characters per line. `td-path` floors the width.
+_PATH_HEADER_PREFIXES: tuple[str, ...] = ("path", "파일 경로", "경로")
+
+
+def _path_columns(header_cells: list[str]) -> set[int]:
+    return {
+        col
+        for col, header in enumerate(header_cells)
+        if _INLINE_MD_STRIP_RE.sub("", header or "")
+        .strip()
+        .lower()
+        .startswith(_PATH_HEADER_PREFIXES)
+    }
 
 
 _DANGEROUS_URL_SCHEME_RE = re.compile(
@@ -960,6 +983,10 @@ def _inline(text: str) -> str:
     # markdown source intentionally stacks short fields with <br>). html.escape
     # above turned them into &lt;br&gt;; restore the tag.
     out = out.replace("&lt;br&gt;", "<br>").replace("&lt;br/&gt;", "<br>").replace("&lt;br /&gt;", "<br>")
+    # `<small>` demotes a cell's technical detail line below its plain-language
+    # first line (File Structure `details`). Allowlisted alongside <br>; every
+    # other tag stays escaped.
+    out = out.replace("&lt;small&gt;", "<small>").replace("&lt;/small&gt;", "</small>")
     return out