okstra 0.196.0 → 0.197.1

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -83,16 +83,59 @@ WORKER_ERROR_CONTRACT_FILENAME = "worker-error-contract.md"
 # 따르되 라운드 원장 밖이라 번호가 없다. 실측(2026-09-09 dev-10642): 이 kind 가
 # 없어 gap 검증 프롬프트를 만들 수 없었고 gap 3건 전부 `gapsUnverified` 로 남았다.
 CRITIC_VERIFY_DISPATCH_KIND = "critic-verify"
+REVERIFY_DISPATCH_KIND_PREFIX = "reverify-r"
+# 계획 본문 검증(§5.5.9) 라운드의 dispatch kind. 결과 파일명 규약이 이미
+# `<role>-worker-plan-verify-r<N>-…` 이라(`plan-body-verification.md` §"Round
+# protocol", `dispatch_state._plan_verify_result_workers`) kind 도 같은 번호를
+# 단다. 실측(2026-09-09 dev-10642 implementation-planning 001): 이 kind 가 없어
+# 계획 항목 큐를 `reverify-r<N>` 으로 보낼 수밖에 없었고, 그러면 검증 계약이
+# `okstra convergence reverify-prompt` 서명을 요구하는데 계획 항목 큐의 정본
+# 렌더러는 `okstra plan-items prompt` 라 통과할 값이 하나도 없었다. 라운드가
+# 한 번도 열리지 못한 채 `planBodyVerification.roundCount` 가 0 으로 남았다.
+PLAN_VERIFY_DISPATCH_KIND_PREFIX = "plan-verify-r"
+
+
+def _numbered_round(dispatch_kind: str, prefix: str) -> int | None:
+    """`<prefix><N>` 의 N. 접두사가 다르거나 N 이 양의 정수가 아니면 None."""
+    if not dispatch_kind.startswith(prefix):
+        return None
+    suffix = dispatch_kind[len(prefix):]
+    if not suffix.isdigit() or int(suffix) < 1:
+        return None
+    return int(suffix)
 
 
 def is_verification_dispatch_kind(dispatch_kind: str) -> bool:
-    """번호 reverify 라운드와 critic gap 검증 — 검증 프롬프트 계약을 받는 kind."""
+    """번호 reverify·계획 본문 라운드와 critic gap 검증 — 검증 프롬프트 계약을
+    받는 kind."""
     return (
-        dispatch_kind.startswith("reverify-r")
+        dispatch_kind.startswith(REVERIFY_DISPATCH_KIND_PREFIX)
+        or dispatch_kind.startswith(PLAN_VERIFY_DISPATCH_KIND_PREFIX)
         or dispatch_kind == CRITIC_VERIFY_DISPATCH_KIND
     )
 
 
+def is_plan_verify_dispatch_kind(dispatch_kind: str) -> bool:
+    """계획 본문 검증 라운드인가. 검증 계약이 요구하는 렌더러 서명이 번호
+    reverify 와 다르므로 계약 검사가 이 둘을 갈라야 한다."""
+    return _numbered_round(dispatch_kind, PLAN_VERIFY_DISPATCH_KIND_PREFIX) is not None
+
+
+def verification_dispatch_round(dispatch_kind: str) -> int | None:
+    """검증 kind 가 적는 라운드 번호. 번호 없는 kind(`critic-verify`)는 1,
+    검증 kind 가 아니거나 번호가 깨졌으면 None.
+
+    예약(`agent-prompt materialize`)과 디스패치가 같은 값을 적어야 한다 —
+    validate-run 이 team-state 의 kind 와 예약된 invocation 의 `dispatchKind`
+    를 대조하므로, 두 계산이 갈리면 그 디스패치가 거부된다."""
+    if dispatch_kind == CRITIC_VERIFY_DISPATCH_KIND:
+        return 1
+    for prefix in (REVERIFY_DISPATCH_KIND_PREFIX, PLAN_VERIFY_DISPATCH_KIND_PREFIX):
+        if dispatch_kind.startswith(prefix):
+            return _numbered_round(dispatch_kind, prefix)
+    return None
+
+
 @dataclass(frozen=True)
 class PromptPlan:
     audience: PromptAudience

package/runtime/skills/okstra-brief-gen/SKILL.md

