okstra 0.202.0 → 0.205.0

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

@@ -1,262 +0,0 @@
-# okstra-brief-gen AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
-- brief template: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
-- brief validator: [`validators/validate-brief.py`](../../../validators/validate-brief.py)
-- lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](../../../scripts/okstra_ctl/improvement_lenses.py)
-
-## Purpose
-
-`okstra-brief-gen` produces a task brief to feed into the okstra pipeline. A brief is a pre-discovery artifact. It is not a document that turns requirements into an implementation plan; it is a handoff document that separates the reporter's verbatim material from the AI-verified evidence/interpretation using labels, so the next phase can start without questions.
-
-Output location:
-
-```text
-<PROJECT_ROOT>/.okstra/briefs/<task-group>/<brief-id>.md
-<PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/.../<brief-id>.md
-```
-
-## Three variants
-
-| Variant | Input | Recommended next phase |
-|---|---|---|
-| Reporter input | files, tickets, URLs, conversation/free text | `requirements-discovery` or `error-analysis` |
-| Codebase scan | scan scope, priority lenses, candidate cap, context | `improvement-discovery` |
-| Error feedback | a single error cluster from the zip produced by `okstra error-zip` | `error-analysis` |
-
-## Core invariants
-
-1. Source Material is a verbatim-preservation area. Do not paraphrase, summarize, or reorder.
-2. The AI's interpretation, file links, terminology mapping, and format conversion all go under `Augmentation` or a `> augmented:` blockquote.
-3. An augmentation carries one of four labels: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
-4. `intent-inference` is paired with `intent-check:` in `Open Questions`. This relationship is checked by `validators/validate-brief.py`.
-5. A `terminology-mapping` augmentation is paired with `terminology:` in `Open Questions` (validator-checked). Exception: the Step 4.5 result markers `applied glossary:` / `skipped glossary:` need no paired row.
-6. Questions only the reporter can answer are collected in Step 6.5 and recorded verbatim under `## Reporter Confirmations`.
-7. Ticket split/link/order relations go in the structured table of `## Related Task Graph`. Do not infer work order from parent-id alone.
-8. Every okstra-owned write stays inside `<PROJECT_ROOT>/.okstra/`. External files are read only when the reporter explicitly cited them as source.
-9. Every row in `Open Questions` starts with one of five prefixes: `general:`, `terminology:`, `intent-check:`, `conversion-block:`, `adr-candidate:` (validator-enforced). `adr-candidate:` is only a signal — the decision file is written by `implementation-planning` into `<PROJECT_ROOT>/.okstra/decisions/`.
-
-## Preflight
-
-Run as a 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. This skill
-does not use an `npx` fallback.
-
-## Input collection
-
-### Reporter input
-
-More than one source type is allowed, but each source is stored as a separate block under `Source Material`.
-
-- File: read the entire file and insert it as-is.
-- Issue tracker ticket: detect Linear/Jira/GitHub/Notion and use MCP or the `gh` CLI. If no access tool is available, ask the user to paste the body or skip.
-- Link URL: fetch it. On failure / login wall / body truncation, ask the user to paste.
-- User input: if conversation context is sufficient, use conversation synthesis; if thin, take a single free-text input.
-
-If a ticket has children/sub-tasks, ask once at the parent how to handle the tree.
-
-- Full tree: generate a brief per descendant.
-- Parent only: put child keys/URLs in Related Artifacts and leave a `parent-of` edge in `Related Task Graph`.
-- Selected: recurse only into the chosen direct-child branch.
-
-During recursion, manage the visited set as `<tracker>:<ticket-id>`, and on re-run reseed from the existing brief frontmatter's `ticket-id` + `source-type`.
-When Full tree or Selected produces multiple briefs, copy the same `Related Task Graph` into every generated brief. That way, even if only one child brief is passed to a downstream phase, the split topology, predecessor/successor relations, and de-duplication signals are preserved.
-
-`Related Task Graph` table schema:
-
-| Column | Meaning |
-|---|---|
-| From | task key, brief id, tracker id, or URL |
-| Relation | `parent-of`, `child-of`, `depends-on`, `blocks`, `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to` |
-| To | task key, brief id, tracker id, or URL |
-| Direction | `directed` or `undirected` |
-| Source | tracker linked issue, task-list checkbox, reporter statement, manual split, prior okstra task |
-| Impact | meaning the downstream phase must preserve |
-
-`depends-on`, `blocks`, parent/child, follow-up, and split relations are `directed`. `duplicates` and `related-to` are `undirected`. Do not create a relation with no source.
-
-### Codebase scan
-
-Collected values:
-
-- `scan_scope`: a list of real paths inside the project.
-- `priority_lenses`: 1–4 of the `LENSES` enum.
-- `out_of_scope`: optional.
-- `candidate_cap`: 1–12, default 8.
-- context, desired outcome, constraints.
-
-Verify path existence, the lens enum subset, and the candidate-cap range before writing. Final validation is done by `validate-brief.py`, which checks `scope: codebase`, `Scan Scope`, and `Priority Lenses`.
-
-### Error feedback
-
-The input is the zip produced by `okstra error-zip --out <path>`.
-
-Processing:
-
-1. Confirm the zip contains `report.md` and `errors/anonymized.jsonl`.
-2. Pick exactly one cluster from the frequent-cluster table.
-3. Move only the chosen cluster's anonymized records into Source Material.
-4. Do not mix different errorTypes into one brief.
-5. Set the next-step guidance to `error-analysis`.
-
-## task-group and filename
-
-For task-group, show existing-group recommendations first. Call `okstra task-list --text`, read the distinct fixed `Task group` values in `Updated at` order, and offer the 2 most recent + enter-directly. If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop. If `Task count` is `0`, ask for free text. In tracker recursion, task-group must be obtained before building any child path.
-
-File path rule:
-
-```text
-depth 0: .okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
-depth 1: .okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
-depth N: .okstra/briefs/<task-group>/<sub/ repeated N>/<ticket-id>-<file-title>.md
-```
-
-The frontmatter's `depth` must equal the number of `sub/` segments in the path. The validator checks this.
-
-On collision, the default is Skip. You may offer Append suffix or Overwrite. Do not silently perform a bulk overwrite in tracker multi-generation.
-
-## Domain alignment
-
-First look at okstra's internal memory.
-
-- `<PROJECT_ROOT>/.okstra/glossary.md`
-- `<PROJECT_ROOT>/.okstra/decisions/`
-- the related task's `history/fix-cycles.jsonl`
-
-Read external domain docs only when the reporter explicitly cited them as source material. Record conflicting/ambiguous terms under `Augmentation > Domain alignment` with `terminology-mapping`, and put a `terminology:` row in `Open Questions`.
-
-When a file path or symbol is mentioned, find the actual in-repo reference with `Read`/`Grep` and record it as `evidence-link`. If it cannot be mapped, do not guess — leave a `conversion-block:` row.
-
-## Sharpening pass
-
-Do not run a full interview. Ask only about gaps that source and codebase cannot fill.
-
-Default budget:
-
-- at most 1 question per section the source skill designates as fill-in.
-- at most 2 questions for terminology/fuzzy disambiguation.
-- at most 6 questions overall.
-- codebase-scan up to 8 questions.
-
-Prefer codebase-first checks over questions. Put remaining gaps in `_(none)_` or `Open Questions`.
-
-## template writing rules
-
-The template `templates/reports/brief.template.md` is the SSOT. Follow the section order, frontmatter keys, top blockquote shape, and HTML comment guidance.
-
-Reporter input and Error feedback:
-
-- keep `## Source Material`.
-- keep `## Problem / Symptom`.
-- omit `## Scan Scope`, `## Priority Lenses`.
-
-Codebase scan:
-
-- `scope: codebase` in frontmatter.
-- omit `## Source Material`, `## Problem / Symptom`.
-- keep `## Scan Scope`, `## Priority Lenses`.
-
-Do not fabricate empty sections. When there is no value, use `_(none)_`.
-
-## frontmatter key
-
-Every brief carries the following keys. The key set is checked by `validate-brief.py`.
-
-- `type`
-- `brief-id`
-- `parent-id`
-- `ticket-id`
-- `source-type`
-- `task-group`
-- `depth`
-- `created`
-- `generator`
-- `reporter-confirmations`
-
-`brief-id` must equal the filename stem. At depth 0 the `parent-id` is `self`; a descendant's `parent-id` is its direct parent's `brief-id`.
-
-## Recommended next phase
-
-Write it into the `Recommended next phase:` of the brief body's top blockquote.
-
-- observable error, repro, stack trace, error-zip record: `error-analysis`
-- a requirement with ambiguity or large Open Questions: `requirements-discovery`
-- `scope: codebase`: `improvement-discovery`
-- if ambiguous: `requirements-discovery`
-
-Do not auto-start `okstra-run`.
-
-## Reporter Confirmations
-
-Collect the rows in `Open Questions` that only the reporter can answer.
-
-- `intent-check:`
-- `conversion-block:`
-
-If a `[CONFIRMED <date> → RC-N]` marker already exists, exclude it from pending. Ask the user whether to answer now; if they answer, record it verbatim under `## Reporter Confirmations`. Do not delete the row — attach a marker.
-
-At most 12 questions per run. If pending exceeds 12, ask only the top 12 in `conversion-block:` → `intent-check:` order, leave the rest as `partial`, then tell the user which rows remain.
-
-Status values:
-
-- `complete`: all pending reporter-only rows are answered. The validator checks that every `intent-check:`/`conversion-block:` row has a `[CONFIRMED …]` marker.
-- `partial`: only some are answered. The validator checks that at least one row has a `[CONFIRMED …]` marker (if nothing was received, `skipped`).
-- `skipped`: the user chose to defer to a downstream phase.
-- `pending`: treated as a pre-handoff state; do not proceed.
-
-## Validation
-
-After writing, run the validator before emitting the handoff message.
-
-Installed copy:
-
-```bash
-~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
-```
-
-repo checkout:
-
-```bash
-validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
-```
-
-On failure, fix the cited brief and re-run. Fall back to a manual checklist only when the validator is absent.
-When a `Related Task Graph` is present, the validator also checks the table header, relation enum, direction enum, and directed/undirected mismatch.
-
-## Completion message
-
-Single brief:
-
-```text
-brief saved: <abs-path>
-next: /okstra-run  (recommended task-type: <phase>)
-```
-
-Multi-brief:
-
-```text
-briefs saved (N):
-  - <abs>/<task-group>/<brief>.md (depth 0, parent, recommended: <phase>)
-  - <abs>/<task-group>/sub/<brief>.md (depth 1, child, recommended: <phase>)
-next: /okstra-run
-```
-
-Before the hand-off block, once per task-group (Step 7a): if `<PROJECT_ROOT>/.okstra/briefs/<task-group>/group-context.md` is absent, ask whether to create the skeleton (`okstra group-context init --project-root <PROJECT_ROOT> --task-group <task-group>`; recommended for a new group) or skip. Never fill it from the tickets. When created, add `group context skeleton: <abs>/<task-group>/group-context.md   (fill before /okstra-run)` to the block — preparation refuses the group's tasks while a `<...>` placeholder line remains. The file's trailing `## Task Memory` region is okstra's (rewritten by `report-finalize` with the group's start order and each task's latest conclusion); `init` inserts the human sections above an existing region. Brief ordinals (`<TICKET>-<n>-<slug>`) are the start order okstra reads; `Related Task Graph` edges are quoted beside it as `waits for`.
-
-## Forbidden patterns
-
-- Summarizing or tidying Source Material before inserting it.
-- Guessing tracker/URL content without tool verification.
-- Writing unlabelled augmentation.
-- Leaving `intent-inference` without `intent-check:`.
-- Writing a decision file into external docs/ADR. okstra decisions belong only in `<PROJECT_ROOT>/.okstra/decisions/`.
-- Silently overwriting an entire child tree.
-- Auto-starting `okstra-run` right after brief generation.

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

