okstra 0.202.0 → 0.205.0

package/runtime/skills/okstra-brief-gen/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: okstra-brief-gen
 description: Use when the user wants to generate a task brief file for okstra from a requirements document, an existing markdown file, an issue-tracker ticket (Linear / Jira / GitHub / Notion), a link URL, conversation context, or short user input. Produces the markdown brief consumed by `okstra-run` Step 5 (task-brief). Trigger words include "okstra brief", "make a brief", "generate a brief", "make a brief from requirements", "make an okstra input", "write a task brief", "brief from this ticket", "brief from this link".
+disable-model-invocation: true
 ---
 
 # okstra-brief-gen
@@ -153,6 +154,40 @@ and retain the explicit free-text follow-up where this skill specifies one.
 
 ## Step 1: Choose input source
 
+### Capture contract (binds every sub-flow below)
+
+`Source Material` is the one section a later phase can fall back to when a
+derived section reads wrong, so it carries the source whole. Three rules hold
+for every variant and every source type below.
+
+1. **Capture in full.** Length is never a reason to excerpt, summarize, or
+   restructure. A source too long to be comfortable in the conversation is
+   still written into the brief in full. "In full" is measured against the
+   source the reporter named, not against the file that happens to contain
+   it: when they point at one section of a larger document — a backlog item,
+   one `## Cross-Repo Carry — <repo>` appendix — that section is what must
+   arrive whole, and `ref` names the containing file and the heading. Taking
+   a section the reporter did not name is the same failure as dropping half
+   of one they did.
+2. **Capture the record, not only the body.** What the record is, per source
+   type:
+
+   | Source type | Captured into `## Source Material` |
+   |---|---|
+   | `File` | the entire file, or the named section whole when the reporter pointed at one |
+   | `Issue tracker ticket` | title, description body, every comment, status, labels, assignee, and linked / child issue references — plus the remaining response metadata |
+   | `Link URL` | title and full body text, quotes and examples included |
+   | `User input` | the utterance as typed, or the conversation's key utterances quoted |
+   | `Error feedback` | the chosen cluster's anonymized error records |
+
+3. **What the tool could not deliver is recorded, never silently dropped.** A
+   truncated fetch, an attachment the API hands back as a signed link, an
+   embed the response carries as an opaque node, a body behind auth — each one
+   gets a `conversion-block:` row in `## Open Questions` naming what is
+   missing and where it lives. A bracketed note inside the captured block
+   helps the reader, but it does not replace that row: the row is what a later
+   phase sees when it asks whether the source arrived complete.
+
 ### 1.0. brief variant
 
 `AskUserQuestion` (single-select):
@@ -456,7 +491,7 @@ to Source Material body, not to the filename):
 Validate the full `<ticket-id>-<file-title>` slug: must have at least one
 alphanumeric character after slugification. Apply Step 2c on collision.
 
-**Enforced:** `validators/validate-brief.py` checks the brief's filename and its task-group directory segment against the slugified frontmatter `task-group`, and rejects a Source Material section whose entry does not match the source it names.
+**Enforced:** `validators/validate-brief.py` checks the brief's filename and its task-group directory segment against the slugified frontmatter `task-group`.
 
 ### 2c. Collision handling
 
@@ -553,7 +588,7 @@ empty or trivially thin **after** reading Source Material verbatim, ask **at
 most one** `AskUserQuestion` to fill it. Never ask about sections already
 covered by the source material.
 
-**Enforced:** `validators/validate-brief.py` fails a brief whose required section is missing, is left as a template placeholder (`is_placeholder`), or carries only the template's own example lines (`is_template_example`) — so a section skipped here does not pass as filled.
+**Enforced:** `validators/validate-brief.py` fails a brief whose required section is missing, has a blank body (`check_variant_required_sections`), or still carries the template's `<...>` text (`check_template_scaffold`). `## Source Material` is exempt from the template-text check because it holds the reporter's words verbatim.
 
 ### Sharpening pass (bounded grill)
 