@@ -1024,13 +1024,30 @@ per-page ratio instead of origin load). If the file is absent, ask once via
 - `Skip — this group needs no shared context`.
 
 Never fill the skeleton yourself from the tickets: a ticket summary decides
-nothing, and the sections ask for what the tickets do not say. If the file
-exists, leave it untouched and mention its path in the hand-off block. The
-file's trailing `## Task Memory` region (between `<!-- okstra:task-memory:begin -->`
-and `end`) is okstra's: `report-finalize` rewrites it after every run with the
-group's start order and each task's latest conclusion, and a group whose
-runs finished before anyone created the file already has one holding that
-region alone — `init` then inserts the human sections above it.
+nothing, and the sections ask for what the tickets do not say.
+
+If the file exists, what you do with it depends on what you are writing:
+
+- **A new brief** leaves it untouched. Mention its path in the hand-off block.
+- **A rewrite or correction of an existing brief** reconciles it in the same
+  response, whenever the change supersedes something the group document
+  states — a Definition of Better figure, a success signal, a Group-Wide
+  Constraint, a Ticket Relation, or what it says is executable from the
+  project root. okstra copies this file into every run's
+  `instruction-set/task-group-context.md` and carries it in the analysis
+  packet **ahead of the brief extract**, so a sentence you corrected in the
+  brief is still outranked by the group document's stale copy of it. Qualify a
+  diverged figure with the date and method of the measurement that contradicts
+  it rather than deleting it, and name the brief the correction came from.
+
+Either way, edit only the authored sections. The file's trailing `## Task Memory`
+region (between `<!-- okstra:task-memory:begin -->` and `end`) is okstra's: it
+holds the group's start order and each task's latest conclusion, and okstra
+redraws it after every run's `report-finalize`, at `okstra set-work-status`, and
+before each run copies the file into its instruction set. Anything written there
+by hand is overwritten without warning. A group whose runs finished before
+anyone created the file already has one holding that region alone — `init` then
+inserts the human sections above it.
 
 Then stop. Do not invoke `okstra-run` directly — the user chooses when to
 proceed, and they may want to edit the brief externally first. In the

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -6,7 +6,7 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
 
-On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline / `group-context.md`.
+On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs the `recap-log.jsonl` append, the `notes/` note authoring (recap.5), and the group-context reconciliation that note triggers (recap.6); it never mutates `task-manifest.json` / catalog / timeline, and it touches `group-context.md` only in the authored sections above the `<!-- okstra:task-memory:begin -->` marker.
 
 ### recap.1 — Resolve target
 
@@ -144,3 +144,19 @@ Write the body to the scratchpad as markdown first, then pass it with `--body-fi
 4. **`notes/` is inert to okstra** — no run reads it automatically. After writing, relay the `clarificationResponseArg` the CLI printed (e.g. `--clarification-response <notePath>`) to the user verbatim, telling them it only takes effect when the next run is executed with that argument.
 
 **Guardrail:** `.okstra/` is gitignored — treat `notes/` as local scratch and never `git add` it. Creating a new note is easy to undo (delete the file), so always prefer it over editing a generated or user-owned file.
+
+### recap.6 — Reconcile the task-group context (required whenever recap.5 writes a note)
+
+A group's shared context does not stay true while its tasks run. Figures get re-measured, a success signal turns out to be satisfiable without a fix, a constraint names the wrong place. `group-context.md` states in its own header that okstra copies it into each run's `instruction-set/task-group-context.md` and carries it in the analysis packet's `## Task-Group Context` section, **ahead of the brief extract** — so a stale sentence there outranks a corrected brief for every task in the group.
+
+**After writing a note, read `<PROJECT_ROOT>/.okstra/briefs/<task-group>/group-context.md` if it exists.** If anything the note establishes touches its Definition of Better figures, success signals, Group-Wide Constraints, Ticket Relations, or its statement of what is executable from the project root, update those sections **in the same response that wrote the note**. A note written without that check is an incomplete deliverable, the same way a `.project-docs/` document without its index row is.
+
+Three rules for the edit:
+
+1. **Only above the marker.** Edit the authored sections above `<!-- okstra:task-memory:begin -->`. The region below is okstra's projection — start order, per-task status, recorded runs — and it is redrawn from the task manifests at every `report-finalize`, at `okstra set-work-status`, and before each run copies the file. Anything you write there is overwritten without warning.
+2. **Qualify a diverged figure; do not delete it.** An audit number is the baseline for the window it was measured in, not a current reading. Where a direct measurement contradicts it, say so with the measurement's date and method, and keep both. Deleting the old figure destroys the reason the group exists.
+3. **Say which task and note the correction came from.** The next reader needs to get from the sentence back to its evidence.
+
+If the group has no `group-context.md`, do not create one here — `okstra group-context init` (via okstra-brief-gen) owns that skeleton, and creating an empty one pre-empts the sections a human meant to author.
+
+The same exposure applies to any other edit that supersedes group-wide facts, a brief rewrite most of all. Treat this check as belonging to the fact, not to this sub-command.

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

