okstra 0.205.1 → 0.206.1

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

@@ -93,7 +93,7 @@ This section adds report-specific checks to [okstra-lead-contract](./okstra-lead
 2. The ledger lives at `runs/<task-type>/state/report-writer-corrections-<task-type>-<seq>-a<N>.json` (schema `schemas/report-writer-corrections-v1.0.schema.json`) and holds one entry per defect: `replace` with the exact replacement value (add `current` when you want it checked), `remove` for an item or optional field, `rewrite` with a `rule` when the writer has to re-author prose. Paths use the validator's grammar (`implementationOptionSelection.rankedOptions[1].coverageSummary.coveragePercent`), so a report-assembly refusal can be copied into the ledger verbatim. Never write an indirect instruction such as `use the schema value`, `use the valid status`, or `fix the enum`: a `replacement` is the literal, and a `rule` names the required outcome. You do not copy allowed enum literals by hand — okstra attaches each `rewrite`'s schema constraint from the frozen schema.
 3. Run `okstra agent-prompt check-corrections --project-root <root> --run-manifest <path> --corrections <ledger>` until it reports no defect. It applies the ledger to a scratch copy of the base narrative and validates the complete proposed narrative against the writer-owned value schema and the task's semantic validator, listing every defect at once. Validating only the edited field is insufficient because one replacement can select a different schema branch, which is why the check covers the whole narrative.
 4. When the check reports `mechanical: true` and has corrections, run `okstra agent-prompt apply-corrections` with the same arguments: okstra writes the corrected narrative to `reportNarrativePath` and records a `lead-correction-applied` activity row naming the ledger and its correction ids. This includes validated `replace`, `remove`, `add`, `move`, and derived step counts. No writer dispatch, `record-dispatch`, or `link-result` follows; the roster row's result already exists.
-5. Otherwise materialize the writer prompt with the same `--corrections <ledger>` under a new invocation id and prompt path (retire the first attempt's link with `reject-result` as [plan-body-verification](./plan-body-verification.md) describes). okstra renders the correction-only field values, evidence, schema constraints, replacement-file contract, application command, and output paths. Put context in the ledger; the initial instruction body is not sent to the correction writer.
+5. Otherwise materialize the writer prompt with the same `--corrections <ledger>` under a new invocation id and prompt path (retire the first attempt's link with `reject-result` as `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) describes). okstra renders the correction-only field values, evidence, schema constraints, replacement-file contract, application command, and output paths. Put context in the ledger; the initial instruction body is not sent to the correction writer.
 
 A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs, and four of six re-runs in the 2026-09-03 measurement were lead instructions that contradicted the authoring contract. Only a narrative whose structure does not parse (line grammar, an unknown top-level field) is re-authored, not corrected: that dispatch needs no ledger, and its body quotes the parser's message. Because re-authoring overwrites the live file in place, okstra copies the existing narrative to `worker-results/<narrative-name>.pre-<invocation-id>.md` at materialization and renders a `## Previous Attempt` section naming that copy (**Enforced:** `_preserve_reauthored_narrative` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`); the 2026-09-09 dev-10642 run lost a 579-line attempt to a failed in-place re-indent command with no copy to fall back on. A narrative that breaks the line grammar is not a produced artifact: the dispatcher settles that attempt as `required worker artifact is unusable: narrative does not parse: …` and retries it inside the same batch, so you see the parser's message at collection, not at Phase 7 assembly (**Enforced:** `okstra_ctl.dispatch_state.unusable_result_defect`, read by `missing_completion_paths` and the `team await` record path). The synthesis packet's Authoring Contract carries the line grammar itself (`report_narrative.NARRATIVE_GRAMMAR_INSTRUCTIONS`), so a writer that reads only the packet still sees it. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are exactly what the ledger fixes; the a3 attempt of the 2026-09-03 run carried twenty `SC-` ids that assembly refused and was still a corrective base.
 
@@ -106,7 +106,7 @@ A report-writer materialization without `--corrections` whose narrative already
 3. Run initial plan-body verification as round 1.
 4. Apply at most one automatic planner self-fix to the narrative. Skip this step when `gating` is `false`.
 5. Run targeted re-verification as round 2 when needed. Skip this step when `gating` is `false`.
-6. Persist the completed `planBodyVerification` value in convergence state. Run `okstra plan-items next-dispatch`: after the single automatic self-fix, settle eligible judgements with `resolve-dissent`; ask the user immediately for decisions outside lead authority. Preserve dissent and do not restart the automatic loop. The exact procedure and enforced authority checks are in `prompts/lead/plan-body-verification.md` step 8.
+6. Persist the completed `planBodyVerification` value in convergence state. Run `okstra plan-items next-dispatch`: after the single automatic self-fix, settle eligible judgements with `resolve-dissent`; ask the user immediately for decisions outside lead authority. Preserve dissent and do not restart the automatic loop. The exact procedure and enforced authority checks are in `scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` step 8.
 7. Complete the design-surface detector snapshot: `okstra design-snapshot --narrative <reportNarrativePath> --output <designPreparationPath>`, taking both paths from the run manifest. Nothing else writes that snapshot, and step 8 fails without it — `report_inputs._PLANNING_INPUT_FIELDS` lists `designPreparationPath` as a required planning input.
 8. Run Phase 7 report assembly.
 

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

@@ -5,7 +5,7 @@
 - When verifying worker team composition and operational rules
 - When applying model assignment rules
 
-**Not applicable to `release-handoff`** — that profile is lead-only and intentionally has no `Required workers:` block (see `prompts/profiles/release-handoff.md`). The worker-dispatch contract in this document does not engage during `release-handoff` runs.
+**Not applicable to `release-handoff`** — that profile is lead-only and intentionally has no `Required workers:` block (see `scripts/okstra_ctl/phases/release_handoff/profile.md`). The worker-dispatch contract in this document does not engage during `release-handoff` runs.
 
 ## Team Structure
 

package/runtime/prompts/profiles/_coding-conventions-preflight.md

@@ -16,7 +16,7 @@ prompt through `prepare_agent_invocation()` before `worker-dispatch`.
 Load the applicable coding conventions for every language the diff will touch, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`). Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, and untruthful names all pass a green pipeline; this gate is what keeps them out of the diff.
 
 - **Resource selection — read the routed pack, never inline it here.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Detect each touched file's language and framework from its extension or project manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `build.gradle*`, `prisma/schema.prisma`), then read that pack's resources via the Read tool by absolute path. Always read `overview.md` (the router) + `clean-code.md`, then select per the router's three ordered stages — Stage 1 language → `languages/<lang>.md`, Stage 2 framework → `frameworks/<fw>.md` (e.g. `frameworks/node-server.md` for server-side Node), Stage 3 architecture → `architectures/<arch>.md` (e.g. `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex). Each stage is a list of rules; include EVERY matching resource (a change set can touch multiple languages/frameworks/architectures) — do not stop at the first match. These files are runtime resources, not Skill-tool skills, so always read them by path.
-- **Project policy projection:** before selecting resources, run `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <task-ref>`. Consume its `Architecture style`, `Project Review Rule Packs`, and `Project QA Commands` sections; do not open Okstra-owned JSON storage.
+- **Project policy projection:** before selecting resources, run `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Consume its `Architecture style`, `Project Review Rule Packs`, and `Project QA Commands` sections; do not open Okstra-owned JSON storage.
 - **Declared architecture style — an authoritative Stage 3 input, and it binds.** A projected `hexagonal` selects `architectures/hexagonal.md` even when none of Stage 3's layout signals matched, so the declaration — not the directory shape — decides. A projected `layered` has no pack resource; its invariant applies from this line: dependencies run one direction only — an upper layer may import a lower one, never the reverse — and a variation point is extracted onto a layer boundary. A declared style makes this overlay binding rather than advisory, and which rule binds follows the style: under `hexagonal` the overlay's otherwise-advisory concrete-adapter item is blocking, so a service dependency you add or modify goes through a port instead of a concrete implementation and that placement violation is fixed before the write rather than recorded as a note; under `layered` what binds is the direction invariant just stated — your own judgement over the import list of every file the diff touches, plus extracting a variation point onto a layer boundary — while the concrete-adapter item stays advisory, since `layered` has no ports to route it through. An absent or `none` projected style leaves Stage 3 detection-driven and its overlay advisory. The verifier re-grades the same diff under the same declaration (`_implementation-verifier.md` → Static design & test-quality review), so a placement violation missed here returns as a verdict `FAIL`.
 - **Project review rule packs:** a pack applies when either source names it — the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or the project-context projection lists it as a standing standard. The two sources are a union. Read only those files and the `references/*.md` files they directly name; a declared path that will not open is recorded as `project-review-rules: declared <path> unreadable`, never silently dropped. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
 - **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.

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

@@ -91,7 +91,7 @@ profile document.
   - if a schema-v1 table or an analysis-worker result table requires a recommended answer, alternatives, or an evidence-check note, encode it inside the existing 4-column schema: put evidence notes in `Statement` as `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>`, and put recommendations/options in `Expected form` as `Recommended: (a) <answer> — <rationale>; Alternatives: (b) <option> (c) <option>`. The recommended answer is always the first option and MUST carry the `(a)` label; alternatives continue the same letter sequence from `(b)` (a lone alternative is `(b) <option>`, never restart at `(a)`), so the full option set reads `(a) (b) (c) …` in order and renders each as its own selectable option. Do **not** append a pick-one answer-space summary such as `(pick 1 of A / B)` or `(pick N of …)` to `<options>` — the rendered `<select>` already enforces single choice, and that annotation leaks verbatim into an option label. Do not add `Recommended`, `Evidence`, `Alternatives`, or `evidence-checked` columns, and do not break the merged record-meta cell back into separate columns.
   - For schema v2, data.json is canonical and the HTML exports answers to a user-response sidecar; the source report is never edited. `--resume-clarification` carries those answers into the next run. The lower-level `--clarification-response <path>` remains available for scripted runs.
   - When a response is carried in, reconcile every prior `clarificationItems[]` row against new evidence and update its status to `resolved` or `obsolete` before issuing the next verdict. Schema-v1 compatibility Markdown may additionally render its conditional Section 0; the schema-v2 full reading copy records decisions under `## Clarification and User Decisions`.
-  - **Supersession (BLOCKING).** Reconciling the `C-*` row is only half of incorporating an answer. An answer does not merely *add* a decision — it *invalidates* whatever the previous run wrote under the opposite assumption. Before issuing the next decision, walk the prior deliverable prose for every statement the answer makes false and **delete or rewrite it**, then record the retirement. Adding the new decision while leaving the contradicting sentence in place puts two opposite instructions for the same symbol in one document; the implementer must then guess which is live, and the next verification round correctly blocks on it. In `implementation-planning` this record is `implementationPlanning.supersessionLedger[]` — one entry per answered clarification, either `disposition: superseded` (with the retired statement, its replacement, and the sections revised) or `disposition: no-dependent-statement` (with a rationale). A plan built from a selected direction inherits the answers the option-selection record carried before it has any statement to retire, so those carried rows need no entry; the rows this plan itself raised and settled still do. **Enforced:** `validators/validate-run.py` `_validate_supersession_ledger` requires an entry per answered clarification, exempting the ledger's `carriedDecisions[]` ids on a selected-direction plan; whether the claim is *true* is what the §5.5.9 adversarial round tests.
+  - **Supersession (BLOCKING).** Reconciling the `C-*` row is only half of incorporating an answer. An answer does not merely *add* a decision — it *invalidates* whatever the previous run wrote under the opposite assumption. Before issuing the next decision, walk the prior deliverable prose for every statement the answer makes false and **delete or rewrite it**, then record the retirement. Adding the new decision while leaving the contradicting sentence in place puts two opposite instructions for the same symbol in one document; the implementer must then guess which is live, and the next verification round correctly blocks on it. In `implementation-planning` this record is `implementationPlanning.supersessionLedger[]` — one entry per answered clarification, either `disposition: superseded` (with the retired statement, its replacement, and the sections revised) or `disposition: no-dependent-statement` (with a rationale). A plan built from a selected direction inherits the answers the option-selection record carried before it has any statement to retire, so those carried rows need no entry; the rows this plan itself raised and settled still do. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_supersession_ledger` requires an entry per answered clarification, exempting the ledger's `carriedDecisions[]` ids on a selected-direction plan; whether the claim is *true* is what the §5.5.9 adversarial round tests.
 - Verdict Card data consistency (shared; schema-v1 Markdown keeps the legacy visible card):
   - The Card carries no verdict token — the token lives once, in `finalVerdict.verdictToken`, and every gate reads it there. `verdictCard.direction` byte-matches `finalVerdict.direction`; next-step routing agrees with `recommendedNextSteps[0]`. The full reading copy and human summary are derived from the data fields without repeating both visible sections. **Enforced in part:** the v3.0 schema's `verdictCard` is `additionalProperties: false` with no verdict-token property, so the token cannot be duplicated onto the Card, and `scripts/okstra_ctl/report_narrative.py` `writer_owned_schema` applies the finished report's `$defs.Direction` enum to the narrative, rejecting an off-enum `direction` while the writer can still be re-run. The byte-match between the two `direction` fields is not compared by anything — assembly overwrites `nextStep` on both when the plan-body gate passes (`scripts/okstra_ctl/report_assembly.py:590-604`) but leaves `direction` as the writer wrote it.
 - Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 6.` / `## 2.` tables in the final-report):

package/runtime/prompts/profiles/_coverage-critic.md

@@ -14,4 +14,4 @@ mode:" when the include directive (placed at column 0) is resolved in-place.
 Do NOT write the literal include directive token in this file's body — the
 resolver matches it anywhere and would recurse on this file itself.
 -->
-  - **Coverage critic (opt-in, one slot)**: critic `min` is 0 and `recommended`/`max` are 1 — the wizard asks whether to add the slot with 1 recommended, and the user picks the model when they add it (`--role-model critic=<provider>/<model>` or the wizard role-model step). `--critic off` and a 0-count selection are both accepted; the run then dispatches no critic pass, and an analyser 1-1 tie stays `needs-reverify` with no slot to settle it — `okstra plan-items next-dispatch` answers `user-decision` for those items and the lead opens an approval decision instead of another round. A reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface **both** findings nobody covered and work the findings propose that no requirement asked for (`category: "unrequested-scope"`); its candidates are judged only after a 1-round adversarial reverify that follows convergence. The two halves are disposed of differently — a contested coverage gap is dropped as a hallucination, while a contested over-scope candidate is recorded as a `## 5. Missing Information and Risks` row instead of vanishing. In `implementation-planning`, the same critic slot also settles plan-body 1-1 splits (`critic-worker` on `--tie-vote` items only). See `prompts/lead/convergence.md` "Coverage critic pass" and `prompts/lead/plan-body-verification.md` even-split rule.
+  - **Coverage critic (opt-in, one slot)**: critic `min` is 0 and `recommended`/`max` are 1 — the wizard asks whether to add the slot with 1 recommended, and the user picks the model when they add it (`--role-model critic=<provider>/<model>` or the wizard role-model step). `--critic off` and a 0-count selection are both accepted; the run then dispatches no critic pass, and an analyser 1-1 tie stays `needs-reverify` with no slot to settle it — `okstra plan-items next-dispatch` answers `user-decision` for those items and the lead opens an approval decision instead of another round. A reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface **both** findings nobody covered and work the findings propose that no requirement asked for (`category: "unrequested-scope"`); its candidates are judged only after a 1-round adversarial reverify that follows convergence. The two halves are disposed of differently — a contested coverage gap is dropped as a hallucination, while a contested over-scope candidate is recorded as a `## 5. Missing Information and Risks` row instead of vanishing. In `implementation-planning`, the same critic slot also settles plan-body 1-1 splits (`critic-worker` on `--tie-vote` items only). See `prompts/lead/convergence.md` "Coverage critic pass" and `scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` even-split rule.

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

@@ -1,100 +1,6 @@
 {
-  "requirements-discovery": [
-    "source code edits of any kind",
-    "implementation planning or detailed design beyond what is required to choose the next phase",
-    "executing builds, migrations, deployments, or any state-mutating command",
-    "starting `error-analysis`, `implementation-planning`, or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
-  ],
-  "improvement-discovery": [
-    "source code edits of any kind",
-    "implementation planning, root-cause analysis, builds, migrations, or deployments",
-    "starting `implementation-planning`, `implementation`, `error-analysis`, or any other lifecycle phase inside this run",
-    "generating candidates outside the lens whitelist (Lens enum violation rejects the report)",
-    "exceeding the candidate cap (absolute cap 12)",
-    "free external data fetch beyond the brief's Source Material or Phase 1.5 resolved scope",
-    "interpreting user phrases like `다음 단계 진행해` as authorisation to enter another phase"
-  ],
-  "project-analysis": [
-    "source or configuration edits",
-    "tests, builds, migrations, or deployments",
-    "starting any other lifecycle phase inside this run"
-  ],
-  "feature-analysis": [
-    "source or configuration edits",
-    "tests, builds, migrations, or deployments",
-    "starting any other lifecycle phase inside this run"
-  ],
-  "change-impact-analysis": [
-    "source or configuration edits",
-    "tests, builds, migrations, or deployments",
-    "starting any other lifecycle phase inside this run",
-    "implementation alternatives",
-    "file change specifications",
-    "stepwise execution plans"
-  ],
-  "error-analysis": [
-    "source code edits, refactors, or fix attempts",
-    "implementation design or planning artifacts",
-    "executing builds, migrations, deployments, or any state-mutating command",
-    "starting `implementation-planning` or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
-  ],
-  "implementation-option-selection": [
-    "source or configuration edits, refactors, or fix attempts",
-    "tests, builds, migrations, deployments, or any state-mutating command",
-    "detailed file lists, stage maps, execution commands, or plan approval",
-    "starting `implementation-planning` or `implementation` inside this run",
-    "displaying more than three merged candidates or omitting rejected-candidate audit records"
-  ],
-  "implementation-planning": [
-    "source code edits of any kind (Edit/Write on project source files is forbidden)",
-    "file writes outside the run`s artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`), including task-root QA scripts, manifest, and tsconfig (planning declares conformance commands and required dependencies; implementation writes these files); in particular, do not write to `docs/superpowers/specs/` or `docs/superpowers/plans/`",
-    "executing builds, migrations, deployments, or any state-mutating command",
-    "starting `implementation` inside this run (must be a separate run authorised by an approved deliverable from this phase), even if the user says \"다음 단계 진행해\"",
-    "dispatching parallel sub-agents beyond the required worker roster (okstra owns worker fan-out)",
-    "leaving placeholders such as TBD / TODO / \"handle edge cases\" / \"similar to Option N\" in the report",
-    "delegating the self-review pass — the Okstra lead must run it"
-  ],
-  "implementation": [
-    "any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md whose frontmatter has `approved: true`)",
-    "`git push` of any kind (including `--dry-run` against a real remote that produces side-effects), `npm publish` / `cargo publish` / `pip publish`, `gh release`, `docker push`",
-    "real database migrations, schema changes against shared environments, or writes to non-local datastores",
-    "production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)",
-    "external API write calls (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures",
-    "source edits or Bash mutations performed by any verifier role (`Antigravity verifier`, `Codex verifier`, `Claude verifier` are read-only — recommend, do not apply)",
-    "dispatching parallel sub-agents beyond the required worker roster",
-    "silent scope expansion: every file edited outside the approved plan list MUST appear in the `Out-of-plan edits` block with rationale",
-    "leaving placeholders such as TBD / TODO / \"implement later\" / \"handle edge cases\" in newly-added lines of this run (check via `git diff <base>..HEAD | grep -E '^\\+[^+].*\\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\\b'`; pre-existing strings in untouched regions are out of scope)",
-    "lead substituting its own verdict when every verifier present in the resolved roster returned a non-result terminal status (`timeout`/`error`/`not-run`); in that case the run MUST end as `blocked` with routing recommendation back to `error-analysis`, never with a lead-only verdict",
-    "declaring overall task acceptance — that is `final-verification` ownership; this phase reports only \"ready for final-verification\" or \"needs new planning loop\"",
-    "delegating the self-review pass — the Okstra lead must run it"
-  ],
-  "final-verification": [
-    "source code edits, follow-up bug fixes, or scope expansion",
-    "state-mutating commands against the project or shared environments; permitted mutations are limited to the run's own `.okstra` artifacts (reports, state, `<task_root>/qa/result-*.json` sidecars, `okstra handoff record-verified` on acceptance) and Tier3 conformance scripts that mutate only their qaEnv replica datastore — everything else is read-only execution of pre-existing test or validation commands",
-    "starting any follow-up phase inside this run; record findings and end the run"
-  ],
-  "release-handoff": [
-    "entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited",
-    "local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` / `git rebase --onto` / `git cherry-pick` / `git commit --amend` run by the lead. The single exception is the merge commits `okstra handoff pr-plan` itself creates on a `merge-base` branch — the lead never merges by hand. Rewriting a stage branch breaks the PR stack that sits on it.",
-    "any git push variant that rewrites remote history, regardless of intent or whether the user said \"force it\": `git push --force`, `git push --force-with-lease`, `git push -f`, `git push +<refspec>`, or any other history-rewriting invocation",
-    "pushing directly to a release base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the release base in this run. The only permitted push targets are the branches `okstra handoff pr-plan` listed for this run (each stage `head_branch`, and any `merge-base` branch).",
-    "bypassing repo safeguards: `--no-verify` / `-n` on `git push`, bypassing GPG signing, disabling safeguards via equivalent flags, or any hook bypass.",
-    "release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.",
-    "source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.",
-    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local checkout`; pushing when the user picked `skip`; switching the release base branch silently after the user already chose one; opening a PR for a stage outside `HANDOFF_STAGES`.",
-    "squash-merging, or instructing anyone to squash-merge, a stage PR — and `gh pr merge` in any form. A squash replaces the commits the next stage's PR base points at, so the stack breaks; the PR body states merge-commit-or-rebase and the lead never merges.",
-    "retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.",
-    "worker dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Okstra lead.",
-    "silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim."
-  ],
   "unknown": [
     "any action that belongs to a different lifecycle phase",
     "source code edits or state-mutating commands unless this task type explicitly authorises them"
-  ],
-  "technical-verification": [
-    "source edits or installs in the project checkout, task worktree, or another worker's experiment copy",
-    "production credentials, remote writes, deployments, migrations, publishing, commits or merging experiments into product branches",
-    "marking candidates feasible, selecting a direction, approving a plan, or declaring task acceptance",
-    "starting another lifecycle phase inside this run; return the evidence to implementation-option-selection"
   ]
 }

package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py

@@ -25,7 +25,7 @@ from ..activity import (
 )
 from ...final_report_schema import load_schema_version
 from ...json_boundary import load_owned_object
-from ...implementation_options import validate_implementation_option_selection
+from ...phases.implementation_option_selection.validation import validate_implementation_option_selection
 from ...report_contract import TASK_TYPE_DATA_PROPERTY
 from ...report_assembly import validate_plan_draft
 from ...report_corrections import (

package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py

@@ -34,7 +34,11 @@ from ...assignment_environment import load_assignment_context
 from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignment
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
-from ...worker_prompt_contract import complete_reverify_instruction, validate_reverify_prompt
+from ...worker_prompt_contract import (
+    complete_reverify_instruction,
+    validate_plan_verify_dispatch_identity,
+    validate_reverify_prompt,
+)
 from ...worker_prompt_policy import (
     critic_assignment_ref,
     is_plan_critic_verification,
@@ -340,6 +344,11 @@ def _materialize_run(
         active_context=active_context,
     ))
     body = instruction_path.read_text(encoding="utf-8")
+    identity_errors = validate_plan_verify_dispatch_identity(
+        body, dispatch_kind=args.dispatch_kind, result_name=result_path.name,
+    )
+    if identity_errors:
+        raise AgentPromptCliError("; ".join(identity_errors))
     is_reverify = is_verification_dispatch_kind(args.dispatch_kind)
     if is_reverify:
         body = _complete_run_reverify_body(args, manifest, active_context, assignment, body, instruction_path)

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -73,7 +73,6 @@ _EVIDENCE_RELATION_BY_TYPES = {
 _REPORT_NAME_RE = re.compile(
     r"^final-report-.+-(?P<run_seq>[^-]+)\.data\.json$"
 )
-_FEATURE_ID_RE = re.compile(r"PF-\d{3}")
 _FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
 _RUN_SEQ_RE = re.compile(r"[0-9]{3}")
 
@@ -347,41 +346,3 @@ def resolve_evidence_inputs(
             freshness="exact" if candidate.source_commit == current_commit else "stale",
         ))
     return tuple(resolved)
-
-
-def resolve_analysis_target(
-    raw_target: str,
-    evidence_inputs: Sequence[ResolvedEvidenceInput],
-    candidates: Mapping[Path, AnalysisReportCandidate],
-) -> dict[str, object]:
-    """Normalize a feature-index identifier or a non-empty free-text target."""
-    target = raw_target.strip()
-    if not target:
-        raise AnalysisInputError("analysis target must not be empty")
-    if not _FEATURE_ID_RE.fullmatch(target):
-        return {"inputMode": "free-text", "requestedValue": target}
-    matches: list[dict[object, object]] = []
-    for evidence in evidence_inputs:
-        if evidence.relation != "project-context":
-            continue
-        candidate = candidates.get(evidence.report_path)
-        if candidate is None:
-            candidate = next(
-                (value for path, value in candidates.items() if path.resolve() == evidence.report_path),
-                None,
-            )
-        if candidate is None:
-            continue
-        matches.extend(
-            feature for feature in candidate.feature_index
-            if isinstance(feature, dict) and feature.get("id") == target
-        )
-    if len(matches) != 1:
-        raise AnalysisInputError(
-            f"exactly one project-context feature must match {target}"
-        )
-    return {
-        "inputMode": "feature-index",
-        "requestedValue": target,
-        "feature": dict(matches[0]),
-    }

package/runtime/python/okstra_ctl/analysis_scope.py

@@ -0,0 +1,31 @@
+"""분석 증거와 단계 내용 검증이 공유하는 프로젝트 상대 경로 판독."""
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+
+def _normalized_project_path(path: object) -> PurePosixPath | None:
+    if not isinstance(path, str):
+        return None
+    raw = path.strip().rstrip("/")
+    if not raw or raw == "." or raw.startswith("/"):
+        return None
+    if any(part in {"", ".", ".."} for part in raw.split("/")):
+        return None
+    normalized = PurePosixPath(raw)
+    if normalized.is_absolute():
+        return None
+    return normalized
+
+
+def _path_is_included(path: object, included_paths: list[object]) -> bool:
+    candidate = _normalized_project_path(path)
+    if candidate is None:
+        return False
+    for raw in included_paths:
+        included = _normalized_project_path(raw)
+        if included is not None and (
+            candidate == included or included in candidate.parents
+        ):
+            return True
+    return False

package/runtime/python/okstra_ctl/asset_roots.py

@@ -0,0 +1,19 @@
+"""Ancestor-based runtime asset lookup independent of run and phase state."""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+
+def walk_to_asset_root(
+    relative: Sequence[str],
+    *,
+    start: Path,
+    is_present: Callable[[Path], bool] = Path.is_file,
+) -> Path | None:
+    """Return the nearest ancestor carrying the asset without home overrides."""
+    here = Path(start).resolve()
+    for parent in [here, *here.parents]:
+        if is_present(parent.joinpath(*relative)):
+            return parent
+    return None

package/runtime/python/okstra_ctl/consumers.py

@@ -430,3 +430,15 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
         settled_stages.add(stage)
         recovered += 1
     return recovered
+
+
+def require_done_task_key(rows: List[Dict[str, Any]], stage: int) -> str:
+    from .handoff_error import HandoffError
+
+    done = latest_done_by_stage(rows)
+    row = done.get(stage)
+    if not row:
+        raise HandoffError(
+            f"stage {stage} has no done row in consumers.jsonl — "
+            "finish the implementation stage first")
+    return row.get("impl_task_key", "")

package/runtime/python/okstra_ctl/contract_graph.py

@@ -10,6 +10,14 @@ from typing import Any
 
 from .final_report_schema import validate as validate_schema
 from .json_boundary import JsonBoundaryError, load_owned_object
+from .phases.catalog import (
+    PHASES,
+    UnknownTaskType,
+    is_migrated,
+    package_root,
+    profile_contract,
+    profile_markdown,
+)
 
 
 _SCHEMA_FILES = {
@@ -199,16 +207,12 @@ def _load_contracts(root: ContractGraphRoot) -> _LoadedContracts:
         common = _load_json_contract(root.common, "agents/common.json")
         roles = _load_directory(root.roles, "agents/roles")
         duties = _load_directory(root.duties, "prompts/duties")
-        profiles = _load_directory(
-            root.profiles,
-            "prompts/profiles",
-            excluded_names=frozenset({"forbidden-actions.json"}),
-        )
+        profiles = _load_profile_contracts(root)
         operations = _load_directory(root.operations, "agents/operations")
     except JsonBoundaryError as exc:
         relative = str(exc.artifact)
         raise ContractGraphError([f"{relative}: <root>: {exc.reason}"]) from exc
-    markdown = _load_profile_markdown(root.profiles, profiles)
+    markdown = _load_profile_markdown(root, profiles)
     return _LoadedContracts(common, roles, duties, profiles, operations, markdown)
 
 
@@ -234,25 +238,86 @@ def _load_json_contract(path: Path, relative_path: str) -> ContractFile:
     return ContractFile(relative_path, schema_version, _digest(path), payload)
 
 
+def _load_profile_contracts(root: ContractGraphRoot) -> tuple[ContractFile, ...]:
+    legacy = _load_directory(
+        root.profiles,
+        "prompts/profiles",
+        excluded_names=frozenset({"forbidden-actions.json"}),
+    )
+    migrated = _migrated_profile_contracts(_asset_root(root.profiles))
+    return _merge_profile_contracts(legacy, migrated)
+
+
+def _asset_root(profiles_dir: Path) -> Path:
+    # `ContractGraphRoot.from_base` 가 profiles 를 <base>/prompts/profiles 로 만든다.
+    # 손으로 만든 루트도 같은 배치를 따라야 단계 패키지를 찾는다.
+    return profiles_dir.parent.parent
+
+
+def _migrated_profile_contracts(asset_root: Path) -> tuple[ContractFile, ...]:
+    if package_root(asset_root) is None:
+        return ()
+    rows: list[ContractFile] = []
+    for record in PHASES:
+        if not record.migrated:
+            continue
+        path = profile_contract(asset_root, record.task_type)
+        logical = f"prompts/profiles/{record.task_type}.json"
+        if not path.is_file():
+            raise ContractGraphError([
+                f"{logical}: migrated profile contract missing: {path}"
+            ])
+        rows.append(_load_json_contract(path, logical))
+    return tuple(rows)
+
+
+def _merge_profile_contracts(
+    legacy: tuple[ContractFile, ...],
+    migrated: tuple[ContractFile, ...],
+) -> tuple[ContractFile, ...]:
+    # 단계 패키지의 계약이 정본이다. 같은 id 의 prompts/profiles 사본은 업데이트가
+    # 남긴 옛 파일이다: `okstra install` 은 Python 트리를 먼저 복사하고 prompts 를
+    # 나중에 복사·정리하므로, 그 사이나 중간 실패 뒤에는 두 곳에 다 있다. 저장소에
+    # 옛 사본이 없다는 것은 test_phase_catalog 가 확인한다.
+    migrated_ids = {Path(row.relative_path).stem for row in migrated}
+    current = tuple(
+        row for row in legacy if Path(row.relative_path).stem not in migrated_ids
+    )
+    return tuple(sorted((*current, *migrated), key=lambda row: row.relative_path))
+
+
 def _load_profile_markdown(
-    directory: Path, profiles: Sequence[ContractFile]
+    root: ContractGraphRoot, profiles: Sequence[ContractFile]
 ) -> dict[str, ContractFile]:
+    asset_root = _asset_root(root.profiles)
     rows: dict[str, ContractFile] = {}
+    missing: list[str] = []
     for profile in profiles:
         profile_id = Path(profile.relative_path).stem
-        path = directory / f"{profile_id}.md"
+        logical = f"prompts/profiles/{profile_id}.md"
+        path = _profile_markdown_path(asset_root, root.profiles, profile_id)
         if not path.is_file():
+            if is_migrated(profile_id):
+                missing.append(f"{logical}: missing migrated profile markdown: {path}")
             continue
-        relative_path = f"prompts/profiles/{path.name}"
         rows[profile_id] = ContractFile(
-            relative_path,
+            logical,
             profile.schema_version,
             _digest(path),
             {"text": path.read_text(encoding="utf-8")},
         )
+    if missing:
+        raise ContractGraphError(missing)
     return rows
 
 
+def _profile_markdown_path(asset_root: Path, profiles_dir: Path, profile_id: str) -> Path:
+    try:
+        return profile_markdown(asset_root, profile_id)
+    except UnknownTaskType:
+        return profiles_dir / f"{profile_id}.md"
+
+
 def _validate_documents(
     loaded: _LoadedContracts, schemas: Mapping[str, Mapping[str, Any]]
 ) -> None:

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -59,6 +59,7 @@ from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
+    validate_plan_verify_dispatch_identity,
     validate_prompt_model_header,
     validate_reverify_prompt,
 )
@@ -1905,6 +1906,26 @@ def validate_initial_prompts(
         raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
 
 
+def _validate_plan_verify_identities(jobs: Sequence[WorkerJob]) -> None:
+    errors: list[str] = []
+    for job in jobs:
+        try:
+            text = job.prompt_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            errors.append(f"{job.worker_id}: cannot read prompt {job.prompt_path}: {exc}")
+            continue
+        errors.extend(
+            f"{job.worker_id}: {error}"
+            for error in validate_plan_verify_dispatch_identity(
+                text,
+                dispatch_kind=job.dispatch_kind,
+                result_name=job.worker_result_path.name,
+            )
+        )
+    if errors:
+        raise DispatchError("plan-body dispatch contract: " + "; ".join(errors))
+
+
 def validate_dispatch_prompts(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -1912,6 +1933,7 @@ def validate_dispatch_prompts(
 ) -> None:
     if isinstance(manifest.get("agentContract"), Mapping):
         _validate_agent_invocations(manifest, jobs)
+    _validate_plan_verify_identities(jobs)
     initial_jobs = [
         job for job in jobs if not is_verification_dispatch_kind(job.dispatch_kind)
     ]

package/runtime/python/okstra_ctl/doctor.py

@@ -11,8 +11,10 @@ from typing import Iterable
 from okstra_project import ResolverError, project_json_path, resolve_project_root
 from okstra_project.resolver import resolve_review_rule_packs
 
-from . import improvement_lenses, worktree_registry
+from . import worktree_registry
+from .phases.improvement_discovery import lenses as improvement_lenses
 from .models import provider_wrappers
+from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
 from .workers import resolve_profile_workers
 from .worktree import is_git_work_tree, main_worktree_path
 from .json_boundary import JsonBoundaryError, load_owned_object
@@ -207,7 +209,10 @@ def _review_rule_pack_check(project_root: Path) -> DoctorCheck | None:
 
 
 def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
-    profile = _profile_path(workspace, phase)
+    try:
+        profile = _profile_path(workspace, phase)
+    except PhaseAssetError as exc:
+        return _fail("profile", str(exc))
     if profile.is_file():
         return _ok("profile", str(profile))
     return _fail("profile", f"not found: {profile}")
@@ -311,7 +316,10 @@ def _worker_dispatch_checks(
     phase: str,
     host_runtime: str,
 ) -> list[DoctorCheck]:
-    workers = resolve_profile_workers(_profile_path(workspace, phase))
+    try:
+        workers = resolve_profile_workers(_profile_path(workspace, phase))
+    except PhaseAssetError as exc:
+        return [_fail("worker dispatch", str(exc))]
     if not workers:
         return [_ok("worker dispatch", "no workers required")]
     if not host_runtime:
@@ -456,7 +464,10 @@ def _agent_path(home: Path, worker: str) -> Path:
 
 
 def _profile_path(workspace: Path, phase: str) -> Path:
-    return workspace / "prompts" / "profiles" / f"{phase}.md"
+    try:
+        return profile_markdown(workspace, phase)
+    except UnknownTaskType:
+        return workspace / "prompts" / "profiles" / f"{phase}.md"
 
 
 def _run(

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -281,7 +281,8 @@ class ExecutionMutationAudit:
             + tuple(f"unattributed change outside assigned worktree and artifact paths: {path}"
                     for path in sorted(external))
             + _plan_change_warnings(rows, source_changes | untracked_changes,
-                                    artifact_changed, out_of_plan_edits, unobserved),
+                                    artifact_changed, out_of_plan_edits, unobserved)
+            + _linked_dependency_warnings(after.root),
             changed_artifact_paths=tuple(sorted(artifact_changed - external)),
             declared_out_of_plan_paths=tuple(out_of_plan_edits),
             unobserved_artifact_paths=tuple(sorted(unobserved)),
@@ -370,6 +371,31 @@ def _audit_warnings(untracked_artifact_changes: set[str]) -> tuple[str, ...]:
     )
 
 
+def _linked_dependency_warnings(root: Path) -> tuple[str, ...]:
+    """worktree 밖을 가리키는 `node_modules` 링크를 알린다.
+
+    감사는 `node_modules` 를 보지 않으므로, 그 링크를 통한 패키지 설치가 메인
+    체크아웃의 의존성 트리를 덮어써도 흔적이 남지 않는다(2026-09-25 실측).
+    """
+    linked: list[str] = []
+    for current, directories, _ in os.walk(root, followlinks=False):
+        kept: list[str] = []
+        for name in directories:
+            path = Path(current) / name
+            if name == ".git":
+                continue
+            if name not in _INSTALLED_DEPENDENCY_DIRS:
+                kept.append(name)
+            elif path.is_symlink() and not _is_relative_to(path.resolve(), root.resolve()):
+                linked.append(f"{path.relative_to(root).as_posix()} -> {path.resolve()}")
+        directories[:] = kept
+    return tuple(
+        f"dependency tree links outside the assigned worktree: {row}; "
+        "a package install through it rewrites that target and this audit does not observe it"
+        for row in sorted(linked)
+    )
+
+
 def _branch_switch_warnings(
     before: MutationSnapshot, after: MutationSnapshot, switched: set[str],
 ) -> tuple[str, ...]: