okstra 0.202.0 → 0.204.0

package/docs/for-ai/skills/okstra-memory.md

@@ -1,126 +0,0 @@
-# okstra-memory AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
-- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- memory CLI: [`src/commands/memory/memory.mjs`](../../../src/commands/memory/memory.mjs)
-
-## Purpose
-
-`okstra-memory` manages the Memory Book in the user's home.
-
-```text
-~/.okstra/memory-book/
-```
-
-It is not a project-local `.okstra/` artifact. It can be used even without `<PROJECT_ROOT>/.okstra/project.json`.
-
-## When to use
-
-Use it when:
-
-- The user explicitly asks to save, e.g. "remember this", "save the conversation", "organize and store this in okstra", "remember this", "save this decision".
-- The user wants to search, list, read, or archive stored memory.
-
-Do not use it when:
-
-- The user is only brainstorming with no save request. In that case, ask a confirmation question first.
-- The content should be kept as a project task artifact. In that case, use the brief/report/decision path of the relevant okstra task.
-
-## safety rule
-
-Do not save without an explicit save request. Do not store credentials, API keys, tokens, private personal data, or secrets. If the conversation includes sensitive material, exclude it from the summary and note the omission.
-
-The CLI can also detect high-confidence secret shapes and refuse `memory add`. If refused, redact the content and retry.
-
-## CLI availability
-
-Check the help first.
-
-```bash
-okstra memory --help
-```
-
-If `okstra` is not on PATH, do not run `npx okstra@latest install` directly; tell the user to install it once and then retry.
-
-## project-group selection
-
-Every memory entry belongs to a project-group. Pick the group before storing or searching.
-
-Enumerate existing groups:
-
-```bash
-okstra memory groups
-```
-
-Recommendations:
-
-- the most-used existing group
-- the second existing group
-- Enter directly
-
-For a personal note, recommend `private` first. If there is no group or no selection, use the CLI default `global`.
-
-Pass the chosen group to `add`, `search`, and `list` as `--project-group <group>`. Omit the flag only when the user explicitly wants a cross-group search.
-
-## Store procedure
-
-Do not store the full conversation transcript. Extract only durable memory worth keeping long-term and turn it into a concise Markdown summary.
-
-Include:
-
-- the reason for storing
-- source: `conversation`
-- `--project` when the related project id is clear
-- tags for search
-- memory type
-
-The `okstra memory --help` output is authoritative for the type values. Categories per the source:
-
-- `decision`
-- `preference`
-- `requirement`
-- `person`
-- `project-hint`
-- `follow-up`
-- `context`
-
-Store command shape:
-
-```bash
-okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --project-group <group> --tag <tag> --project <id> --source conversation --yes
-```
-
-Repeat `--tag` and `--project` as needed. Omit `--project` when no related project is clear.
-
-Use `--yes` only when the user explicitly asked to save.
-
-## search / read / archive
-
-The default scope is the chosen project-group.
-
-```bash
-okstra memory search "<query>" --project-group "<group>"
-okstra memory list --project-group "<group>" --tag "<tag>"
-okstra memory groups
-okstra memory show "<memory-id>"
-okstra memory archive "<memory-id>"
-```
-
-Read IDs from the fixed text rows. Show the user only a short summary plus the entry id/path.
-
-## Output rules
-
-- On store, summarize title, type, project-group, tags, and the generated id.
-- On search, show the match count and the most relevant entry first.
-- Run archive only when the user's intent is clear.
-- Do not write into a project `.okstra/`.
-
-## Forbidden patterns
-
-- Auto-saving without an explicit request.
-- Storing a secret/token/key.
-- Storing the full transcript verbatim.
-- Writing into `.okstra/` as if it were project-local task memory.
-- Performing a cross-group search by default when the user did not ask for it.

package/docs/for-ai/skills/okstra-pr-gen.md

