okstra 0.186.7 → 0.187.0

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

@@ -19,7 +19,7 @@ text task blocks as the overview source.
 | `currentStatus` | task-level status |
 | `currentPhase` | lifecycle current phase |
 | `currentPhaseState` | lifecycle phase state |
-| `nextRecommendedPhase` | next-phase pointer — an **object** `{phase, status, rationale}`, never a string. `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready`, but that is an authoring rule, not a constraint the struct enforces — `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal state to read. Decide launchability from `status` alone. Render `phase` (or `--` when it is empty) — never the object itself. |
+| `nextRecommendedPhase` | next-phase pointer — an **object** `{phase, status, rationale}`, never a string. `status` is `ready` / `pending` / `blocked` / `terminal`. `phase` is non-empty only under `ready`, a property of the projection rather than a constraint the struct enforces — `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal state to read. Decide launchability from `status` alone. Render `phase` (or `--` when it is empty) — never the object itself. |
 | `awaitingApproval` | whether awaiting approval |
 | `latestRunStatus` | latest run status |
 | `latestReportRecordPath` | latest report path |
@@ -96,12 +96,13 @@ The status response always includes one of:
 
 1. **Resume current run** — if `latestResumeCommandPath` exists, display that path.
 2. **Ask the user to approve** — if `workflow.awaitingApproval` is true. Tell the user to approve the plan (`okstra-run` with `--task-type implementation`, which asks `approve_plan_confirm`, or `--approve`). Quote `nextRecommendedPhase.rationale`. A `ready` pointer to `implementation` here means implementation is next after approval, not that it may launch as if already approved. Do not re-run `implementation-planning`.
-3. **Restart current phase** — only when `awaitingApproval` is false and the pointer is not `ready`. The task can be re-run with the same `task-key` and current `taskType`.
-Branches 4–6 are decided by `workflow.nextRecommendedPhase.status` when `awaitingApproval` is false — one status, one branch:
+3. **Answer the open clarifications** — after `implementation-planning`, when `latestReportRecordPath` is non-empty and the pointer is not `ready`. Route to `okstra-user-response`; its first step (`okstra user-response list-view`) prints this task's open-item count, and a non-zero count means the report published with `Blocks=approval` rows still open. This branch holds even when `latestRunStatus` reads `contract-violated` / `failed` and the pointer's `rationale` prescribes re-running the phase — the answers are the missing input, so a planning re-run without them reproduces the same block. Do not start implementation.
+4. **Restart current phase** — only when there is nothing to answer: `latestReportRecordPath` is empty, or the open-item count is zero and `latestRunStatus` is `contract-violated`. Only an allowlisted blocking-class failure produces that status; findings demoted to `validation.advisories` leave the run passed and are not a reason to re-run. The task can be re-run with the same `task-key` and current `taskType`.
+Branches 5–7 are decided by `workflow.nextRecommendedPhase.status` when `awaitingApproval` is false — one status, one branch:
 
-4. **Start next phase** — `status` is `ready` and `awaitingApproval` is false. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched without a prior approval ask, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
-5. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. After `implementation-planning`, the first action is `okstra-user-response` on the named `C-NNN` ids; do not re-run planning until those answers exist, and do not start implementation.
-6. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
+5. **Start next phase** — `status` is `ready` and `awaitingApproval` is false. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched without a prior approval ask, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
+6. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. After `implementation-planning`, branch 3 already owns the routing: the `C-NNN` answers come first, and planning is not re-run until they exist.
+7. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
 
 ### status.4 — Update workStatus (write)
 

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

@@ -52,7 +52,7 @@ from this list and nothing else:
 
 `feat/`, `bugfix/`, `chore/`, `hotfix/` are not in the allowlist — do not emit
 them. This mirrors okstra's worktree branch namespace, whose SSOT is
