okstra 0.166.2 → 0.168.0

package/README.md

@@ -225,7 +225,7 @@ Major workflow changes added to `main` after 0.8.0:
 
 - **Automatic isolated worktrees for every task type** — During preparation, `okstra-ctl` runs `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` once per task key to create an isolated working tree and a `<work-category-namespace>/<task-id-segment>` branch (for example, `feature/dev-9436` or `fix/dev-7311`). The user chooses the base ref with `--base-ref`, using the same choices as the release-handoff PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or a custom value. It is required in the first phase; the okstra-run skill collects it through `AskUserQuestion`, while non-interactive callers must pass `--base-ref` explicitly. Later **non-`implementation`** phases for the same task key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`) reuse the same path and branch. `implementation` runs are **stage-isolated**: each run executes one stage in its own `.../<task>/stage-<N>/` worktree on a `<work-category-namespace>/<task>-s<N>` branch, so independent stages with `depends-on (none)` can run concurrently without sharing a tree. The registry reserves both task keys and **stage keys** with flock. Provisioning is skipped when the caller is already in another worktree or project_root is not a Git repository; stage isolation degrades to a flat path in those cases. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus release/removal of the registry entry. Details: [`docs/architecture.md`](docs/architecture.md), in the *Task type* section, and [`docs/cli.md#--executor`](docs/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/prd/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
