okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/workflow.py

@@ -7,14 +7,13 @@ task/run status, render-only flag) 만 받아서 WORKFLOW_* 필드 dict 를 돌
 `okstra_ctl.next_phase` 하나가 소유하고, 값은 리포트가 저작한 라우팅에서
 투영된다.
 
-task-type 별 PHASE_ALLOWED_OUTPUTS 본문 매핑은 모듈 상수(`PHASE_RULES`)로 보유하고,
-PHASE_FORBIDDEN_ACTIONS 는 `prompts/profiles/forbidden-actions.json` SSOT 에서 로드한다.
+단계별 출력·금지 문구는 선택한 단계의 boundary.json 에서 읽는다.
 """
 from __future__ import annotations
 
-import json
 from pathlib import Path
 from .json_boundary import load_owned_object
+from .phases.catalog import phase_boundary, phase_record, task_types
 
 PHASE_SEQUENCE = [
     "requirements-discovery",
@@ -35,125 +34,6 @@ ERROR_ANALYSIS_ROUTING_DIRECTIONS = {
     "implementation-option-selection": "begin-option-selection",
 }
 
-# Phase 별 allowed outputs. bash heredoc 원문 그대로 옮긴 값 — 들여쓰기와 백틱은
-# prompt template 에 그대로 박혀 lead 가 읽는다. forbidden actions 는 이 dict 가
-# 아니라 prompts/profiles/forbidden-actions.json (load_phase_forbidden) 이 SSOT.
-PHASE_RULES: dict[str, dict[str, str]] = {
-    "technical-verification": {
-        "allowed": (
-            "  - falsifiable experiment plans for the frozen unresolved facts\n"
-            "  - dependency installation, source experiments, tests and builds only in this run's experiment copies\n"
-            "  - command logs, observed signals and per-fact supported/refuted/inconclusive/not-run results\n"
-            "  - return to implementation-option-selection with evidence, without adoption or plan approval"
-        ),
-    },
-    "requirements-discovery": {
-        "allowed": (
-            "  - work-category classification (bugfix / feature / refactor / ops / improvement)\n"
-            "  - routing decision as the `routing` object `{nextTaskType, readyWhen, rationale}`: `nextTaskType` is `error-analysis` or `implementation-option-selection` and nothing else — this phase never hands off directly to planning or implementation. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `nextTaskType`\n"
-            "  - missing-input list and clarification requests\n"
-            "  - approval / confirmation checkpoints recorded for the next phase\n"
-            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
-        ),
-    },
-    "improvement-discovery": {
-        "allowed": (
-            "  - improvement candidate discovery within the lens whitelist defined in `scripts/okstra_ctl/improvement_lenses.py`\n"
-            "  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n"
-            "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence (path:line)\n"
-            "  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n"
-            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique / unverified)"
-        ),
-    },
-    "project-analysis": {
-        "allowed": (
-            "  - components, dependency directions, entry points, repositories, and external integrations\n"
-            "  - shallow feature index and scan scope\n"
-        ),
-    },
-    "feature-analysis": {
-        "allowed": (
-            "  - confirmed target and normal, alternate, and failure flows\n"
-            "  - rules, state transitions, external calls, and test coverage scope\n"
-        ),
-    },
-    "change-impact-analysis": {
-        "allowed": (
-            "  - preserved behavior, impacted items, and dependency propagation\n"
-            "  - test and operational impact\n"
-            "  - constraints and open decisions passed to implementation-planning\n"
-        ),
-    },
-    "error-analysis": {
-        "allowed": (
-            "  - symptom and trigger evidence\n"
-            "  - root-cause hypotheses with supporting citations\n"
-            "  - reproduction gaps and missing observability\n"
-            "  - validation paths to confirm or refute hypotheses\n"
-            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
-        ),
-    },
-    "implementation-option-selection": {
-        "allowed": (
-            "  - candidate-comparison evidence for up to three options per worker\n"
-            "  - preselected-validation of exactly ONE candidate: every analyser returns its own feasibility verdict on that one direction, `candidateAudit` stays empty, and no analyser generates an alternative. It is not a re-evaluation of the merged set — `okstra_ctl.implementation_options._validate_mode` rejects a preselected-validation report carrying more than one option or a non-empty audit\n"
-            "  - a ranked display of at most three options with requirement mappings\n"
-            "  - an audit record for every rejected candidate\n"
-            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
-        ),
-    },
-    "implementation-planning": {
-        "allowed": (
-            "  - pre-planning context exploration notes (files/interfaces inspected, recent commits scanned, ambiguities flagged)\n"
-            "  - selected-direction planning: realize the one validated selected direction without reopening candidate comparison, with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
-            "  - legacy candidate-comparison planning only: at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
-            "  - legacy candidate-comparison planning only: a trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
-            "  - bite-sized stepwise execution order for the selected direction or legacy recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
-            "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
-            "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
-            "  - report record `frontmatter.approved: false` awaiting `--approve` or the in-session wizard\n"
-            "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)\n"
-            "  - one endStateCoverage row per brief end-state id, each mapped to the R-NNN row that carries it"
-        ),
-    },
-    "implementation": {
-        "allowed": (
-            "  - approved-plan reference and quoted user-approval evidence\n"
-            "  - commit list with SHA, message, and the plan step each commit satisfies\n"
-            "  - `git diff --stat <base>..HEAD` summary plus per-file one-line change summary\n"
-            "  - `Out-of-plan edits` block listing every file touched outside the approved plan with rationale (empty block preferred)\n"
-            '  - validation evidence: actual stdout/stderr and exit code for every pre / mid / post command from the plan (no paraphrased "tests pass")\n'
-            "  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n"
-            "  - per-verifier sections for every verifier in the resolved roster, with an independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by the Okstra lead\n"
-            "  - rollback verification (advisory, never blocks — record the revert path for a human; `result` is ok / not-applicable / advisory — human-run)\n"
-            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`, and `rationale` is why that one and nothing else. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
-        ),
-    },
-    "final-verification": {
-        "allowed": (
-            "  - acceptance verdict with requirement coverage assessment\n"
-            "  - residual risk and regression notes\n"
-            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`, and `rationale` ties that choice to the verdict and the blocker list. Both `release-handoff` forms require a release-ready verdict — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`); either verification scope may route there, because release-handoff opens one PR per stage. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
-        ),
-    },
-    "release-handoff": {
-        "allowed": (
-            "  - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n"
-            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n"
-            "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
-            "  - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n"
-            "  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n"
-            "  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n"
-            "  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n"
-            "  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template"
-        ),
-    },
-}
-
-PHASE_RULES_UNKNOWN = {
-    "allowed": "  - outputs defined by the active task type",
-}
-
 
 def render_forbidden(items: list[str]) -> str:
     """Render a forbidden-action list to the `  - item` bullet block injected