-`_WORK_CATEGORY_NAMESPACE` in `scripts/okstra_ctl/worktree.py`. A branch name
+`_WORK_CATEGORY_NAMESPACE` in `scripts/okstra_ctl/worktree/naming.py`. A branch name
 the user states explicitly wins verbatim; never rewrite it.
 
 ### A1. Pick a template

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

@@ -57,7 +57,7 @@ Submit the answer shape required by `interaction.answerProtocol`; do not add nor
 
 The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `Abort`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `Abort` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
 
-Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself, never to wizard-provided options.
+Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) shapes the **option set** only for prompts this skill authors itself, never for wizard-provided options — you may not add, drop, or reorder a wizard option to produce a shortlist. It does not excuse you from recommending: before relaying a wizard step whose answer turns on something readable (the carried report, the sidecar the user already wrote, the prior Stage Map), read it, put what you found in the question body, and name which of the wizard's own options you recommend and why. Relaying a step with no context and no recommendation hands the whole question back to the user — see the lifecycle core contract "Asking the user (BLOCKING)". **Enforced:** the option order is fixed by `scripts/okstra_ctl/wizard.py` `Prompt.__post_init__`, which refuses a step whose free-input option is not last; the recommendation itself is on you.
 
 ## Step 1: Preflight
 
@@ -77,6 +77,8 @@ Read the fixed text lines. If the first line is `Okstra preflight: failed`, show
 
 On `Okstra preflight: ready`, require `Runtime readiness: ready` before Step 2. These checks come from the selected host adapter and are independent of worker-provider choices. Any other readiness value is unrecognized runtime output: show it and stop before Step 2 instead of guessing that the host is ready.
 
+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.
 
 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.
@@ -147,7 +149,7 @@ okstra wizard init \
   --project-root /abs/path/to/project \
   --project-id   my-project-id \
   --host-runtime <host-runtime> \
-  --entry-mode current-session \
+  --entry-mode <lead-entry-mode> \
   --available-function plain_text_input \
   --available-function <each-additional-function-in-the-effective-intersection>
 ```
@@ -344,7 +346,7 @@ If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent
 
 ## Step 6: Take over as Okstra lead
 
-Read `<INSTRUCTION_SET_PATH>/lead-execution-prompt.md` verbatim and take over as `Okstra lead` in the current host-native session. The prompt selects exactly one runtime adapter and points to compact intake artifacts first (`active-run-context`, `analysis-profile.md`, and `analysis-packet.md`); full source files such as `analysis-material.md`, `reference-expectations.md`, and `final-report-template.md` are lazy/fallback inputs. Follow the rendered prompt order, do not preempt it.
+Read `resources.leadExecutionPromptPath` from the run manifest at `<RUN_MANIFEST_PATH>` — the same manifest Step 5 already opened for `resources.leadPromptMetadataPath` — then read that file verbatim and take over as `Okstra lead` in the current host-native session. Do not construct the path yourself: the prompt is written per run under `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md`, not in the instruction set, and the `<seq>` is assigned at prepare time. The prompt selects exactly one runtime adapter and points to compact intake artifacts first (`active-run-context`, `analysis-profile.md`, and `analysis-packet.md`); full source files such as `analysis-material.md`, `reference-expectations.md`, and `final-report-template.md` are lazy/fallback inputs. Follow the rendered prompt order, do not preempt it.
 
 Then proceed through the phases exactly as the lead prompt directs (Phase 1 context → Phase 2+ worker dispatch → final synthesis → final report).
 
@@ -360,7 +362,7 @@ Queue = the topologically-sorted stage list from splitting `orchestration.chainS
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
 3. After confirming that `done` row was written, close the panes of the stage you just finished: run `okstra team teardown --project-root <projectRoot> --run-manifest <that stage's RUN_MANIFEST_PATH>`. That stage's run is over, so this is the run-end command rather than the round-boundary one. Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — close the panes the same way, then stop the queue per "Stage ended FAIL" above.
