okstra 0.180.0 → 0.183.2

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

@@ -40,10 +40,10 @@ No sub-command writes outside this machine.
 Run once before any sub-command.
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-The project check only sees the cwd of the Bash call. For a project that is not the cwd (a sibling repo, a monorepo subdir, or a project named in the request), `ok:false` is a false negative, not a missing setup — do not stop immediately; retry with `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project without a leading `cd`). Only when that also returns `ok:false` do you guide the user to `/okstra-setup` and stop. Then use `projectRoot` as a literal value, and pass it to the sub-command CLIs that accept it (`recap`, `context-cost`, etc.) via `--cwd`/`--project-root <projectRoot>`.
+The project check only sees the cwd of the Bash call. For a project that is not the cwd (a sibling repo, a monorepo subdir, or a project named in the request), `Okstra preflight: failed` can be a false negative rather than missing setup. Retry with `okstra preflight --runtime claude-code --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project without a leading `cd`). Only when that also reports `Okstra preflight: failed` do you show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root` as a literal value and pass it to the sub-command CLIs that accept it (`recap`, `context-cost`, etc.) via `--cwd`/`--project-root <projectRoot>`.
 
 ## intent routing
 
@@ -62,10 +62,10 @@ Many facets accept the following target forms.
 A bare task-id uses the shared resolver.
 
 ```bash
-okstra resolve-task-key <task-id> --project-root <projectRoot> --json
+okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>
 ```
 
-Handling `matches[]`:
+Handling the fixed text projection's `Match count` and repeated task lines:
 
 - 0: say it cannot be found; do not guess.
 - 1: use that `taskKey`.
@@ -75,7 +75,7 @@ Handling `matches[]`:
 
 ### Project overview
 
-Read `.okstra/discovery/task-catalog.json`. Do not re-open individual manifests for the overview. The catalog is the projected source.
+Run `okstra model-io status-input --project-root <projectRoot>`. Its fixed text task blocks are the projected source.
 
 Sort: `updatedAt` desc, then `taskKey`.
 
@@ -91,7 +91,7 @@ Keep the table narrow.
 
 ### Specific task
 
-For a single task's detail, check the catalog first, then if needed read `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, and the latest run manifest.
+For a single task's detail, run `okstra model-io status-input --project-root <projectRoot> --task-ref <task-key>` and use its named lines.
 
 Information to show:
 
@@ -117,7 +117,7 @@ Allowed values:
 - `blocked`
 - `done`
 
-Procedure: update via a single `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --json` call — do not edit the manifest by hand. On `stage:"ambiguous"`, re-ask with `matches[]`; on `stage:"not-found"`, answer that it cannot be found.
+Procedure: update via a single `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --text` call — do not edit the manifest by hand. On `Stage: ambiguous`, re-ask with the listed `Match` values; on `Stage: not-found`, answer that it cannot be found.
 
 When `workStatus` is absent in a read display, infer it from the lifecycle state, but do not back-fill on read alone.
 
@@ -128,20 +128,15 @@ First branch: distinguish re-run from resume.
 - Re-run: create a new run from previous run parameters. A new run-seq is created.
 - Resume: continue an interrupted existing run. No new run-seq is created.
 
-If the catalog is absent, fall back to the `.okstra/tasks/*/*/task-manifest.json` glob. The disk manifest is the source of truth.
+Run `okstra model-io history-input --project-root <projectRoot>` for project history, or add `--task-ref <task-key>` for one task.
 
-Re-run extracts `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides, and so on from the source run-manifest to assemble the command. `implementation`'s `--base-ref` is not in the run-manifest but in the worktree registry, so ask for it as the situation requires.
+Re-run obtains `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, related tasks, model overrides, and executor provider through `okstra model-io rerun-input --run-manifest <runManifestPath>`. Omit `implementation`'s `--base-ref` to reuse a registration; if launch reports that a base is required, ask the user.
 
 Resume checks `latestResumeCommandPath` or the timeline entry's `resumeCommandPath`, and if the file exists, guides/runs `bash <resume-command-path>`. If the path is empty or the file is missing, declare "no resume" and guide to history.3 (re-run).
 
 ## report
 