@@ -854,11 +889,56 @@ The required-key set (`type`, `brief-id`, `parent-id`, `ticket-id`,
 Step 6.6. The byte-for-byte field shape remains the job of
 `~/.okstra/templates/reports/brief.template.md`.
 
+### Source requirement sweep (run before asking for approval)
+
+Source Material holds the reporter's words, but every later phase reads the
+derived sections. A requirement that is captured and then never carried into a
+derived section is invisible from that point on, and no downstream phase can
+recover it — it has no id to map and no heading to cite. Close that gap here,
+while the source is still in front of you.
+
+Read `## Source Material` from its first line to its last and list every
+**requirement unit** it holds:
+
+- an imperative or a request ("switch to S3", "il faudrait les extraire")
+- a checklist row, whatever its box state
+- a condition or a threshold ("only under 50 MB", "daily, not continuous")
+- a prohibition ("never overwrite a non-empty value")
+- a decision the reporter states as still open ("to be decided: who is alerted")
+- a number the reporter gives as a target or a bound
+
+Give every unit exactly one destination, and write it there before you ask for
+approval:
+
+| Unit | Destination |
+|---|---|
+| Runtime behaviour an okstra phase can reach by changing repository files | `## Expected Behavior` |
+| Behaviour that must survive the change unchanged | `## Preserved Behavior` |
+| Artifact state the finished work must leave behind | `## Expected Outcome` |
+| A must-pass point a person or live infrastructure owns | `## External Gates` |
+| A limit, a deadline, or an untouchable area | `## Constraints` |
+| A decision the reporter left open | `## Open Questions` |
+| Deliberately not part of this task | `## Constraints`, as `out of scope: <unit> — <why>` |
+
+No unit may end the sweep without a destination. `out of scope:` is the only
+way to drop one, and it costs a line that names the reason — an omission
+nobody wrote down cannot be told apart from an oversight when the run later
+misses it. A unit whose destination is genuinely unclear is an
+`## Open Questions` `general:` row, not a silent drop.
+
+The sweep reads the source; it does not interview the user. It runs after
+Step 4's question budget is spent and adds no questions of its own — a gap it
+surfaces is filled from Source Material, or parked in `## Open Questions`.
+
 Echo the file path back on one line. Show the rendered brief to the user
-inline and ask:
+inline, and directly above the approval question show the sweep as a table —
+one row per requirement unit, its destination section, and for an end-state
+unit the `EB-` / `PB-` / `EO-` id it became. That table is what lets the
+reporter check their own list in one pass. Then ask:
 
 `AskUserQuestion`: `"Proceed with this brief?"` — options `Save` / `Edit`.
-On `Edit`, return to Step 4 for the section to revise.
+On `Edit`, return to Step 4 for the section to revise; a unit the user reports
+missing returns to this sweep instead.
 
 ## Step 6: Recommend next okstra phase
 

package/runtime/skills/okstra-chat/SKILL.md

@@ -8,7 +8,7 @@ description: Use when the user wants to create or join a global okstra chat room
 Cross-session rooms in the global okstra home. Not a project task artifact.
 Do not write JSON. Call `okstra chat` and read its fixed text.
 
-Rooms are independent of tasks and runs. A participant is this host session.
+Rooms are independent of tasks and runs. A participant is a display name that this host session joins with; the CLI does not tie the name to a session, so every command acts as whichever member `--as` names.
 The display name is typed at join. Do not invent a default name.
 
 ## When to use
@@ -114,5 +114,5 @@ The whole room, including messages not addressed to you. Log does not move the c
 
 - Call only `okstra chat`. Do not open files under the chat store.
 - Do not treat chat rows as evidence for a finding, verdict, or assignment.
-- Workers may run the same commands with `--name` and `--as`. Joining is optional.
+- Workers may run the same commands: `join` with `--name`, then the rest with `--as`. Taking part is optional, but `send`, `unread`, `inbox`, `log`, and `ack` fail with `not a member` until that name has joined.
 - Do not generate a display name from the provider, model, or execution label.

package/runtime/skills/okstra-code-review/SKILL.md

@@ -109,7 +109,7 @@ pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
 2. Collect the diff from the work directory chosen in Step 1 — `git -C <workdir> diff --name-status <baseCommit>..<headCommit>` for the file list, and `git -C <workdir> diff <baseCommit>..<headCommit>` for the hunks. Before trusting that range, run `git -C <workdir> rev-list --count <headCommit>..<baseCommit>`: anything but `0` is the rewritten-history case in the Exceptions table. An empty diff skips Steps 3–3.5 (also in Exceptions).
 3. **Route the packs once, here — and fix both absolute paths the briefs carry.** `okstra paths --field home` prints the okstra home; read `<okstraHome>/prompts/coding-preflight/overview.md` and walk all three stages of its routed resource selection over the changed-file list. The result is the applied pack list — the absolute paths reviewers will read. This routing happens exactly once per run; no reviewer repeats it.
 
-   The second path is this skill's own calibration file. A subagent has no "next to this file" coordinate, so the brief must spell it out: the installed skill home is `~/.claude/skills/okstra-code-review/`, making the literal path `~/.claude/skills/okstra-code-review/references/review-calibration.md` — the same string whether the skill was copied in or dev-linked. Carry it, together with the pack list, into every Step 3 brief.
+   The second path is this skill's own calibration file. A subagent has no "next to this file" coordinate, so the brief must spell it out: `okstra install` writes this skill to `~/.agents/skills/okstra-code-review/` on every machine (and to `~/.claude/skills/` only when `~/.claude` exists), making the literal path `~/.agents/skills/okstra-code-review/references/review-calibration.md` — the same string whether the skill was copied in or dev-linked. Carry it, together with the pack list, into every Step 3 brief.
 4. Build the cells per `references/census-rules.md` and print, in this response: one cell table per axis, the exclusion list with a reason on every entry, and the applied pack list.
 5. Restate both completion criteria and show they hold: censused files + exclusions = files in the diff, and every hunk maps to a censused function or to file-level code.
 
@@ -119,23 +119,37 @@ A large census is never truncated. Report the cell count and confirm before disp
 
 ## Step 3 — Materialize and dispatch four reviewers in parallel
 
-Every reviewer and later gap-fill is a separate auditable standalone invocation. Before dispatch, create
+Ask the runtime what this operation runs — do not choose the role, the providers, or the reviewer count
+here:
+
+```
+okstra agent-prompt resolve-operation --operation code-review
+```
+
+It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
+provider and model. The contract owns those values (`agents/operations/code-review.json`), so a machine
+with too few distinct models fails here rather than quietly running fewer reviewers. Dispatch exactly the
+slots it prints.
+
+Every reviewer and later gap-fill is a separate auditable standalone invocation. For each slot, create
 `.okstra/agent-invocations/code-review/<invocation-id>.instructions.md` from that reviewer's brief, then run
-`okstra agent-prompt materialize` with `--purpose code-review`, `--audience code-reviewer`, and the canonical
-`.prompt.md` path beside it. Pass the current host runtime, selected provider, and `--model-role analyser`;
-the returned assignment is authoritative. Run `okstra agent-prompt verify` against the returned
-`metadataPath` before invoking any model.
+`okstra agent-prompt materialize` with `--purpose code-review`, `--audience <dutyId>`, that slot's
+`--provider` and `--model <modelRef>`, and the canonical `.prompt.md` path beside it; the returned
+assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
+invoking any model.
 
 For a native host call, pass the verified prompt body and `hostModelValue`. For a deterministic provider
-process, run `okstra worker-dispatch` with the verified prompt path and `modelExecutionValue`; never
-substitute one model value for the other. Dispatch the four verified calls in parallel when the host supports
+process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path>`
+with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
+standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
+`.log`. Never substitute one model value for the other. Dispatch the four verified calls in parallel when the host supports
 it. Every brief carries:
 
 - the diff, plus the work directory path so the reviewer can read whole files for context
 - the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
 - **its own axis's cell list**, verbatim from the census
 - the absolute paths of the packs its axis reads (from step 2's routing)
-- the calibration path, written out in full as Step 2 fixed it — `~/.claude/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
+- the calibration path, written out in full as Step 2 fixed it — `~/.agents/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
 
 Each axis is **one rule group**, so a cell is `target × <axis>` — never `target × <individual rule>`. The reviewer names the specific rule it found violated inside the verdict's `rule` field, and one cell may carry findings from several rules of its group.
 

package/runtime/skills/okstra-container-build/SKILL.md

@@ -6,13 +6,13 @@ description: |
 
 # OKSTRA Container Build
 
-Single entry point for the okstra user-test container runtime. okstra provisions a docker-compose group from an `implementation` task's worktree (the `docker-compose.yml` at the worktree root), and labels it with the task's run-trace so later sub-commands can find the group. This skill drives that lifecycle. Sub-commands:
+Single entry point for the okstra user-test container runtime. okstra provisions a docker-compose group from an `implementation` task's worktree (the `docker-compose.yml` at the worktree root), and labels every service with `okstra.task-key`, `okstra.project-name`, and `okstra.run-trace`; `status` finds the group by its `okstra.project-name` label. This skill drives that lifecycle. Sub-commands:
 
 | Sub-command | What it does |
 |---|---|
 | `up` | Integrate the task's stages into the worktree, run `docker compose up -d`, and poll healthchecks. |
-| `status` | Query the running containers for a task-key (by run-trace label). |
-| `down` | Tear down the containers (label query); `--all` covers every container group in the project. |
+| `status` | List the task's containers in any state (by `okstra.project-name` label). |
+| `down` | Tear down the task's compose project by name; `--all` covers every task in the project that has a container deploy state. |
 
 ## Step 0: Preflight (shared)
 
@@ -69,8 +69,8 @@ Every sub-command needs a **task-key** (`<project-id>:<task-group>:<task-id>`)
 Brings up the task's container group: integrates the implementation stages into the task worktree, synthesizes the compose env override, runs `docker compose up -d`, and polls healthchecks.
 
 **Preconditions** (state them if unmet, do not guess):
-- The task must be an `implementation` task whose worktree is registered in `~/.okstra/worktrees/registry.json`. If `up` fails with "task worktree is not in the registry" → the task has no implementation worktree yet; tell the user to run the `implementation` phase first.
-- The worktree root must contain a `docker-compose.yml`. If `up` fails with "there is no ... at the worktree root" → no compose file shipped with this task; surface the message verbatim.
+- The task's worktree must be registered in `~/.okstra/worktrees/registry.json`, and the task must have a done `implementation-planning` run. `up` does not check the task type. If `up` refuses because the task-key's worktree is not in the registry → surface the message verbatim; the task has no worktree yet, so the user runs a phase of the task (normally `implementation`) first.
+- The worktree root must contain a `docker-compose.yml`. If `up` refuses because the worktree root has no `docker-compose.yml` → no compose file shipped with this task; surface the message verbatim.
 - Every stage declared in the approved plan's Stage Map must be `done`. `up` integrates the whole task, so a partially-finished task (e.g. only stage 1 of 3 done) is refused rather than deployed as if complete (gate in `stage_targets.py`, shared with whole-task `final-verification`). If `up` fails with `final-verification(whole-task): stage N not done — run implementation --stage N first`, surface that message verbatim and tell the user to finish the named stage via the `implementation` phase with `--stage N`.
 
 Run:
@@ -81,13 +81,13 @@ okstra container up --project-root <projectRoot> --task-key <task-key> --text
 
 Read the fixed output fields and report the provisioned services. If a service failed its healthcheck, the call surfaces the failing services and the `docker compose ... logs` line to inspect — relay that line; do not invent your own.
 
-After a successful `up`, run the `status --text` command below and read its numbered container `ports` fields to tell the user how to reach the running build. Also explain that `okstra container status <task-key>` / `okstra container down <task-key>` manage it from here. For *what to verify* once it is up, point the user to the implementation report's §5.7.9 Manual User Test (Draft) — its steps and expected results are the manual test script for this build.
+After a successful `up`, run the `status --text` command below and read its numbered container `ports` fields to tell the user how to reach the running build. Also explain that `okstra container status --project-root <projectRoot> --task-key <task-key>` / `okstra container down --project-root <projectRoot> --task-key <task-key>` manage it from here. For *what to verify* once it is up, point the user to the implementation report's §5.7.9 Manual User Test (Draft) — its steps and expected results are the manual test script for this build.
 
 ---
 
 ## status
 
-Reports the running containers, queried by the run-trace label — the source of truth for "is it up".
+Reports the task's containers, queried by the `okstra.project-name` label with `docker ps -a` — so stopped and exited containers are listed too. The label query is the source of truth for "is it up".
 
 ```bash
 okstra container status --project-root <projectRoot> --task-key <task-key> --text
@@ -98,9 +98,9 @@ Read the fixed `Project name` and numbered `Container` fields and report:
 | Field | Meaning |
 |---|---|
 | `projectName` | the compose project name (label group) |
-| `containers` | running containers found by label — empty array means nothing is up |
+| `containers` | containers found by label, in any state — empty array means no container exists; a non-empty list is up only where `state` is `running` |
 
-If `containers` is empty, say the group is not running and offer `up`.
+If `containers` is empty, or no container's `state` is `running`, say the group is not running and offer `up`.
 
 To follow a service's live logs, the user runs `docker compose -p <projectName> logs -f <service>` (get `<projectName>` from `status`).
 
@@ -108,7 +108,7 @@ To follow a service's live logs, the user runs `docker compose -p <projectName>
 
 ## down
 
-Tears down the container group — removes the containers found by the run-trace label.
+Tears down the container group by compose project name — no label query. `--all` finds its targets from the tasks that have a `container/deploy-state.json`.
 
 Single task:
 

package/runtime/skills/okstra-inspect/SKILL.md

@@ -11,7 +11,7 @@ and direct completion records are available to status, recap, group context, and
 For an explicit status change, dispatch to status.4 before catalog-only task selection.
 An unregistered brief will not appear in that selection yet.
 
-Single read-side entry point for okstra runtime inspection plus the one status mutation that belongs here (`workStatus`) and read-derived artifact rendering (`errors` report). Each sub-command's full procedure lives in a lazily loaded facet file — after dispatch, Read exactly the one facet you need.
+Single read-side entry point for okstra runtime inspection plus the one status mutation that belongs here (`workStatus`) and read-derived artifact rendering (`errors` report). One more write sits underneath: the task-key lookup used by `time-report`, `context-cost`, `error-report`, `recap record`, `recap note`, and `model-io recap-input --task-group` self-heals a finished implementation phase — when a task's current phase is `implementation`, it appends a `done` row to `runs/implementation-planning/consumers.jsonl` for each stage whose carry file is complete but has no settled row, and when every stage of the latest plan has a `done` row and a pass-grade carry it marks the phase completed in `task-manifest.json` (`workflow`, `phaseOutcome.implementation`) and refreshes the catalog entry. `status-input`, `history-input`, `report-input`, and task-scope `recap-input` do not take that path. Each sub-command's full procedure lives in a lazily loaded facet file — after dispatch, Read exactly the one facet you need.
 
 | Sub-command | Facet file | What it does |
 |---|---|---|

package/runtime/skills/okstra-inspect/facets/cost.md

@@ -6,7 +6,7 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra context-cost", "context cost", "context-cost", "read cost", "artifact cost", "task bundle cost", "agent read cost".
 
-Read-only estimate of how much file/context surface a prepared task bundle asks the lead, analysis workers, and report-writer to absorb. This sub-command does **not** mutate task artifacts.
+Estimate of how much file/context surface a prepared task bundle asks the lead, analysis workers, and report-writer to absorb. This sub-command does **not** mutate task artifacts itself; a task-key target goes through the lookup that may self-heal a finished implementation phase (see `SKILL.md`).
 
 ### cost.1 — Resolve target
 

package/runtime/skills/okstra-inspect/facets/error-zip.md

@@ -28,14 +28,14 @@ okstra error-zip --out <resolved-path> --text
 
 Use the fixed text labels and report:
 
-| Field | Source |
+| Field | Label |
 |---|---|
-| Output zip | `outPath` |
-| Total errors | `errorCount` |
-| Logs (runs) | `runCount` |
-| Unreachable runs | `unreachableRuns` |
-| Cluster count | `clusterCount` |
-| Project count | `projectCount` |
-
-- If `unreachableRuns > 0`, surface it (no silent omission).
+| Output zip | `Output zip` |
+| Total errors | `Total errors` |
+| Logs (runs) | `Run count` |
+| Unreachable runs | `Unreachable runs` |
+| Cluster count | `Cluster count` |
+| Project count | `Project count` |
+
+- If `Unreachable runs` > 0, surface it (no silent omission).
 - End with the next step: "To fix okstra itself with this zip, build a brief with the error-feedback variant of `/okstra-brief-gen`, then run `okstra-run --task-type error-analysis` in the okstra repo."

package/runtime/skills/okstra-inspect/facets/errors.md

@@ -6,7 +6,7 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra errors", "error report", "error summary", "gather the errors", "clean up failure logs".
 
-Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-observed + worker-reported) into a timestamped markdown report and summarize it. This sub-command renders a **read-derived artifact** (a `.md` file) but never mutates task state (`task-manifest.json`, catalog, timeline).
+Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-observed + worker-reported) into a timestamped markdown report and summarize it. This sub-command renders a **read-derived artifact** (a `.md` file) and never edits task state itself (`task-manifest.json`, catalog, timeline); a task-key target goes through the lookup that may self-heal a finished implementation phase (see `SKILL.md`).
 
 ### errors.1 — Resolve target
 
