okstra 0.202.0 → 0.205.0

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

@@ -1,262 +0,0 @@
-# okstra-inspect AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
-- Facet bodies: `skills/okstra-inspect/facets/<sub-command>.md` — the skill is a thin core (preflight + dispatch + shared rules); each sub-command's full procedure is a lazily loaded facet file, guarded by `tests/contract/test_okstra_inspect_facets.py`
-- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- context-cost CLI: `scripts/okstra_ctl/context_cost.py`
-- time-report CLI: `scripts/okstra_ctl/time_report.py`
-- log-report CLI: `scripts/okstra_ctl/log_report.py`
-- error-report CLI: `scripts/okstra_ctl/error_report.py`
-- container is a separate skill: [`okstra-container-build.md`](okstra-container-build.md)
-
-## Purpose
-
-`okstra-inspect` is the single entry point for okstra read-side work. Most of it is read-only, with two exceptions.
-
-- `status.4`: writes the user-requested `workStatus` into `task-manifest.json`.
-- `errors`, `error-zip`, `recap record`: produce report/zip/log artifacts from the information read.
-
-No sub-command writes outside this machine.
-
-## sub-command list
-
-| Sub-command | Role | Writes? |
-|---|---|---|
-| `status` | check task/phase/workflow status, change workStatus | manifest edit in `status.4` |
-| `history` | list past runs, assemble rerun/resume command | read by default |
-| `report` | resolve final-report path and optionally read | read |
-| `time` | aggregate elapsed time per task type/worker | read |
-| `logs` | inventory wrapper `.log` sidecars and suggest cleanup commands | read |
-| `cost` | estimate task bundle context/read cost | read |
-| `errors` | aggregate task error logs into a timestamped markdown report | generates report |
-| `error-zip` | build an anonymized zip of cross-project error logs | generates zip |
-| `run-audit` | check every run's artifacts against progress invariants — catches a run that ended wrong without ever logging a failure | read |
-| `recap` | summarize a task's before/after runs, or a task-group's per-brief status and latest conclusions, and record Q&A | appends `recap-log.jsonl` (task `recap/`, group `.recap/`) |
-
-## Preflight
-
-Run once before any sub-command.
-
-```bash
-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), `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
-
-Classify the user request into one or more facets. If ambiguous, show the entire sub-command table and let the user pick by number/name. Do not hide a facet because of AskUserQuestion's option limit.
-
-If several facets appear in one message, execute them sequentially. Step 0 runs only once.
-
-## task-key resolution — shared rule
-
-Many facets accept the following target forms.
-
-1. full task-key: `<project-id>:<task-group>:<task-id>`
-2. bare task-id
-3. task root path
-
-A bare task-id uses the shared resolver.
-
-```bash
-okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>
-```
-
-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`.
-- N: show the candidate `taskKey`s and `updatedAt`, and take a disambiguation.
-
-## status
-
-### Project overview
-
-Run `okstra model-io status-input --project-root <projectRoot>`. Its fixed text task blocks are the projected source.
-
-Sort: `updatedAt` desc, then `taskKey`.
-
-Keep the table narrow.
-
-- Task Key
-- Category
-- Phase
-- workStatus
-- Next
-
-`nextRecommendedPhase` is an object `{phase, status, rationale}`. The Next cell is its `phase`, or `--` when that is empty. If `awaitingApproval`, or `nextRecommendedPhase.status` is anything but `ready`, add a marker to the Next cell and explain it. When `awaitingApproval` is true, the next human action is to approve the plan (`okstra-run` → `implementation`, or `--approve`); do not re-run `implementation-planning`. When the pointer is `blocked` after planning, send the user to `okstra-user-response` on the named `C-NNN` ids first.
-
-### Specific task
-
-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:
-
-- work category
-- current phase/state
-- last completed phase
-- next-phase pointer: `phase` (or `--`), its `status`, its `rationale`
-- awaiting approval
-- task status, latest run status
-- latest report, resume command
-- workStatus, note
-- phase states
-- safe resume checkpoint
-
-### workStatus update
-
-Write only when the user explicitly requests a status change.
-
-Allowed values:
-
-- `todo`
-- `in-progress`
-- `blocked`
-- `done`
-
-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.
-
-## history
-
-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.
-
-Run `okstra model-io history-input --project-root <projectRoot>` for project history, or add `--task-ref <task-key>` for one task.
-
-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
-
-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.
-
-## time
-
-The CLI does the time computation. The AI does not recompute duration by hand.
-
-```bash
-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.
-
-`unavailable[]` is not summed into totals; show it as a separate note.
-
-## cost
-
-For context/read cost, the CLI output is the source of truth.
-
-```bash
-okstra context-cost <task-key> --project-root <projectRoot>
-```
-
-Interpretation points:
-
-- the token estimate is a heuristic, not a billing figure.
-- if `leadPhase1.mode == "active-run-context"`, the compact lead intake is primary.
-- if `analysisWorker.mode == "analysis-packet-primary"`, the worker reads the analysis-packet first and opens the full source only when needed.
-- if `skillAssets` is large, it is a prompt-diet target.
-- if there are many legacy timestamp artifacts, propose current-view/cold-artifact separation rather than a destructive delete.
-
-## logs
-
-wrapper sidecar log inventory:
-
-```bash
-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.
-
-Deleting an active run's log loses the live trace, so recommend checking `status` first.
-
-## errors
-
-Aggregate task error logs into a markdown report.
-
-```bash
-okstra error-report <task-key> --project-root <projectRoot> --text
-```
-
-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.
-
-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> --text
-```
-
-Summary fields:
-
-- `outPath`
-- `errorCount`
-- `runCount`
-- `unreachableRuns`
-- `clusterCount`
-- `projectCount`
-
-At the end, guide the user to build a brief with the error-feedback variant of `/okstra-brief-gen`, then run `error-analysis` in the okstra repo.
-
-## recap
-
-The default is artifact mode. It builds the before/after summary and answers questions using only `.okstra/` artifacts.
-
-Read the fixed recap projection:
-
-```bash
-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.
-
-Group scope — when the user names a task-group, or the bare token resolves only via `taskGroup`:
-
-```bash
-okstra model-io recap-input --project-root <projectRoot> --task-group <task-group>
-```
-
-The projection joins the group's briefs (start order, `waits for` edges), the catalog / task-manifests (real status, progress, run count, next phase, report), and the group document's Task Memory (headline, decisions, watch-outs, follow-ups). Read `Brief count` / `Task count` / `Next in group`, then the repeated `Queue entry` and `Task` blocks. Run-count / time / error totals belong to `okstra-rollup`.
-
-record:
-
-```bash
-okstra recap record <task-key> --project-root <projectRoot> --kind <summary|qa> --mode <artifact|code> --question "<question>" --answer "<summary>" --citation "<path:line>"
-```
-
-In group scope, `--task-group <task-group>` replaces `<task-key>` and the line lands at `.okstra/tasks/<task-group>/.recap/recap-log.jsonl`. `recap note` has no group form.
-
-Enter code mode only when the user explicitly requests it, such as "including the diff" or "the code changes too". Entering recap alone does not read the code diff.
-
-## Output rules
-
-- Answer in Korean, spelling out task ids, phase names, and status values on first mention.
-- Prefer project-relative paths.
-- Show disk field values as-is without normalizing.
-- Clearly indicate an awaiting-approval state.
-- If there is no recent report, show `--`.
-- Display dates in `YYYY-MM-DD HH:MM`.
-
-## Forbidden patterns
-
-- Failing immediately because the catalog is absent. There is a manifest fallback.
-- Confusing `workStatus` with `currentStatus`.
-- Hand-computing time duration without the CLI.
-- Running a cleanup command directly.
-- Arbitrarily reinterpreting raw files instead of CLI output in `errors`/`cost`/`time`.
-- Automatically reading code changes in recap artifact mode.

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

@@ -1,86 +0,0 @@
-# okstra-manager
-
-Use this to bundle okstra tasks across multiple projects into a single manager-owned context. The authoritative contract is [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md); the CLI implementation is [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py).
-
-## When to Use
-
-- The user says something like "multiple projects", "cross-project", "okstra manager", or "group projects together".
-- Register projects under a manager, or discover candidate projects.
-- Plan child project tasks under a shared task-group/task-id and assign roles/directives.
-- Sync child project `.okstra` state into the manager snapshot, or view status.
-- Prepare a launch packet and a manager child context for running a specific child task.
-
-## Execution Rules
-
-1. Every command starts with the literal `okstra`. Do not wrap it in shell variables, `$(...)`, `&&`, `eval`, or a leading env assignment.
-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.
-6. When the actual child task id differs under the same manager task id, pass `--child-task-id <id>` to both `task assign` and `task run`.
-
-## Command Surface
-
-```bash
-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>]
-okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
-okstra manager list managers
-okstra manager list projects --manager-id <manager-id>
-okstra manager list tasks --manager-id <manager-id>
-okstra manager view --manager-id <manager-id>
-```
-
-- `list managers`: every manager in this home with its project count and manager-task count.
-- `list projects`: the manager's registered projects with root, role, tags and link time.
-- `list tasks`: the manager's tasks by task-group and task-id with objective, progress mode and child count.
-- `task split`: reads a tracker split plan (one Linear project or parent issue, each issue assigned to one or more projects with a scope), writes one brief per (issue, project) pair to `<projectRoot>/.okstra/briefs/<task-group>/<ticketId>-<file-title>.md` with a `## Project Scope` section, and registers each pair as child `<project-id>:<task-group>:<slug(ticketId)>`. Every brief passes the brief validator before any file is written; an existing brief with different content stops the run unless `--overwrite` is given. The skill's Tracker Split section defines the plan JSON and the fetch/confirm procedure.
-- `view`: writes `view/index.html` (summary tiles, project table, one panel per task with child rows, directives and events) and returns `View path` and `View URL`. It does not sync; each panel shows its last sync time and the sync command.
-
-## Storage Model
-
-Manager state is stored under `~/.okstra/managers/<manager-id>/`, split into two layers: the manager root and the task directory.
-
-Directly under the manager root:
-
-- `manager.json`: manager id / schema / createdAt
-- `projects.json`: registered projectId, projectRoot, role, tags
-
-Under the task directory `task-groups/<safe-group>/<safe-task>/`:
-
-- `manifest.json`: manager task objective, common brief, progress mode
-- `children.json`: child task plan, assignment, launch metadata; children made by `task split` also carry `ticketId`, `briefPath`, `scope` and `recommendedPhase`
-- `split-plan.json`: the last plan `task split` applied
-- `directives.jsonl`: shared/project directive rows
-- `snapshots.json`: the read-side snapshot `task sync` read from the project-local `.okstra`
-- `events.jsonl`: manager events such as `task-created`, `task-split` and `child-launch-prepared`
-- `child-context/<safe-project>-<safe-task>.md`: the child lead context `task run` produced
-- `view/index.html` (under the manager root): the overview page `view` writes; rewritten on every run
-
-A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<sha1-prefix>` path segment, but the manifest and the child `taskKey` preserve the original input value.
-
-## Child launch
-
-`task run` does not run the child work directly; it prepares a launch packet. The key fixed fields of the returned packet:
-
-- `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`: always `spawn-process` — the child lead runs as a separate host process started by the installed launcher
-- `Worker dispatch backend`: always `subagent` in v1
-- `Project root`: the child project root
-- `Context path`: the manager child context markdown
-- `Run command`: the installed launcher, `~/.okstra/bin/okstra.sh`
-- every numbered `Run arg N`: the ordered launcher arguments `--project-root … --project-id … --task-group … --task-id … --directive "Read manager child context: …"`. A child made by `task split` also gets `--task-brief <briefPath>`, and `--task-type <recommendedPhase>` while the child task does not exist yet in its project
-- `Shell command`: `Run command` plus every `Run arg N`, shell-quoted; the skill hands this line to the user to run in a new terminal
-
-The launcher fills the task type and brief from the child task manifest when it exists and asks for the rest, then prepares the run and starts the lead with the directive in its prompt. `okstra run` is not a substitute: for a lead host it adds `--launch-only`, which drops the task inputs and the directive.
-
-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

@@ -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`.