@@ -53,7 +53,7 @@ The wizard tells you which relay operation to use via `next.interaction.kind`. S
 - `kind: "done"` → input collection finished; move to Step 5.
 - `kind: "aborted"` → the user picked abort; the wizard is terminally cancelled. Tell the user on one short line that the run setup was aborted, delete the state file (`rm` with the literal path), and stop this skill — do NOT call `render-args` or `render-bundle` (the wizard rejects `render-args` on an aborted state).
 
-When native single selection is available, the runtime divides long lists and unsupported multi-selections into selectable screens. Render the returned screen without rebuilding the full list. This applies to plan confirmation, stages, role counts, and provider/model lists. Submit navigation and completion option values normally; the runtime retains the current step until its answer is complete. A ban on textual choice lists does not authorize asking the user to type a model identifier. If a required selector is unavailable, preserve state and follow the relay's recovery. Genuine text steps still collect text.
+When native single selection is available, the runtime divides long lists and unsupported multi-selections into selectable screens. Render the returned screen without rebuilding the full list. This applies to plan confirmation, stages, role counts, and provider/model lists. Submit navigation and completion option values normally; the runtime retains the current step until its answer is complete. A ban on textual choice lists does not authorize asking the user to type a model identifier. If a required selector is unavailable, preserve state and follow the relay's `recovery` object. Genuine text steps still collect text.
 
 Submit the answer shape required by `interaction.answerProtocol`; do not add normalization beyond the registered relay's explicit mapping. Invalid, out-of-range, or ambiguous answers return `ok: false` and must re-render the same complete interaction.
 
@@ -83,11 +83,11 @@ On `Okstra preflight: ready`, require `Runtime readiness: ready` before Step 2.
 
 Carry the fixed `Lead entry mode` line into Step 2's `--entry-mode` as a literal. It is the mode the run must launch in, which is not always the mode this session is in: a host adapter may report that this session cannot host the lead while the run itself is ready. `spawn-process` means okstra starts its own lead process and this session is not the lead — when the line reads `spawn-process` and a readiness check carries `action: spawn-unsandboxed-codex-lead`, tell the user in one line that their current Codex session is sandboxed so okstra will open an unsandboxed lead instead, then continue. Never substitute `current-session` for a `spawn-process` answer, and never recompute the value from the host ID.
 