@@ -32,28 +32,28 @@ For a task-root path, run `okstra error-report <path>` directly. Do not parse th
 
 Use the fixed text labels and report:
 
-| Field | Source |
+| Field | Label |
 |---|---|
-| Report file | `reportPath` (project-root-relative `.md`) |
-| Total errors | `totals.errorCount` |
-| Logs (runs) | `totals.runCount` |
-| By errorType | `totals.byErrorType` (tool-failure / cli-failure / contract-violation) |
-| By source | `totals.bySource` (lead-observed / worker-reported) |
-| By phase | `byPhase[]` |
-| By agent | `byAgent[]` |
-| Parse-skipped lines | `parseSkipped` |
-
-- If `reportPath` is empty AND `totals.errorCount == 0`: report `This task has no recorded error logs.` and do not claim a file was written.
+| Report file | `Report path` (project-root-relative `.md`) |
+| Total errors | `Total errors` |
+| Logs (runs) | `Run count` |
+| By errorType | `Error type <name>` lines (tool-failure / cli-failure / contract-violation) |
+| By source | `Source <name>` lines (lead-observed / worker-reported) |
+| By phase | `Phase <name>` lines |
+| By agent | `Agent <name>` lines |
+| Parse-skipped lines | `Parse skipped` |
+
+- If `Report path` is `-` AND `Total errors` is 0: report `This task has no recorded error logs.` and do not claim a file was written.
 - Otherwise show the `.md` path and offer to read it.