-4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
+4. One-line report at each stage start/finish: `stage N start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.
 
@@ -390,4 +392,4 @@ Do not read the wizard state file directly. `okstra wizard outcome` exposes any
 
 - Echo each captured answer (`result.echo`) on one short line so the user sees what was registered.
 - Never invent identity; if a `text` prompt returns an empty answer where the wizard rejects it, the user must retry.
-- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When the lead (or this skill, after the lead returns) reports the run over, close with the user's next action — one command they can run now. A prohibition is not a next action. After `implementation-planning`, read `workflow.awaitingApproval` and the next-phase pointer from the task manifest. Open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. Awaiting approval → `/okstra-run` → `implementation` or `--approve` (do not start another planning run). Phase 7 `validate-run` failed → one-line cause, then `/okstra-run` to re-run this phase with the sidecar, or `/okstra-inspect recap`. Pointer `status: ready` → `/okstra-run` for that phase. Otherwise `/okstra-inspect status`.
+- After Step 6, begin the lead workflow without re-summarizing the skill itself. For a single run, the end of Step 6 is the end of the run — but in an unattended chain where `orchestration.chainStages` has 2+ elements, repeat Step 6 per stage until Step 7's queue is empty (or it stops at a "not ready" / exception gate), then finish. When the lead (or this skill, after the lead returns) reports the run over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take the pointer from the `report-finalize` result's top-level `nextRecommendedPhase` (`phase`, `status`, `rationale`; also on stderr as `next phase status:` / `next phase:` / `next phase rationale:`) — do not re-derive it from the report, and treat a `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. The same result also carries `nextCommand` — `{command, note}`, the table below already applied to this run. When `command` is non-empty it is the close; when it is empty the `note` says what to do with the `rationale` instead. After `implementation-planning`, open `blocks: approval` rows → `/okstra-user-response`. A recorded `accept-risk` / `select` / `answer` is not an open blocker. No open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type, quote the pointer's `rationale` in every branch — that sentence is the report's own reason and it is what the user asked to be analysed. Pointer `status: ready` → `/okstra-run` for that phase; `status: terminal` → say the task is finished, name any follow-up tasks this run registered, and do not say `/okstra-inspect`; `status: blocked` → issue the command the `rationale` calls for (`/okstra-user-response` for the `C-NNN` ids, `/okstra-run` for the phase it names); `validate-run` failed → one-line cause then `/okstra-run`; otherwise `/okstra-inspect status`.

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

@@ -34,7 +34,7 @@ Follow the task-specific schema order and write the prose in English.
 
 These are the only names allowed at the top level:
 
-`Analysis Common`, `Change Impact Analysis`, `Error Analysis`, `Feature Analysis`, `Final Verdict`, `Final Verification`, `Follow Up Tasks`, `Human Summary`, `Implementation`, `Implementation Option Selection`, `Implementation Planning`, `Improvement Discovery`, `Project Analysis`, `Rationale`, `Recommended Next Steps`, `Release Handoff`, `Requirements Discovery`, `Summary`, `Ticket Coverage`, `Verdict Card`
+`Analysis Common`, `Change Impact Analysis`, `End State Coverage`, `Error Analysis`, `Feature Analysis`, `Final Verdict`, `Final Verification`, `Follow Up Tasks`, `Human Summary`, `Implementation`, `Implementation Option Selection`, `Implementation Planning`, `Improvement Discovery`, `Project Analysis`, `Rationale`, `Recommended Next Steps`, `Release Handoff`, `Requirements Discovery`, `Summary`, `Ticket Coverage`, `Verdict Card`
 
 Any other top-level name is rejected however reasonable it reads — a section title copied out of a lead procedure document (`Clarification Response Carried In`, `Stage Map`, `Rollback Strategy`) is a heading in that document, not a top-level field here. Nested names come from the task's block in `schemas/final-report-v3.0.schema.json`; when a name is refused, the parser's message lists the names allowed at that exact position, so correct against that list rather than guessing a second time.
 