-For a ready response, read the absolute path in the fixed `Relay contract` line with the current host's file-read primitive. Do not derive the path from the host ID or search `PATH`. In that file, find the `Wizard interaction relay` JSON block, require `schemaVersion: 1` and `runtime` equal to the fixed `Runtime` line, then take its `semanticFunctions` allowlist and intersect it with the functions the live harness exposes. The live harness does not expose tools named `native_single_select`. Map each allowlist token to the matching `interactions` kind (`native_single_select` → `native-single`, `native_multi_select` → `native-multi`, `native_question_group` → `native-group`). Include the token in the intersection only when this session can call the string in that kind's `function` field. If the kind is absent from `interactions`, omit the token. Pass only that intersection to Step 2; `plain_text_input` must be present. Keep the parsed `interactions` object for Step 3's function/input/response conversion. An unreadable file, malformed block, runtime mismatch, absent `plain_text_input`, or later interaction kind missing from the object is a host relay contract failure: show the problem and stop rather than guessing.
+For a ready response, read the absolute path in the fixed `Relay contract` line with the current host's file-read primitive. Do not derive the path from the host ID or search `PATH`. In that file, find the `Wizard interaction relay` JSON block, require `schemaVersion: 1` and `runtime` equal to the fixed `Runtime` line, then take its `semanticFunctions` allowlist and intersect it with the functions the live harness exposes. The live harness does not expose tools named `native_single_select`. Map each allowlist token to the matching `interactions` kind (`native_single_select` → `native-single`, `native_multi_select` → `native-multi`, `native_question_group` → `native-group`). Include the token in the intersection only when this session can call the string in that kind's `function` field. If the kind is absent from `interactions`, omit the token. Pass only that intersection to Step 2; `plain_text_input` must be present. Keep the parsed `interactions` object for Step 3's function/input/response conversion, and the parsed `recovery` object for the branch below. An unreadable file, malformed block, runtime mismatch, absent `plain_text_input`, or later interaction kind missing from the object is a host relay contract failure: show the problem and stop rather than guessing.
 
 If the successful fixed projection has `Relay contract: -`, enter the compatibility branch below. In that branch only, declare `plain_text_input` and keep its built-in `interactions` mapping for Step 3; do not assume a native tool from the host ID. The existing `unknown command: preflight` branch remains the authoritative stale-CLI failure.
 
-Before calculating the effective intersection, apply the registered relay's client-specific tool selection and live mode restrictions. A callable question tool does not necessarily render a selector in the current client. In Codex, use the synchronous picker when permitted; asynchronous question cards are a desktop fallback, not a terminal picker. If the user requires a selectable interface and the current client cannot provide it, preserve the wizard state and follow the relay's recovery instead of printing the option list.
+Before calculating the effective intersection, apply the registered relay's client-specific tool selection and live mode restrictions. A callable question tool does not necessarily render a selector in the current client. In Codex, use the synchronous picker when permitted; asynchronous question cards are a desktop fallback, not a terminal picker. A declared native function can still fail at call time: the client refuses the call, the session has no view to present it in, or it returns no answer. That is not a reason to stop, and not a reason to try a different native function. Follow the relay's `recovery.native-question-refused` entry the first time it happens — drop the tokens it names from the intersection, keep `plain_text_input`, tell the user in one line that the host picker is unavailable, and render every remaining screen through the text mapping. Numbered text is that entry's own recovery path, so the ban on printing a numbered list does not apply once it fires. The wizard state file is untouched by a refused call: `okstra wizard step --state-file <path> --no-submit` returns the pending prompt again.
 
 Plan adoption (`approve_plan_confirm`) is a workflow choice: present the wizard's existing options using the same selector as other `pick` steps. Follow the relay's distinction between plan decisions and execution permissions; the word "approval" alone is not a reason to replace a selector with a typed confirmation.
 