-- If `parseSkipped > 0`, surface it (do not silently hide malformed lines).
+- If `Parse skipped` > 0, surface it (do not silently hide malformed lines).
 
 ### errors — Output template
 
 ```markdown
 ## okstra Error Report — <task-key>
 
-- Report: `<reportPath-or-->`
-- Total errors: <N> across <runCount> log(s)
+- Report: `<Report path-or-->`
+- Total errors: <N> across <Run count> log(s)
 - By type: <tool-failure: a, cli-failure: b, ...>
 - By source: <lead-observed: x, worker-reported: y>
 
@@ -65,5 +65,5 @@ Use the fixed text labels and report:
 |---|---:|
 | codex-worker | 2 |
 
-<If parseSkipped > 0: "⚠ Parse-skipped lines: <N>">
+<If Parse skipped > 0: "⚠ Parse-skipped lines: <N>">
 ```

package/runtime/skills/okstra-inspect/facets/logs.md

@@ -25,21 +25,21 @@ okstra log-report --project-root <projectRoot> --text
 ```
 
 Scans `<projectRoot>/.okstra/tasks/**/runs/*/prompts/*.log` and returns fixed labeled text (sizes are **raw bytes**, mtimes **epoch seconds**):
-- `topLargest[]` — `{path, sizeBytes, mtimeEpoch, taskKey, taskGroup, taskId, phase, worker, seq}`, size desc (widen with `--top <N>`)
-- `perTask[]` — `{taskKey, fileCount, totalBytes, oldestEpoch, newestEpoch}`, total-size desc
-- `totals` — `{fileCount, totalBytes, taskCount}`
+- Top-level total labels — `File count`, `Total bytes`, `Task count` (plus `Prompt bytes`, `Transcript bytes`, `Paired file count`)
+- Repeated `## Log` blocks, size desc (widen with `--top <N>`) — `Task key`, `Phase`, `Worker`, `Sequence`, `Size bytes`, `Modified epoch`, `Path`
+- Repeated `## Task total` blocks, total-size desc — `Task key`, `File count`, `Total bytes`, `Oldest epoch`, `Newest epoch`
 
-If `totals.fileCount` is 0, report `No worker log files found under <projectRoot>` and stop.
+If the top-level `File count` is 0, report `No worker log files found under <projectRoot>` and stop.
 
 ### logs.2 — Summary tables
 
 Render from the CLI output (format bytes → KB/MB; epoch → `Nd`/`Nh` relative to now):
 
-**Table A — Top largest logs** (from `topLargest`): `| # | Task | Phase | Worker | Seq | Size | Age | Path |`.
+**Table A — Top largest logs** (from the `## Log` blocks): `| # | Task | Phase | Worker | Seq | Size | Age | Path |`.
 
-**Table B — Per-task totals** (from `perTask`): `| Task Key | Files | Total Size | Oldest | Newest |`.
+**Table B — Per-task totals** (from the `## Task total` blocks): `| Task Key | Files | Total Size | Oldest | Newest |`.
 
-**Footer:** `Total: <fileCount> files, <totalBytes→MB> across <taskCount> tasks under <PROJECT_ROOT>`.
+**Footer:** `Total: <File count> files, <Total bytes→MB> across <Task count> tasks under <PROJECT_ROOT>`.
 
 ### logs.3 — Suggested cleanup commands
 

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -6,7 +6,7 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
 
-On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs the `recap-log.jsonl` append, the `notes/` note authoring (recap.5), and the group-context reconciliation that note triggers (recap.6); it never mutates `task-manifest.json` / catalog / timeline, and it touches `group-context.md` only in the authored sections above the `<!-- okstra:task-memory:begin -->` marker.
+On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs the `recap-log.jsonl` append, the `notes/` note authoring (recap.5), and the group-context reconciliation that note triggers (recap.6); it never edits `task-manifest.json` / catalog / timeline itself (`recap record` / `recap note` with a task-key target, and `recap-input --task-group`, go through the lookup that may self-heal a finished implementation phase — see `SKILL.md`), and it touches `group-context.md` only in the authored sections above the `<!-- okstra:task-memory:begin -->` marker.
 
 ### recap.1 — Resolve target
 
@@ -144,7 +144,7 @@ Write the body to the scratchpad as markdown first, then pass it with `--body-fi
 **self-check rules (there is no validator, so you keep them yourself):**
 
 1. **Do not hand-edit a rendered report** (`*.md` / `*.data.json` / `*.html` under `runs/*/reports/`). Report assembly regenerates those artifacts, so write findings to `notes/` instead.
-2. **Do not author a `user-responses/` file or apply `created-by: user`.** That is the user's decision, and writing it for them forges a decision the user never made. If your evidence supports a particular answer, write that in `notes/` and leave the decision to the user. The one exception is the echo-back confirmation flow of the `okstra-user-response` skill — there the user makes the decision in-session and the CLI is merely a transcription channel, so recording a `created-by: user` sidecar with `write` is legitimate. This exception holds only after the user has explicitly confirmed "correct", and only for verbatim input.
+2. **Do not author a `user-responses/` file or apply `created-by: user`.** That is the user's decision, and writing it for them forges a decision the user never made. If your evidence supports a particular answer, write that in `notes/` and leave the decision to the user. The one exception is the echo-back confirmation flow of the `okstra-user-response` skill — there the user makes the decision in-session and the CLI is merely a transcription channel, so publishing the `created-by: user` sidecar through that skill's `begin` → `answer` → `finalize` transaction is legitimate (`okstra user-response` has no `write` command). This exception holds only after the user has explicitly confirmed "correct", and only for verbatim input.
 3. **Do not write to okstra-managed directories** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` is the only agent-owned lane. `recap/recap-log.jsonl` is the exception — write it, but not by hand; only via the `okstra recap record` CLI.
 4. **`notes/` is inert to okstra** — no run reads it automatically. After writing, relay the `clarificationResponseArg` the CLI printed (e.g. `--clarification-response <notePath>`) to the user verbatim, telling them it only takes effect when the next run is executed with that argument.
 

