okstra 0.36.0 → 0.36.1

package/runtime/prompts/profiles/implementation.md

@@ -14,148 +14,41 @@
   - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
   - Wherever this profile mentions the `Executor`, it refers to the role bound above. The other two providers in the roster (`claude` / `codex` / `gemini` minus the executor) are dispatched as **verifiers only** for this run and remain strictly read-only.
 {{INCLUDE:_common-contract.md}}
-- Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier set in this phase):
-  - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
-  - **Verifier roles:** the verifier slots are `Claude verifier` and `Codex verifier`, plus `Gemini verifier` **only when `gemini` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
-  - **Verifier QA duties (independent re-run mandate):** every verifier acts as a QA gate, not just a diff reviewer. Trusting the executor's reported evidence is forbidden — verifiers MUST reproduce it themselves from the same worktree path the executor used.
-    - **Two-tier command lookup (NO auto-detection):** verifier obtains the QA command set from exactly two declared sources, in order — there is **no fallback to guessing tools from manifest files**.
-      1. **Tier 1 — plan validation set (task-specific):** every command listed under the approved plan's `validation` block (pre / mid / post).
-      2. **Tier 2 — project baseline (`project.json.qaCommands`):** the project's standing QA baseline declared in `<PROJECT_ROOT>/.project-docs/okstra/project.json` under the `qaCommands` key. Schema (each category is an array of `{ "label", "cmd", "language"? }` objects):
-         ```json
-         {
-           "qaCommands": {
-             "lint":      [{ "label": "cargo clippy", "cmd": "cargo clippy --all-targets -- -D warnings", "language": "rust" }],
-             "format":    [{ "label": "cargo fmt",    "cmd": "cargo fmt --check",                          "language": "rust" }],
-             "typecheck": [{ "label": "tsc",          "cmd": "pnpm exec tsc --noEmit",                     "language": "ts"   }],
-             "test":      [{ "label": "cargo test",   "cmd": "cargo test --workspace --locked",            "language": "rust" }]
-           }
-         }
-         ```
-         `language` is optional; when present, verifier MAY skip categories whose `language` is not represented in this run's diff (recorded as `qa-command skipped: <label> (language=<x> not in diff)`). Absent `language` means "always run".
-    - **Execution rule:** Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Forbidden actions).
-    - **Missing-tier handling:** if a tier is empty or absent, verifier records the single line `qa-command not configured: <category>` per missing category (`lint` / `format` / `typecheck` / `test`) in the worker result and proceeds — silent omission is a contract violation. Verifier MUST NOT auto-detect or invent a command in this case; the user/operator must declare it in `project.json.qaCommands` or in the plan.
-    - **`cmd` field deny-list (Tier 2 validation):** the runtime AND the verifier MUST reject any `cmd` containing tokens that imply mutation: `--fix`, `--write`, ` -w` (gofmt write), ` -u` (jest snapshot update), `--update-snapshots`, `--snapshot-update`, `--update-goldens`, `INSTA_UPDATE=` (with any value other than `no`), `cargo insta accept`, `npm install` (without `ci`), `cargo update`, `pip install -U`, `pnpm add`, `bun add`. Encountering a denied token aborts the verifier run with `contract-violated` and the operator is asked to re-declare the command in check-only form.
-    - **Discrepancy rule:** if the verifier's re-run result differs from what the executor reported (a passing test fails on re-run, a clean lint surfaces warnings, an exit code mismatches), the verifier MUST issue verdict `FAIL` with the divergence cited. `Claude lead` MUST NOT silently prefer the executor's evidence over a verifier's reproduced result during synthesis; if it overrides, it MUST cite a concrete reproduction-time reason (flaky-test commit-cited, environment delta documented) — handwaving is not allowed.
-    - **Read-only command log (per verifier):** the worker result MUST contain a `Read-only command log` block listing every command executed during the verifier run with its exact invocation and exit code, in execution order. No mutating command may appear in this block. This log is copied into the final report's verifier result section verbatim.
-    - **Verifier evidence is independent of executor evidence:** the final report keeps both — executor's `Validation evidence` AND each verifier's `Read-only command log` — so reviewers can compare them line-by-line.
-  - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
-  - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
-  - **All-verifier-failure policy**: if every verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or more verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
-  - that file's YAML frontmatter MUST carry `approved: true`. report-writer emits `approved: false` by default; the user flips it to `true` to authorise this run. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file's frontmatter line to `approved: true` before invoking the implementation run.
-  - Two equally-valid approval paths exist (both end up satisfying the same frontmatter check):
-    - **Manual edit** — the user opens the report, changes the frontmatter line `approved: false` to `approved: true`, saves, then runs `okstra ... --task-type implementation --approved-plan <path>`.
-    - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the frontmatter `approved` to `true` and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard frontmatter validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
-  - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the frontmatter already has `approved: true` (idempotent — only an audit line is appended, the flag is not re-toggled).
-  - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
+  - that file's YAML frontmatter MUST carry `approved: true`. report-writer emits `approved: false` by default; the user flips it to `true` to authorise this run. Free-form approvals such as "lgtm" / "go ahead" / paraphrased confirmations are NOT accepted; re-edit the plan file's frontmatter to `approved: true` before invoking implementation, or pass `--approve` so the CLI flips it on the user's behalf (`okstra_ctl.run._apply_cli_approval`).
+  - The `--approve` flag is meaningful ONLY with `--task-type implementation` and `--approved-plan <path>`; any other use raises `PrepareError`. Idempotent — re-running with `approved: true` already set appends an audit line but does NOT re-toggle.
+  - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; deviations must be justified in the final report and routed back to a new `implementation-planning` run rather than silently expanded.
 - Task worktree (provisioned by `okstra-ctl` at the first phase's run-prep time, reused for every subsequent phase of this task-key):
   - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `reused` | `skipped-in-worktree` | `skipped-not-git`)