-report path resolution priority:
-
-1. `latestReportRecordPath` in `.okstra/discovery/task-catalog.json`
-2. `latestReportRecordPath` in the direct `task-manifest.json`
-3. a specific run's `reportPath` in `history/timeline.json`
-4. specific task-type fallback: `runs/<task-type>/reports/final-report-*.data.json`, including stage-isolated paths. Render a full reading copy on demand with `okstra render-final-report <that data.json>`.
+Run `okstra model-io report-input --project-root <projectRoot> --task-ref <task-key>` for the latest report. For a specific run, use the `Report` line from `okstra model-io history-input --project-root <projectRoot> --task-ref <task-key>`. Render a full reading copy on demand with `okstra render-final-report <that data.json>`.
 
 Match read depth to the request (a final report is 300+ lines / 50K+ tokens). For summary/conclusion/pass questions ("summary", "just the key points", "conclusion", "did it pass?"), do not read the whole thing — read only the verdict in the `runs/<task-type-segment>/status/final-<task-type-segment>-<NNN>.status` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) sidecar plus the report's leading summary block. Ingest the whole file only for "the whole thing / read it all / full body". If a completion signal exists but the file does not, report it as a missing report; if it is not yet complete, show the current status and workStatus.
 
@@ -150,7 +145,7 @@ Match read depth to the request (a final report is 300+ lines / 50K+ tokens). Fo
 The CLI does the time computation. The AI does not recompute duration by hand.
 
 ```bash
-okstra time-report <task-key> --project-root <projectRoot> --json
+okstra time-report <task-key> --project-root <projectRoot> --text
 ```
 
 Convert every `*Ms` to `HH:MM:SS` for display. `CPU sum` is the overlapping cost of lead and workers time combined, not wall-clock. Show wall-clock from `perRunWallClock` only when the user explicitly asks. For `by stage`/`per stage`/`which stage took longest`, the task-type view (the By task type table) is the default answer — do not treat it as 'not measurable'. Render the intra-run `phaseTimelines` only on an explicit request like 'Phase 1–7' / 'which phase', and when it is empty, mention it only as a footnote rather than a headline.
@@ -178,7 +173,7 @@ Interpretation points:
 wrapper sidecar log inventory:
 
 ```bash
-okstra log-report --project-root <projectRoot> --json
+okstra log-report --project-root <projectRoot> --text
 ```
 
 Scans `.okstra/tasks/**/runs/*/prompts/*.log`. Does not delete. The cleanup command merely presents a dry-run and `-delete` pair as fenced bash.
@@ -190,21 +185,21 @@ Deleting an active run's log loses the live trace, so recommend checking `status
 Aggregate task error logs into a markdown report.
 
 ```bash
-okstra error-report <task-key> --project-root <projectRoot>
+okstra error-report <task-key> --project-root <projectRoot> --text
 ```
 
-Read `reportPath`, totals, byPhase, byAgent, parseSkipped from the stdout JSON and summarize. If `reportPath` is absent and errorCount is 0, say there are no recorded error logs. Do not hide `parseSkipped > 0`.
+Read the fixed `Report path`, total, phase, agent, and parse-skipped labels and summarize. If the report path is `-` and total errors is 0, say there are no recorded error logs. Do not hide a nonzero parse-skipped count.
 
 ## error-zip
 
 Bundle the machine's cross-project okstra errors into an anonymized zip.
 
-For the output path, recommend `lastOutputPath` from `~/.okstra/error-zip.json` first, and if absent, propose `~/okstra-error-feedback-<YYYY-MM-DD>.zip`.
+Run `okstra model-io error-zip-input`. Recommend its `Previous output path` first when present; otherwise propose `~/okstra-error-feedback-<YYYY-MM-DD>.zip`.
 
 Run:
 
 ```bash
-okstra error-zip --out <path>
+okstra error-zip --out <path> --text
 ```
 
 Summary fields:
@@ -222,12 +217,14 @@ At the end, guide the user to build a brief with the error-feedback variant of `
 
 The default is artifact mode. It builds the before/after summary and answers questions using only `.okstra/` artifacts.
 
-assemble:
+Read the fixed recap projection:
 
 ```bash
-okstra recap assemble <task-key> --project-root <projectRoot>
+okstra model-io recap-input --project-root <projectRoot> --task-ref <task-key>
 ```
 
+Use the emitted `Run count` and repeated `Transition` fields in order. Do not parse recap JSON or open recap state files directly.
+
 record:
 
 ```bash

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