package/runtime/skills/okstra-inspect/facets/report.md

@@ -10,7 +10,7 @@ Trigger phrases: "find report", "show report for", "read the okstra report", "co
 
 task-key format: `<project-id>:<task-group>:<task-id>`.
 
-**Normalization:** task-key matching is lowercase. Disk segments are slugified (lowercase + non-alphanumeric runs → `-`) per `scripts/okstra_ctl/ids.py:88` (`slugify_task_segment`, the SSOT; `interactive.sh` consumes it via import). Catalog lookup is case-insensitive; file path assembly uses slugified segments.
+**Normalization:** task-key matching is lowercase. Disk segments are slugified (lowercase + non-alphanumeric runs → `-`) per `slugify_task_segment` (`scripts/okstra_ctl/ids.py:78`); the `model-io` projections build task paths with `okstra_project.slugify` (`scripts/okstra_project/slug.py:16`), which applies the same rule. Catalog lookup is case-insensitive; file path assembly uses slugified segments.
 
 Run `okstra model-io report-input --project-root <projectRoot> --task-ref
 <task-key>` and use `Latest report`. For a specific date, run `okstra model-io

package/runtime/skills/okstra-inspect/facets/status.md

@@ -100,7 +100,7 @@ The status response always includes one of:
 4. **Restart current phase** — only when there is nothing to answer: `latestReportRecordPath` is empty, or the open-item count is zero and `latestRunStatus` is `contract-violated`. Only an allowlisted blocking-class failure produces that status; findings demoted to `validation.advisories` leave the run passed and are not a reason to re-run. The task can be re-run with the same `task-key` and current `taskType`.
 Branches 5–7 are decided by `workflow.nextRecommendedPhase.status` when `awaitingApproval` is false — one status, one branch:
 
-5. **Start next phase** — `status` is `ready` and `awaitingApproval` is false. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched without a prior approval ask, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
+5. **Start next phase** — `status` is `ready` and `awaitingApproval` is false. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched without a prior approval ask, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies a final-verification verdict of `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false` (the report validator refuses that routing target otherwise), so do not re-gate it here.
 6. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. After `implementation-planning`, branch 3 already owns the routing: the `C-NNN` answers come first, and planning is not re-run until they exist.
 7. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
 
@@ -112,8 +112,9 @@ This includes briefs whose tasks have never run. Call this command directly with
 token; do not require a catalog match or a prior `okstra-run`. The command resolves the brief
 and registers it when needed. For "do this small task directly and record completion", perform
 the authorized work, then record `done` with `--note` or `--note-file` containing the changes,
-verification results or reasons checks were not run, and remaining limitations. These inputs
-are checked by `set-work-status` and covered by `test_okstra_set_work_status.py`.
+verification results or reasons checks were not run, and remaining limitations. `set-work-status`
+refuses a direct completion whose note is empty (`test_okstra_set_work_status.py`); it does not
+check the note's content, so including those three parts is on you.
 
 Read `Direct work record` alongside `Work status`. A direct result is user-recorded work,
 not a passed cross-verification run. The command shares the result in group context and

package/runtime/skills/okstra-inspect/facets/time.md

@@ -19,20 +19,21 @@ okstra time-report <task-key> --project-root <projectRoot> --text
 ```
 
 Returns fixed labeled text (all durations are **raw milliseconds**):