@@ -1,49 +0,0 @@
-# okstra-pr-gen AI Manual
-
-## Sources
-
-- Skill source: [`skills/okstra-pr-gen/SKILL.md`](../../../skills/okstra-pr-gen/SKILL.md)
-- Template core (CLI): [`scripts/okstra_ctl/pr_template.py`](../../../scripts/okstra_ctl/pr_template.py)
-- Node wrapper: [`src/commands/pr/pr.mjs`](../../../src/commands/pr/pr.mjs)
-- Bundled default template: [`src/commands/pr/default.md`](../../../src/commands/pr/default.md)
-
-## Purpose
-
-`okstra-pr-gen` registers PR body templates and generates PR descriptions from a branch diff. Templates live in the user home at `~/.okstra/template/pr/`. This skill is **global** — it does not require `<PROJECT_ROOT>/.okstra/project.json`. PR generation additionally requires the current directory to be a git repository.
-
-## Check CLI availability
-
-A separate Bash call with a literal leading token:
-
-```bash
-okstra pr --help
-```
-
-If `okstra` is not on PATH: `okstra not installed — run npx okstra@latest install once, then retry`. Every Bash command starts with the literal `okstra` token and passes literal arguments (do not wrap it in `$(...)`/leading `VAR=`/`if`/`eval`/`||`/`&&`).
-
-## Pick the mode (always first)
-
-A 3-option picker via `AskUserQuestion`:
-
-1. `Generate PR` — generate a PR body from a branch diff
-2. `Register template` — save a new PR body template
-3. `Enter directly` — always last (okstra picker convention)
-
-## Mode A — Generate PR
-
-1. Pick a template: `okstra pr template list`. If the numbered `Templates` rows are empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
-2. Pick the base branch: `okstra pr branches`. Build a 3-option picker from the numbered `Recommended` rows plus `Enter directly`. Carry the choice as `<base>`.
-3. Generation bundle: `okstra pr gen --base <base> --template <template>`. Read the fixed `Base`, `Current branch`, `Template name`, `Commits`, `Diff stat`, and `Template` sections. Then **read the real diff honestly** (SSOT): `git diff <base>...HEAD` (large diffs section by section). Fill the placeholders from the diff and commits, describing **only actual changes**. Mark a checklist box `[x]` only when the diff supports it (tests touched → tests box, docs touched → docs box). If `Commits` or `Diff stat` is empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
-4. Identifier allowlist for the title and body: only repo-relative source paths (optionally `path:line`), symbol names present in the diff, branch names / commit subjects / SHAs, and issue-tracker ticket ids the reviewer can open. okstra's own artifact identifiers are out of the allowlist — report item ids (`F-001`, `C-001`, `R-001`, `D-0001`, `PREP-001`), run artifact names and their `<task-type>-<seq>` suffixes, phase/stage/worker labels (`final-verification`, `stage-2`, `codex-worker`), and any path under `.okstra/`. They resolve to nothing for a reviewer; restate the substance in code terms instead of citing the id.
-5. Output and offer to create the PR: print the filled PR body as a single fenced markdown block. Ask whether to open a PR. **Only on an explicit yes**: write the body to a temp file and run `gh pr create --base <base> --title "<title>" --body-file <path>`. If `gh` is missing or unauthenticated (`gh auth status` fails), leave the text in chat and give manual-creation guidance. **No push/PR creation without the user's confirmation.**
-
-## Mode B — Register template
-
-1. Template name (`AskUserQuestion`, free text) — must match `^[A-Za-z0-9._-]+$`, otherwise re-ask.
-2. body — pasted text or an absolute path.
-3. Save: `okstra pr template add --name <name> --file <abs-path>` (or, for pasted text, `--content "<body>"`). Add `--yes` only when the user confirmed overwriting a same-named template. Report the saved path (`saved: ...`).
-
-## Output Rules
-
-- Not read-side — write actions (PR creation, template saving) happen only after the user's explicit confirmation.
-- Do not invent changes not in the diff. Stop if commit/diffStat is empty.