+- **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the installed default at `~/.okstra/templates/pr/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
 - **Host-aware lead adapters** — `okstra-run` resolves the current harness through the same dynamic host registry used by the terminal front door. Claude Code, Codex, Antigravity, Grok, and Kimi keep their matching provider assignment native; `external` remains the explicit all-CLI host. Host and provider are separate axes, and every non-native worker assignment uses its provider's registered CLI wrapper. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.

package/docs/pr-template-usage.md

@@ -13,22 +13,26 @@ Higher priority matches first. Once an upper step matches, the lower steps are n
 | 1 | **per-run override** | `okstra render-bundle --pr-template-path <path>` or the wizard's one-time input | A relative path is resolved against the caller cwd (override) or against `project_root` (using the same function as project scope). |
 | 2 | **project scope** | the `prTemplatePath` field in `<project_root>/.okstra/project.json` | A relative path is resolved against `project_root`. |
 | 3 | **global scope** | the `prTemplatePath` field in `~/.okstra/config.json` | **Only an absolute path or a `~/`-prefixed path** is allowed. A relative path is ambiguous and rejected. |
-| 4 | **default (skill bundle)** | the first existing file among the candidate paths (§2 below) | The fallback path right after `npx okstra install`. |
+| 4 | **default (installed runtime)** | the first existing file among the candidate paths (§2 below) | The fallback path right after `npx okstra install`. |
 
 If the file named in any of the 4 steps does not exist, it fails immediately with `PrTemplateError` (no silent fallback).
 
 ## 2. Default candidate paths
 
-1. `$OKSTRA_SKILLS_DIR/templates/prd/pr-body.template.md` — only when the `OKSTRA_SKILLS_DIR` environment variable is set.
-2. `~/.claude/skills/templates/prd/pr-body.template.md` — the standard location `npx okstra install` installs to.
+| # | Path | When it exists |
+|---|------|----------------|
+| 1 | `$OKSTRA_SKILLS_DIR/okstra-run/templates/pr-body.template.md` | Only when the `OKSTRA_SKILLS_DIR` environment variable is set. Nothing in okstra sets it for you — it is an escape hatch for a non-standard skill home. |
+| 2 | `$OKSTRA_HOME/templates/pr/pr-body.template.md` — `~/.okstra/templates/pr/pr-body.template.md` unless `OKSTRA_HOME` overrides the home | The location `npx okstra install` writes to. This is the candidate that normally matches. |
 
-The candidates are tried in priority order, and if all are absent it ends with an explicit error as follows.
+The candidates are tried in priority order, and if all are absent it ends with an explicit error that names every path it searched:
 
-> `no PR template available: default skill template not found. Reinstall okstra (npx okstra install) or set prTemplatePath in project.json / ~/.okstra/config.json.`
+```text
+no PR template available: default template not found. Searched: <candidate paths>. Reinstall okstra (`npx okstra install`) or set prTemplatePath in project.json / ~/.okstra/config.json.
+```
 
 ## 3. The original inside the source repository
 
-- [`templates/prd/pr-body.template.md`](../templates/prd/pr-body.template.md) — the original that `npx okstra install` copies to the §2 default location. To change the copy, edit this file and install again.
+- [`templates/pr/pr-body.template.md`](../templates/pr/pr-body.template.md) — the original that `npx okstra install` copies to `~/.okstra/templates/pr/pr-body.template.md` (§2 candidate 2). To change the copy, edit this file and install again.
 
 ## 4. Configuration commands — persistence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.166.2",
+  "version": "0.168.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.166.2",
-  "builtAt": "2026-08-11T13:40:27.396Z",
+  "package": "0.168.0",
+  "builtAt": "2026-08-12T10:32:35.419Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/coding-preflight/architectures/hexagonal.md

@@ -133,7 +133,33 @@ When a change adds or modifies a service's dependency on a concrete adapter —
 
 The verdict is mechanical: this change adds or modifies such a dependency → finding; the injection sits entirely on lines this change did not touch → clean.
 
-**An existing convention does not clear this one.** A codebase that injects concrete `*Repository` classes everywhere is precisely the debt this rule pays down, one touched injection at a time — matching the surrounding style is the condition being flagged, not a defence against it. Record it, say so in the note (*"matches existing convention — advisory"*), and propose the port: its name and the two or three method signatures it would declare — unless the project declares `architecture.style = hexagonal` in `.okstra/project.json`, where this item is blocking and that same port sketch is what you write rather than what you record: fix the injection before the write, never record-and-pass. This is the single rule in this overlay where a project-local convention does not override the pack; every other conflict still resolves in the project's favour.
+**An existing convention does not clear this one.** A codebase that injects concrete `*Repository` classes everywhere is precisely the debt this rule pays down, one touched injection at a time — matching the surrounding style is the condition being flagged, not a defence against it. Record it, say so in the note (*"matches existing convention — advisory"*), and propose the port: its name and the two or three method signatures it would declare — unless the project declares `architecture.style = hexagonal` in `.okstra/project.json`, where this item is blocking and that same port sketch is what you write rather than what you record: fix the injection before the write, never record-and-pass.
+
+---
+
+## Rule H6 — Business rules live in the domain, not in application services
+
+A service orchestrates: fetch, delegate the decision to a domain function, persist, publish. Flag changed service code that *decides* a business outcome inline instead of calling into the domain.
+
+Violations:
+
+- An `if` / `else` chain over domain fields that decides an outcome — eligibility, validity, which branch of a business process runs.
+- Arithmetic expressing a business formula: money, ranking, quota, date-based entitlement.
+- A private service method whose name is a domain concept (`isEligible…`, `computeDowngrade…`, `resolve…Status`). The name is telling you where it belongs.
+
+Not a violation:
+
+- Orchestration control flow — early return on not-found, `try` / `finally` around a transaction, threading a transaction through repository calls.
+- DTO → domain mapping.
+- Calling a domain predicate and acting on its result. That IS the pattern.
+
+The test: **if this decision changed, would the change be described as a business rule change or as a plumbing change?** A business rule change that lands in a service is the violation — the rule is now invisible to the domain's own tests, and the next caller that needs it writes its own copy.
+
+Severity: `should-fix`, and blocking when the embedded rule is substantial — money, permissions, or a state machine. Under a declared `architecture.style = hexagonal` the substantial case is fixed before the write, never record-and-pass.
+
+---
+
+**How far a project convention reaches.** H5 above is the one rule in this overlay a project-local convention cannot clear. Elsewhere here, a documented convention does resolve the conflict in the project's favour — but that latitude stops at okstra's own gates. It never clears a check the implementation verifier's blocking list declares **mechanical**: a changed file under the domain folder importing an ORM / DB layer, a framework or its DI decorators, or anything under adapters / infrastructure / services is decided by reading the import list, and no convention argument reaches that verdict (`prompts/profiles/_implementation-verifier.md` §"Static design & test-quality review" → Hexagonal). Resolving a declared-mechanical finding as "project convention" is the failure this paragraph exists to prevent — a real run did exactly that, returned `clean`, and the team's own PR review then flagged the same import.
 
 Severity: advisory in a project that has not declared `architecture.style = hexagonal` — a direction-of-travel rule there, not a correctness gate, so it never blocks on its own. Under that declaration it is blocking: the injection is fixed before the write.
 

package/runtime/prompts/coding-preflight/clean-code.md

@@ -314,6 +314,19 @@ A new mock, state setter, or repository branch that no test calls is unfinished
 
 A change to memory use, concurrency, batching, or stream handling is not covered by a functional test that passes on a small input. Add a test that pins the bound the change claims to hold — peak size, concurrent count, chunk count.
 
+## Trace what this change can do wrong
+
+The rules above name defect shapes. A defect with no name on this list is still a defect, and the ones that reach production usually have no name — they are ordinary code that produces a wrong result for one input nobody walked.
+
+For every source file this change touches, follow the paths the change creates or alters to their end, and state where a wrong result comes out:
+
+- **error** — what the caller sees when each new call fails, and whether that is distinguishable from the other failures it must be told apart from.
+- **partial** — the change succeeded halfway; what is left written, and what the next run sees.
+- **concurrent** — something else is still writing, or the deadline fired and the work did not stop.
+- **selection** — when several candidates fail, which one's evidence survives.
+
+**A finding names the input or state that produces the wrong result.** *"If the archive yields no entries, line 42 reports success and stores an empty result"* is a finding. Code that works as written is `clean`, however you would have written it differently: alternative structures, guards for states no caller can reach, extra tests for covered paths, and "consider extracting / renaming / memoizing" are improvements, not findings. A real failure that is small and cheap to fix is still a finding.
+
 ## No magic numbers
 
 Replace hardcoded values with named constants.

package/runtime/prompts/profiles/_implementation-diff-review.md

@@ -34,6 +34,8 @@ Do not scan holistically and stop when it "looks fine". Work the matrix exhausti
    - a file that decides, mutates, or persists state → `clean-code.md` "Mutation and state boundaries": decide on the direct identifier rather than a status/flag proxy, capture before-state in one snapshot ahead of the mutating boundary, update only this work's owned fields on an existing row, re-read state before calling a zero-affected-rows write success or failure, put priority-between-inputs in a named domain function, and keep error messages to what was actually observed. Also check that no state union/enum was re-declared beside an authoritative one the domain or a dependency exports.
    - test file (`*.spec.*` / `*.test.*` / `test_*.py` / `*_test.go` …) → `clean-code.md` "Testing discipline": no self-mocking of the SUT, behavioral (outcome) assertions not interaction-only, no tautological delegation assertion, no effect claimed under its own mock, shared-fixture defaults left on the ordinary path, setup values that actually separate the scenarios, every new test helper/mock used by a test in this same diff, no positional mock-argument access (`rg 'mock\.calls'`), every branch this diff adds covered by a test that fails when the branch body is deleted, assertions on the last write to a record rather than an intermediate one, and test titles naming their unit plus the single condition each case isolates.
    - port / adapter / domain file, when the hexagonal overlay is loaded → `architectures/hexagonal.md`: no business logic in a port body, adapter methods are I/O only (no post-fetch filtering on domain state, no `findValid*`/`findActive*` names hiding a rule), domain objects declared under the domain boundary, no changed domain file importing an ORM / framework / adapter / service (read the import list — mechanical), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory only while the project has not declared `architecture.style = hexagonal` in `.okstra/project.json` — record it with the port sketch; blocking under that declaration, so fix it in place before the commit rather than record-and-pass, exactly as `_implementation-verifier.md` re-grades this same diff. Either way, the codebase already injecting concrete classes is the debt this pays down, not a reason to skip it).
+   - a service file, when the hexagonal overlay is loaded → `architectures/hexagonal.md` Rule H6: a decision this diff puts in a service — an `if`/`else` chain over domain fields, a business formula, a private method named for a domain concept — belongs in a domain function. Orchestration control flow, DTO mapping and calling a domain predicate are not violations.
+   - every changed source file → `clean-code.md` "Trace what this change can do wrong": walk the error, partial, concurrent and selection paths this diff creates to their end and fix wherever a wrong result comes out. Name the input that produces it — if you cannot name one, there is nothing to fix here and you move on rather than restructuring code that works.
    A file can hold several roles — apply every rule set that fits it.
 3. **Decide clean-or-finding for each cell.** Read the full file when a rule needs context (never judge a port/adapter/domain or a naming rule from the hunk alone).
 4. **Fix each finding in place** before the commit. When a readability finding is real, the fix is a named helper or named intermediate value — sketch the cleaner shape (a few lines) in your audit note, then apply it. When the fix is genuinely out of this stage's scope, record it as an `Out-of-plan` note instead of silently leaving it.

package/runtime/prompts/profiles/_implementation-executor.md

@@ -63,7 +63,7 @@ persisted prompt lacks the heading `Coding-conventions preflight`
 
 ## Stage execution contract (this run owns one stage)
 
-- **Sidecar evidence writer (BLOCKING).** When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object with **exactly** these fields (spec `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2), as a fenced ```json``` block in the worker result under the heading `### Stage Carry Evidence`, and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The schema is inlined here because a CLI-wrapper executor runs in its own process and never receives a native worker definition — a carry emitted with an ad-hoc shape (`stage`/`files`/`validation`) is a `contract-violated` gap the lead must rewrite by hand:
+- **Sidecar evidence writer (BLOCKING).** You emit the evidence; you do NOT write the file. `carry/stage-<N>.json` sits inside your task scope, so nothing stops your tools from creating it — but the lead's post-stage persistence is what writes it, and only on a non-`FAIL` verdict. Your own gate passes before the verifier's, so a file you write exists exactly when the verdict may still withhold it: the lead then refuses to overwrite, the report says the sidecar was withheld, and the disk disagrees with the record. Emit the block and stop. When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object with **exactly** these fields (spec `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2), as a fenced ```json``` block in the worker result under the heading `### Stage Carry Evidence`, and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The schema is inlined here because a CLI-wrapper executor runs in its own process and never receives a native worker definition — a carry emitted with an ad-hoc shape (`stage`/`files`/`validation`) is a `contract-violated` gap the lead must rewrite by hand:
 
   ```json
   {

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -164,7 +164,9 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
   - **Interaction-only assertion:** a test whose only/primary assertion is `toHaveBeenCalled*` / `toHaveBeenCalledTimes` on an internal helper or a non-side-effecting collaborator, with no assertion on the returned value / resulting state / persisted row / emitted event.
   - **Tautological delegation assertion:** a test asserts the SUT result equals a direct call to the same pure helper/collaborator that the SUT delegates to, instead of asserting an independent literal value or observable state.
   - **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that writes/inserts/mutates; an adapter or repository name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*` / `findActive*`).