@@ -161,24 +41,30 @@ def render_forbidden(items: list[str]) -> str:
     return "\n".join(f"  - {item}" for item in items)
 
 
-def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
-    """Load the forbidden-actions SSOT and render each phase to its bullet block.
-
-    `workspace_root` is the resolved okstra asset root (repo or runtime); the
-    JSON lives beside the profile `.md` files at
-    `prompts/profiles/forbidden-actions.json`.
-    """
-    path = Path(workspace_root) / "prompts" / "profiles" / "forbidden-actions.json"
-    data = load_owned_object(path, artifact="forbidden actions profile")
-    if "unknown" not in data:
-        # compute_workflow_state falls back to the "unknown" entry for any
-        # unmapped task_type; without it a missing/renamed key would surface as
-        # a KeyError deep in prompt assembly instead of here at the SSOT seam.
+def load_phase_boundary(workspace_root: Path, task_type: str) -> dict[str, str]:
+    """선택한 단계의 출력 경계를 읽고 구형 자산 루트의 금지 목록도 보존한다."""
+    fallback_path = Path(workspace_root) / "prompts" / "profiles" / "forbidden-actions.json"
+    fallback = load_owned_object(fallback_path, artifact="forbidden actions profile")
+    if "unknown" not in fallback:
         raise ValueError(
-            f"forbidden-actions SSOT at {path} is missing the required "
+            f"forbidden-actions SSOT at {fallback_path} is missing the required "
             "'unknown' fallback entry"
         )