package/runtime/templates/reports/brief.template.md

@@ -56,7 +56,9 @@ it briefly and stop. Use the blockquote below when augmentation is needed.>
 
 > augmented: <label> — <Interpretation added by the skill or user.>
 
-<!-- label MUST be one of: `evidence-link` / `format-conversion` /
+<!-- **Enforced:** `validators/validate-brief.py` `validate_brief` rejects an
+augmentation entry whose label is outside `AUGMENTATION_LABELS`.
+label MUST be one of: `evidence-link` / `format-conversion` /
 `terminology-mapping` / `intent-inference`. Do NOT add any extra
 interpretation outside the `> augmented:` blockquote. -->
 
@@ -270,7 +272,9 @@ Use `_(none)_` if none. -->
 
 ### Intent inferences
 
-<!-- Every entry here is an unverified hypothesis. Each one MUST have a
+<!-- **Enforced:** `validators/validate-brief.py` `validate_brief` fails when the
+`intent-inference` augmentation count exceeds the `intent-check:` row count.
+Every entry here is an unverified hypothesis. Each one MUST have a
 paired `intent-check:` row under Open Questions.
 
 Allowed entry shape:

package/runtime/templates/reports/error-analysis-input.template.md

@@ -80,6 +80,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Analysers MUST NOT expand the hypothesis space or evidence collection into items listed here. If an analyser believes an excluded item is causally linked to the symptom, it is reported as a recommended follow-up analysis task in the final report — never silently merged into the current root-cause narrative. If this section is left empty, analysers treat any cause beyond what `Symptom Summary` and `Reproduction Context` describe as out of scope by default.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
 ## Questions for Analysers
 
 1. What is the most likely root cause?

package/runtime/templates/reports/final-verification-input.template.md

@@ -83,6 +83,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Verifiers MUST NOT extend acceptance checks, regression scans, or sign-off recommendations into items listed here. If a verifier believes an excluded item must pass before release, it is reported as a recommended follow-up verification task in the final report — never silently included in the pass/fail decision of this run. If this section is left empty, verifiers treat any check beyond what `Acceptance Criteria` enumerates as out of scope by default.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
 ## Config and Deployment Verification Targets
 
 - Relevant config files:

package/runtime/templates/reports/implementation-input.template.md

@@ -26,6 +26,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Approved Plan Reference (mandatory)
 