-  - **Hexagonal (only when the overlay is loaded):** business logic inside a port body; an adapter method that is not pure I/O (post-fetch JS filtering on domain state, domain-rule evaluation); a domain object declared outside the `domain/` boundary; a changed file under the domain folder importing an ORM / DB layer, a framework or its DI decorators, or anything under adapters / infrastructure / services (read the import list — this verdict is mechanical, not a judgment).
+  - **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every file you excluded with its reason (lockfiles, generated code, pure config), and close the section with `general: <N> files — all verdicted, <M> excluded`.
+  - **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that decides a business outcome inline — an `if`/`else` chain over domain fields, a business formula in arithmetic, a private method named for a domain concept — instead of calling a domain function (`architectures/hexagonal.md` Rule H6). Orchestration control flow, DTO mapping, and calling a domain predicate are not violations. Blocking when the embedded rule is substantial: money, permissions, a state machine.
+  - **Hexagonal (only when the overlay is loaded):** business logic inside a port body; an adapter method that is not pure I/O (post-fetch JS filtering on domain state, domain-rule evaluation); a domain object declared outside the `domain/` boundary; a changed file under the domain folder importing an ORM / DB layer, a framework or its DI decorators, or anything under adapters / infrastructure / services (read the import list — this verdict is mechanical, not a judgment). **The routed pack's project-convention latitude does not reach this cell.** `architectures/hexagonal.md` lets a documented convention resolve conflicts in the project's favour elsewhere in that overlay; here the import list decides, and "matches existing convention" is not an answer to it (see that file's §"How far a project convention reaches"). A run that resolved exactly this finding as project convention returned `clean` and the team's PR review flagged the same import.
   - **gitignored file committed to the branch:** any path in the `git diff --name-only <base>...HEAD` enumeration that `.gitignore` excludes — enumerate them by piping that list through `git check-ignore --stdin --no-index`. A committed ignored file means the executor bulk-added (`git add .`/`-A`) or force-staged (`git add -f`) it, leaking build output, scratch files, or verification artifacts into the eventual PR. This explicitly includes `.okstra/` paths (and `.project-docs/` when the legacy symlink is present): `.okstra/**` is gitignored, so a committed okstra file (qa scripts, conformance results) is always this defect. Cite each path; recommend `git rm --cached <path>` to untrack it while keeping the file on disk. Conformance/qa evidence belongs in the carry sidecar / verifier result, never in git history.
   - **Real-IO test in source tree:** a changed/added test under the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*` — that opens a **real** DB connection / DSN, makes a real `fetch` / `axios` / `http` request, or otherwise hits real external IO without mocking the injected collaborator (a live handle, not a stub/spy). Real-IO tests MUST live under `<task_root>/qa/scripts/` per the executor's *Real-IO test isolation* rule — a live-IO test in source silently breaks the project's CI suite and violates the artifact-home rule. Cite the test file + the real-IO line; recommend moving it to `<task_root>/qa/scripts/` (or declaring it as a Tier 3 conformance script). Mock-only unit tests in source are NOT a hit.
   - **Proxy-based identity decision:** a move / ownership / re-parenting decision taken from a status field or flag while the source and destination identifiers were available and never compared. Cite the condition and the identifiers it should have compared, and show the opposite case the condition also reads true for.

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Antigravity host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. |
+| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through their status sidecars, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh native worker or CLI wrapper attempt according to the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Perform host or process cleanup only for resources owned by this run. |

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -136,7 +136,7 @@ For a `host-text` mapping, render each numbered item as its option label followe
 | `read_artifacts` | Use the host file-read primitive and preserve the core contract's read order. |
 | `write_artifact` | Use the host file-write primitive only for paths authorized by the active lifecycle phase. |
 | `prompt_user` | Use the native question tool for approvals and clarifications; do not infer an answer from silence. |
-| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. |
+| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
 | `redispatch_worker` | Dispatch a fresh `Agent(...)` session with the same prompt plus the core reverify/retry reason. |
 | `shutdown_workers` | For each confirmed-complete worker selected for cleanup, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to idle the roster member **and** call `TaskStop(task_id: "<name>")` to stop its background task. Both are required; neither subsumes the other. |

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current host's file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through synchronous dispatch, then verify team-state terminal records and Result Paths for both. |
 | `redispatch_worker` | Start a fresh native worker or `okstra codex-dispatch` attempt according to the persisted assignment's `runner`, and record the retry/reverify dispatch kind. |
 | `shutdown_workers` | Perform process cleanup when a wrapper remains live; otherwise this operation is a no-op recorded in state. |

package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current host's file or shell interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and require an explicit approval or clarification response. |
-| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
 | `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
 | `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -76,7 +76,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Grok host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
-| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |

package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md

@@ -76,7 +76,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Kimi host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
-| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |

package/runtime/python/okstra_ctl/consumers.py

@@ -27,6 +27,11 @@ CONSUMERS_FILENAME = "consumers.jsonl"
 # carrying a confirmed regression as complete.
 STAGE_LIFECYCLE_STATUSES = ("started", "done", "failed")
 
+# The lead has already ruled on a stage whose last row is one of these — `done`
+# closed it, `failed` deliberately did not. Neither may be re-derived from disk:
+# closing a stage is the lead's verdict gate, not a file's existence.
+_LEAD_SETTLED_STATUSES = ("done", "failed")
+
 
 @dataclass(frozen=True)
 class StageConsumerState:
@@ -308,16 +313,29 @@ def _carry_dir(plan_run_root: Path) -> Path:
 def backfill_done_from_carry(plan_run_root: Path) -> int:
     """Recover missing `done` rows from carry sidecars (carry is SSOT).
 
-    For every `runs/implementation/carry/stage-<N>.json` that is complete and
-    not already recorded as `done` in consumers.jsonl, append a `done` row with
-    the head commit read from the carry. Returns the number of rows recovered.
-    Stages with no carry or an unfinished carry are skipped, so the dependency
-    gate still legitimately blocks genuinely-unstarted stages."""
+    Recovers the crash window between the lead writing the carry file and
+    appending the `done` row: for every `runs/implementation/carry/stage-<N>.json`
+    that is complete and whose stage has no terminal row yet, append a `done` row
+    with the head commit read from the carry. Returns the number of rows
+    recovered. Stages with no carry or an unfinished carry are skipped, so the
+    dependency gate still legitimately blocks genuinely-unstarted stages.
+
+    A stage the lead has already ruled on is never re-derived from disk. That
+    includes `failed`: the executor emits its carry evidence when its own Tier 1/2
+    validation passes, which happens BEFORE the verifier's gate, so a carry file
+    exists for exactly the runs where the verifier then returned `FAIL`. Reading
+    the file as completion would promote a stage carrying a confirmed regression
+    to `done` and let its dependents proceed — and it would contradict this
+    module's own rule that a stage's position is its last lifecycle row."""
     carry_dir = _carry_dir(plan_run_root)
     if not carry_dir.is_dir():
         return 0
     existing = read_consumers(plan_run_root)
-    done_stages = {r.get("stage") for r in existing if r.get("status") == "done"}
+    settled_stages = {
+        stage
+        for stage, status in last_lifecycle_status_by_stage(existing).items()
+        if status in _LEAD_SETTLED_STATUSES
+    }
     key_by_stage: Dict[Any, str] = {}
     fallback_key = ""
     for r in existing:
@@ -335,7 +353,7 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
         if not isinstance(carry, dict):
             continue
         stage = _carry_stage_number(carry, cf.name)
-        if stage is None or stage in done_stages:
+        if stage is None or stage in settled_stages:
             continue
         if not _carry_is_complete(carry):
             continue
@@ -358,6 +376,6 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
             carry_path=carry_path,
             source="carry-backfill",
         )
-        done_stages.add(stage)
+        settled_stages.add(stage)
         recovered += 1
     return recovered

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -31,6 +31,7 @@ from .dispatch_state import (
     transition_worker_status as _transition_worker_status,
     string_list as _string_list,
     string_value as _string_value,
+    TEARDOWN_BEFORE_TERMINAL_REASON,
     utc_now as _utc_now,
     validate_dispatch_prompts as _validate_dispatch_prompts,
     worker_jobs_from_file as _worker_jobs_from_file,
@@ -231,6 +232,7 @@ def await_dispatches(
     timeout_seconds: int | None = None,
     heartbeat_seconds: int = 30,
 ) -> int:
+    _correct_teardown_marked_dispatches(plan)
     deadline = time.monotonic() + timeout_seconds if timeout_seconds is not None else None
     last_heartbeat = 0.0
     while True:
@@ -643,6 +645,35 @@ def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
     )
 
 
+def _correct_teardown_marked_dispatches(plan: DispatchPlan) -> None:
+    """Let the wrapper's own exit settle a record teardown wrote off.
+
+    `okstra team teardown` marks every non-terminal dispatch `error` — right for a
+    worker it killed, wrong for one that had already exited while its record was
+    still `running`, which happens when the lead awaited by polling artifacts
+    instead of `team await` (the component that transitions the record). The run
+    then reports `error` for workers whose wrapper exited 0 with every output in
+    place, and nothing could undo it: teardown's `error` drops the record out of
+    the running set this function's caller scans, so a later await never saw it.
+
+    Only a success is corrected, and only from process-level evidence — the
+    wrapper's terminal status plus its exit code, judged by the same
+    `_outcome_from_status` path every other dispatch goes through. A non-zero exit
+    or a missing output stays an error, and no retry is spawned: teardown has
+    already taken the panes, so re-running here would start work nobody is
+    watching.
+    """
+    for record in _teardown_marked_dispatches(plan.team_state_path):
+        status_path = _optional_path(record.get("statusSidecarPath"))
+        status = read_wrapper_status(status_path) if status_path else None
+        if status is None or not status.is_terminal:
+            continue
+        outcome = _outcome_from_status(record, status)
+        if outcome.returncode != 0 or outcome.missing_completion_paths or outcome.timeout:
+            continue
+        _finish_record(plan, record, outcome)
+
+
 def _advance_running_dispatches(plan: DispatchPlan, records: Sequence[Mapping[str, Any]]) -> None:
     for record in records:
         status_path = _optional_path(record.get("statusSidecarPath"))
@@ -811,6 +842,22 @@ def _update_dispatch_status(
     _write_json(team_state_path, payload)
 
 
+def _teardown_marked_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
+    """Records `okstra team teardown` wrote off, matched by its own reason string
+    so a genuine dispatch error is never mistaken for one."""
+    payload = _load_json_object(team_state_path, "team-state")
+    dispatches = payload.get("workerDispatches")
+    if not isinstance(dispatches, list):
+        return []
+    return [
+        record
+        for record in dispatches
+        if isinstance(record, dict)
+        and record.get("status") == "error"
+        and _string_value(record.get("reason")) == TEARDOWN_BEFORE_TERMINAL_REASON
+    ]
+
+
 def _running_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
     payload = _load_json_object(team_state_path, "team-state")
     dispatches = payload.get("workerDispatches")

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -58,6 +58,12 @@ def detect_terminal_backend() -> str:
 LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
 LIVENESS_WRAPPER_STATUS = "wrapper-status"
 
+# `okstra team teardown` stamps this on a dispatch it wrote off, and a later
+# `okstra team await` matches it to tell those apart from a genuine dispatch
+# error before letting the wrapper's own exit settle them. Two sides of one fact,
+# so the string lives here rather than in whichever module wrote it first.
+TEARDOWN_BEFORE_TERMINAL_REASON = "teardown before terminal status"
+
 # The worktree argument grants the wrapper `--add-dir` write access outside
 # project-root. Only the phases whose workers mutate a stage worktree get it;
 # analysis phases write their artifacts under project-root (see the contract in

package/runtime/python/okstra_ctl/doctor.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from dataclasses import asdict, dataclass
 from pathlib import Path
@@ -89,9 +90,68 @@ def _project_checks(cwd: Path) -> tuple[Path | None, list[DoctorCheck]]:
                 f"{project_json} not found — run okstra setup in this project first",
             )
         )
+    architecture = _architecture_declaration_check(project_root)
+    if architecture is not None:
+        checks.append(architecture)
     return project_root, checks
 
 
+_LAYOUT_SCAN_SKIP = frozenset(
+    {".git", ".okstra", "node_modules", "dist", "build", "coverage", "__pycache__"}
+)
+
+
+def _ports_and_adapters_marker(project_root: Path) -> str:
+    """The first ports-and-adapters layout signal found, or "".
+
+    Only the two signals the pack states mechanically (`architectures/hexagonal.md`
+    Stage 3 row): a `ports/` directory beside a `domain/` one, and a `*.port.*`
+    file. The other two — NestJS hex split, abstract classes at a boundary — are
+    worker judgment and are deliberately not guessed at here.
+    """
+    for current, dirnames, filenames in os.walk(project_root):
+        dirnames[:] = [d for d in dirnames if d not in _LAYOUT_SCAN_SKIP]
+        here = set(dirnames)
+        if "ports" in here and "domain" in here:
+            return str(Path(current).relative_to(project_root) / "ports")
+        for name in filenames:
+            if ".port." in name:
+                return str(Path(current).relative_to(project_root) / name)
+    return ""
+
+
+def _architecture_declaration_check(project_root: Path) -> DoctorCheck | None:
+    """Report placement rules running advisory because no style was declared.
+
+    The routed coding-preflight pack promotes its placement rules from advisory to
+    blocking only under `architecture.style` in `project.json`
+    (`architectures/hexagonal.md` Severity). With the key absent they stay advisory,
+    a verifier records `architecture-style: none`, and the run reads as fully gated
+    — the downgrade is invisible to both lead and user. A project that genuinely is
+    not ports-and-adapters silences this by declaring `none`, which is why the raw
+    value is read here: `resolve_architecture()` maps absent and `none` alike.
+    """
+    try:
+        payload = json.loads(project_json_path(project_root).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    architecture = payload.get("architecture") if isinstance(payload, dict) else None
+    declared = architecture.get("style") if isinstance(architecture, dict) else None
+    if isinstance(declared, str) and declared.strip():
+        return _ok("architecture style", f"declared: {declared.strip()}")
+    marker = _ports_and_adapters_marker(project_root)
+    if not marker:
+        return None
+    return _ok(
+        "architecture style",
+        f"not declared, but the layout shows a ports-and-adapters signal ({marker}) "
+        "— placement rules run advisory, so a misplaced domain object or a concrete "
+        "adapter injection is recorded rather than blocking. Declare "
+        '`architecture: {"style": "hexagonal"}` in .okstra/project.json to gate '
+        'them, or `"none"` to say the layout is not ports-and-adapters.',
+    )
+
+
 def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
     profile = _profile_path(workspace, phase)
     if profile.is_file():

package/runtime/python/okstra_ctl/pr_template.py

@@ -6,8 +6,8 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
     1. per-run override (okstra-run Step 6 에서 입력)
     2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
-    4. default: ``$OKSTRA_HOME/templates/prd/pr-body.template.md`` (구버전
-       ``~/.claude/skills/...`` 후보는 backward-compat 로 유지)
+    4. default: ``$OKSTRA_SKILLS_DIR/okstra-run/templates/pr-body.template.md``
+       (env 가 설정된 경우에만) → ``$OKSTRA_HOME/templates/pr/pr-body.template.md``
 
 경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project
 스코프는 ``project_root`` 기준, override 는 호출자 cwd 기준으로 해석한다.
@@ -41,10 +41,7 @@ def _default_template_candidates() -> list[Path]:
     env_dir = os.environ.get("OKSTRA_SKILLS_DIR", "").strip()
     if env_dir:
         out.append(Path(env_dir) / "okstra-run" / "templates" / _DEFAULT_FILENAME)
-    out.append(okstra_home() / "templates" / "prd" / _DEFAULT_FILENAME)
-    out.append(
-        Path.home() / ".claude" / "skills" / "okstra-run" / "templates" / _DEFAULT_FILENAME
-    )
+    out.append(okstra_home() / "templates" / "pr" / _DEFAULT_FILENAME)
     return out
 
 

package/runtime/python/okstra_ctl/team.py

@@ -19,6 +19,7 @@ from . import tmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
+from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON
 from .dispatch_core import (
     BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
@@ -256,7 +257,7 @@ def _mark_teardown_errors(team_state_path: Path) -> None:
     for record in payload.get("workerDispatches", []):
         if isinstance(record, dict) and record.get("status") not in _TERMINAL_STATUSES:
             record["status"] = "error"
-            record["reason"] = "teardown before terminal status"
+            record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
     _write_json(team_state_path, payload)
 
 

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -55,6 +55,12 @@ def _looks_like_file_path(path: str) -> bool:
         return False
     if re.fullmatch(r"[0-9a-fA-F]{7,64}", path):
         return False
+    # A dotted name is the usual filename signal, and an IPv4 literal is dots and
+    # digits too. `127.0.0.1:13306` in a Read-only command log is a host and port —
+    # the worker cannot record an Evidence read of it, so reading it as a citation
+    # fails the run over something it has no way to satisfy.
+    if re.fullmatch(r"\d{1,3}(?:\.\d{1,3}){3}", path):
+        return False
     return (
         "/" in path
         or "." in Path(path).name

package/runtime/skills/okstra-setup/references/project-config.md

@@ -155,7 +155,7 @@ overwriting silently.
 ## D. Project PR body template (release-handoff)
 
 `release-handoff` fills the PR body from a template — by default
-`~/.okstra/templates/prd/pr-body.template.md`. Most projects want their own
+`~/.okstra/templates/pr/pr-body.template.md`. Most projects want their own
 (e.g. `.github/PULL_REQUEST_TEMPLATE.md`). Pre-registration during setup is
 opt-in; the same prompt is offered again on the first `release-handoff` run,
 so deferring (`Later`) is safe.

package/runtime/validators/validate-run.py

@@ -693,6 +693,58 @@ def _is_legal_concurrent_run_skip(
     )
 
 
+def _validate_cmux_workers_were_dispatched_by_okstra(
+    team_state: dict,
+    workers: list,
+    dispatched_statuses: set[str],
+    failures: list[str],
+) -> None:
+    """Under cmux, okstra owns the worker panes — so it must have started them.
+
+    `prompts/lead/adapters/cmux.md` overrides the host relay's worker-dispatch
+    mapping: every lead goes through `okstra team dispatch`, a Claude Code lead
+    included. A lead that follows its own relay instead and starts the worker
+    in-process gets no pane, and the user cannot see the work — which is the whole
+    point of the adapter owning them.
+
+    The tell is the absent record, not the backend: `okstra team` appends a
+    `workerDispatches[]` row for every worker it starts, and an in-process worker
+    leaves none. Backend alone cannot separate the two, because a pane dispatch
+    that degrades legitimately records `backendType: cli-wrapper`
+    (`dispatch_core._dispatch_record`). A worker that was never attempted has no
+    row either, so only attempted statuses are checked.
+    """
+    adapter = team_state.get("leadAdapter")
+    if not isinstance(adapter, dict):
+        return
+    if str(adapter.get("name", "")).strip() != "cmux":
+        return
+    recorded = {
+        str(row.get("workerId", "")).strip()
+        for row in team_state.get("workerDispatches") or []
+        if isinstance(row, dict)
+    }
+    missing = []
+    for worker in workers:
+        if not isinstance(worker, dict):
+            continue
+        if str(worker.get("status", "")).strip() not in dispatched_statuses:
+            continue
+        worker_id = str(worker.get("workerId", "")).strip()
+        if worker_id and worker_id not in recorded:
+            missing.append(worker_id)
+    if missing:
+        failures.append(
+            "team-state.workerDispatches has no record for "
+            f"{', '.join(sorted(missing))} in a cmux run — those workers ran "
+            "without okstra starting them, so they had no pane and the user "
+            "could not watch the work. Under cmux every lead dispatches through "
+            "`okstra team dispatch`, a Claude Code lead included "
+            "(prompts/lead/adapters/cmux.md); the host relay's in-process "
+            "`Agent(...)` mapping does not apply to this run."
+        )
+
+
 def validate_team_state(
     team_state: dict,
     project_root: Path,
@@ -777,6 +829,10 @@ def validate_team_state(
                         f"Found: `{tc_status}`."
                     )
 
+    _validate_cmux_workers_were_dispatched_by_okstra(
+        team_state, workers, dispatched_statuses, failures
+    )
+
     by_role: dict[str, dict] = {}
     for worker in workers:
         if not isinstance(worker, dict):