-    return {phase: render_forbidden(items) for phase, items in data.items()}
+    if task_type not in task_types():
+        return {
+            "allowed": "  - outputs defined by the active task type",
+            "forbidden": render_forbidden(fallback.get(task_type, fallback["unknown"])),
+        }
+    path = phase_boundary(workspace_root, task_type)
+    if path is None:
+        # 패키지 없는 외부 프로필 루트는 기존 코드의 출력 정책과 자체 금지 목록을 쓴다.
+        path = Path(__file__).parent / "phases" / phase_record(task_type).package_name / "boundary.json"
+        data = load_owned_object(path, artifact="phase boundary")
+        items = fallback.get(task_type, fallback["unknown"])
+    else:
+        data = load_owned_object(path, artifact="phase boundary")
+        items = data["forbidden"]
+    return {"allowed": data["allowed"], "forbidden": render_forbidden(items)}
 
 
 def phase_position(task_type: str) -> str:
@@ -203,7 +89,7 @@ def compute_workflow_state(
     current_run_status: str,
     current_task_status: str,
     render_only: bool,
-    forbidden_by_phase: dict[str, str],
+    boundary: dict[str, str],
     work_category: str = "",
 ) -> dict:
     """WORKFLOW_* + PHASE_* 값을 dict 로 돌려준다."""
@@ -234,7 +120,6 @@ def compute_workflow_state(
     else:
         checkpoint_label = "run-prepared"
 
-    rules = PHASE_RULES.get(task_type, PHASE_RULES_UNKNOWN)
     last_completed = task_type if current_run_status == "completed" else ""
 
     resolved_work_category = (work_category or "").strip() or "unknown"
@@ -256,8 +141,6 @@ def compute_workflow_state(
         "WORKFLOW_LAST_COMPLETED_PHASE": last_completed,
         "WORKFLOW_AWAITING_APPROVAL": "false",
         "WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL": checkpoint_label,
-        "PHASE_ALLOWED_OUTPUTS": rules["allowed"],
-        "PHASE_FORBIDDEN_ACTIONS": forbidden_by_phase.get(
-            task_type, forbidden_by_phase["unknown"]
-        ),
+        "PHASE_ALLOWED_OUTPUTS": boundary["allowed"],
+        "PHASE_FORBIDDEN_ACTIONS": boundary["forbidden"],
     }

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

@@ -345,7 +345,7 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 
 1. `AskUserQuestion` (free text):
    `"Scan scope — comma-separated paths inside the project (e.g. src/foo/, src/bar/baz.py)"` → `scan_scope` (CSV).
-2. `AskUserQuestion` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/improvement_lenses.py`):
+2. `AskUserQuestion` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`):
    `"Priority lenses (pick 1–4)"` → `priority_lenses` (1..4 values from the enum).
    Current `LENSES` values (this list mirrors the module — if they diverge, the module wins; Step 6.6 `validate-brief` enforces the subset): `performance`, `security`, `readability`, `architecture`, `test-coverage`, `dx`, `observability`, `accessibility`.
 3. `AskUserQuestion` (free text):
@@ -362,7 +362,7 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 Validation (before Step 4 sharpening):
 
 - Confirm that each path in `scan_scope` actually exists inside `<PROJECT_ROOT>` via `ls` — if not, correct it with a single question.