+**Enforced:** `approvedPlanReference` is required in the final-report v3 schema's `implementation` block, with `planFile`, `approvalEvidence`, `executorWorktreePath`, and `baseRefSha` all required.
+
 - Approved plan path: `runs/implementation-planning/<run-id>/reports/final-report.md`
 - Approval evidence (quoted exactly from the plan's YAML frontmatter, e.g. `approved: true`):
 - Planning contract: `selected-direction` or `legacy-option-candidates`
@@ -50,6 +52,10 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > The executor MUST NOT modify items listed here, even when an edit looks "trivial" or "while I'm in this file". Excluded items that block plan execution are reported back as a recommended follow-up task and the run halts for re-planning rather than silently expanding scope. This section is enforced together with `Forbidden In This Run` below.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
+**Enforced (declared edits only):** `_validate_out_of_plan_edits_are_real` in `validators/validate-run.py` fails an `Out-of-plan edits` row naming a file that is absent from `diffSummary`. The other direction — a file changed outside the approved plan and never declared — needs the plan's own file list resolved through `approvedPlanReference.planFile`, and is not built.
+
 ## Validation Commands (must be runnable from clean state)
 
 - Pre-execution checks:
@@ -68,7 +74,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - `git push`, publish, deploy, migration execution, third-party write APIs, production credentials
 - Edits or Bash mutations performed by any verifier role
 - Sub-agent dispatch beyond the required worker roster
-- Silent scope expansion — every file touched outside the plan's list MUST be recorded in `Out-of-plan edits`
+- Silent scope expansion — every file touched outside the plan's list MUST be recorded in `Out-of-plan edits` (**Enforced (declared edits only):** `_validate_out_of_plan_edits_are_real`)
 
 ## Verifier Worker Inputs
 

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -53,6 +53,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Analysers MUST NOT expand option candidates, file lists, or step plans into items listed here. If an analyser believes an excluded item must be addressed to satisfy the requirement, it is reported as a recommended follow-up task in the final report — never silently folded into a candidate option. If this section is left empty, analysers treat any change beyond what `Requirement Summary` explicitly demands as out of scope by default.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
 ## Planning Concerns
 
 - Selected direction realization concerns:
@@ -122,6 +124,8 @@ When no selected-direction snapshot exists on a compatibility rerun, the final r
 
 ## Stage Output Shape (reference)
 
+**Enforced:** `validators/validate-implementation-plan-stages.py` fails a plan missing `## 5.5 Stage Map` and checks each `## 5.5.<i> Stage <i>` section against it (S1–S13).
+
 This run's final report MUST emit `## 5.5 Stage Map` and `## 5.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative Stage Map tables:
 
 ### Shape A — single stage (small work)

package/runtime/templates/reports/quick-input.template.md

@@ -52,6 +52,8 @@ taskType: "{{FM_TASK_TYPE}}"
 > If left blank, any changes beyond the explicit requirements of the input will be treated as out of scope by default.
 > Any exclusions that appear necessary will be recorded only as follow-up recommendations in the final report, and no further action will be taken.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
 ## Config and Deployment References
 
 - Related config files:

package/runtime/templates/reports/release-handoff-input.template.md

@@ -27,7 +27,10 @@ taskType: "{{FM_TASK_TYPE}}"
 
 - Mode: `{{HANDOFF_MODE}}`
 - Stages: `{{HANDOFF_STAGES}}`
-- Reports (one row per cited `final-verification` final-report; every Verdict Token MUST be `accepted`):
+- Reports (one row per cited `final-verification` final-report; every Verdict Token MUST be `accepted`).
+  **Enforced:** `validators/validate-run.py` routes through
+  `okstra_ctl.release_gate.release_handoff_allowed`, which passes `accepted` and
+  admits `conditional-accept` only when no condition still blocks the handoff:
 
 | Stage | Report path (project-relative) | Verdict Token |
 |---|---|---|
@@ -77,6 +80,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > The lead MUST NOT extend handoff actions into items listed here. If an excluded item should ship in this PR, edit this section before the run starts — do not silently fold it in.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
 ## Questions for Lead Drafting
 
 1. What PR title best describes the cumulative committed diff?

package/runtime/templates/reports/report.js

@@ -474,13 +474,16 @@
     var text = out.textContent;
     if (navigator.clipboard && navigator.clipboard.writeText) {
       navigator.clipboard.writeText(text).catch(function () {
-        fallbackCopy(text);
+        if (!fallbackCopy(text)) offerManualCopy(out, text);
       });
     } else {
-      fallbackCopy(text);
+      if (!fallbackCopy(text)) offerManualCopy(out, text);
     }
   }
 
+  // Returns whether the text actually reached the clipboard. A browser can
+  // refuse the copy either by throwing or by returning false, and a silent
+  // refusal reads as "the button does nothing".
   function fallbackCopy(text) {
     var ta = document.createElement("textarea");
     ta.value = text;
@@ -488,8 +491,21 @@
     ta.style.opacity = "0";
     document.body.appendChild(ta);
     ta.select();
-    try { document.execCommand("copy"); } catch (e) {}
+    var copied = false;
+    try {
+      copied = document.execCommand("copy") === true;
+    } catch (e) {
+      console.warn("okstra report: clipboard copy was refused", e);
+    }
     document.body.removeChild(ta);
+    return copied;
+  }
+
+  // The clipboard is unavailable, so put the text where the reader can select
+  // it by hand instead of leaving the click with no visible result.
+  function offerManualCopy(out, text) {
+    console.warn("okstra report: clipboard unavailable, select the text below");
+    showOutput(out, text);
   }
 
   function showDismiss(show) {
@@ -596,6 +612,7 @@
       collectAnalysisReview: collectAnalysisReview,
       collectDirectionSelection: collectDirectionSelection,
       exportUserResponse: exportUserResponse,
+      copyUserResponse: copyUserResponse,
       setReaderMode: setReaderMode,
     };
   }