-- Repeated `Task type` blocks — task type, runs, lead ms, workers ms, and CPU sum ms, plus total labels
-- `perWorker` — `{<taskType>: [{workerId, agents[], runs, totalMs, avgMs}]}`; only workers with a nonzero run appear, and `agents[]` lists agent labels that differ from `workerId`
-- `perRunWallClock[]` — `{runTimestamp, taskType, wallClockMs}` (max `endedAt` − min `startedAt` per run)
-- `phaseTimelines[]` — `{runTimestamp, taskType, phases:[{phase, firstAt, wallMsToNext}]}`
-- `unavailable[]` — `{runTimestamp, taskType, reason}` for runs with no Phase-7 durations (never summed into totals)
+- Top-level total labels — `Total runs`, `Total lead ms`, `Total workers ms`, `Total CPU sum ms`
+- Repeated `## Task type` blocks — `Task type`, `Runs`, `Lead ms`, `Workers ms`, `CPU sum ms`
+- Repeated `## Worker` blocks — `Task type`, `Worker ID`, `Agents` (comma-separated agent labels that differ from the worker ID), `Runs`, `Total ms`, `Average ms`; only workers with a nonzero run appear
+- Repeated `## Run wall clock` blocks — `Run timestamp`, `Task type`, `Wall clock ms` (max `endedAt` − min `startedAt` per run)
+- Repeated `## Phase` blocks, one per phase marker — `Run timestamp`, `Task type`, `Phase`, `First at`, `Wall ms to next`
+- Repeated `## Unavailable run` blocks — `Run timestamp`, `Task type`, `Reason` for runs with no Phase-7 durations (never summed into totals)
 
 ### time.3 — Render
 