@@ -198,7 +198,7 @@ That is the entire interactive flow. The wizard handles:
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number). Implementer slots use role-count / role-model like every other role (`executor` is only a compatibility alias for `implementer`). When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
-- launch selection after identity/worktree steps: one screen per static role, in profile order. A role that can run several instances (`max > 1`) is a checkbox step `role-models:<role>` (`multi: true`) — the number of models checked is the number of instances, there is no separate count question; the label states the profile range and recommended count, every executable candidate is listed on that one screen (defaults first, the recommended set flagged), and when the list exceeds the host's native checkbox limit the runtime either splits it into several checkbox questions on one `pick_group` screen (interaction plan `native-group`; the question steps are `role-models:<role>#1`, `#2`, … and the answer is one JSON object keyed by them, each value a CSV) when the host's native question group holds every option, or returns the interaction plan `numbered-multi` — render the whole list, never a shortlist or pages. An optional role (`min = 0`, e.g. critic) carries a `추가 안 함` row. A fixed single role (`min = max = 1`, e.g. report-writer) is a single pick `role-model:<role>:1`. current-session lead is this session and is listed on the confirmation summary, not as a wizard step. The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. `--workers` is compatibility-only, not a launch picker. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
+- launch selection after identity/worktree steps: one screen per static role, in profile order. A role that can run several instances (`max > 1`) is a checkbox step `role-models:<role>` (`multi: true`) — the number of models checked is the number of instances, there is no separate count question; the label states the profile range and recommended count, every executable candidate is listed on that one screen (defaults first, the recommended set flagged), and when the list exceeds the host's native checkbox limit the runtime either splits it into several checkbox questions on one `pick_group` screen (interaction plan `native-group`; the question steps are `role-models:<role>#1`, `#2`, … and the answer is one JSON object keyed by them, each value a CSV) when the host's native question group holds every option, or returns the interaction plan `numbered-multi` — render the whole list, never a shortlist or pages. An optional role (`min = 0`, e.g. critic) carries a `추가 안 함` row. A fixed single role (`min = max = 1`, e.g. report-writer) is a single pick `role-model:<role>:1`, and a role capped at one model (`max = 1`, e.g. critic) is a single pick on its `role-models:<role>` step; both split the same way when they exceed the native option limit — the tabs are checkbox questions, the answer is the same keyed JSON object, and the wizard rejects a screen whose tabs together name more than one value. current-session lead is this session and is listed on the confirmation summary, not as a wizard step. The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. `--workers` is compatibility-only, not a launch picker. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
 - **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills role-count·role-model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
 - **re-verification scope (`reverify_scope_pick`, `implementation-planning` clarification re-runs only)** — asked right before `confirm` when the re-run is narrowable **or** an answered `C-NNN` traces to no stage. When every answered id traces to a stage: 3 options — `auto` (recommended — leave it to the lead's `okstra incremental-scope` decision) / `full` (re-verify every stage) / Enter directly (a stage-number CSV, validated against the prior report's Stage Map). When an id is unlinked, `auto` is omitted and the user names stages or picks `full`; that unlinked id does not freeze the run at full. The answer goes out as `--reverify-scope` and reaches the lead prompt as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens; it shapes that CLI's inputs rather than replacing the decision. The confirmation block's `reverify-scope` line names unlinked ids as needing stage numbers, not as a forced full re-run,
 - `release-handoff` PR template override + persist scope,
