okstra 0.202.0 → 0.204.0

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

@@ -1,240 +0,0 @@
-# okstra-schedule-gen AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-schedule-gen/SKILL.md`](../../../skills/okstra-schedule-gen/SKILL.md)
-- Schedule template: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
-- Schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
-- Stage Map read side: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py)
-- Selection semantics: [`scripts/okstra_ctl/schedule_semantics.py`](../../../scripts/okstra_ctl/schedule_semantics.py)
-- Work-category source of truth: [`scripts/okstra_ctl/work_categories.py`](../../../scripts/okstra_ctl/work_categories.py)
-- workStatus inference reference: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
-
-## Purpose and invocation
-
-`okstra-schedule-gen` gathers non-done tasks in a task group and produces one client-facing work schedule from user-selected unfinished implementation stages.
-
-Public invocation:
-
-```text
-/okstra-schedule-gen [task-group]
-```
-
-This is a host skill, not a schedule-generation shell command. Use `stage-map` and `validate-schedule.py` only as backend contracts inside the skill.
-
-Output location:
-
-```text
-<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
-```
-
-Do not use it for single-task status analysis or phase execution. Use `okstra-inspect status` and `okstra-run` for those jobs.
-
-## Preflight and task-group resolution
-
-Run one literal-token preflight call:
-
-```bash
-okstra preflight --runtime claude-code
-```
-
-On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On
-`Okstra preflight: ready`, carry the fixed `Project root` line. Resolve an
-explicit task-group from the invocation or host request. If none is unambiguous,
-run `okstra model-io task-selection-input --project-root <projectRoot>` and ask
-the user to choose from the fixed `Task` rows; never guess. Then run
-`okstra model-io schedule-input --project-root <projectRoot> --task-group <group>`
-and use only its fixed task metadata rows.
-
-On zero matches, report that the task group was not found and do not create a file.
-
-## Candidate filter
-
-`workStatus` is used only to decide which tasks are candidates. When it is missing or empty, use the `okstra-inspect` `status.4` inference table.
-
-- Exclude resolved `done` tasks.
-- Include every other resolved state.
-- If no task remains, report that all tasks are done and do not create a file.
-
-Do not render `workStatus` as the detailed task status. The per-task `Status` value is `<taskType> / <currentPhase>`.
-
-## Source-aware Stage Map resolution
-
-For every candidate task, call:
-
-```bash
-okstra stage-map <task-key> --text
-```
-
-The successful fixed response carries `Status`, `Task key`, `Task root`, `State`,
-`Source plan path`, and lossless numbered `Stages`, `Done stages`, and `Planning`
-count/name/value rows.
-
-Handle each result explicitly:
-
-- `Status: ready`, `State: ready`: use exactly `Source plan path`; do not pick a report by mtime or `latestReportRecordPath`. Select only stages not present in the done-stage rows.
-- `Status: ready`, `State: missing`: record an empty source and empty stage sets, mark the task `[NEEDS-PLANNING]`, and emit no forward Work Breakdown, Gantt, or day total for it.
-- `Status: error` or another state: stop before drafting and report `Failure stage` and `Failure reason`. A corrupt or conflicting source must never fall back to a guessed report.
-
-A valid selected set is dependency-closed: every transitive prerequisite of a selected stage is either also selected or present in `doneStages`. Completed prerequisites remain evidence only and are never scheduled forward.
-
-If a ready task has no unfinished stages, render `_Complete — no remaining stage_` and omit forward effort.
-
-## Stage selection
-
-Offer up to three dependency-closed cumulative bundles in topological order, plus all remaining stages. A custom set is accepted only after closing it over unfinished prerequisites; completed prerequisites are preserved separately.
-
-Skip the picker when the remaining work has only one possible bundle and use all unfinished stages. Record the final stage numbers as `selectedStages`.
-
-## Temporary selection contract
-
-Write a paired draft and selection input with one timestamp:
-
-```text
-.okstra/tasks/<task-group-segment>/schedule/.draft/<timestamp>.md
-.okstra/tasks/<task-group-segment>/schedule/.draft/<timestamp>.selection.json
-```
-
-The selection file is a temporary verification input. It freezes the exact source, full stage map, completed stages, and user-selected forward work so both validators judge the same facts instead of re-resolving mutable task state.
-
-Schema version 1:
-
-```json
-{
-  "schemaVersion": 1,
-  "tasks": [
-    {
-      "taskKey": "demo:group:DEV-1",
-      "taskId": "DEV-1",
-      "state": "ready",
-      "sourcePlanPath": "/absolute/path/final-report-implementation-planning-001.data.json",
-      "selectedStages": [2, 3],
-      "doneStages": [1],
-      "stages": [
-        {
-          "stageNumber": 1,
-          "title": "Prepare port",
-          "dependsOn": [],
-          "stepCount": 2
-        },
-        {
-          "stageNumber": 2,
-          "title": "Build adapter",
-          "dependsOn": [1],
-          "stepCount": 3
-        },
-        {
-          "stageNumber": 3,
-          "title": "Wire consumer",
-          "dependsOn": [2],
-          "stepCount": 2
-        }
-      ]
-    }
-  ]
-}
-```
-
-Include every candidate task. A `missing` task has an empty `sourcePlanPath`, `selectedStages`, `doneStages`, and `stages`. Convert the CLI stage-row keys to the camel-case selection boundary exactly as shown.
-
-## Phase classification
-
-Only these canonical categories are valid:
-
-| workCategory | Default phase |
-|---|---|
-| `bugfix` | Phase 1 for High or Med-High risk; otherwise Phase 2 |
-| `feature` | Phase 2 |
-| `improvement` | Phase 2 |
-| `refactor` | Phase 3 |
-| `ops` | Phase 3 |
-
-Priority overrides category: P0 maps to Phase 1, P1/P2 to Phase 2, and P3 to Phase 3. An unknown or missing raw category falls back to Phase 2 with a one-line rationale naming the raw value. Do not invent another category.
-
-## Template contract
-
-Follow `schedule.template.md` exactly. The required top-level order is:
-
-1. `## At a Glance`
-2. `## Executive Summary`
-3. `## Task Dependency Graph`
-4. optional `## Gantt Chart`
-5. `## Phase 1: Critical Fixes`
-6. `## Phase 2: Enhancements`
-7. `## Phase 3: Architecture`
-8. `## Execution Priority Matrix`
-9. `## Cross-Task Dependencies & Shared Concerns`
-10. `## Risk Mitigation Strategy`
-11. `## Recommended Immediate Actions`
-12. optional final `## Glossary`
-
-Keep an empty required section and render `_none_`. Headings and field labels stay as English template literals; body prose is Korean.
-
-Each scheduled task uses this stage-level Work Breakdown shape:
-
-```markdown
-| Stage | Title | Steps | Depends On | Days |
-|---:|---|---:|---|---:|
-| 2 | Build adapter | 3 | 1 (done) | 2.0 ~ 3.0 |
-| 3 | Wire consumer | 2 | 2 | 1.0 ~ 2.0 |
-```
-
-Use the template's Effort Sizing Criteria values without redefining them. Allocate a task's range across selected stages in `stepCount` proportion: round every stage except the last to 0.5 day and let the last absorb the remainder. The stage ranges must sum to the task range, and finite task ranges must sum to the displayed total. XXL, missing, and complete tasks contribute no forward total.
-
-An unrepresentable half-day allocation is a validation error. Do not substitute a fallback allocation algorithm; revise the task sizing or selected-stage scope.
-
-## Gantt contract
-
-Render a plain fenced relative-day Gantt when the selected stages have finite day ranges. Every forward row is identified by stage and repeats its Work Breakdown range:
-
-```text
-DEV-1 Stage 2  ████      days=2.0~3.0
-DEV-1 Stage 3      ████  days=1.0~2.0
-```
-
-A row is labelled `Stage <n>` when exactly one task is scheduled and `<TASK-ID> Stage <n>` when more than one is; the annotation is `days=<lower>~<upper>`. Spell the stage out — `S1` is an opaque code that costs the reader a lookup and saves five characters. Do not emit a row for a completed, unselected, missing, or unknown stage. Bar length is arithmetic: one column is half a day, so a bar runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5` open cells `░`.
-
-Skip the chart only when no forward task has a finite day signal, and state the concrete reason. Do not use calendar dates, Mermaid, PlantUML, Graphviz, or another graph language.
-
-A host-supplied directive or the first `## Directive` in the configured analysis material may override the render/skip heuristic, but it cannot override stage selection, dependency closure, or validated day arithmetic.
-
-## Client-facing boundary
-
-Assume the team has the required authority. Exclude approval waits, permission checks, stakeholder coordination, decision checklists, and internal blocker codes from forward engineering work. Gantt duration and totals represent engineering work only.
-
-Resolve opaque source-report codes inline or in the optional final Glossary. Decision-item codes do not belong in the schedule.
-
-## Two validation gates
-
-Run both gates against the same draft and temporary selection contract.
-
-1. Deterministic gate:
-
-   ```bash
-   python3 ~/.okstra/lib/validators/validate-schedule.py <draft> --selection-json <selection>
-   ```
-
-2. Only after that command passes, create a new `.okstra/agent-invocations/schedule-verification/<invocation-id>.instructions.md` with the draft, selection JSON, and checks, but not the lead's reasoning. Run `okstra agent-prompt materialize --purpose schedule-verification --audience schedule-verifier ...` and verify the returned metadata before dispatch. A native host call uses the verified prompt body plus `hostModelValue`; a deterministic provider process uses `okstra worker-dispatch`, the prompt path, and `modelExecutionValue`. The verifier checks narrative coherence, phase rationale, executable order, engineering-only scope, and contradictions with the structured rows.
-
-Capture the raw verifier return under the purpose directory's `.tmp/`, then run `okstra agent-prompt materialize-result`, `complete`, and `verify-completion` in order. Parse only the verified `returnedBody`; an inline or unverified response cannot pass the narrative gate.
-
-If either gate finds a defect, revise the same draft in place and restart from the deterministic gate. Allow at most two revision rounds across both gates. Never publish a draft that has not passed both gates in that order.
-
-After both gates pass:
-
-1. Move the same draft content to the collision-safe final path; do not re-render it.
-2. Re-read it and run the installed format validator on the final path, falling back to the repository validator only when needed.
-3. Delete the temporary selection file only after final validation passes.
-4. Report completion in Korean with the output path, included/excluded counts, finite total range, and lead-plus-verifier mode.
-
-## Forbidden patterns
-
-- Guessing a planning report after `stage-map` reports a structured error.
-- Treating `workStatus` as the detailed schedule status.
-- Scheduling completed or non-selected stages.
-- Publishing a Gantt row without its `Stage <n>` label and `days=` range, or abbreviating that label to `S<n>`.
-- Drawing stage order in `## Task Dependency Graph` — that graph carries cross-task edges only; stage order lives in the Work Breakdown's `Depends On` column.
-- Dispatching narrative validation before deterministic `--selection-json` validation.
-- Re-rendering after validation instead of promoting the same draft.
-- Deleting the selection contract before final validation.
-- Publishing after more than two unsuccessful revision rounds.

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