package/docs/for-ai/skills/okstra-rollup.md

@@ -1,114 +0,0 @@
-# okstra-rollup AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-rollup/SKILL.md`](../../../skills/okstra-rollup/SKILL.md)
-- aggregation core (CLI): [`scripts/okstra_ctl/rollup.py`](../../../scripts/okstra_ctl/rollup.py)
-- reused single-task aggregators: [`scripts/okstra_ctl/time_report.py`](../../../scripts/okstra_ctl/time_report.py), [`scripts/okstra_ctl/error_log_core.py`](../../../scripts/okstra_ctl/error_log_core.py)
-- catalog enumeration helper: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py) (`list_project_tasks`)
-- unit tests: [`tests/inspect/test_okstra_rollup.py`](../../../tests/inspect/test_okstra_rollup.py)
-
-## Purpose
-
-`okstra-rollup` **collects and summarizes the run results of multiple tasks at once**. It is a cross-task read-side layer, in contrast to `okstra-inspect` which looks at a single task.
-
-- Input scope: one task-group, or the whole-project catalog when `--task-group` is omitted.
-- Deterministic aggregation (counts, time sums, error sums, status/category/phase distributions) is handled entirely by the `okstra rollup` CLI. The skill renders that table and reads each task's report body to write a **cross-task synthesis (digest)**.
-- Design principle: hand-computed aggregation is error-prone for an LLM, so it is pushed to the CLI (SSOT), and only the natural-language synthesis is left to the LLM. This is the same division of labor as `okstra-inspect time`, which insists on "never re-sum the time by hand".
-
-This skill is read-only. It does not mutate task artifacts.
-
-## When to use
-
-Use it when:
-
-- The user asks for "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "run results all at once".
-- You want to look across **multiple tasks** rather than a single one.
-
-Do not use it when:
-
-- A single task's report/time/errors/recap → `okstra-inspect` (report / time / errors / recap facet).
-- "Where does the group stand" — which briefs are done / in progress / not started, what is next, each task's latest conclusion → `okstra-inspect` recap facet with `--task-group`. rollup keeps the numbers (runs, time, errors) and the cross-task digest.
-- A forward-looking work plan (a client-facing schedule of non-done tasks) → `okstra-schedule-gen`. rollup is **retrospective**, collecting past run results; schedule is **forward-looking**, planning future work.
-- Actual phase execution → `okstra-run`.
-
-## Preflight
-
-A single Bash call starting with the literal `okstra` token (not wrapped in `if`/`eval`/`$(...)`/`VAR=`/`||`/`&&`/`npx` fallback):
-
-```bash
-okstra preflight --runtime claude-code
-```
-
-On `Okstra preflight: ready`, carry `Project root` as a literal string. On
-`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
-
-## scope resolution
-
-- The user named a task-group ("summarize the alpha group") → `--task-group <group>`.
-- "all tasks" / "the whole project" / no scope named → omit `--task-group` (whole catalog).
-- If genuinely ambiguous, ask once: one task-group or the whole project? Do not silently guess a specific group.
-
-## CLI call
-
-```bash
-okstra rollup --task-group <group> --project-root <projectRoot> --text
-```
-
-For the whole project, drop `--task-group`. The output is fixed, ordered label/value rows, and **all times are raw milliseconds**.
-
-## Interpreting the output
-
-Fixed fields:
-
-- `Task group` and `Task count` identify the scope.
-- Numbered `Tasks` rows carry task identity, status, phase, next phase, report path, run count, CPU, wall-clock, and error count.
-- `Totals runs`, `Totals CPU sum ms`, `Totals wall clock ms`, and `Totals errors` are the aggregate values.
-- Numbered `Work status`, `Work category`, `Current phase`, and `Task type` rows carry the aggregate distributions.
-
-Numeric meanings (must observe):
-
-- `Run count` is the **total number of runs** in the timeline. CPU and wall-clock rows reflect only runs that reached Phase 7 usage, so they can be `0` even when run count is positive.
-- `CPU sum ms` is the **CPU sum** of the overlapping lead + workers, not wall-clock.
-- `Report path` is project-relative and may be `-` for a task with no report yet.
-- If `Task count` is `0`, say there are no okstra tasks in that scope and stop.
-
-## Render
-
-Convert every `*Ms` to `HH:MM:SS` (zero-pad; never expose raw ms — the same rule as `okstra-inspect time`). Sort tasks by `updatedAt` descending.
-
-```markdown
-## okstra Rollup — <task-group or "whole project"> (<taskCount> tasks)
-
-| Task | Category | workStatus | Phase | Runs | CPU | Errors | Report |
-|------|----------|------------|-------|------|-----|--------|--------|
-| DEV-1 | bugfix | done | final-verification | 2 | 00:25:00 | 2 | ✓ |
-| DEV-2 | feature | in-progress | implementation | 1 | 00:00:00 | 0 | — |
-
-**Totals:** 3 runs · CPU 00:25:00 · 2 errors
-**workStatus:** done 1 · in-progress 1   **category:** bugfix 1 · feature 1
-```
-
-- `Report` column: `✓` when `reportPath` is present, `—` when not.
-- Build the status/category/phase lines from the `totals` tally maps **verbatim**. Do not count the `tasks[]` array yourself (the CLI is the SSOT for aggregation).
-
-## Writing the digest (the summary — the skill's core value)
-
-When the user asks to "summarize"/"organize"/"summarize"/"digest" (the common case):
-
-1. For each task with a non-empty `reportPath` whose `<projectRoot>/<reportPath>` file actually exists, read the report and summarize in 1–2 lines **what it accomplished and its recommended next step**.
-2. Above the per-task lines, write a 2–4 sentence group-level synthesis: what was delivered across the group, where the open work sits (using `byWorkStatus`/`byCurrentPhase`), and whether there are error hot-spots (tasks with high `errorCount`).
-3. Cite each per-task claim with the report path (`<reportPath>`) so the reader can open it directly.
-
-For a task with no report, do not invent a summary; state the current phase/workStatus instead. Do not read non-report artifacts to fill the gap (artifact-home rule). If a report is empty or missing, say so.
-
-If a deep single-task drill-down (full report, per-worker time, error breakdown, run-to-run recap) is needed, point the user to `/okstra-inspect`.
-
-## Forbidden patterns
-
-- Re-counting aggregate numbers (totals, distributions) by hand from `tasks[]`. `totals` is the SSOT.
-- Exposing raw ms. Always `HH:MM:SS`.
-- Labeling `cpuSumMs` as if it were wall-clock.
-- Inventing a summary for a task with no report. Substitute the current phase/workStatus.
-- Reading files outside okstra artifacts (non-`.okstra`) to fill the summary.
-- Handling single-task detail in rollup. Send it to `okstra-inspect`.

package/docs/for-ai/skills/okstra-run.md

@@ -1,250 +0,0 @@
-# okstra-run AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
-- wizard CLI wrapper: [`src/commands/execute/wizard.mjs`](../../../src/commands/execute/wizard.mjs)
-- wizard state machine: [`scripts/okstra_ctl/wizard/`](../../../scripts/okstra_ctl/wizard/)
-- render-bundle CLI: [`src/commands/execute/render-bundle.mjs`](../../../src/commands/execute/render-bundle.mjs)
-- prepare entrypoint: [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py)
-
-## Purpose
-
-`okstra-run` starts an okstra task run inside the current supported agent host. Input collection is owned entirely by the `okstra wizard` state machine; the skill relays the wizard prompts to the user and then prepares the task bundle via `okstra render-bundle`. Once the bundle is ready, the current Claude Code, Codex, or Antigravity session takes over as the host-native Okstra lead.
-
-Single authority:
-
-- Question order: `scripts/okstra_ctl/wizard/registry.py` (`STEPS`); branching: `engine.py`; per-step validation: `steps_*.py`
-- task bundle materialization: `prepare_task_bundle()`
-- Skill document: thin prompt-relay loop
-
-## When to Use
-
-Use it when:
-
-- The user wants to start an okstra task in the current session.
-- The user wants to continue the next phase of an existing task.
-- "okstra run", "okstra start", "start okstra in this session", "run the next phase", etc.
-
-Do not use it when:
-
-- The user only wants status: `okstra-inspect status`
-- The user wants past runs or a resume command: `okstra-inspect history`
-- The user explicitly named a new terminal / new claude process: point them to inspect history/resume
-
-## Preflight
-
-Resolve `<host-runtime>` from the executing harness: Claude Code → `claude-code`, Codex → `codex`, Antigravity CLI → `antigravity`, and another adapter host → `external`. This is a host capability, not a `PATH` inference or worker-provider choice. The lead provider is derived from this value and cannot be selected independently. Then make one Bash call:
-
-```bash
-okstra preflight --runtime <host-runtime>
-```
-
-On `Okstra preflight: failed`, show `Reason`, `Recovery`, `Runtime readiness`,
-and every repeated `Readiness check` line, then stop. On
-`Okstra preflight: ready`, require `Runtime readiness: ready`, carry the fixed
-`Project root` line, and read the `Relay contract` path. Do not create an
-`export PYTHONPATH`.
-
-## Bash invocation rule
-
-Every okstra call begins with the literal token `okstra`. Read the `--state-file`, `--answer`, path, model, and worker values from the prior JSON/tool output and paste them as literal strings.
-
-Avoid:
-
-- `$STATE_FILE`, `$ANSWER`
-- `$(...)`
-- `VAR=... okstra ...`
-- `eval`, `export`
-- `okstra ... && okstra ...`
-
-Do not drop the flag even for an empty answer.
-
-```bash
-okstra wizard step --state-file /tmp/okstra-wizard/state.json --answer ""
-```
-
-## wizard initialization
-
-Create the state file:
-
-```bash
-okstra wizard new-state-file
-```
-
-Carry the printed absolute path verbatim.
-
-wizard init:
-
-```bash
-okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id --host-runtime <host-runtime>
-```
-
-The result is `{ok, next}` JSON. The first step is `task_pick`.
-
-## Interpreting the wizard JSON
-
-Pick the UI according to `next.kind`.
-
-| kind | Handling |
-|---|---|
-| `pick`, `multi: false` | Render every `options[]` verbatim as a selectable choice. Submit the chosen option's `value` |
-| `pick`, `multi: true` | Submit all chosen values as a comma-separated string. An empty selection still submits `--answer ""` |
-| `pick_group` | Render the wizard's `questions[]` as a single multi-question UI. Build a JSON object of per-step values and submit it in one shot |
-| `text` | Show a plain text label without a picker, then submit the user's next message verbatim |
-| `done` | Input collection finished. Move to render-args |
-| `aborted` | Delete the state file and stop. Do not call render-args/render-bundle |
-
-`progress.label` is a string the wizard composed. Append it verbatim after the UI prompt; do not compute it yourself.
-
-## wizard loop
-
-1. Render the prompt.
-2. Submit the user's answer as a literal `--answer`.
-3. `ok: true`: show `result.echo` to the user on one line and advance to the next step.
-4. `ok: false`: show `result.error` verbatim and retry the same step via `result.current`.
-5. `current: null`: a terminal error where the prompt cannot be reconstructed. Show the error and stop.
-
-Important: never trim, hide, or restructure the wizard-provided options into a "recommended + Enter directly" form. The wizard's `options[]` is the complete choice set.
-
-## brief candidate ordering
-
-The brief selection is handled by the wizard. A new task is asked for its brief right after task-group and **before** the task-type; an existing task is asked only on an entry phase (`requirements-discovery`, `error-analysis`, `improvement-discovery`, `project-analysis`, `feature-analysis`, `change-impact-analysis`).
-
-- task-group candidates are shown newest-first by combining recent task-catalog use with the recent brief creation/modification times under `.okstra/briefs/<group>/`.
-- brief file candidates are chosen from within the selected group's `.okstra/briefs/<task-group>/**/*.md`.
-- The brief-file sort key is `max(file created/modified time, task-catalog updatedAt of the task that used this brief)`.
-- direct input is always last.
-- for a new task the following task-type pick offers entry phases only, and its recommended slot is the selected brief's `Recommended next phase:` line (fallback `requirements-discovery`).
-
-## confirm step
-
-When `next.step == "confirm"`, first fetch the confirmation summary.
-
-```bash
-okstra wizard confirmation --state-file /tmp/okstra-wizard/state.json
-```
-
-Show `text` to the user, then render the Proceed/Edit/Abort picker as the final output of that turn — the rendered question is the last thing you emit in that turn, and text emitted after the call renders below the picker. `Edit` rewinds the wizard to an earlier step.
-
-## outcome and render-bundle
-
-When `next.kind == "done"`:
-
-```bash
-okstra wizard outcome --state-file /tmp/okstra-wizard/state.json
-```
-
-Run `outcome.persistActions[]` first, then pass each key of the `outcome.renderArgs` object exactly once as an `okstra render-bundle` flag. Pass empty string values explicitly too, and add `--lead-runtime <host-runtime>` from preflight. Do not enumerate provider-specific keys in this manual; the wizard and provider registry own the emitted arguments. Exception: the `chain-stages` key is not a render-bundle flag — it drives the Step 7 unattended-chaining loop, so do not pass it as a flag (`run.py` accepts only `--stage`/`--stages`).
-
-```bash
-okstra render-bundle \
-  --lead-runtime <host-runtime> \
-  --<first-renderArgs-key> "<first-renderArgs-value>" \
-  --<each-remaining-renderArgs-key> "<corresponding-value>"
-```
-
-Parse the following labeled lines from stdout.
-
-- `okstra task root:`
-- `okstra instruction-set:`
-- optionally `okstra concurrent-run stages:`
-
-render-bundle calls `prepare_task_bundle()` in render-only mode to prepare the manifests, run context, instruction set, and discovery files, and registers the run as `prepared` in `~/.okstra/recent.jsonl`.
-
-## conformance waiver
-
-Classify the entry before offering a waiver. If `requires` contains `db`,
-`http`, or `external`, do not offer a waiver: Okstra still attempts the command,
-but any non-PASS or unavailable outcome is an external advisory with a
-user-owned rerun method. If `requires=[]`, fail closed as a declaration or
-contract defect and do not offer a waiver. Offer the waiver only when
-`requires=[io]` and that blocking local conformance command is genuinely
-impossible to run in the environment. A waiver requires user approval and a
-verbatim reason. Neither the AI lead nor a worker creates a self-exemption.
-The resulting blocking/advisory policy is enforced by
-`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
-`validators/validate-run.py::_validate_conformance`; the picker restriction is
-defined by `prompts/host-orchestration/implementation.md` Step 5.1 (the
-`okstra-run` skill body carries a generated copy).
-
-When chosen, add it to `render-bundle` only.
-
-```bash
---qa-waiver "<stageKey>:<reason>"
-```
-
-Omit the flag entirely when there is no value.
-
-## concurrent-run branch
-
-If `render-bundle` stdout carries `okstra concurrent-run stages:`, the no-team background gate is already reflected in the prompt.
-
-Give the user three options.
-
-1. Proceed as no-team background.
-2. Wait — hold the dispatch, preserve the stage worktree·run context. After the occupying run finishes, print the resume command (`okstra-inspect` history → resume) so the user can resume the same stage.
-3. Enter directly.
-
-This picker is authored by the skill, so it is separate from the wizard-option-abbreviation ban.
-
-## stale git SHA recovery
-
-When a `PrepareError` such as `Recorded stage SHAs no longer match the git history` appears, do not fix the registry/consumers by hand.
-
-1. Run the `okstra git-reconcile ... --check --text` printed in the error message verbatim.
-2. For each confirm item, ask the user for the current branch tip, a different ref, or abort.
-3. Run `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>` with the chosen ref.
-4. Retry the failed render-bundle with the same arguments.
-
-If the anchor is unresolvable, run `--reset-anchor <ref>` after user confirmation.
-
-## PR template persistence
-
-In release-handoff, when `outcome.persistActions[]` returns a `config.set` / `pr-template-path` action, save the config before render-bundle.
-
-```bash
-# action.scope == "project"
-okstra config set pr-template-path "<path>" --scope project
-# action.scope == "global"
-okstra config set pr-template-path "<path>" --scope global
-```
-
-Read the scope and path from the persist action of `okstra wizard outcome`, not from the wizard state file. Do not read the raw state file directly.
-
-## Okstra lead takeover
-
-After render-bundle, read the run manifest's `resources.leadExecutionPromptPath` (project-relative, under `runs/<task-type>/prompts/`), read that file verbatim, and proceed from Phase 1 in that prompt's order. Before any in-run approval or clarification question, follow the lead contract "User confirmation before an approval blocker": read cited plan items, worker findings, and files, then ask in the user's language with each option's outcome.
-
-Inform the user on one line.
-
-```text
-Took over as Okstra lead (`<host-runtime>`) for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
-```
-
-For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements. When the run is over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take it from the `report-finalize` result: `nextCommand` (`{command, note}`) is the table below already applied, and `nextRecommendedPhase` (`phase`, `status`, `rationale`) is what it was applied to — do not re-derive either from the report, and treat `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. After `implementation-planning`: open approval blockers → `/okstra-user-response`; a recorded `accept-risk` / `select` / `answer` is not an open blocker; no open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type: pointer `ready` → `/okstra-run` for that phase; `validate-run` failed → one-line cause then `/okstra-run`; otherwise `/okstra-inspect status`.
-
-## implementation unattended chaining (chain-stages)
-
-When `task-type == implementation` and the render-args `chain-stages` CSV has 2 or more elements, the current session acts as the orchestrator and runs the stages as an unattended chain in dependency order. Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`. For each stage `N` in the queue, in order:
-
-1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
-2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
-3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary. A `status:"failed"` row in place of `done` means the stage ended `FAIL` — stop the queue per the FAIL branch below.
-4. One-line report at each stage start/finish: `stage N start` / `stage N done → next K`.
-
-Once the whole queue is consumed, end the chain and report completion.
-
-- **Next stage not yet ready — normal termination:** When a stage in the queue is occupied by another implementation run as started/reserved and render-bundle is rejected with `--stage N already in progress or reserved by another run` (StageTargetError), this is not an exception — **terminate the chain normally** and report the remaining queue (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`).
-- **Stage ended FAIL — stop the queue and report:** When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row instead of `done`. **Stop the queue there** and report the failed stage, its report path, and the remaining queue. Do not continue to the next stage even when it is dependency-independent — later work must not be stacked on a confirmed regression. The `failed` row frees the occupancy, so `--stage <N>` re-enters that stage on its preserved worktree and branch.
-- **Exception gate during chaining:** If render-bundle raises a concurrent-run conflict or git stale-SHA reconciliation, **stop the chain at that stage** and present the gate to the user per the Step 5 procedure. Once the user resolves it, resume the remaining queue in place. Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining.
-
-## Forbidden patterns
-
-- Changing the question order the wizard emitted.
-- Hiding wizard options or keeping only the recommendations.
-- Turning a `text` prompt into a picker.
-- Dropping the `--answer` flag on an empty answer.
-- Bypassing the wizard/render-bundle path by calling `okstra.sh`.
-- Calling render-args on a state the user aborted before render-bundle.
-- Starting phase work arbitrarily before reading the Okstra lead prompt.