@@ -290,6 +290,65 @@ The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.
 
 You can delete the literal state-file path after this point — its job is done. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` is what keeps a `rm='rm -i'` alias from turning this into a confirmation prompt nobody is there to answer.
 
+<!-- BEGIN FRAGMENT: host-orchestration-implementation-planning -->
+## Host orchestration rules — implementation-planning
+
+These are the rules the **host orchestrator** follows around an
+`implementation-planning` run: when a stage genuinely cannot write a RED step,
+and what only the user can grant. They are not lead phase rules — the lead's
+rules live in `prompts/profiles/`.
+
+### Step 5.1 (implementation-planning only): user-confirmed TDD bypass offer
+
+Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a
+later `GREEN:` step (validator S10c). `tddExemption` waives that, and until
+2026-09-10 only for `doc-only`, `config-only`, or `pure-rename` work — so a
+stage that is truthfully none of the three had no passable value, and the plan
+got through by filing the nearest category. That is the failure this flag
+exists to remove: **a closed reason list with no escape makes the plan
+misdescribe itself.**
+
+`render-bundle` accepts an optional `--tdd-bypass "<stage>:<reason>"` flag
+(implementation-planning only). It records a **user-acknowledged** bypass into
+`<task-root>/qa/tdd-bypass.json`, and S10e then accepts that stage declaring
+`tddExemption: user-bypass`. The reason is stored **verbatim**.
+
+Offer it only when the run's own output says the stage cannot reach RED — a
+planning report blocked at S10e on a `user-bypass` stage, or a plan-body
+verification round whose disagreements say the expected FAIL is unreachable
+(e.g. the stage worktree HEAD is already the accepted commit). Never offer it
+to save a stage that simply has no test written yet; that stage's answer is the
+RED step.
+
+This is **never** a lead/worker self-exemption — only the user may grant it,
+and the lead has no command that writes this record. Surface it as a 3-option
+recommendation picker (per the run-prompt recommendation rule):
+
+1. (recommended) Keep the RED/GREEN requirement — re-plan the stage so its
+   first step writes the failing test.
+2. Bypass this stage — ask the user for the stage number and reason, then pass
+   `--tdd-bypass "<stage>:<reason>"` to `render-bundle` (reason = the user's
+   words, unedited).
+3. Enter directly — the user types the full `<stage>:<reason>` value.
+
+When the user picks a bypass, append `--tdd-bypass "<stage>:<reason>"` to the
+`render-bundle` invocation. Omit the flag entirely otherwise (do **not** pass
+`--tdd-bypass ""`). A malformed value aborts `render-bundle` with a
+`PrepareError`. The grant is per stage number and per task, and it persists
+across runs of that task — the next plan of the same stage may still declare
+`user-bypass` until the user's grant is removed from the ledger.
+
+**A stage whose work already landed is usually not a bypass case.** When the
+product change is committed and its conformance result is PASS but the stage
+never registered as done, the honest fix is to close that stage rather than to
+re-plan it without a RED step. Check `okstra stage-map <task-key>` first: when
+`doneStages` omits a stage whose commit is on the stage branch, close it with
+`okstra stage-close <task-key> --stage <N> --from-commit <sha>` and re-plan only
+what is left. That command refuses unless the commit exists and the stage's
+conformance gate permits progress, so it cannot close a stage the run validator
+would have blocked.
+<!-- END FRAGMENT: host-orchestration-implementation-planning -->
+
 <!-- BEGIN FRAGMENT: host-orchestration-implementation -->
 ## Host orchestration rules — implementation
 

package/runtime/templates/reports/group-context.template.md

@@ -31,7 +31,7 @@ generator: okstra-brief-gen
 <Which tickets are causes, which are observation means, which depend on which. Write `_(none)_` when the briefs' Related Task Graph already says it all.>
 
 <!-- okstra:task-memory:begin -->
-<!-- okstra rewrites this region at every report-finalize. Edit the sections above it, not this one. -->
+<!-- okstra redraws this region after every report-finalize, at `okstra set-work-status`, and before each run copies this file. Edit the sections above it, not this one. -->
 ## Task Memory
 
 _(no runs recorded yet)_

package/runtime/validators/validate-implementation-plan-stages.py

@@ -21,6 +21,11 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
+from okstra_ctl.tdd_bypass import (  # noqa: E402
+    REASON_TOKEN as TDD_USER_BYPASS_TOKEN,
+    bypass_file,
+    granted_stages,
+)
 from okstra_ctl.stage_map import (  # noqa: E402
     STAGE_MAP_HEADING,
     StageMapError,
@@ -185,6 +190,15 @@ TDD_EXEMPTION = re.compile(_LABEL_PREFIX + r"TDD exemption\s*:\s*(?:\*\*)?\s*(.+
 # Profile implementation-planning.md:81 limits the exemption to these three
 # categories; any other reason (e.g. "refactor") must not waive RED/GREEN.
 TDD_EXEMPTION_ALLOWED = ("doc-only", "config-only", "pure-rename")
+# The fourth reason is not a category the plan may assert on its own: it holds
+# only while `<task-root>/qa/tdd-bypass.json` records the user's grant for that
+# stage. Every caller therefore passes the granted stage numbers in, and a plan
+# naming the token with no grant fails S10e like any arbitrary reason. Without
+# it a stage that is genuinely none of the three has no passable value and the
+# plan misdescribes itself to get through (2026-09-10, fontsninja-v3-site
+# dev-10628-3: product work already committed and conformance-proved in a prior
+# run of the same stage, filed as `config-only`).
+TDD_EXEMPTION_USER_BYPASS = TDD_USER_BYPASS_TOKEN
 TEST_CASE_CATEGORIES = ("success", "boundary", "failure")
 TEST_CASE = {
     cat: re.compile(
@@ -196,18 +210,48 @@ CONFORMANCE_TESTS = re.compile(_LABEL_PREFIX + r"Conformance tests\s*:\s*(?:\*\*
 CONFORMANCE_EXEMPTION = re.compile(_LABEL_PREFIX + r"Conformance exemption\s*:\s*(?:\*\*)?\s*\S", re.M)
 
 
-def _exemption_reason_allowed(section: str) -> bool:
-    """True when a `TDD exemption:` line is present AND its reason names an
-    allowed category (doc-only / config-only / pure-rename, case-insensitive).
-    A present-but-unlisted reason returns False so S10e can reject it."""
+def _exemption_reason_message(stage_number: int) -> str:
+    """S10e 의 거절 문구. 통과할 수 있는 값을 전부 이름으로 말한다.
+
+    사유 목록만 나열하면 세 카테고리 중 어느 것도 사실이 아닌 stage 는
+    거짓 신고 외에 길이 없다. 네 번째 값과 그 값을 얻는 명령을 함께 적어
+    다음 행동이 문구 안에 있게 한다.
+    """
+    return (
+        "S10e: 'tddExemption' reason must be one of "
+        + " / ".join(TDD_EXEMPTION_ALLOWED)
+        + f" — or `{TDD_EXEMPTION_USER_BYPASS}`, which holds only while the "
+        "user has granted it for this stage: re-run prepare with "
+        f'`--tdd-bypass "{stage_number or 1}:<reason>"` so the reason is '
+        "recorded verbatim in <task-root>/qa/tdd-bypass.json. An empty or "
+        "arbitrary reason cannot waive RED/GREEN and the three test cases"
+    )
+
+
+def _exemption_reason_allowed(
+    section: str, *, stage_number: int = 0, user_bypassed: frozenset[int] = frozenset(),
+) -> bool:
+    """True when a `TDD exemption:` line is present AND its reason is allowed.
+
+    Allowed means one of the three categories (doc-only / config-only /
+    pure-rename, case-insensitive), or `user-bypass` for a stage the user
+    granted — that grant lives outside the plan, so it is passed in.
+    A present-but-unlisted reason returns False so S10e can reject it.
+    """
     m = TDD_EXEMPTION.search(section)
     if not m:
         return False
     reason = m.group(1).lower()
+    if TDD_EXEMPTION_USER_BYPASS in reason:
+        return stage_number in user_bypassed
     return any(cat in reason for cat in TDD_EXEMPTION_ALLOWED)
 
 
-def _check_slice_tdd(text: str, stages: List[StageMapStage]) -> List[ValidationError]:
+def _check_slice_tdd(
+    text: str,
+    stages: List[StageMapStage],
+    user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """S10: each stage declares a vertical slice and follows RED→GREEN ordering.
 
     S10a — `Slice value:` line with a non-empty value.
@@ -237,11 +281,11 @@ def _check_slice_tdd(text: str, stages: List[StageMapStage]) -> List[ValidationE
                 "S10b: 'Acceptance:' line missing or empty"))
 
         if TDD_EXEMPTION.search(section):
-            if not _exemption_reason_allowed(section):
+            if not _exemption_reason_allowed(
+                section, stage_number=s.stage_number, user_bypassed=user_bypassed,
+            ):
                 errs.append(ValidationError("S10", s.stage_number,
-                    "S10e: 'TDD exemption:' reason must be one of "
-                    "doc-only / config-only / pure-rename — an arbitrary reason "
-                    "cannot waive RED/GREEN"))
+                    _exemption_reason_message(s.stage_number)))
             continue
 
         missing_cases = [
@@ -419,7 +463,9 @@ def _check_parallel_safety(
     })
 
 
-def collect_validation_errors(text: str) -> List[ValidationError]:
+def collect_validation_errors(
+    text: str, user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """All S1–S11 checks against the report text; empty list means valid.
 
     S1 (missing `## 5.5 Stage Map` heading) makes the rest unparseable, so it