-- Confirm that `priority_lenses` is a subset (1–4) of `LENSES` in `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` — on violation, show the enum + re-select. Final enforcement is done by Step 6.6 `validate-brief` (`check_codebase_scope`).
+- Confirm that `priority_lenses` is a subset (1–4) of `LENSES` in `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py` — on violation, show the enum + re-select. Final enforcement is done by Step 6.6 `validate-brief` (`check_codebase_scope`).
 - Confirm that `candidate_cap` is an integer in 1–12.
 
 Once validation passes, jump to Step 2 (task key).
@@ -632,7 +632,7 @@ These 5 rules apply only to `scope: codebase` briefs. The budget expands from th
 
 1. **scan-scope path existence check.** Confirm each path via `ls` / `Read`. If missing, correct it with a single question (offer the nearest path candidate as `Recommended:`).
 2. **Ambiguous path narrowing.** Narrow abstract paths like `"backend"`, `"payment module"` down to one or more concrete directories. Guess codebase-first, then confirm with a single question.
-3. **priority-lenses whitelist check.** Confirm it is a subset of `LENSES` in `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py`. If out-of-enum, offer the nearest in-enum value as `Recommended:`.
+3. **priority-lenses whitelist check.** Confirm it is a subset of `LENSES` in `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py`. If out-of-enum, offer the nearest in-enum value as `Recommended:`.
 4. **out-of-scope consistency.** Confirm each path in `out-of-scope` is a subset of `scan-scope`. If a path is unrelated, remove it with a single question or absorb it into scan-scope.
 5. **One line of lens-priority rationale.** If the brief body lacks a line on *why* each priority lens takes precedence in this scope, offer the result of a first codebase pass as `Recommended:` and ask one question.
 

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

@@ -428,7 +428,7 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
 ### Stage ended FAIL — stop the queue and report (not an exception gate)
-When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
 
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)

package/runtime/skills/okstra-user-response/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 
 # OKSTRA User Response
 
-Use this skill for open `C-*` clarification items and explicit plan decisions. The user alone selects or writes every answer. Never infer an answer or approval.
+Use this skill for open `C-*` clarification items, explicit plan decisions, and the implementation direction a finished `implementation-option-selection` comparison awaits. The user alone selects or writes every answer. Never infer an answer or approval.
 
 The model-facing commands are fixed text reads and typed transaction writes:
 
@@ -17,6 +17,7 @@ The model-facing commands are fixed text reads and typed transaction writes:
 | `user-response begin` | Open a sidecar transaction for one report identity. |
 | `user-response answer` | Add or replace one validated clarification answer. |
 | `user-response plan-decision` | Record an explicit plan decision in the transaction. |
+| `user-response direction` | Record the implementation direction the user picked in the transaction. |
 | `user-response legacy-report-authoring` | Record legacy report-authoring permission for report contract 2.0 only. |
 | `user-response finalize` | Atomically merge and publish the user-owned sidecar. |
 
@@ -71,7 +72,7 @@ Never invent a picker function. Never ask the user to type a number when the nat
 okstra user-response list-view --home <resolved-home> --project <projectId> --limit 3
 ```
 
-The view gives `Task key`, `Task type`, `Report`, open-item counts, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.
+The view gives `Task key`, `Task type`, `Report`, open-item counts, `Direction selection required`, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.
 
 Present up to three task choices through the host picker. A host free-text row or unmatched next message is the report path or task key.
 
@@ -89,6 +90,8 @@ Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approv
 
 When an axis says `not stated in the report`, repeat that text. Do not infer missing report-owned impact. The skill must **never invent it**.
 
+When the view prints `Direction candidates:`, the comparison awaits a direction. Each `Direction option N:` row gives the candidate id and name, `Recommended`, `Goal`, `Core mechanism`, and `Selectable`. The `Direction picker:` block lists only selectable candidates, recommended first, each with its `Option number`.
+
 ## Step 2b: Investigate cited context before asking
 
 Do not present a picker from the raw field dump. For each still-open item, read the investigation list the view printed:
@@ -127,9 +130,15 @@ Use the displayed values to confirm the user's choice. Do not copy a predefined
 
 Copy `kind` from the view. A `reframe` does not satisfy the gate. If the user asks what an item means, explain from the view plus the cited files already read, then ask the same item again.
 
+## Step 3b: Ask for the direction
+
+Only when `Current direction selection: none` and `Direction picker:` has rows. Ask one single-select question through the host picker, after any clarification whose answer would change the choice. The body says that the comparison is finished, that the chosen candidate becomes the input of `implementation-planning`, and that planning cannot start until one is chosen. Copy each `Direction picker:` `- Label:` / `Description:` pair in order. Remember the `Option number` of the picked row. A `Selectable: no - <reason>` candidate is never offered; when the user asks for it, state the reason.
+
+When the user adds a note or a constraint for the planner, keep their words verbatim for Step 6.
+
 ## Step 4: Confirm the complete response
 
-Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision or legacy report-authoring decision. Ask through the host picker, two options:
+Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision, direction, or legacy report-authoring decision. Ask through the host picker, two options:
 
 1. `Record as shown` (Recommended)
 2. `Change an answer`
@@ -150,7 +159,7 @@ For a predefined option, pass only its one-based number from the fixed view:
 okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
 ```
 