@@ -13,7 +13,8 @@ Use this to bundle okstra tasks across multiple projects into a single manager-o
 ## Execution Rules
 
 1. Every command starts with the literal `okstra`. Do not wrap it in shell variables, `$(...)`, `&&`, `eval`, or a leading env assignment.
-2. JSON stdout is the source of truth. Do not reconstruct manager state or child launch args from docs/memory.
+2. The fixed CLI fields are the source of truth. Do not reconstruct manager state or child launch args from docs/memory.
+   Nested project, manifest, child, snapshot, and directive values use numbered count/name/value rows; carry every returned row.
 3. `--workspace-root` is owned by the Node wrapper. The CLI rejects it if the user passes it.
 4. `new project`'s `--project-root` must be an already-existing directory. It performs setup-equivalent registration only when there is no `.okstra/project.json` inside it.
 5. The public child task identity is `project-id:task-group:task-id`. The `new task --task` example shows the full key form first.
@@ -22,16 +23,16 @@ Use this to bundle okstra tasks across multiple projects into a single manager-o
 ## Command Surface
 
 ```bash
-okstra manager init --manager-id <manager-id> --json
-okstra manager discover-projects --json
-okstra manager new project --manager-id <manager-id> --project-id <project-id> --project-root <abs-path> [--role <role>] [--tag <tag>] --json
-okstra manager new task-group --manager-id <manager-id> --task-group <task-group> --json
-okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--task <project-id:task-group:task-id> ...] [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>] --json
-okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>] --json
-okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text> --json
-okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
-okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
-okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] --json
+okstra manager init --manager-id <manager-id>
+okstra manager discover-projects
+okstra manager new project --manager-id <manager-id> --project-id <project-id> --project-root <abs-path> [--role <role>] [--tag <tag>]
+okstra manager new task-group --manager-id <manager-id> --task-group <task-group>
+okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--task <project-id:task-group:task-id> ...] [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>]
+okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
+okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
+okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
+okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
+okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>]
 ```
 
 ## Storage Model
@@ -56,13 +57,13 @@ A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<s
 
 ## Child launch
 
-`task run` does not run the child work directly; it prepares a launch packet. The key fields of the returned packet:
+`task run` does not run the child work directly; it prepares a launch packet. The key fixed fields of the returned packet:
 
-- `taskKey`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
-- `backend`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
-- `workerDispatchBackend`: always `subagent` in v1
-- `projectRoot`: the child project root
-- `contextPath`: the manager child context markdown
-- `runArgs`: the `okstra run ... --directive "Read manager child context: ..."` args for the host launcher to use
+- `Task key`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
+- `Backend`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
+- `Worker dispatch backend`: always `subagent` in v1
+- `Project root`: the child project root
+- `Context path`: the manager child context markdown
+- every numbered `Run arg N`: the ordered `okstra run ... --directive "Read manager child context: ..."` arguments for the host launcher to use
 
 When packet creation succeeds, that child launch's status in `children.json` is updated to `prepared`, and a `child-launch-prepared` is appended to `events.jsonl`. On failure it does not modify the project-local task state.

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

@@ -51,7 +51,7 @@ Every memory entry belongs to a project-group. Pick the group before storing or
 Enumerate existing groups:
 
 ```bash
-okstra memory groups --json
+okstra memory groups
 ```
 
 Recommendations:
@@ -108,7 +108,7 @@ okstra memory show "<memory-id>"
 okstra memory archive "<memory-id>"
 ```
 
-Prefer `--json` when you need to parse IDs. Show the user only a short summary plus the entry id/path.
+Read IDs from the fixed text rows. Show the user only a short summary plus the entry id/path.
 
 ## Output rules
 

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

@@ -31,9 +31,9 @@ A 3-option picker via `AskUserQuestion`:
 
 ## Mode A — Generate PR
 
-1. Pick a template: `okstra pr template list --json`. If empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
-2. Pick the base branch: `okstra pr branches --json`. 3-option from the top `recommended` entries plus `Enter directly`. Carry the choice as `<base>`.
-3. Generation bundle: `okstra pr gen --base <base> --template <template> --json` → `{base, currentBranch, templateName, template, commits, diffStat}`. 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`/`diffStat` are empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
+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.**
 

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