@@ -1,34 +0,0 @@
-# okstra-chat AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-chat/SKILL.md`](../../../skills/okstra-chat/SKILL.md)
-- CLI: [`src/commands/chat/chat.mts`](../../../src/commands/chat/chat.mts)
-
-## Purpose
-
-Global rooms under the okstra home so host sessions from different providers can send and read messages. Not a project `.okstra/` artifact.
-
-## CLI
-
-```bash
-okstra chat rooms
-okstra chat create --room <name>
-okstra chat join --room <name> --name <display>
-okstra chat members --room <name>
-okstra chat send --room <name> --as <display> (--to <all|name> | --reply-to <id>) (--body <text> | --body-file <path>)
-okstra chat unread --room <name> --as <display>
-okstra chat inbox --room <name> --as <display>
-okstra chat log --room <name> --as <display>
-okstra chat ack --room <name> --as <display> --through <id>
-```
-
-Display names are typed. The CLI does not generate them.
-
-Unread is the inbox after the read cursor minus messages whose `from` equals `--as`. It does not move the cursor. `inbox` and `log` keep those messages. Rows are `id @from YYYY-MM-DD HH:MM body`. A reply inserts `↑parentId` after the time. Recipient is not on the line. A body with several lines continues on rows indented by two spaces; those rows carry no id.
-
-`send --to` may equal `--as`. `--to` and `--reply-to` are exactly one. `--body` and `--body-file` are exactly one; either may hold several lines, and only an all-blank body is rejected. A reply inherits `to` from the parent. `members` is the full roster. `ack --through` rejects an id behind the current cursor. `.` and `..` are reserved names. A stale `.lock` (dead owner pid, or older than 5 s) is reclaimed by the next writer.
-
-The skill picker is `all` plus `members` minus the current display name. Skill send and reply use `--body`, not `--body-file`. Before joining an existing room the skill runs `members`; if the typed display name is already listed, it asks whether this session is already in the room under that name (a re-entry after context loss) and, if so, continues with `--as` without joining. After showing unread rows, the skill runs `ack --through` with the id of the last row that starts with an id, unless the output is `no unread`. The Step 3 menu is send, unread, inbox, log, reply, done. Reply takes a free-input id and body; there is no recipient picker and no `okstra chat reply` subcommand.
-
-Read the fixed text rows. Do not parse JSON.

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.