-Every value, rationale, and reason body file must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; do not use an external file or a symbolic link. For a direct user answer, write the exact value there. Write the rationale to a separate Markdown file only when present. Then run:
+Every value, rationale, and reason body file — and every direction note or constraints file — must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; do not use an external file or a symbolic link. For a direct user answer, write the exact value there. Write the rationale to a separate Markdown file only when present. Then run:
 
 ```bash
 okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <disposition> --value-file <value.md> [--rationale-file <rationale.md>]
@@ -174,6 +183,14 @@ okstra user-response plan-decision --transaction <transaction> --status <revisio
 
 Never infer a plan decision from the user's tone.
 
+When the user picked a direction, pass the picked row's `Option number`. Write a note or constraints the user stated to separate Markdown files in that same temporary directory, one constraint per line:
+
+```bash
+okstra user-response direction --transaction <transaction> --option-number <N> [--note-file <note.md>] [--constraints-file <constraints.md>]
+```
+
+The command refuses a candidate the planning gate would refuse and a report that does not await a direction.
+
 Only for a report whose fixed view says `Report contract: 2.0`, an explicit legacy report-authoring decision may be recorded. A reason file in that same temporary directory is always required:
 
 ```bash
@@ -194,6 +211,8 @@ Leave this guidance in the final answer:
 
 > This answer was recorded in the `user-responses/` sidecar (`<sidecar path>`). Re-running this task with `/okstra-run` attaches the answer to the next eligible phase.
 
+When a direction was recorded, add: start `implementation-planning` with `/okstra-run` and pick this report in the wizard's direction-report step.
+
 ## Output rules
 
 - Keep responses in the user's language.

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

@@ -52,7 +52,7 @@ 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.
+**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 `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Config and Deployment References
 

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

@@ -95,7 +95,7 @@ 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.
+**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 `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Configuration References and Expected Values
 

package/runtime/validators/validate-brief.py

@@ -32,7 +32,7 @@ Checks performed per brief file:
 10. `scope` is one of {reporter-input, codebase} (absent ⇒ reporter-input).
 11. codebase-scan variant (`scope: codebase`): the Scan Scope section is
     non-empty and Priority Lenses lists 1–4 values from the lens whitelist
-    (`scripts/okstra_ctl/improvement_lenses.py` SSOT).
+    (`scripts/okstra_ctl/phases/improvement_discovery/lenses.py` SSOT).
 12. When present, `Related Task Graph` is a markdown table with the canonical
     columns and relation/direction values from the okstra-brief-gen contract.
 13. The requirement/objective section `## Desired Outcome` (required in every
@@ -70,7 +70,7 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
     if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
         sys.path.insert(0, str(_ssot_dir))
 
-from okstra_ctl.improvement_lenses import (
+from okstra_ctl.phases.improvement_discovery.lenses import (
     LENSES,
     MAX_PRIORITY_LENSES,
     MIN_PRIORITY_LENSES,