@@ -37,10 +37,11 @@ Do not use it when:
 A single Bash call starting with the literal `okstra` token (not wrapped in `if`/`eval`/`$(...)`/`VAR=`/`||`/`&&`/`npx` fallback):
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-`ok:false` → point to `/okstra-setup` and stop. If `ok:true`, carry `projectRoot` as a literal string and proceed.
+On `Okstra preflight: ready`, carry `Project root` as a literal string. On
+`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
 
 ## scope resolution
 
@@ -51,26 +52,26 @@ okstra preflight --runtime claude-code --json
 ## CLI call
 
 ```bash
-okstra rollup --task-group <group> --project-root <projectRoot> --json
+okstra rollup --task-group <group> --project-root <projectRoot> --text
 ```
 
-For the whole project, drop `--task-group`. The output is always JSON, and **all times are raw milliseconds**.
+For the whole project, drop `--task-group`. The output is fixed, ordered label/value rows, and **all times are raw milliseconds**.
 
 ## Interpreting the output
 
-Top level:
+Fixed fields:
 
-- `taskGroup` — the scope (`null` = whole project), `taskCount` — number of tasks.
-- `tasks[]` — per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`.
-  - `nextRecommendedPhase` is an object `{phase, status, rationale}`, not a string. Print `phase`, or `--` when it is empty. Never interpolate the object itself.
-- `totals` — `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus` / `byWorkCategory` / `byCurrentPhase` / `byTaskType` (each a `{value: count}` map).
+- `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):
 
-- `runCount` is the **total number of runs** in the timeline. `cpuSumMs`/`wallClockMs` reflect only runs that reached Phase 7 usage, so they can be `0` even when `runCount > 0`.
-- `cpuSumMs` is the **CPU sum** of the overlapping lead + workers, not wall-clock. Label it "CPU", and show wall-clock as `wallClockMs` only when the user explicitly asks.
-- `reportPath` is project-relative and may be empty (a task with no report yet).
-- If `taskCount` is `0`, say there are no okstra tasks in that scope and stop.
+- `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
 

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

@@ -37,10 +37,14 @@ Do not use it when:
 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> --json
+okstra preflight --runtime <host-runtime>
 ```
 
-If there is no runtime or project setup (`ok:false`), point the user to `/okstra-setup` and stop. Do not create an `export PYTHONPATH`.
+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
 
@@ -187,7 +191,7 @@ This picker is authored by the skill, so it is separate from the wizard-option-a
 
 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 --json` printed in the error message verbatim.
+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.

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

@@ -35,16 +35,16 @@ Do not use it for single-task status analysis or phase execution. Use `okstra-in
 Run one literal-token preflight call:
 
 ```bash
-okstra preflight --runtime claude-code --json
+okstra preflight --runtime claude-code
 ```
 
-On `ok: false`, point the user to `/okstra-setup` and stop. Otherwise:
-
-1. Read `.okstra/discovery/task-catalog.json`.
-2. Resolve an explicit task-group from the invocation or host request. If none is unambiguous, ask the user to choose; never guess.
-3. Lowercase the token and strip characters outside `[a-z0-9]`.
-4. Apply the same transform to each catalog `taskGroupPathSegment` and compare only those normalized values.
-5. Read each matched `task-manifest.json`; it is authoritative when the catalog is stale.
+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.
 
@@ -63,21 +63,18 @@ Do not render `workStatus` as the detailed task status. The per-task `Status` va
 For every candidate task, call:
 
 ```bash
-okstra stage-map <task-key> --json
+okstra stage-map <task-key> --text
 ```
 
-The successful response has this boundary shape:
-
-```text
-{ ok, taskKey, taskRoot, state, sourcePlanPath,
-  stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }
-```
+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:
 
-- `state: ready`: use exactly `sourcePlanPath`; do not pick a report by mtime or `latestReportRecordPath`. Select only `stages − doneStages`.
-- `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.
-- `ok: false` or another state: stop before drafting and report the structured `stage` and `reason`. A corrupt or conflicting source must never fall back to a guessed report.
+- `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.
 

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

@@ -49,7 +49,7 @@ After `okstra install`, every subsequent command must begin with the literal `ok
 Allowed forms:
 
 ```bash
-okstra check-project --json
+okstra preflight
 okstra setup --yes --project-root /abs/project --project-id my-project
 okstra doctor --runtime claude-code
 ```
@@ -62,22 +62,22 @@ Forms to avoid:
 - `$(...)` 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 a path, run `okstra paths --json` as a separate call and read the JSON value.