package/runtime/templates/reports/schedule.template.md

@@ -137,6 +137,8 @@ DEV-2 -> DEV-4
 
 ## Gantt Chart
 
+**Enforced:** `validators/validate-schedule.py` pins the `## Gantt Chart` heading literal and its position among the optional sections.
+
 <!-- OPTIONAL: include only when per-task day estimates are available.
      If included, MUST use this exact heading literal `## Gantt Chart`.
      Render as ASCII inside a fenced ``` block with NO language tag.

package/runtime/templates/reports/settings.template.json

@@ -48,16 +48,6 @@
           }
         ]
       }
-    ],
-    "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end"
-          }
-        ]
-      }
     ]
   }
 }

package/runtime/templates/reports/task-brief.template.md

@@ -95,6 +95,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Workers MUST NOT expand into items listed here. If a worker believes an excluded item must be addressed to satisfy the requirement, the worker records it as a recommended follow-up task in the final report and stops — it does not silently include the work. If this section is left empty, workers treat any change beyond what `Request Summary` and `Current Context` explicitly demand as out of scope by default.
 
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+
 ## Configuration References and Expected Values
 
 - Which config files matter for this task?
@@ -147,6 +149,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - "proceed to the next step" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
 - For `implementation-option-selection` specifically: compare or validate implementation directions without editing source, running tests/builds, or writing exact file lists, stage maps, and test commands. Only directions with 100% requirement coverage and 100% scope precision may be displayed.
+- **Enforced (start refusal):** `scripts/okstra_ctl/run.py` `_validate_approved_plan` raises `PrepareError` before the run is prepared when the record's frontmatter is not `approved: true`, when a blocking plan-body gate stands, or when a `Blocks=approval` clarification row is still open. The phase-output half of this section is not machine-checked.
 - For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
 
 ## Available MCP Servers

package/runtime/templates/reports/user-response.template.md

@@ -11,8 +11,8 @@ This file defines the standard format of the markdown produced by the **Export u
 task-key: <task-group>/<task-id>
 task-type: <requirements-discovery | error-analysis | implementation-option-selection | implementation-planning | implementation | final-verification | release-handoff | improvement-discovery | project-analysis | feature-analysis | change-impact-analysis>
 seq: <3-digit zero-padded run sequence>
-source-report: <project-relative path to the final-report .md the HTML was derived from>
-source-data: <project-relative path to the final-report data.json; omit for legacy reports without one>
+source-report: <task-root-relative path (runs/...) to the final-report .md the HTML was derived from>
+source-data: <task-root-relative path (runs/...) to the final-report data.json; omit for legacy reports without one>
 source-data-sha256: <SHA-256 of the exact source-data bytes; omit when source-data is omitted>
 created-by: user
 created-at: <ISO 8601 UTC timestamp>
@@ -123,8 +123,12 @@ Selecting one ranked direction and checking `Confirmed` appends this block. `Sel
 
 The parser accepts exactly one block, lowercase `selected`, and lowercase `true`. A `preselected-validation` report displays its confirmed upstream direction read-only and does not export a new selection block.
 