@@ -1,167 +0,0 @@
-# okstra-setup AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
-- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- project registration impl: `src/commands/lifecycle/setup.mjs`
-- install/ensure-installed impl: `src/commands/lifecycle/install.mjs`
-
-## Purpose
-
-`okstra-setup` handles two things.
-
-1. Machine-level runtime install: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
-2. Project-level registration: `<PROJECT_ROOT>/.okstra/project.json`
-
-It is not a day-to-day task-running skill. If a task is already prepared, route to `okstra-run` or `okstra-inspect`.
-
-## When to use
-
-Use it when:
-
-- The user asks for "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time setup".
-- `~/.okstra/version` is missing or looks stale.
-- The current project has no `.okstra/project.json`.
-
-Do not use it when:
-
-- The user wants to start a task run. Use `okstra-run` instead.
-- The user wants to view status/history/report. Use `okstra-inspect` instead.
-- `.okstra/project.json` already exists and only day-to-day usage is needed.
-
-## Pre-run checks
-
-Tell the user that Node 18+ and Python 3.10+ are required. If it is unclear whether the current working directory is inside the project that will host the okstra metadata, confirm the project root first.
-
-Install command:
-
-```bash
-npx -y okstra@latest install --runtime claude-code
-```
-
-Treat this command as idempotent. Even if already installed, re-run it to align the runtime, skill, and agent payload with the current package version (agent payload = the `~/.claude/agents/<worker>.md` worker definitions + the `~/.okstra/installed-agents.json` manifest). If it fails, show the stderr to the user verbatim. Do not fall back to the legacy `okstra-install.sh`.
-
-## Command invocation rule
-
-After `okstra install`, every subsequent command must begin with the literal `okstra` token.
-
-Allowed forms:
-
-```bash
-okstra preflight
-okstra setup --yes --project-root /abs/project --project-id my-project
-okstra doctor --runtime claude-code
-```
-
-Forms to avoid:
-
-- `export PYTHONPATH=...`
-- `eval "$(okstra paths --shell)"`
-- shell variables like `$PROJECT_ROOT`
-- `$(...)` command substitution
-- okstra calls wrapped in `if`, `&&`, `||`
-
-Because `okstra <subcmd>` bootstraps its own Python path, do not use `okstra paths --shell` in this skill. If you need the okstra home, run `okstra paths --field home` as a separate call and carry the printed path.
-
-## Project root resolution
-
-Run first:
-
-```bash
-okstra preflight
-```
-
-Handle the result:
-
-- `Okstra preflight: ready`: already a registered project. Show `Project root`, `Project JSON`, and `Project ID` to the user and confirm whether to keep it.
-- `Okstra preflight: failed` with `Stage: resolve`: get an absolute project root from the user and re-run `okstra preflight --cwd /abs/path`.
-- `Okstra preflight: failed` with `Stage: project_json_missing`: proceed with the normal create path.
-- any other failure stage: show `Reason` verbatim and follow `Recovery`.
-
-## Create or keep project.json
-
-If `<PROJECT_ROOT>/.okstra/project.json` exists, show `projectId` and `projectRoot` and confirm whether to keep or overwrite. The default is keep. Changing the existing `projectId` requires deleting the file, so do not overwrite automatically.
-
-If the file does not exist, ask for a project id. The answer must be non-empty and contain at least one alphanumeric character. Calling `okstra setup --yes` with an empty value fails, so re-ask.
-
-Create command:
-
-```bash
-okstra setup --yes --project-root /abs/project --project-id my-project
-```
-
-`okstra setup` also refreshes the okstra-managed citation-guidance block in
-`<PROJECT_ROOT>/CLAUDE.md` and `AGENTS.md` when those files already exist (it never
-creates them). The block tells agents not to carry okstra-internal references — report
-section numbers, `C-NNN` clarification ids, run/stage ids, `.okstra/...` paths — into
-writing that is not an okstra report, where the reader cannot resolve them. The command
-reports the files it touched in its JSON `citationGuidance` array; a failure there is a
-`warning:` line, not a non-zero exit. Tell the user which guidance files were updated so
-they can review the appended block.
-
-## Optional configuration
-
-Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.
-
-Optional settings:
-
-- `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
-- `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
-- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns
-  Okstra uses to attempt Tier 3 automatically; real DB/API verification remains
-  a user-owned advisory when the environment is unavailable or the result is
-  non-PASS.
-- PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
-- final report language: `okstra config set report-language <language-tag> --scope project` (`en`, `ko`, `fr`, `pt-BR`, …; default `en`)
-- `architecture.style`: the project's declared architecture — `hexagonal`,
-  `layered`, or `none` (default `none` when absent, unrecognized, or
-  unreadable). `okstra setup` never writes it; hand-add it to `project.json`
-  and the upsert preserves it. Declaring a style promotes that architecture's
-  placement rules from advisory to a binding planning + verification
-  constraint — under `hexagonal` an extracted variation point must be a port,
-  under `layered` the dependency direction is worker-judged with no machine
-  check. See section F of `references/project-config.md`.
-- `reviewRulePacks`: absolute paths to the project's own review rule packs (a
-  team PR-review skill's `SKILL.md`). Without a declaration a pack applies only
-  when the task brief cites its exact path; declared here it applies to every
-  run, and the two channels are a union. Read by `implementation-planning`, the
-  executor preflight, the implementation verifier, and `final-verification`.
-  `okstra setup` never writes it. `okstra doctor --phase <phase>` fails when a
-  declared path is not readable. See section G of
-  `references/project-config.md`.
-
-If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.
-
-## Automatic Claude settings symlink
-
-`okstra setup` provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to `~/.okstra/templates/settings.local.json`. If an existing regular file is present, it backs it up as `.bak.<timestamp>` and then places the symlink. If a failure message appears, the user must manually merge the existing project-specific rules.
-
-## Verify
-
-Run last:
-
-```bash
-okstra doctor --runtime claude-code
-```
-
-If every check is OK, report setup complete. If any check fails, show the output verbatim and let the user decide whether to reinstall or skip.
-
-## Completion message
-
-Keep it short and include the following.
-
-- runtime location: `~/.okstra` (also show the `version stamp: x.y.z` line from the install summary)
-- project metadata: `<PROJECT_ROOT>/.okstra/project.json`
-- `projectId`
-- next step: `/okstra-run`
-
-## Common failure handling
-
-| Symptom | Handling |
-|---|---|
-| `command not found: npx` | Point to installing Node 18+ |
-| `--project-id is required` | Re-ask for the project id and re-run with a non-empty value |
-| `projectId mismatch` | Confirm with the user which id is canonical. Do not delete automatically |
-| `.okstra/` write EACCES | Explain the ownership/writability problem |
-| `.claude/settings.local.json` symlink warning | Show the backup file and symlink state to the user and guide a manual merge |

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