+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 check-project --json
+okstra preflight
 ```
 
 Handle the result:
 
-- `ok: true`: already a registered project. Show `projectRoot`, `projectJsonPath`, `projectId` to the user and confirm whether to keep it.
-- `ok: false`, `stage: "resolve"`: get an absolute project root from the user and re-run `okstra check-project --cwd /abs/path --json`.
-- `ok: false`, `stage: "project_json_missing"`: proceed with the normal create path.
-- any other failure stage: show the JSON `reason` verbatim and follow the recovery the source names.
+- `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
 

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

@@ -11,14 +11,15 @@ digest (`okstra-rollup`).
 Run preflight, resolve a positive day count (default 30), then call exactly once:
 
 ```bash
-okstra usage-report --days 30 --project-root <projectRoot> --json
+okstra usage-report --days 30 --project-root <projectRoot> --text
 ```
 
 ## Render contract
 
-Render returned task-type rows and totals without recomputing them. Show Runs,
-Coverage, Raw tokens, Billable, Cost, CPU, and Wall. Surface unavailable reason
-counts and unmatched model names. Missing usage is excluded data, not zero usage.
+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
 

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

@@ -3,51 +3,69 @@
 ## Sources
 
 - Skill source: [`skills/okstra-user-response/SKILL.md`](../../../skills/okstra-user-response/SKILL.md)