@@ -437,7 +483,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
         return [ValidationError("S2", 0, exc.reason)]
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
-        errors.extend(_check_slice_tdd(text, stages))
+        errors.extend(_check_slice_tdd(text, stages, user_bypassed))
         errors.extend(_check_markdown_step_commands(text, stages))
         errors.extend(_check_conformance_declaration(text, stages))
         errors.extend(_check_depends_on(stages))
@@ -465,7 +511,9 @@ def _data_stage_metas(
     return rows, _stage_numbers_monotonic(rows)
 
 
-def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
+def _check_data_slice_tdd(
+    stage: dict, user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """S10c / S10e over one schema-v2 `stages[]` entry.
 
     The schema already requires `sliceValue`, `acceptance`, and — through its
@@ -479,12 +527,12 @@ def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
     number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
     if "tddExemption" in stage:
         reason = str(stage.get("tddExemption") or "").lower()
+        if TDD_EXEMPTION_USER_BYPASS in reason:
+            if number in user_bypassed:
+                return []
+            return [ValidationError("S10", number, _exemption_reason_message(number))]
         if not any(cat in reason for cat in TDD_EXEMPTION_ALLOWED):
-            return [ValidationError("S10", number,
-                "S10e: 'tddExemption' reason must be one of "
-                + " / ".join(TDD_EXEMPTION_ALLOWED)
-                + " — an empty or arbitrary reason cannot waive RED/GREEN "
-                "and the three test cases")]
+            return [ValidationError("S10", number, _exemption_reason_message(number))]
         return []
 
     steps = [s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)]
@@ -625,7 +673,9 @@ def _check_data_stage_identities(
     return errs
 
 
-def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
+def collect_data_validation_errors(
+    planning: dict, user_bypassed: frozenset[int] = frozenset(),
+) -> List[ValidationError]:
     """The S-checks that schema v2 cannot express, over `implementationPlanning`.
 
     `collect_validation_errors` scans rendered v1 Markdown, which a v2 report
@@ -663,7 +713,7 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
         if not meta.depends_on
     }))
     for stage in stages:
-        errors.extend(_check_data_slice_tdd(stage))
+        errors.extend(_check_data_slice_tdd(stage, user_bypassed))
         number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
         for step in stage.get("stepwiseExecution") or []:
             if isinstance(step, dict):
@@ -671,26 +721,62 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     return errors
 
 
-def collect_plan_errors(plan_path: Path) -> List[ValidationError]:
+def collect_plan_errors(
+    plan_path: Path, user_bypassed: frozenset[int] | None = None,
+) -> List[ValidationError]:
     """The S-checks for one approved plan, whichever schema wrote it.
 
     A schema-v2 report keeps its stage map in the `.data.json` sidecar and
     renders no `## 5.5 Stage Map` section, so scanning its markdown reports the
     section as missing and blocks every run that approved such a plan.
     """
+    granted = (
+        user_bypassed if user_bypassed is not None
+        else user_bypassed_stages_for_plan(plan_path)
+    )
     planning = schema_v2_report(plan_path).get("implementationPlanning")
     if isinstance(planning, dict) and planning:
-        return collect_data_validation_errors(planning)
-    return collect_validation_errors(plan_path.read_text(encoding="utf-8"))
+        return collect_data_validation_errors(planning, granted)
+    return collect_validation_errors(plan_path.read_text(encoding="utf-8"), granted)
+
+
+def user_bypassed_stages_for_plan(plan_path: Path) -> frozenset[int]:
+    """이 계획이 속한 task 의 우회 원장에서 부여된 stage 번호들.
+
+    레이아웃 해석은 `RunRef.from_run_dir` 이 소유한다 — 부모를 세는 계산은
+    배치가 하나만 바뀌어도 조용히 다른 디렉터리를 가리킨다. run 디렉터리로
+    해석되지 않는 입력은 빈 집합이고, 그때는 `--tdd-bypass-ledger` 로 원장을
+    직접 넘기는 것이 경로다. 원장이 없으면 빈 집합 — 우회 없음이다.
+    """
+    from okstra_ctl.paths import RunRef
+
+    try:
+        task_root = RunRef.from_run_dir(plan_path.resolve().parent.parent).task_root
+    except (ValueError, IndexError):
+        return frozenset()
+    return frozenset(granted_stages(bypass_file(task_root)))
 
 
 def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser()
     p.add_argument("--plan", required=True)
+    p.add_argument(
+        "--tdd-bypass-ledger",
+        default="",
+        dest="tdd_bypass_ledger",
+        help=(
+            "path to <task-root>/qa/tdd-bypass.json; defaults to the ledger of "
+            "the task the --plan report lives in"
+        ),
+    )
     args = p.parse_args(argv)
 
+    granted = (
+        frozenset(granted_stages(Path(args.tdd_bypass_ledger)))
+        if args.tdd_bypass_ledger else None
+    )
     try:
-        errors = collect_plan_errors(Path(args.plan))
+        errors = collect_plan_errors(Path(args.plan), granted)
     except StageMapError as exc:
         print(f"S0 stage=0: {exc.reason}", file=sys.stderr)
         return 1