-Convert every `*Ms` to `HH:MM:SS` (zero-pad; never show raw ms). Task types in `byTaskType` are already in chronological (first-appearance) order.
+Convert every `ms` label to `HH:MM:SS` (zero-pad; never show raw ms). `## Task type` blocks are already in chronological (first-appearance) order.
 
-- **By task type** — `| Task type | Runs | CPU sum | Lead | Workers |` from `byTaskType`, plus a `grandTotal` row. `CPU sum` (= Lead + Workers) overlaps because workers run inside the lead's window — it is *not* wall-clock. Surface wall-clock only when the user explicitly asks, from `perRunWallClock`.
-- **Per worker** (per task type) — `| Worker | Runs | Total | Avg/run |` from `perWorker`. Render the worker as bare `workerId` when `agents` is empty, else `workerId (agent1, agent2)`.
-- **Phase breakdown** — "by stage"/"per stage"/"which stage took longest" in okstra most often means the **lifecycle stage (task-type)** view, which the *By task type* table above already answers — lead with that table, do not treat the request as unanswerable. Render the intra-run phase timeline only when the user clearly means within-a-run phases ("which phase", "Phase 1~7", "phase timeline"): one table per run from `phaseTimelines`: `| Phase | Start | Wall to next |` using `firstAt`/`wallMsToNext` (`null` → `--`). When `phaseTimelines` is empty, do **not** headline "not measurable" — the By-task-type table is the stage answer; mention the missing intra-run markers only as a trailing footnote.
-- If `unavailable[]` is non-empty, append a trailing note listing each run with its reason. Never fold them into totals.
+- **By task type** — `| Task type | Runs | CPU sum | Lead | Workers |` from the `## Task type` blocks, plus a total row from the `Total …` labels. `CPU sum` (= Lead + Workers) overlaps because workers run inside the lead's window — it is *not* wall-clock. Surface wall-clock only when the user explicitly asks, from the `## Run wall clock` blocks.
+- **Per worker** (per task type) — `| Worker | Runs | Total | Avg/run |` from the `## Worker` blocks. Render the worker as bare `Worker ID` when `Agents` is `-`, else `<Worker ID> (agent1, agent2)`.
+- **Phase breakdown** — "by stage"/"per stage"/"which stage took longest" in okstra most often means the **lifecycle stage (task-type)** view, which the *By task type* table above already answers — lead with that table, do not treat the request as unanswerable. Render the intra-run phase timeline only when the user clearly means within-a-run phases ("which phase", "Phase 1~7", "phase timeline"): one table per run from the `## Phase` blocks grouped by `Run timestamp`: `| Phase | Start | Wall to next |` using `First at`/`Wall ms to next` (`-` → `--`). When there is no `## Phase` block, do **not** headline "not measurable" — the By-task-type table is the stage answer; mention the missing intra-run markers only as a trailing footnote.
+- If any `## Unavailable run` block exists, append a trailing note listing each run with its reason. Never fold them into totals.
 - Show the resolved `<task-key>` in the heading.
 
 ```markdown

package/runtime/skills/okstra-manager/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: okstra-manager
 description: Use when the user wants to manage okstra work across multiple project roots, register or discover projects under a manager, create or update a shared manager task, sync project child-task status into manager state, split a Linear project or issue into per-project scoped briefs, or launch a child task from manager context. Trigger words include "okstra manager", "okstra-manager", "multiple projects", "cross-project", "group projects together", "manager task", "split this Linear project", "brief per project".
+user-invocable: true
+disable-model-invocation: true
 ---
 
 # OKSTRA Manager
@@ -22,7 +24,7 @@ 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>
+okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--task <project-id:task-group:task-id>]
 okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
 okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
 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>]
@@ -31,14 +33,28 @@ okstra manager task run --manager-id <manager-id> --project-id <project-id> --ta
 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 task-groups --manager-id <manager-id>
 okstra manager list tasks --manager-id <manager-id>
+okstra manager task update --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>]
+okstra manager task remove-child --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--confirm]
+okstra manager remove project --manager-id <manager-id> --project-id <project-id> [--confirm]
+okstra manager remove task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> [--confirm]
+okstra manager remove task-group --manager-id <manager-id> --task-group <task-group> [--confirm]
 okstra manager view --manager-id <manager-id>
 ```
 
 - Public child task identity is `project-id:task-group:task-id`.