@@ -1,29 +0,0 @@
-# okstra-usage AI Manual
-
-## Purpose
-
-Use `okstra-usage` for a project-wide historical resource snapshot. It is not a
-single-task inspection (`okstra-inspect`) and not a cross-task status/report
-digest (`okstra-rollup`).
-
-## Call
-
-Run preflight, resolve a positive day count (default 30), then call exactly once:
-
-```bash
-okstra usage-report --days 30 --project-root <projectRoot> --text
-```
-
-## Render contract
-
-Render the numbered `By task type` rows and fixed totals without recomputing them.
-Show Runs, returned collection rate as Coverage, Raw tokens, Billable, Cost, CPU, and Wall. Surface numbered
-unavailable-reason and unmatched-model rows. Missing usage is excluded data, not
-zero usage.
-
-## Boundaries
-
-- One task's elapsed/context detail: `okstra-inspect`.
-- Task-group/project status and report digest: `okstra-rollup`.
-- HTML dashboards, budgets, forecasts, and task/model/worker drill-downs are not
-  part of this MVP.

package/docs/for-ai/skills/okstra-user-response.md

@@ -1,72 +0,0 @@
-# okstra-user-response AI Manual
-
-## Sources
-
-- Skill source: [`skills/okstra-user-response/SKILL.md`](../../../skills/okstra-user-response/SKILL.md)
-- Response core: [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
-
-## Purpose
-
-`okstra-user-response` answers unresolved `C-*` clarification items and records explicit plan decisions without hand-editing a report or sidecar. The user selects or writes every answer. Publication changes only the user-owned `runs/<task-type>/user-responses/` sidecar.
-
-The model-facing reads are fixed text. Do not use the automation-compatible JSON reads to drive a conversation. Do not open the final-report record directly.
-
-| Command | Purpose |
-|---|---|
-| `okstra user-response list-view --home <home> --project <projectId> --limit 3` | List tasks that still need clarification answers or a plan decision. |
-| `okstra user-response show-view --report <reportPath> --project-root <projectRoot>` | Show open questions, choices, impact, why asked, linked plan items, cited artifacts, approval context, plan candidates, and current state after validating project ownership. |
-| `okstra user-response begin --report <reportPath> --task-key <taskKey>` | Open a typed transaction and return an opaque id. |
-| `okstra user-response answer ...` | Add one validated answer to the draft. |
-| `okstra user-response plan-decision ...` | Record an explicit plan decision. |
-| `okstra user-response legacy-report-authoring ...` | Record contract 2.0 report-authoring permission. |
-| `okstra user-response finalize --transaction <transaction>` | Merge and atomically publish the sidecar. |
-
-The legacy `list` and `show` JSON commands remain for automation compatibility. They are not model-facing reads.
-
-## Flow
-
-1. Run `okstra preflight --runtime <host-runtime>` for the current harness. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root`, `Project ID`, `Runtime`, and `Relay contract`, then run `okstra paths --field home`.
-2. Read the relay `Wizard interaction relay` JSON. When `native-single` is available and the option count fits `nativeLimits`, call `interactions.native-single.function` (`AskUserQuestion` / `ask_user_question` / `request_user_input` from that field). Do not print a numbered list in chat while the native tool is available. Emit the question as the last thing in that turn; text emitted after the call renders below the question. Otherwise render a numbered Markdown list. Do not substitute one host function name for another. Copy the view's `Picker:` `- Label:` / `Description:` pairs into that function in that order. Do not rebuild labels from the `Options:` dump. `--option-number` is the 1-based `Option N:` index, which is the same order as `Picker:`. The HTML report's `<select>` uses the same `option.answer` values. Pass only the `list-view` `Picker:` rows, the report `Picker:` rows, or the two confirmation labels. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row are `Enters an answer`; on a numbered list, so is a next message that is not a listed label or its 1-based number. Do not ask a second question for the custom value.
-3. Select a task from `list-view` through that host picker. A host free-text row or unmatched next message is the report path or task key.
-4. Read only `show-view --report <reportPath> --project-root <projectRoot>` for report facts. The view also prints `Why asked`, `Linked plan items`, and `Cited artifacts`.
-5. Read every cited `path:line` under the project root and every linked plan-item definition before asking. Do not search beyond that list. Investigation explains; it never changes `options[]`.
-6. Ask one open clarification at a time in the user's language through the host picker. The question body is why, what is already decided, the fork, and what stays blocked. Do not lead with `Kind`, `Blocks`, `Expected form`, or `C-NNN`. Keep the row id in parentheses at the end.
-7. Echo the complete response and confirm through the host picker (`Record as shown` / `Change an answer`). Do not ask them to type `confirmed`.
-8. Begin the transaction, add answers and decisions, then finalize it.
-
-Each `options[]` row displays `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. Contract 3.0 additionally displays `reach`, `scopeEffects`, and row-level `approvalContext`. Option descriptions use this order: If you pick this (`addedWork`). What it reverses (`directionChange`). Scope (`reach` or `scopeImpact`). Why it is on the board (`rationale`). If the view says `not stated in the report`, repeat that text and never invent a value. A quote from a cited file may follow those axes; it does not replace them.
-
-When the user selects a predefined option, pass only the fixed view's one-based option number. Python resolves that option's `disposition`, answer, reach, and scope effects from the validated report:
-
-```bash
-okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
-```
-
-Every value, rationale, and reason body file must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; external files and symbolic links are rejected. For direct input, write the user's exact words there and use the mutually exclusive direct form:
-
-```bash
-okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <answer|reframe> --value-file <value.md> [--rationale-file <rationale.md>]
-```
-
-Record a plan decision only when the user states it explicitly. Any reason file stays in that same temporary directory:
-
-```bash
-okstra user-response plan-decision --transaction <transaction> --status approved [--implementation-option <candidate-name>]
-okstra user-response plan-decision --transaction <transaction> --status <revision-requested|rejected> --reason-file <reason.md>
-```
-
-The implementation option must match a candidate printed by `show-view`. A report with no open clarification can still require this decision.
-
-Contract 2.0 alone supports legacy report-authoring permission. Its reason file stays in that same temporary directory:
-
-```bash
-okstra user-response legacy-report-authoring --transaction <transaction> --status <approved|denied> --reason-file <reason.md>
-```
-
-Finish with:
-
-```bash
-okstra user-response finalize --transaction <transaction>
-```
-
-Do not decode the transaction id. Do not inspect transaction state. Do not hand-edit report records, rendered reports, or sidecars.

package/runtime/agents/workers/claude-worker.md

@@ -1,128 +0,0 @@
----
-name: claude-worker
-description: |
-  Use this agent when dispatched as a Claude worker for okstra cross-verification tasks. Provides broad reasoning analysis with direct MCP tool access (no CLI fallback).
-
-  <example>
-  Context: The okstra skill is orchestrating a multi-agent cross-verification run.
-  user: "okstra this task bundle"
-  assistant: "Spawning claude-worker agent to get Claude analysis."
-  <commentary>The okstra skill dispatches this agent as part of the worker roster.</commentary>
-  </example>
-
-  <example>
-  Context: A cross-verification needs Claude perspective on broad reasoning.
-  user: "cross verify this implementation"
-  assistant: "Running claude-worker for independent Claude analysis."
-  <commentary>Cross-verification tasks require independent AI worker outputs.</commentary>
-  </example>
-model: inherit
-color: blue
-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch"]
----
-
-This is the Claude host-native execution adapter for a materialized Okstra
-invocation. The final prompt's duty contract owns the role boundary,
-responsibility, and prohibited actions. This file owns Claude tool usage,
-artifact persistence, and liveness procedure only. Do not shell out to another
-model CLI, and refuse a dispatch whose prompt has no adjacent verified
-invocation metadata. Consume the stored `executionLabel`; do not infer a role
-from the provider name. `lead` is a compatibility alias for `leader`.
-
-## Execution Rules
-
-1. The summon message you were invoked with carries the absolute path of your dispatch prompt document — it is not the prompt itself. Read that document COMPLETELY before doing anything else: the `Read` tool returns up to 2000 lines per call, so continue with `offset` until you have seen the last line of the file. Every later rule that says "the lead prompt" means that document. If the summon carries no path, immediately return:
-   `CLAUDE_PROMPT_PATH_MISSING: dispatch prompt document path was not provided`
-
-2. Extract the absolute `Project Root` from the lead prompt (look for a line starting with `**Project Root:**` or `Project Root:`). If it is missing, immediately return:
-   `CLAUDE_PROJECT_ROOT_MISSING: absolute Project Root was not provided in the lead prompt`
-
-3. The document already lives at its own `Assigned worker prompt history path:` — the lead persisted and verified it before dispatch. Do NOT rewrite it. Check that the path you were summoned with matches that header (resolve a relative header value against `Project Root`); on a mismatch, return:
-   `CLAUDE_PROMPT_PATH_MISSING: summon path does not match the document's assigned prompt history path`
-
-4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
-   - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls).
-   - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code. Use this worker prompt's `**Coding preflight pack:**` anchor header; read that pack's `overview.md` and `clean-code.md`, then follow the routed pack's language → framework → architecture stages, iterating every rule and loading every matching resource (for example `frameworks/node-server.md` and `architectures/hexagonal.md` when their conditions match). The preflight pack is a runtime resource, not an auto-invoked skill; read the files via the Read tool by absolute path.
-   - **Executor post-write gates (BLOCKING, before your final commit / before claiming done):** the same dispatch prompt carries two gate blocks the lead appends after the preflight — `Pre-commit diff review sweep` (`prompts/profiles/_implementation-diff-review.md`) and `Implementation self-check` (`prompts/profiles/_implementation-self-check.md`). Execute both and record their coverage lines in your worker result exactly as the blocks specify. The codex/antigravity wrappers refuse to launch when an executor prompt lacks these blocks (`*_POSTWRITE_GATE_MISSING`); this worker runs in-process with no wrapper gate, so the contract lands on you directly — if either block is missing, record a typed `tool-failure` through `okstra error-log append-observed` and tell the lead to re-dispatch with the blocks included.
-   - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
-   - **Shell commands must not be able to prompt:** this worker runs inside the host session, so its Bash calls see the user's own shell, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form. The confirmation that alias raises has nobody to answer it and the dispatch hangs until it is killed. Invoke these as `command cp` / `command mv` / `command rm` — alias expansion is skipped and the tool behaves exactly as written. Do not reach for `-f` instead; it also changes what the tool does on failure (`rm -f` reports success on a path that never existed).
-   - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
-
-5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the analysis packet's `Available MCP Servers` section. If the section is absent or says none, treat MCP as unavailable for this run; never infer tools from host configuration. When the task requires inspection of an external system covered by a listed server, call the tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
-
-6. If your dispatch prompt carries a `**Phase 1.5 Grilling Log:** <abs-path>` anchor header (the lead injects it only on `improvement-discovery` runs), the file it points to is the authoritative scope and lens definition. Read it at the absolute path from the anchor — do NOT synthesize the path from `<RUN_DIR>`. Use its `Resolved scope` and `Resolved lenses` blocks and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses` fields. Findings that violate the resolved lens whitelist or scope are rejected by `validators/validate_improvement_report.py`.
-
-## Required Reading Before Any Analysis
-
-Before producing any output, you MUST:
-
-1. Extract `**Worker Preamble Path:**` and `**Worker Error Contract Path:**` from the lead prompt and Read both selected files end-to-end with one full-file `Read` each. The preamble owns audience procedure; the error contract owns typed error-log write rules. Never replace the selected path with a hard-coded analysis preamble.
-2. Read every primary input file the lead enumerated under `## Inputs` (or equivalent heading) end-to-end, following the selected preamble. Analysis workers normally receive `analysis-packet.md`; implementation workers receive their role sidecar and approved deliverable inputs.
-3. When the prompt carries `**Evidence ledger:** required-v1`, follow the selected preamble's `Evidence read ledger` procedure for every claim-evidence file you open. Do not invent a separate audit-row format here.
-
-**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent, a cmux surface, or a CLI wrapper subprocess, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang.
-
-- **Where:** the absolute path in `**Audit sidecar path:**`.
-- **Start (before the per-file reads):** immediately after extracting `Project Root` and the assigned paths, `Write` just the heading line (`# Claude Worker Audit — <task-key>`) plus one `- PROGRESS: started <ISO-8601-UTC>` line.
-- **Append per stage** (`Edit` or heredoc `>>`): `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`.
-- **Cadence MUST NOT exceed 5 minutes:** if a single analysis stage runs longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` line. A 5-minute-stale sidecar mtime is the canonical "this worker has hung" signal for the operator.
-- **Enforcement:** the Phase 7 validator (`validate_session_conformance.py`) parses these `- PROGRESS:` lines post-hoc and fails the run when the first stage is not `started`, `write-result-start` is missing despite an existing result file, timestamps regress/unparse, or consecutive lines are more than 5 minutes (+60s grace) apart.
-
-## Worker Output Structure
-
-Follow the output contract selected for your audience. Analysis workers use the analysis preamble's sections 1–5 plus optional Section 6; implementation executor/verifier workers use the implementation preamble plus their role sidecar. Set `workerId: "claude"`.
-
-## Stop Condition (BLOCKING)
-
-When Lead dispatches you with `run_in_background: true`, its `Agent()` call returns `Spawned successfully` **immediately** and does NOT block on your completion — Lead detects your completion by self-scheduled polling of your worker-results file (see `team-contract` "Worker-completion detection"). Therefore you MUST write your worker-results file at the canonical Result Path before returning: that file's appearance is the ONLY completion signal Lead uses. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping.
-
-After your `Write` to the assigned worker-results file (path provided by Lead as `**Result Path:**` — the canonical anchor header defined in `team-contract` "Worker Prompt Composition" — or derived under `runs/<task-type>/worker-results/claude-worker-<task-type>-<seq>.md`) succeeds:
-
-1. Return your final assistant message **immediately**. Begin every return with your model identity, per the preamble §"Return message to the lead", then the status line — for an analysis dispatch:
-   ```
-   **Model:** Claude worker, <modelExecutionValue>
-   Worker results written to <abs path>. Sections 1–5 complete. Findings: <n>.
-   ```
-   The `**Model:**` line precedes whatever you return — analysis status above, or a convergence reverify verdict summary.
-2. Do NOT perform additional `Read`, `Grep`, `Glob`, MCP, or self-review tool calls after the file is written.
-3. Do NOT rewrite the worker-results file with `Write` more than once. If a correction is genuinely required, perform a single `Edit` and then return immediately.
-4. The only exception is recording a `tool-failure` with the typed error-log command when a post-Write failure is itself the failure being reported — return immediately after that command.
-
-**Enforced:** `validators/validate-run.py` `validate_team_state` fails a run whose worker carries a terminal status with no saved result file at its assigned Result Path (and no saved prompt history at its assigned prompt path).
-
-If you find yourself thinking "let me double-check section 3" or "I should read one more file to be safer" after the Write succeeded — stop. Convergence (Phase 5.5) and the Report writer worker (Phase 6) will reconcile gaps across all three workers; over-investing in single-worker depth at the expense of returning quickly is a net loss for the run.
-
-## Error reporting
-
-Record your own tool failures per the file selected by `**Worker Error Contract Path:**`: extract `**Errors log path:**` from the dispatch prompt (return `CLAUDE_WORKER_ERRORS_PATH_MISSING` without proceeding if absent), then invoke its typed `okstra error-log append-observed` command. This worker has no external CLI, so MCP and Bash failures use the same typed protocol.
-
-## Notes
-
-- Return error messages as-is on failure.
-- Do not summarize or modify your own analysis output beyond the structured sections above.
-
-## Stage evidence emission (BLOCKING, implementation task only)
-
-When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2:
-
-```json
-{
-  "schemaVersion": 1,
-  "sourcePlanPath": "<approved-plan path>",
-  "stageNumber": <int>,
-  "stageTitle": "<from Stage Map>",
-  "completedAt": "<ISO-8601 with tz>",
-  "stageCommitRange": { "base": "<sha>", "head": "<sha>" },
-  "filesChanged": ["<rel/path>", "..."],
-  "newIdentifiers": ["<name>", "..."],
-  "stepResults": [{"step": <int>, "status": "done", "commit": "<sha>"}],
-  "validationsPassed": ["<label>", "..."],
-  "notes": []
-}
-```
-
-Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The host-native Okstra lead is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
-
-This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.
-
-**Enforced:** `scripts/okstra_ctl/implementation_outcome.py` `_load_carry` / `_carry_passed` read the persisted `carry/stage-<N>.json`; a stage with no carry block never reaches `done`, and `validators/validate_session_conformance.py` `_check_progress_checkpoints` requires the `phase-5-stage-complete` line the lead can only write by parsing this block.