-- Response core (CLI): [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
-- Node wrapper: [`src/commands/inspect/user-response.mjs`](../../../src/commands/inspect/user-response.mjs)
+- Response core: [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
+- Node wrapper: [`src/commands/inspect/user-response.mts`](../../../src/commands/inspect/user-response.mts)
 
 ## Purpose
 
-`okstra-user-response` answers the **unresolved clarification questions** an okstra run left behind (the open `C-*` rows under the final report's `## 1. Clarification Items`) **in-session**, and records those answers as a `runs/<type>/user-responses/` sidecar. The next `/okstra-run` auto-attaches this sidecar via `--clarification-response`.
+`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.
 
-**Core principle — the skill never picks an answer for the user.** It builds the option board — background, a self-contained question, the report's options with their impact, `Enter directly` — and the user alone picks from it; every `value` is what the user chose or typed. It does not call `write` until the user has explicitly confirmed (`confirmed`).
+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.
 
-**Second principle — one question at a time.** Never batch two clarification items into one question, and never dump the whole open list at the user.
+| 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, 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. |
 
-Distinguish it from starting a run (`okstra-run`), inspecting a finished task (`okstra-inspect`), and generating a brief (`okstra-brief-gen`).
+The legacy `list` and `show` JSON commands remain for automation compatibility. They are not model-facing reads.
 
-## Sub-commands
+## Flow
 
-| Sub-command | What it does |
-|---|---|
-| `list` | List tasks that still have approval-open clarification (newest report first) |
-| `show` | Expand one report's open `C-*` rows (statement + options + contextRefs) |
-| `write` | Record the collected answers (+ optional approval) as a `user-responses/` sidecar |
+1. Run `okstra preflight --runtime claude-code`. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry `Project root` and `Project ID`, then run `okstra paths --field home`.
+2. Select a task from `list-view`.
+3. Read only `show-view --report <reportPath> --project-root <projectRoot>` for report facts.
+4. Ask one open clarification at a time.
+5. Echo the complete response and require an explicit `confirmed` before opening a transaction.
+6. Begin the transaction, add answers and decisions, then finalize it.
 
-## Preflight
+Each `options[]` row displays `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. Contract 3.0 additionally displays `reach`, `scopeEffects`, and row-level `approvalContext`. Show `scopeImpact`, `addedWork`, and `directionChange` in that order. If the view says `not stated in the report`, repeat that text and never infer a value.
 
-A single Bash call with the literal `okstra` token (not wrapped):
+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 preflight --runtime claude-code --json
+okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
 ```
 
-`ok:true` → carry `projectRoot` and `projectId` as literals. `ok:false` → point to `/okstra-setup` and stop (retry a specific directory with `--cwd <dir>` — a leading `cd` breaks the permission match). Then resolve home once: `okstra paths --field home` → paste it literally into `--home`.
+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:
 
-## Flow
+```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>
+```
 
-1. **list**: `okstra user-response list --home <home> --project <projectId> --limit 3` → an array of `{taskKey, taskType, seq, reportPath, reportMtime, openBlockerCount, openApprovalCount, unreadable}` (`openBlockerCount` = open rows with `Blocks` in `{approval, next-phase}`; `openApprovalCount` = the `approval`-only subset). If the array is empty, stop with "no open clarification". A 3-option picker (top recommendations + the final option always "Enter directly" for pasting a `reportPath`/`task-key` directly). `unreadable:true` is a §1 format drift — flag it with `⚠` and do not proceed (do not fabricate rows).
-2. **show (data fetch, not a presentation step)**: `okstra user-response show --report <reportPath>` → `rows[]` of `{id, kind, blocks, status, statement, expectedForm, options, contextRefs, resolvedRefs}`. Each `options[]` entry is `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`; `resolvedRefs` carries the `definition` of record coordinates such as `RB-002`. A leftover `§4.7` stays unresolved. Activity-contract v1 approval options carry the gate action in `disposition`. A legacy schema-v1 report has nowhere to record impact or a gate action, so those fields arrive empty. Do not print `rows` at the user and **do not paste the raw `statement` as the question** — announce only `<N> open items — I'll go through them one at a time.`
-3. **ask, one item at a time**: iterate the rows in report order, **one item per `AskUserQuestion` call**, headed `[n/N] C-014 — blocks: approval gate`. Per item:
-   - **Background first**, in the message text above the picker, 3–6 lines: (a) *Situation* — what the run was doing when it stopped here; (b) *What is undecided* — the fork, internal tokens expanded inline from `resolvedRefs[].definition`, plus what is stuck (`approval` → the approval gate stays shut and `implementation` cannot start; `next-phase` → the next phase cannot begin); (c) *What changes with your answer*. Source it from `resolvedRefs[].definition`, else **Read** the report record (`.data.json`) for the cited row id; **never invent it** — say the report is silent instead. Do not chase a `§` number on the full reading copy. Close with `Source: C-014 — "<raw statement>"`.
-   - **Picker: the row's `options[]` plus `Enter directly`** — slots follow array order, the `role: recommended` entry first with its label suffixed `(Recommended)`, `Enter directly` always last. Each `label` is the option's `answer`; each `description` is `<rationale> — Scope: <scopeImpact> · Added work: <addedWork> · Direction: <directionChange>`, in that fixed order. Never fold the three axes into one phrase. An empty axis is written `not stated in the report` — never inferred. More than three entries: keep the recommended one plus the two alternatives whose `scopeImpact` differs most, and say how many were left out. Never mark anything but `recommended` as recommended.
-   - **Transcribe**: an `options[]` pick → `value` = that option's `answer` text and `disposition` = that option's `disposition` (`answer` only when absent on a legacy option); `Enter directly` → the user's utterance verbatim, `disposition:"answer"`; free text asking for a re-ask → `disposition:"reframe"` (does not satisfy the approval gate). A question back from the user records nothing — **Read** the ref, explain, re-ask the same item with the same options. Echo `[n/N] C-014 → answer: …` and move on. Each item's JSON: `{id, kind, value, rationale?, disposition}`.
-4. **echo → confirmed gate**: before `write`, echo the whole collection (each `id`·`disposition`·`value`·`rationale`·approval) as-is and get explicit confirmation. Never `write` before `confirmed`. On any change, re-echo and re-confirm.
-5. **plan decision (optional)**: only when the user stated one outright. Approval also needs the approval-blocking items **all filled with an answer**: `--plan-decision '{"status":"approved","implementationOption":"<selected option>"}'`. If any item is unfilled/reframe, do not approve and say the gate is still open. A turn-down takes the same flag with a mandatory reason: `--plan-decision '{"status":"rejected","reason":"<the user's own words>"}'` (`revision-requested` when the same plan should be reworked).
-6. **write**: `okstra user-response write --report <reportPath> --answers '<json>' [--plan-decision '<json>'] --task-key <taskKey>` → report the returned `{sidecar:<path>}`. (When a same-named sidecar exists, the same `id` is overwritten with the new value and merged.)
-
-## Output Rules
-
-- Concise, in the language the user is using.
-- Give path guidance host-relative (`~/.okstra/...` or relative to `projectRoot`). Use repo paths only when pointing at a code source.
-- **Never hand-edit a rendered report** (`runs/*/reports/*.md` / `*.data.json`). Sidecar recording goes only through the `okstra user-response write` CLI.
+Do not decode the transaction id. Do not inspect transaction state. Do not hand-edit report records, rendered reports, or sidecars.