okstra 0.201.3 → 0.204.0

package/docs/for-ai/skills/okstra-code-review.md

@@ -1,57 +0,0 @@
-# okstra-code-review AI Manual
-
-## Sources
-
-- Skill source: [`skills/okstra-code-review/SKILL.md`](../../../skills/okstra-code-review/SKILL.md)
-- Census rules: [`skills/okstra-code-review/references/census-rules.md`](../../../skills/okstra-code-review/references/census-rules.md)
-- Review calibration: [`skills/okstra-code-review/references/review-calibration.md`](../../../skills/okstra-code-review/references/review-calibration.md)
-- Target core (CLI): [`scripts/okstra_ctl/code_review_target.py`](../../../scripts/okstra_ctl/code_review_target.py)
-- Review path core: [`scripts/okstra_ctl/code_review_paths.py`](../../../scripts/okstra_ctl/code_review_paths.py)
-- Rules the review applies: [`prompts/coding-preflight/`](../../../prompts/coding-preflight/)
-
-## Purpose
-
-`okstra-code-review` reviews what a diff changed — one okstra `implementation` stage, or any branch unrelated to an okstra run — against this project's coding-preflight rules, and leaves the result as a file under the project.
-
-**Core principle — the census is law.** The orchestrator turns the diff into an explicit worklist of cells **once, deterministically**, before any reviewer is dispatched. Reviewers receive their slice as input and never rebuild, reinterpret, or extend it. Each returns a verdict for **every** cell it was given (`clean` or findings), so a skipped cell is visible rather than silently absent, and the coverage audit re-dispatches every cell that came back without one.
-
-**Second principle — the rules are not in the skill.** They live in `prompts/coding-preflight/` (`overview.md` router + `clean-code.md` + the routed `languages/` / `frameworks/` / `architectures/` resources). Briefs point at absolute pack paths; they never restate a rule.
-
-Distinguish it from writing a PR body (`okstra-pr-gen`), starting a run (`okstra-run`), and inspecting a finished task (`okstra-inspect`).
-
-## Modes
-
-| Mode | Trigger | Diff range | Result file |
-|---|---|---|---|
-| stage | a task token (`DEV-9184`, or a full `project-id:task-group:task-id` key) | the stage's registry `base_ref` → the stage branch head | `.okstra/tasks/<task-group>/<task-id>/code-reviews/stage-<NN>.md` (re-review: `-r2`, `-r3`, …) |
-| branch | a branch name | `--base` when given, otherwise the CLI's estimate against the default branch | `.project-docs/code-reviews/<branch>/<YYYY-MM-DD>-<NN>.md` |
-
-The branch-mode result path is the one deliberate exception to the `.okstra/`-only artifact rule: a branch review belongs to no task bundle.
-
-## Preflight
-
-A single Bash call with the literal `okstra` token (not wrapped in `if` / `eval` / `export` / `$(...)` / `VAR=` / `||` / `&&` / `npx`):
-
-```bash
-okstra preflight --runtime claude-code
-```
-
-`Okstra preflight: ready` → carry `Project root` as a literal. `Okstra preflight: failed` → retry the intended directory with `--cwd <dir>`; if that also fails, show `Reason` and `Recovery`, then stop. `unknown command: preflight` or `unknown command: code-review` means the `okstra` binary predates the skill — `npm i -g okstra@latest`, then stop.
-
-## Flow
-
-1. **Resolve the target.** A full `project-id:task-group:task-id` token is already the key. For a bare token, run `okstra model-io task-selection-input --project-root <projectRoot> --task-ref <token>` and use the fixed `Match count`, `Task`, and `Updated at` rows. Then run `okstra stage-map <taskKey> --project <projectRoot> --text` and pick from the fixed `Stages` and `Done stages` rows with a 3-option picker (recommendations first, `Enter directly` last). Branch mode picks the branch the same way; a detached HEAD is refused.
-2. **Call the target CLI**: `okstra code-review target --task-key <k> --stage <N> --project-root <dir> --text`, or `okstra code-review target --branch <name> [--base <ref>] --project-root <dir> --text`. Carry the returned `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, and `Round` values; stage mode also carries `Task key`, `Task root`, and `Stage`. Then run `okstra model-io code-review-input --project-root <projectRoot> --base <baseCommit> --head <headCommit>` and pass only that fixed Markdown view to model prompts. **Never derive the base** — the CLI owns it, and `Base commit` may be a ref rather than a commit id, so pass it through verbatim. Run git in `Worktree path` when non-empty, otherwise in `Project root` against `Branch`.
-3. **Show the base and confirm it** with a 3-option picker before censusing anything — the returned `baseCommit` plus `git log -1 --oneline <baseCommit>` first, `Enter directly` last. Only an override calls the target CLI a second time, with `--base <ref>`.
-4. **Census the diff** per `census-rules.md`: four axes (`structural`, `semantic`, `state-and-tests`, `general`), one cell per target per axis — the axis **is** the rule group, never one cell per individual rule. Membership is mechanical; judgment only ever decides a verdict. Route the coding-preflight packs exactly once here (`okstra paths --field home` → `<okstraHome>/prompts/coding-preflight/overview.md`), and fix the calibration path the briefs carry (`~/.claude/skills/okstra-code-review/references/review-calibration.md`). Print every cell table, every exclusion with its reason, the applied packs, and both completion criteria. Never truncate a large census — report the cell count and confirm.
-5. **Materialize and dispatch four reviewers in parallel.** Each reviewer is a separate standalone invocation under `.okstra/agent-invocations/code-review/`. Write `<invocation-id>.instructions.md`, run `okstra agent-prompt materialize --purpose code-review --audience code-reviewer ...`, and verify the returned `metadataPath` before dispatch. A native host call receives the verified prompt body and `hostModelValue`; a deterministic provider process receives the prompt path and `modelExecutionValue` through `okstra worker-dispatch`. Each brief carries the diff, the work directory, its own axis's cell list verbatim, its packs' absolute paths, and the absolute calibration path.
-6. **Complete and audit the results.** Capture each raw return under the purpose directory's `.tmp/`, then run `agent-prompt materialize-result`, `complete`, and `verify-completion` in order. Parse only the verified `returnedBody`. Diff those cells against the assigned slice; re-dispatch one gap-fill invocation per axis for missing cells, using a new invocation ID and the same full materialize/verify/result/completion boundary. A missing or unverified verdict is unfinished work, never an implicit `clean`.
-7. **Merge and write.** Dedupe across axes, never re-grade a severity, and write the report to `reviewPath` with `Write` (frontmatter `mode` / `taskKey` / `branch` / `stage` / `round` / `baseCommit` / `headCommit` / `packs` / `generatedAt`; body `## Coverage`, `## Must-fix`, `## Should-fix`, `## Nits`, `## Score`). An empty diff dispatches no reviewer and still writes the report — Coverage reading zero cells and a Score table totalling 0.
-
-## Output Rules
-
-- The file is the deliverable. In session, print only `reviewPath`, the count per severity, and the score total — do not replay the findings in chat.
-- The report's prose is Korean; paths, identifiers, rule names, and quoted code stay verbatim.
-- Every finding cites a line **this diff changed**, and carries a concrete fix (a pseudocode sketch for readability, an alternative name for naming, a destination for structural).
-- Read-only against the repository: `okstra code-review target` creates no directory and no file, and the review never reconciles git history. A rewritten base is reported, not force-fixed.
-- Branch mode keeps the final review at `.project-docs/code-reviews/<branch>/`, but its invocation prompts, result envelopes, and completion markers remain under `.okstra/agent-invocations/code-review/`.