+`Option-ID` alone decides which candidate was selected. `Option-Name` is recorded for the reader and is NOT compared against the report: the HTML is rendered from a translated copy of the record, so on a run whose `meta.reportLanguage` is not `en` the exported name is the reader's language while the record keeps English. The name that travels on to planning is always the record's own (`_selected_option` in `scripts/okstra_ctl/implementation_direction.py`).
+
 ## Compatibility Rules
 
 - If `Kind` has an unknown value, the form renders with a `<textarea>` fallback, and the received `Kind` string is preserved as-is during serialization.
 - Rows whose `Status` is `resolved` or `obsolete` render `disabled` in the HTML form and are automatically excluded from the Export result. To reopen such a row, revert the final-report `Status` to `open` / `answered` and regenerate the report.
-- The output of the Python (`serialize_user_response` in `scripts/okstra_ctl/report_views.py`) and the JavaScript (`buildUserResponseMarkdown` in `templates/reports/report.js`) MUST be **byte-identical**. `tests/test_report_views.py` verifies the equivalence of the two implementations.
+- Both `source-report` and `source-data` are relative to the **task root** (`.okstra/tasks/<group>/<task>/`), so they start at `runs/`. The single reference point for that base is `sidecar_source_rel` in `scripts/okstra_ctl/final_report_paths.py`; the reader that compares them back (`_relative_source` in `scripts/okstra_ctl/implementation_direction.py`) resolves from the task root, and a value written against any other base fails the direction gate even when it names the same file.
+
+The output of the Python (`serialize_user_response` in `scripts/okstra_ctl/report_views.py`) and the JavaScript (`buildUserResponseMarkdown` in `templates/reports/report.js`) MUST be **byte-identical**. `tests/test_report_views.py` verifies the equivalence of the two implementations.

package/runtime/validators/checks/fixtures-01.py

@@ -0,0 +1,57 @@
+"""fixtures-01 — 셸 시나리오에서 꺼낸 단언 블록.
+
+호출부: validators/lib/fixtures.sh:99
+규칙 R1 은 실행될 소스를 문자열/heredoc 이 아니라 실파일에 두게 한다.
+이 파일의 내용은 꺼내기 전과 같다 — 옮기기만 했다.
+"""
+from pathlib import Path
+import json
+import sys
+
+project_root = Path(sys.argv[1])
+task_manifest_path = project_root / sys.argv[2]
+target_worker_id = sys.argv[3]
+task_manifest = json.loads(task_manifest_path.read_text())
+team_state_path = project_root / task_manifest["teamStatePath"]
+team_state = json.loads(team_state_path.read_text())
+
+target_worker = None
+for worker in team_state.get("workers", []):
+    if isinstance(worker, dict) and worker.get("workerId") == target_worker_id:
+        target_worker = worker
+        break
+
+if target_worker is None:
+    raise SystemExit(f"worker not found in team-state: {target_worker_id}")
+
+prompt_relative = str(target_worker.get("promptPath", "")).strip()
+if not prompt_relative:
+    raise SystemExit(f"worker promptPath is missing: {target_worker_id}")
+
+prompt_path = project_root / prompt_relative
+prompt_path.parent.mkdir(parents=True, exist_ok=True)
+artifacts = task_manifest.get("artifacts", {})
+analysis_packet_path = (
+    str(artifacts.get("analysisPacketPath", "")).strip()
+    if isinstance(artifacts, dict)
+    else ""
+)
+prompt_path.write_text(
+    "\n".join(
+        [
+            "**Worker Error Contract Path:** /okstra/templates/worker-error-contract.md",
+            f"**Errors log path:** {project_root}/run/logs/errors.jsonl",
+            f"**Errors sidecar path:** {project_root}/run/worker-results/"
+            f"{target_worker_id}-errors.json",
+            f"Assigned worker prompt history path: {prompt_relative}",
+            "**Prompt Delivery Mode:** eager-include",
+            f"**Model:** Fixture worker, {target_worker.get('modelExecutionValue', '')}",
+            f"- Primary analysis packet: `{analysis_packet_path}`",
+            "",
+            "# Initial Analysis Prompt",
+            f"Task Key: {task_manifest.get('taskKey', '')}",
+            "Validation fixture prompt body.",
+        ]
+    )
+    + "\n"
+)