+- `--task` on `new task` is optional and repeatable; without it the task is created with no children.
 - `okstra manager new task --task ...` should prefer the full child key form above. The CLI also accepts shorthand under the command's `--task-group`, but the full key is the public form to show users.
 - When a manager task id differs from the actual child task id for a specific project, pass `--child-task-id <child-task-id>` to `task assign` and `task run`.
 
+## Removal Rule
+
+`remove project`, `remove task`, `remove task-group` and `task remove-child` change nothing without `--confirm`; they print what would be removed (`Removed: no — dry run`). Run the command without `--confirm` first, show the user the listed project, path, tasks or kept children, and rerun with `--confirm` only after the user approves that exact target. These commands touch manager files only; project `.okstra/` state and briefs written by `task split` stay.
+
+- `remove project` unregisters the project and keeps its child tasks. `task status` shows them with `project linked: no`, the view marks them `unlinked`, and `task run` refuses them until the project is registered again with `new project`.
+- `task update` changes only the fields given and needs no confirmation. `new task` still refuses to change an existing task's objective, common brief or progress mode.
+
 ## Tracker Split
 
 Use this when one Linear project, or one parent issue, covers work in several registered projects and each project needs its own brief. A Linear project can point at several projects, and one issue can too; every (issue, project) pair gets its own brief and child task.
@@ -77,7 +93,7 @@ Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommend
 }
 ```
 
-The CLI writes each brief to `<projectRoot>/.okstra/briefs/<task-group>/<ticketId>-<file-title>.md` with a `## Project Scope` section: this project's scope, `outOfScope`, and the scope of every other project the same issue went to. It validates every brief with the brief validator before writing any file, registers the child tasks, and keeps the plan at `split-plan.json` in the manager task directory.
+The CLI writes each brief to `<projectRoot>/.okstra/briefs/<group-slug>/<ticketId>-<file-title>.md` (`<group-slug>` is the task group lowercased, with each run of characters other than `a-z` and `0-9` replaced by `-`, so `Upload V2` becomes `upload-v2`) with a `## Project Scope` section: this project's scope, `outOfScope`, and the scope of every other project the same issue went to. It validates every brief with the brief validator before writing any file, registers the child tasks, and keeps the plan at `split-plan.json` in the manager task directory.
 
 ## Overview Page
 

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -61,10 +61,10 @@ the user states explicitly wins verbatim; never rewrite it.
 okstra pr template list
 ```
 
-- If `templates` is non-empty, present a picker: 1–2 recommended templates from
+- If it prints template names (one per line), present a picker: 1–2 recommended templates from
   the list, plus `Default template` (the bundled default), plus `Enter directly`
   last.
-- If empty, tell the user the bundled default template will be used.
+- If it prints `(no templates)`, tell the user the bundled default template will be used.
 
 Carry the chosen template name as `<template>` (`default` for the bundled one).
 
@@ -74,8 +74,9 @@ Carry the chosen template name as `<template>` (`default` for the bundled one).
 okstra pr branches
 ```
 
-Present a 3-option base picker from `recommended` (top entries) plus `Enter directly`
-last. Carry the choice as `<base>`.
+It prints the recommended base branches one per line, current branch excluded, or `(no branches)`.
+Present a 3-option base picker from the first two printed branches plus `Enter directly` last; with
+`(no branches)`, ask for the base directly. Carry the choice as `<base>`.
 
 ### A3. Build the generation bundle and fill the template
 
@@ -94,7 +95,7 @@ git diff <base>...HEAD
 For a large diff, read it in sections. Fill the `template` placeholders from the
 diff and commits: describe only what actually changed. Mark checklist boxes
 `[x]` only when the diff supports them (tests touched → tests box, docs touched →
-docs box). If `commits`/`diffStat` are empty, tell the user there is nothing to
+docs box). If the `Commits`/`Diff stat` sections print `-` (empty), tell the user there is nothing to
 describe and stop. **Never** append AI trailers/footers.
 
 ### A3b. Identifier allowlist for the body