package/docs/for-ai/skills/okstra-container-build.md

@@ -1,129 +0,0 @@
-# okstra-container-build AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-container-build/SKILL.md`](../../../skills/okstra-container-build/SKILL.md)
-- container CLI: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
-- container runtime: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
-- stage integration gate: [`scripts/okstra_ctl/stage_targets.py`](../../../scripts/okstra_ctl/stage_targets.py)
-
-## Purpose
-
-`okstra-container-build` manages a user-test container group using the `docker-compose.yml` in an implementation task worktree. okstra labels the compose group with the task/run trace so later sub-commands can find it.
-
-## sub-command
-
-| Sub-command | Role | side effect |
-|---|---|---|
-| `up` | Integrate the implementation stages into the task worktree, then `docker compose up -d`, poll healthchecks | create/start containers |
-| `status` | Check running containers (by label query) | read |
-| `down` | Remove the container group by label query | stop/remove containers |
-
-## Preflight
-
-Single call:
-
-```bash
-okstra preflight --runtime claude-code
-```
-
-On `Okstra preflight: ready`, carry the fixed `Project root` line. On
-`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. A Docker
-daemon is required. On a Docker connection error, tell the user to start Docker
-Desktop/daemon; do not start Docker yourself.
-
-## task-key resolution
-
-Most sub-commands need a full task-key.
-
-1. If a full task-key is given, use it as-is.
-2. For a bare task-id, use the resolver:
-
-```bash
-okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>
-```
-
-3. On multiple matches, show the candidates and let the user pick.
-4. Only `down --all` can run without a task-key.
-
-## intent routing
-
-Clear verbs:
-
-- "bring up/deploy", "up": `up`
-- "status": `status`
-- "tear down", "down": `down`
-
-If ambiguous, show the full facet list and offer an Enter directly option. When multiple facets are in one message, run Step 0 once and execute the sub-commands sequentially.
-
-## up
-
-Run:
-
-```bash
-okstra container up --project-root <projectRoot> --task-key <task-key> --text
-```
-
-Preconditions:
-
-- The task must have an implementation worktree registered in the registry.
-- The worktree root must contain a `docker-compose.yml`.
-- Every stage of the approved plan must be `done`. Do not deploy a partial-stage state as if it were a complete task.
-
-Handling failure messages:
-
-- Message that the task worktree is not in the registry: tell the user to run the implementation phase first.
-- No compose file: show the CLI message verbatim.
-- `final-verification(whole-task): stage N not done`: tell the user to finish that stage via implementation.
-- healthcheck failure: relay the failing service and the `docker compose ... logs` line the CLI provides, verbatim.
-
-On success, read the fixed `Service` rows, then run the `status --text` command below and read its numbered container `ports` fields. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
-
-## status
-
-Run:
-
-```bash
-okstra container status --project-root <projectRoot> --task-key <task-key> --text
-```
-
-Fixed fields:
-
-- `projectName`: compose project name
-- `containers`: running containers found by run-trace label
-
-The label query is authoritative for whether it is alive. If `containers` is empty, say the group is not running and offer `up`. To follow a service's live logs, get `Project name` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
-
-## down
-
-Single task:
-
-```bash
-okstra container down --project-root <projectRoot> --task-key <task-key> --text
-```
-
-Whole project:
-
-```bash
-okstra container down --project-root <projectRoot> --all --text
-```
-
-A single-task down is fine to run after resolving the task-key. `--all` takes down every okstra container group in the project, so confirm with the user before running it.
-
-Report the fixed `Downed` rows. Show each torn-down project name.
-
-## Output rules
-
-- The fixed text fields are the source of truth.
-- Do not second-guess it with raw `docker` commands. The only exception is when the CLI failed and the user asked for a manual fallback.
-- Show the resolved task-key in the heading or on the first line.
-- Show CLI failure messages verbatim, including the remediation line.
-- Show container/service state as the fixed values, without normalizing.
-
-## Forbidden patterns
-
-- Trying to start the Docker daemon yourself.
-- Guessing the cause of an `up` failure and editing the compose file.
-- Dressing up a partial-stage task as deployable.
-- Running `down --all` without user confirmation.
-- Overriding the CLI result arbitrarily with a raw docker query.

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,69 +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>]
-```
-
-## 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
-- `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` and `child-launch-prepared`
-- `child-context/<safe-project>-<safe-task>.md`: the child lead context `task run` produced
-
-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 `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

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