-  - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created` or `reused`, this is the task's `git worktree` rooted at `~/.okstra/worktrees/<project>/<task-group>/<task-id>/` (segments sanitised — `/` `:` → `-`). When skipped, this is the caller's `project_root`.
-  - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` — empty when status is `skipped-*`. The branch name encodes `<work-category-prefix>-<task-id-segment>` and is globally unique across task-keys via `~/.okstra/worktrees/registry.json`.
-  - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — commit SHA the worktree was branched from at the first phase; canonical `<base>` for every `git diff` / `git log` in this run.
+  - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created` or `reused`, this is the task's `git worktree` rooted at `~/.okstra/worktrees/<project>/<task-group>/<task-id>/`. When skipped, this is the caller's `project_root`.
+  - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` — empty when status is `skipped-*`. Branch name = `<work-category-prefix>-<task-id-segment>`, globally unique via `~/.okstra/worktrees/registry.json`.
+  - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — canonical `<base>` for every `git diff` / `git log` in this run.
   - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
-  - **Executor behaviour**: when status is `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the working tree path above as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files; if a file outside the worktree is needed, the dependency is a planning gap — record it in `Out-of-plan edits` and continue.
-    - **How to set cwd per Bash call**: the Claude Bash tool inherits its cwd from the lead session, which is NOT the worktree. To put cwd-sensitive toolchains (`cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, `go`) into the worktree, prefix the command with `cd {{EXECUTOR_WORKTREE_PATH}} && ` inside the same Bash invocation — e.g. `cd {{EXECUTOR_WORKTREE_PATH}} && cargo test -p foo`. **Never wrap in `bash -lc "..."` or `bash -c "..."`** — the wrapper hides the leading `cd` token from Claude Code's permission auto-allow layer (causing prompts on every call) without any safety benefit. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form over the `cd && ` chain. Edit / Write / Read tool calls already use absolute paths and need no cwd handling. The codex / gemini executor CLI wrappers (`okstra-codex-exec.sh -C`, `okstra-gemini-exec.sh --include-directories`) already inject worktree cwd at the CLI layer, so this rule applies primarily to the Claude executor.
-  - **Verifier behaviour**: all verifier roles in the resolved roster read from the SAME working tree path so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
-  - **Lifecycle**: the worktree is kept after the run completes (no automatic cleanup) and is reused by every subsequent phase of the same task-key. Cleanup, when the task is fully done, is manual: `git -C <main-worktree> worktree remove <path>` followed by `git -C <main-worktree> branch -D <branch>`, plus removing the task-key entry from `~/.okstra/worktrees/registry.json`.
-  - **Skipped paths**: when status is `skipped-in-worktree` or `skipped-not-git`, the executor operates in `project_root` as before. Cite the status in the final report's metadata header so reviewers know which path was taken.
-  - **Synced okstra state directory (symlink into the MAIN worktree)**: at provision time `okstra-ctl` may symlink `.project-docs/` from the repo's **main worktree** into the task worktree. This is NOT an independent copy — writes through it land in the main worktree. Inside this run the executor MUST confine okstra artifact writes to its own task scope (i.e. `.project-docs/okstra/tasks/<this-task-id>/...`). Other synced directories, if present due to local configuration, are not implicit okstra context; read them only when the brief explicitly cites them as source material.
-- Pre-implementation context exploration (executor before first edit):
-  - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
-    - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.
-    - Doc-only / config-only / pure-rename steps that have no observable runtime behaviour are exempt from the failing-test requirement, but the executor MUST cite the exemption per step in the final report (`TDD exemption: <reason>`).
-    - When the touched area has no existing test harness, the executor MUST stand up the minimum harness needed to host one regression test for this run rather than skipping TDD entirely. Record the harness-bootstrap step as an `Out-of-plan edit` if it is not in the plan.
-  - re-read the approved plan end-to-end and parse the `## 4.5 Stage Map`. Determine **start stage**:
-    - if `--stage <N>` is supplied, use N. Otherwise auto = the lowest stage number whose `depends-on` are all recorded as `status:done` in `runs/<plan-key>/consumers.jsonl` AND that itself has no `status:done` row. Multiple stages may match — two parallel `implementation` runs may pick different ones and proceed concurrently.
-    - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(start_stage)` and inject them into the executor's working context as "runtime carry-in". For `depends-on (none)` stages, no sidecar load — task-brief only.
-    - extract the **start stage's** file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path. These — not the whole plan — are the authoritative scope for this run.
-  - inspect the current state of every file the plan names; if any file has changed materially since the plan was written, stop and route to a new `implementation-planning` run instead of editing speculatively
-  - "materially changed" means: the function, class, section, or behaviour the plan targets has been edited, renamed, moved, removed, or otherwise altered in a way that invalidates the plan's reasoning. Cosmetic edits (whitespace, comment-only changes, unrelated function modifications elsewhere in the same file) do NOT trigger a re-plan; cite the diff (`git log --oneline <plan-created-at>..HEAD -- <file>`) in the final report and proceed.
-  - distinguish the two file-scope rules (they are not in conflict):
-    - **drift rule** (this section): if a file *named in the plan* has materially drifted, refuse to edit and route back to planning. This protects trust in the approved scope.
-    - **out-of-plan rule** (Allowed actions section below): if a step *requires touching a file NOT in the plan list*, that is permitted with `Out-of-plan edits` justification. This handles honest scope discovery during execution.
-  - confirm the test/build commands referenced in the plan still exist and run from a clean state
-- Stage execution contract (this run owns exactly one stage of the plan):
-  - **Sidecar evidence writer (BLOCKING).** When the start stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal).
-  - **Reverse link (BLOCKING).** Before the first Edit/Write, append a `status:"started"` row to `runs/<plan-task-key>/consumers.jsonl` (lock via the okstra runtime). On stage completion, append a `status:"done"` row with `carry_path` populated.
-  - **One-PR-per-stage.** This run creates exactly one PR titled `Stage <N>: <stage title>`. The PR body MUST include:
-    - `## Stage` — number and title (from Stage Map row).
-    - `## Carry-In summary` — depends-on list + cited identifiers/SHAs from each loaded sidecar (omit when depends-on is empty).
-    - `## Next stage` — next stage number/title or `(last stage)`.
-    Stage PRs link back to each other in their bodies (`Previous: #<n>, Next: #<m>` lines) so a reviewer can navigate the chain.
-- Allowed actions during the run:
-  - **Edit / Write on approved project source files**: scope is bounded first by the shared Resource boundary, then by the approved plan's file list. Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in the final report's `Out-of-plan edits` block with rationale.
-  - read-only inspection commands: `git status`, `git diff`, `git log`, `grep`, `rg`, `find`, `cat`, `ls`, file Read tools
-  - build, lint, type-check, and test commands (`npm test`, `pytest`, `go build`, `cargo test`, `bash -n`, etc.)
-  - **local git operations only**: `git add`, `git commit`. Prefer small commits keyed to plan steps.
-  - **Commit message format (mandatory)**: every commit message MUST follow Conventional Commits — `<type>(<scope>): <subject>` for the first line, optional body separated by a blank line, optional footer. Constraints:
-    - `<type>` MUST be one of: `feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`. When the repo is `release-please`-managed, this aligns the commit with a configured changelog section.
-    - `<scope>` SHOULD be the plan step identifier or the primary module touched (e.g. `feat(report-writer): ...`). Omit the parentheses only when no meaningful scope applies.
-    - `<subject>` MUST be ≤72 characters, imperative mood (`add`, `fix`, `remove` — not `added` / `adding`), no trailing period, no emoji, no AI attribution lines (no `Co-Authored-By: Claude ...`, no `Generated with Claude Code`).
-    - Body (when present) explains *why*, not *what*; wrap at ~100 chars.
-    - Do NOT append okstra artefact paths to the commit message — no `Plan: .project-docs/okstra/...`, no `Report: ...`, no `Run: ...`, no `Task: ...` footers, and no other reference to files under `.project-docs/okstra/`. Those paths belong in the final report's `Plan link & approval evidence` section, not in git history; they rot quickly and leak internal layout into the upstream changelog.
-    - Allowed footers are limited to standard Conventional Commits trailers (`BREAKING CHANGE: ...`, `Refs: <issue/ticket-id>`, `Closes #<n>`). When citing a ticket, use the ticket id only (e.g. `Refs: DEV-9423`) — never a filesystem path.
-    - One commit MUST correspond to one plan step (or one cohesive sub-step). Do NOT bundle unrelated steps into a single commit, and do NOT split a single step across commits unless the plan explicitly sequenced it that way.
-    - The exact message used for each commit MUST be reproduced verbatim in the final report's `Commit list` so reviewers can audit it without re-running `git log`.
+  - Treat the working-tree path as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. cwd-sensitive Bash commands MUST be prefixed `cd {{EXECUTOR_WORKTREE_PATH}} && ` in the same Bash invocation (never `bash -lc "..."` wrappers — see executor sidecar for full rules).
+  - Lifecycle: kept after the run completes; reused by every subsequent phase of the same task-key. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` → drop registry entry.
 - Approval gate (phase-specific addendum to shared authority rule):
-  - the pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination
-- Forbidden actions (any occurrence → terminal status `contract-violated`):
+  - the pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination.
+- Forbidden actions — universal (any occurrence → terminal status `contract-violated`):
   - **`git push` of any kind**, including `--dry-run` against a real remote that produces side-effects
   - publishing or release commands: `npm publish`, `cargo publish`, `pip publish`, `gh release`, `docker push`
-  - real database migrations, schema changes that touch shared environments, or any command that writes to a non-local datastore
-  - production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)
-  - external API calls that *write* (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures
-  - source edits or Bash mutations performed by any verifier role
-  - any Edit/Write before the pre-implementation gate has passed
+  - real database migrations or schema changes that touch shared environments
+  - production credentials, deploy commands, infra mutation against non-local clusters
+  - external API WRITE calls (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures
   - dispatching parallel sub-agents beyond the required worker roster
-  - silent scope expansion — adding files, dependencies, or features that the approved plan did not list, without recording an `Out-of-plan edits` justification
-  - leaving placeholders such as TBD / TODO / "implement later" / "handle edge cases" in committed code
-  - **(verifier-specific)** running lint / formatter auto-fix modes during a verifier's re-run — `eslint --fix`, `prettier --write`, `ruff check --fix`, `rustfmt` (writes by default; verifiers MUST use `cargo fmt --check` or `rustfmt --check`), `gofmt -w`, `black .` (use `black --check`), `isort .` (use `isort --check-only`), or any equivalent rewrite mode
-  - **(verifier-specific)** updating snapshots / golden fixtures during verification — `jest -u` / `--updateSnapshot`, `pytest --snapshot-update`, `INSTA_UPDATE=*` (any value other than `no`), `cargo insta accept`, `--update-goldens`, or any equivalent "make the test agree with current output" flag
-  - **(verifier-specific)** masking test failure with selection or shell tricks during re-run — `-k <expr>` / `--ignore` / `--deselect` to skip subsets, trailing `|| true`, `set +e` followed by a manually softened comparison, redirecting non-zero exit to success. The plan's listed test command MUST run in full
-  - **(verifier-specific)** substituting the plan's validation commands — verifier MUST run the plan's pre/mid/post validation commands verbatim; replacing them with paraphrased or "equivalent" commands is forbidden. Adding supplementary check-only lint/type-check is allowed and is logged separately in the verifier's Read-only command log
-  - **(verifier-specific)** mutating lockfiles or dependency manifests — `npm install <pkg>`, `npm install` (without lockfile freeze; use `npm ci`), `pnpm add`, `bun add`, `cargo add`, `cargo update`, `pip install -U`, or any dependency install that is not lockfile-frozen (`--locked` / `--frozen-lockfile` / `npm ci` / `pip install --require-hashes`)
-  - **(verifier-specific)** git state mutations — `git add`, `git commit`, `git stash`, `git checkout -- <file>`, `git restore`, `git reset`, `git rebase`, `git merge`, branch creation/deletion, tag creation. Only read-only git queries (`git status`, `git diff`, `git log`, `git show`, `git rev-parse`, `git blame`) are permitted for verifiers
-  - **(verifier-specific)** running integration / end-to-end tests that produce non-local side effects (DB writes against a non-local datastore, external API writes, docker compose against a non-isolated environment) unless that exact command is listed in the approved plan's validation set
-  - **(verifier-specific)** redirecting tool caches or output to paths outside the worktree — e.g. setting `CARGO_TARGET_DIR`, `PYTEST_CACHE_DIR`, `NODE_OPTIONS=--require=<external>`, or any env var that causes the verifier's command to write outside the worktree's normal build artifact paths
-- Required deliverable shape (final report, in addition to the standard sections):
-  - **Plan link & approval evidence**: path to the approved `final-report.md`, the exact quoted approval marker, AND the executed stage number / title quoted from the Stage Map row.
-  - **Commit list**: each commit's SHA (or short SHA), message, and the plan step it satisfies
-  - **Diff summary**: `git diff --stat <base>..HEAD` output, plus a per-file one-line summary of changes
-  - **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
-  - **Stage sidecar evidence**: the JSON payload of `runs/<impl-task-key>/carry/stage-<N>.json` is embedded verbatim in a fenced ```json``` block, AND the `consumers.jsonl` rows this run appended are quoted line-by-line, so reviewers can audit the carry surface without grepping artifact directories.
-  - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
-  - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
-  - **Verifier results**: a section per verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) containing:
-    - their independent verdict (PASS / CONCERNS / FAIL),
-    - cited diff snippets supporting the verdict,
-    - the verifier's `Read-only command log` (every command they ran with exact invocation and exit code, in execution order — copied verbatim from the worker result),
-    - **independent validation re-run results** — per plan-validation command: command line, exit code, and tail of output captured by the verifier (not the executor); any divergence from the executor's reported result MUST be called out as a `Discrepancy` line citing both sides,
-    - **style / lint / type-check results** — each check-only tool the verifier ran, its exit code, and the count of new findings attributable to lines this run introduced. When no tool is configured for a touched language, record the single line `no lint/style tool configured for <language>`,
-    - any fix recommendations the verifier declined to apply.
-    `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph. If any verifier issued `FAIL` on a `Discrepancy` line, the synthesised verdict MUST be `FAIL` unless lead cites a concrete reproduction-time reason (committed flaky-test record, documented environment delta) for overriding.
-  - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
-    - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
-    - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
-    - **Schema migrations, config-format changes, or any change with persisted state**: a **dry-run of the rollback step is mandatory**, not preferred. Record the exact rollback command and its captured exit code / stdout. If the migration tool offers no dry-run mode (`--dry-run`, `--plan`, equivalent), the executor MUST refuse to claim rollback verification and instead end the run with a routing recommendation back to `implementation-planning` for a safer rollback strategy. Skipping this step on a stateful change is treated as a `contract-violated` outcome by `final-verification`.
-  - **Routing recommendation for `final-verification`**: brief note on whether the changes are ready for final-verification phase or need a new error-analysis / planning loop first.
-  - **Follow-up tasks (Section 7 of the final report)**: every item discovered during this run that was *not* delivered MUST appear in the final report's `## 7. Follow-up Tasks (후속 작업)` table with a concrete `Origin`, `New Task ID`, `Suggested task-type`, `Scope`, and `Reason / Why deferred`. Sources include: out-of-scope discoveries that the executor consciously chose not to fold into this run, verifier concerns the executor declined to fix in-place, scope-boundary items from the approved plan that turned out to need their own ticket, and any unresolved `## 5. Clarification Items` row carried over from the approved plan (`Status` ∈ `{open, answered}` at approval time). An empty section is acceptable but only when expressed as the single line `- 후속 작업 없음.` — silence is treated as a contract violation. Rows with `Auto-spawn? = yes` will be materialised by `scripts/okstra-spawn-followups.py` in Phase 7; rows with `Auto-spawn? = no` MUST also appear in `Section 6. Recommended Next Steps` so the user knows to act manually.
-- Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
-  1. **Plan coverage** — every step in the approved plan's recommended option must point to a commit (or an explicit `Skipped: <reason>` entry). List gaps.
-  2. **Evidence completeness** — every `Validation evidence` and `TDD evidence` claim has the actual command line and exit code? No paraphrased "tests pass" without output?
-  3. **Out-of-plan honesty** — files in the diff that are NOT in the plan list must appear in the `Out-of-plan edits` block. Cross-check with `git diff --name-only`.
-  4. **Verifier dissent preserved** — if the verifiers in the resolved roster disagree, the disagreement is visible in the report? Synthesis hides nothing?
-  5. **Forbidden action audit** — `git push`, publish, deploy, migration, third-party write commands: scan the run's session transcripts for any occurrence and confirm none happened.
-  6. **Placeholder scan** — restrict the scan to lines this run actually introduced; pre-existing placeholders in unchanged regions of touched files are out of scope. Required command (substitute `<base>` with the parent of the first commit in this run's commit list):
-     ```
-     git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
-     ```
-     Only newly-added lines (those starting with `+` and not part of the `+++` header) are inspected. If output is anything other than `clean`, the run MUST either remove the placeholders before finalising or record an explicit justification per occurrence in the final report.
-- Lead post-stage persistence (BLOCKING — runs after the Executor emits `### Stage Carry Evidence`):
-  - Parse the executor's `### Stage Carry Evidence` JSON block. If absent or unparsable, end with status `contract-violated` and route to a follow-up `error-analysis`.
-  - Write the JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json`. Refuse to overwrite an existing file (one stage = one sidecar; re-runs are out of scope for this version).
-  - Append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, and the SHA of HEAD. Use the okstra runtime's `consumers_mutex` helper (NOT a raw filesystem write) to honour the lock.
-  - Quote both files' new contents (the sidecar JSON in full, the new consumers row by itself) in the final report's `Stage sidecar evidence` deliverable section.
+  - any Edit/Write before the pre-implementation gate has passed
+  - source edits or Bash mutations performed by any verifier role (verifier-specific deny-list lives in the verifier sidecar)
 - In-phase debugging:
   - isolate root cause before changing the fix direction, but the executor MUST NOT route to a separate `error-analysis` phase mid-run; if a defect blocks plan progress, the executor records findings and routes to a new run after this one ends.
+
+## Lazy section pointers (BLOCKING for lead — load at the listed phase, not at Phase 1)
+
+The bulk of this profile's body is split into three sidecars so the lead's Phase 1 baseline stays under ~50 effective lines. Read each sidecar ONCE, at the phase noted, into the lead's active context — do NOT pre-load them at Phase 1.
+
+| Sidecar | Read at | Purpose |
+|---------|---------|---------|
+| `prompts/profiles/_implementation-executor.md` | Start of Phase 5 (after Stage Map parse, before Executor's first Edit / Write) | Executor role binding, Pre-implementation context exploration, TDD loop, Stage execution contract, allowed actions, commit-message format |
+| `prompts/profiles/_implementation-verifier.md` | Phase 5, between Executor stage completion and the first verifier dispatch | Verifier roles, Two-tier command lookup, deny-list, discrepancy rule, Read-only command log, verifier-specific forbidden actions |
+| `prompts/profiles/_implementation-deliverable.md` | Start of Phase 6 (after Phase 5.5 convergence completes, before report-writer dispatch prompt construction) | Required deliverable shape, Validation / TDD evidence rules, Verifier results structure, Self-review pass, Lead post-stage persistence |
+
+**Phase 5 / 6 진입 시 해당 sidecar 가 lead context 에 없으면 BLOCKING — phase 진입 거부.** Lead 는 sidecar 를 read 한 후 1 회 turn 안에 phase 의 후속 action 으로 이어가야 한다 (즉 sidecar 의 룰은 read 한 그 turn 부터 효력 발생).

package/runtime/python/okstra_ctl/paths.py

@@ -165,6 +165,9 @@ def compute_run_paths(
         "TASK_TYPE_SEGMENT": task_type_segment,
         "OKSTRA_ROOT": str(okstra_root),
         "OKSTRA_TASKS_ROOT": str(tasks_root),
+        "WORKER_PROMPT_PREAMBLE_PATH": str(
+            Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
+        ),
         "OKSTRA_DISCOVERY_DIR": str(discovery_dir),
         "TASK_ROOT": str(task_root),
         "TASK_MANIFEST_PATH": str(task_manifest),

package/runtime/python/okstra_ctl/render.py

@@ -651,15 +651,25 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "WORKFLOW_WORK_CATEGORY", "unknown"
     )
     # Compute the canonical next phase from current_phase deterministically.
-    # Only preserve `existing.workflow.nextRecommendedPhase` when it is a
-    # legitimate forward pointer — i.e. NOT equal to `current_phase` itself
-    # (which would mean the lifecycle pointer has stalled on the current
-    # phase and would loop forever).
+    # Only advance past `current_phase` when its state is terminal-success
+    # (`completed`). For `prepared` / `in-progress` / `blocked` / `error` /
+    # `contract-violated` states the recommendation MUST stay on
+    # `current_phase` — advancing prematurely makes wizards (and humans)
+    # think the current phase is done when it has merely been provisioned.
+    # Historical bug: implementation provisioned in `prepared` state caused
+    # the wizard to recommend `final-verification` as the default task_type.
     canonical_next = default_next_phase.get(
         current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown")
     )
     existing_next = workflow.get("nextRecommendedPhase") or ""
-    if existing_next and existing_next != current_phase:
+    terminal_success_states = {"completed"}
+    if current_phase_state not in terminal_success_states:
+        # Current phase has not finished — recommend staying on it. Suppress
+        # any stale `existing_next` that points further forward in the
+        # sequence; only honour a stale value if it points to the SAME
+        # current_phase (i.e. encodes "re-enter current phase").
+        next_recommended_phase = current_phase
+    elif existing_next and existing_next != current_phase:
         next_recommended_phase = existing_next
     else:
         next_recommended_phase = canonical_next
@@ -1516,6 +1526,10 @@ def apply_lead_prompt_defaults(ctx: dict) -> None:
     ctx.setdefault("VALIDATION_STATUS", "not-run")
     ctx.setdefault("RELATED_TASKS_BULLETS", "- None recorded")
     ctx.setdefault("RELATED_TASKS_INLINE", "None")
+    ctx.setdefault(
+        "WORKER_PROMPT_PREAMBLE_PATH",
+        str(Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"),
+    )
     if "AVAILABLE_MCP_SERVERS" not in ctx:
         ctx["AVAILABLE_MCP_SERVERS"] = build_available_mcp_servers_block(
             Path(ctx.get("PROJECT_ROOT", "."))

package/runtime/python/okstra_ctl/run.py

@@ -883,7 +883,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # path that does not exist.
     write_claude_resume_command_file(
         resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
-        project_root=project_root, claude_session_id=claude_session_id,
+        project_root=project_root,
+        claude_session_id=claude_session_id,
+        task_key=ctx["TASK_KEY"],
+        task_type=ctx["TASK_TYPE"],
+        phase_state=ctx["CURRENT_RUN_STATUS"],
+        worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
+        prompt_seq=ctx["RUN_PROMPTS_SEQ"],
     )
 
     # ---- write instruction-set scaffolding ----

package/runtime/python/okstra_ctl/session.py

@@ -49,18 +49,76 @@ def resolve_inproc_lead_session_id(project_root: Path) -> str:
 
 
 def write_claude_resume_command_file(
-    *, resume_command_path: Path, project_root: Path, claude_session_id: str,
+    *,
+    resume_command_path: Path,
+    project_root: Path,
+    claude_session_id: str,
+    task_key: str,
+    task_type: str,
+    phase_state: str,
+    worker_prompts_dir_relative: str,
+    prompt_seq: str,
 ) -> None:
     """`bash claude-resume-*.sh` 를 실행하면 task 의 claude 세션을 resume
     하도록 shell 스크립트를 작성하고 chmod +x.
+
+    `claude --resume` 자체는 직전 세션 context 만 복구하고 lead 는
+    사용자 입력 대기 상태로 멈춘다. 따라서 사용자가 resume 후 무엇을
+    입력해야 하는지를 안내하는 guidance 블록을 sh 안에 inline 한다 —
+    sh 가 실행될 때 worker prompt 디스크 존재 여부를 직접 검사해
+    Phase 2 부터 / Phase 3 부터 중 알맞은 다음 명령을 추천한다.
     """
     resume_command_path = Path(resume_command_path)
     resume_command_path.parent.mkdir(parents=True, exist_ok=True)
-    body = (
-        "#!/usr/bin/env bash\n"
-        "# Generated by okstra. Resume the prepared Claude session for this run.\n"
-        f'cd "{project_root}"\n'
-        f'exec claude --resume "{claude_session_id}"\n'
-    )
+    body = f"""#!/usr/bin/env bash
+# Generated by okstra. Resume the prepared Claude session for this run.
+
+TASK_KEY={_sh_single_quote(task_key)}
+TASK_TYPE={_sh_single_quote(task_type)}
+PHASE_STATE={_sh_single_quote(phase_state)}
+PROJECT_ROOT={_sh_single_quote(str(project_root))}
+WORKER_PROMPTS_DIR="$PROJECT_ROOT/{worker_prompts_dir_relative}"
+PROMPT_SEQ={_sh_single_quote(prompt_seq)}
+SESSION_ID={_sh_single_quote(claude_session_id)}
+
+cat >&2 <<EOF
+============================================================
+okstra resume — $TASK_KEY
+Phase: $TASK_TYPE ($PHASE_STATE)
+============================================================
+
+이 스크립트는 Claude 세션 context 만 복구합니다.
+Lead 는 resume 직후 자동으로 진행하지 않으니, 첫 메시지로 다음을
+그대로 (또는 상황에 맞게 수정해서) 입력하세요:
+
+EOF
+
+if compgen -G "$WORKER_PROMPTS_DIR/*-worker-prompt-$TASK_TYPE-$PROMPT_SEQ.md" > /dev/null 2>&1; then
+  cat >&2 <<EOF
+  Phase 3 부터 진행 — TeamCreate 후 Phase 4 worker dispatch 까지.
+  Worker prompts (이미 작성·저장됨):
+    $WORKER_PROMPTS_DIR/*-worker-prompt-$TASK_TYPE-$PROMPT_SEQ.md
+EOF
+else
+  cat >&2 <<EOF
+  Phase 2 부터 진행 — worker prompts 작성·저장 후 Phase 3 진행.
+  Prompts directory (현재 비어 있음):
+    $WORKER_PROMPTS_DIR
+EOF
+fi
+
+cat >&2 <<EOF
+
+============================================================
+EOF
+
+cd "$PROJECT_ROOT"
+exec claude --resume "$SESSION_ID"
+"""
     resume_command_path.write_text(body, encoding="utf-8")
     os.chmod(resume_command_path, 0o755)
+
+
+def _sh_single_quote(value: str) -> str:
+    """POSIX-safe single-quote: `it's` → `'it'"'"'s'`."""
+    return "'" + value.replace("'", "'\"'\"'") + "'"

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

@@ -676,218 +676,9 @@ Use the same template per brief file. In tracker mode producing a parent
 plus N children, you write **N+1 files** (each carries only its own Source
 Material).
 
-Use this exact template. Leave a section's body as `_(none)_` rather than
-fabricating content. (The outer fence uses 4 backticks so it does not
-collide with the inner 3-backtick code block.)
+[`templates/reports/brief.template.md`](../../templates/reports/brief.template.md) is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
 
-````markdown
----
-type: brief
-brief-id: <ticket-id>-<file-title>          # equals the filename stem
-parent-id: self                              # always `self` at root; child briefs use parent's brief-id
-ticket-id: <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12 | "">
-source-type: <file | linear | jira | github | notion | url | user-input>
-task-group: <task-group>
-depth: 0                                     # 0=parent/single, 1=child, 2=grandchild, ...
-created: <YYYY-MM-DD>
-generator: okstra-brief
-reporter-confirmations: <complete | partial | pending | skipped>  # set by Step 6.5
-# codebase-scan variant frontmatter (omit for reporter-input briefs):
-scope: <reporter-input | codebase>              # 'codebase' for codebase-scan variant; omit for reporter-input variant
-priority-lenses: []                              # codebase-scan only: lens enum subset, size 1..4
-scan-scope: []                                   # codebase-scan only: 1+ paths
-out-of-scope: []                                 # codebase-scan only: optional
-candidate-cap: 8                                 # codebase-scan only: 1..12, default 8
----
-
-# Task Brief: <task_group>/<filename-without-ext>
-
-> Generated: okstra-brief · <YYYY-MM-DD>
-> Source type: <file | linear | jira | github | notion | url | user-input>
-> Tracker key (if any): <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12>
-> Parent brief (child briefs only): <relative path>
-> Recommended next phase: <requirements-discovery | error-analysis>  ← from Step 6
-> Handoff contract: see `prompts/profiles/_common-contract.md` § "Brief handoff contract"
-
-## Source Material
-
-<!-- author guidance — strip out at fill-in time:
-Paste each source separately and as-is. No paraphrasing, summarizing, or
-restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
-must be annotated in the header meta. Heading was originally
-"Source Material (verbatim — do not modify)" — the parenthetical is a
-reviewer note, not body text.
--->
-
-### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
-
-- ref: <abs file path | LIN-1234 | https://... | "conversation synthesis">
-- fetched-via: <Read | mcp__linear__getIssue | mcp__notion__... | gh issue view | WebFetch | user-paste>
-- fetched-at: <YYYY-MM-DD HH:MM>
-- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
-
-```
-<Paste the raw source here without changing a single character.>
-```
-
-<!-- Repeat `### Source N — …` blocks as needed. -->
-
-## Context
-
-<Background / scope / why now. If self-evident from Source Material, quote
-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` /
-`terminology-mapping` / `intent-inference`. Do NOT add any extra
-interpretation outside the `> augmented:` blockquote. -->
-
-## Problem / Symptom
-
-<Current state. For bugs: repro / observed / expected. For greenfield: gap
-between current and desired.>
-
-<!-- Same source-quote + `> augmented:` rule as the Context section. -->
-
-## Desired Outcome
-
-<Shape of success.>
-
-<!-- Do NOT prescribe a solution — that belongs to implementation-planning. -->
-
-## Constraints
-
-<Deadlines, compatibility, technical/operational limits. Use _(none)_ if
-none.>
-
-## Scan Scope
-
-<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
-<!-- Author guidance: one bullet per `scan-scope` path with a short description of what lives there. -->
-
-- <path>: <one-line description of contents / responsibility>
-
-## Priority Lenses
-
-<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
-<!-- Author guidance: one bullet per priority lens explaining why it is a priority for THIS scope. -->
-
-- <lens>: <short rationale tying this lens to the scope's risk surface>
-
-## Related Artifacts
-
-- <file path / URL / issue / prior task-key>
-
-## Open Questions
-
-<!-- author guidance — strip out at fill-in time:
-Prefix every row with one of these signals so the next phase knows how to
-handle it. Free-form rows are allowed only as `general:`.
-
-Allowed signals:
-- `general: <unresolved question the user flagged>`
-- `terminology: <reporter word> — needs canonical resolution against
-  <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
-- `intent-check: <restated inference> — confirm with reporter`
-  (auto-paired with every `intent-inference` augmentation)
-- `conversion-block: <reporter statement> — could not be mapped to project
-  vocabulary; reporter query required`
-- `adr-candidate: <topic>` — signal only; `implementation-planning`
-  evaluates and, if accepted, drafts a decision file at
-  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
-
-Use `_(none)_` only if every signal is empty. `intent-check:` and
-`conversion-block:` rows that are answered in Step 6.5 are NOT removed
-from this list — they receive a `[CONFIRMED <YYYY-MM-DD> → RC-N]`
-marker that links to the corresponding entry under
-`## Reporter Confirmations`.
--->
-
-- <fill in one row per signal, or replace with `_(none)_`>
-
-## Reporter Confirmations
-
-<!-- Populated by Step 6.5. Each subsection records one reporter answer
-verbatim, with a link back to the originating `Open Questions` row. -->
-
-_(none — pending or skipped)_
-
-<!-- when populated, the shape is:
-### RC-1 — <intent-check: or conversion-block: row id / topic>
-- asked: <YYYY-MM-DD HH:MM>
-- linked-row: `<exact Open Questions row text>`
-- answer (verbatim):
-
-  > <reporter's answer, byte-for-byte>
--->
-
-## Augmentation
-
-<!-- author guidance — strip out at fill-in time:
-Cross-references / interpretation / context added by the user or skill that
-is not in the original source. May be empty. Keep this section visually
-separated from Source Material — never inline it inside Source Material.
-
-Every entry below must start with one of the four labels:
-`evidence-link` / `format-conversion` / `terminology-mapping` /
-`intent-inference`. Unlabelled entries are forbidden.
--->
-
-### Domain alignment
-
-<!-- author guidance — strip out at fill-in time:
-Observations from Step 3b and the outcome of Step 4.5 (glossary applied
-vs. skipped). The actual glossary edits live in
-`<PROJECT_ROOT>/.project-docs/okstra/glossary.md` when applied; this
-section records what happened. Decision candidates are NOT recorded here —
-they flow through `Open Questions` as `adr-candidate:` rows for
-`implementation-planning` to evaluate (and, if accepted, draft into
-`<PROJECT_ROOT>/.project-docs/okstra/decisions/`).
-
-Allowed entry shapes:
-- `terminology-mapping: <reporter word> → <okstra glossary canonical>` —
-  routine glossary alignment, paired with `terminology:` in Open Questions
-  when unresolved.
-- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
-- `terminology-mapping: skipped glossary: <term> = <definition>` —
-  Step 4.5 outcomes.
-Use `_(none)_` if every alignment entry is empty.
--->
-
-- <fill in one entry per alignment, or replace with `_(none)_`>
-
-### Evidence links (file / symbol resolution)
-
-<!-- Allowed entry shapes:
-`evidence-link: <reporter phrase> → <relative path>:<line>` or
-`evidence-link: <reporter phrase> → <symbol> in <relative path>`.
-Use `_(none)_` if none. -->
-
-- <fill in one entry per link, or replace with `_(none)_`>
-
-### Intent inferences
-
-<!-- Every entry here is an unverified hypothesis. Each one MUST have a
-paired `intent-check:` row under Open Questions.
-
-Allowed entry shape:
-`intent-inference: <reporter phrase> → <qualitative restatement>`
-(qualitative only — never invent numeric thresholds).
-Use `_(none)_` if none. -->
-
-- <fill in one entry per inference, or replace with `_(none)_`>
-
-### Format conversions
-
-<!-- Allowed entry shape:
-`format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`.
-Use `_(none)_` if none. -->
-
-- <fill in one entry per conversion, or replace with `_(none)_`>
-````
-
-**Variant note:** The template above is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, ADD `## Scan Scope` and `## Priority Lenses` sections (already present in the template above, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both variants.
+**Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both variants.
 
 ### Required sections by variant