okstra 0.201.3 → 0.204.0

package/runtime/schemas/final-report-v3.0.schema.json

@@ -905,110 +905,103 @@
       "description": "RENDER_IF taskType == release-handoff. §5.6 deliverables.",
       "required": [
         "handoffScope",
+        "sourceVerificationReports",
         "featureBranchState",
         "userSelections",
         "localCheckoutOutcome",
         "executedCommands",
         "commitList",
         "mergeConflictProbe",
-        "pullRequestOutcome",
+        "pullRequestOutcomes",
         "routingRecommendation",
         "userNarrative"
       ],
       "additionalProperties": false,
-      "allOf": [
-        {
-          "if": {
-            "properties": {
-              "handoffScope": {
-                "properties": {
-                  "mode": {
-                    "const": "stage-group"
-                  }
-                },
-                "required": [
-                  "mode"
-                ]
-              }
-            },
-            "required": [
-              "handoffScope"
-            ]
-          },
-          "then": {
-            "required": [
-              "sourceVerificationReports"
-            ]
-          },
-          "else": {
-            "required": [
-              "sourceVerificationReport"
-            ]
-          }
-        }
-      ],
       "properties": {
         "handoffScope": {
           "type": "object",
           "required": [
-            "mode"
+            "stages",
+            "releaseBase"
           ],
           "additionalProperties": false,
-          "description": "Which shape of handoff this was. 'whole-task' turns the verified task branch into one PR; 'stage-group' merges a user-selected subset of verified stages into a collector branch and opens the PR from that. Without it a reader cannot tell one report from the other, and in stage-group mode cannot tell which stages shipped — the branch name alone does not say.",
+          "description": "What this handoff delivered. One stage is one PR, so the stage list is the PR list, and `stagePlan` is the only place a reader learns which branch each PR sat on — and therefore in what order the stack must be merged.",
           "properties": {
-            "mode": {
-              "enum": [
-                "whole-task",
-                "stage-group"
-              ]
-            },
             "stages": {
               "type": "array",
+              "minItems": 1,
               "items": {
                 "type": "integer",
                 "minimum": 1
               }
             },
-            "collectorBranch": {
-              "type": "string"
+            "releaseBase": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The base branch the user picked for the run. A stage that sits on another stage does NOT target it — see stagePlan[].baseBranch."
             },
-            "mergeCommits": {
+            "stagePlan": {
               "type": "array",
-              "description": "Assemble's merge commit SHAs, in the order the stages were merged into the collector branch. Without them the collector branch's contents cannot be traced back to the stages that produced them once the branch moves on.",
+              "description": "`okstra handoff pr-plan` output, one row per stage. Without it the merge order of a stacked PR set cannot be reconstructed once the branches move.",
               "items": {
-                "type": "string",
-                "minLength": 7
+                "type": "object",
+                "required": [
+                  "stage",
+                  "headBranch",
+                  "baseKind",
+                  "baseBranch"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "stage": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "headBranch": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "headCommit": {
+                    "type": "string"
+                  },
+                  "baseKind": {
+                    "enum": [
+                      "release-base",
+                      "stage",
+                      "merge-base"
+                    ]
+                  },
+                  "baseBranch": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "baseCommit": {
+                    "type": "string"
+                  },
+                  "baseStages": {
+                    "type": "array",
+                    "description": "The predecessor stages this row's base carries. Empty for a release-base row.",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    }
+                  },
+                  "baseMergeCommits": {
+                    "type": "array",
+                    "description": "Merge commits pr-plan created on a merge-base branch. The only commits release-handoff is allowed to produce.",
+                    "items": {
+                      "type": "string",
+                      "minLength": 7
+                    }
+                  }
+                }
               }
-            },
-            "dependencyClosureVerdict": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Whether the selected stages are closed under their dependencies, and on what basis. A stage-group PR that ships a stage without its predecessor is the failure this records."
-            }
-          }
-        },
-        "sourceVerificationReport": {
-          "type": "object",
-          "description": "whole-task mode: the one final-verification report this handoff ships. Required unless handoffScope.mode is stage-group.",
-          "required": [
-            "path",
-            "verdictTokenQuote"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "path": {
-              "type": "string",
-              "minLength": 1
-            },
-            "verdictTokenQuote": {
-              "type": "string",
-              "minLength": 1
             }
           }
         },
         "sourceVerificationReports": {
           "type": "array",
-          "description": "stage-group mode: one row per selected stage, because that handoff ships several verified stages and a single report path cannot say which stage each verdict belongs to.",
+          "description": "One row per selected stage. Each stage ships its own PR under its own verdict, so a single report path cannot say which stage a verdict belongs to.",
           "minItems": 1,
           "items": {
             "type": "object",
@@ -1048,6 +1041,11 @@
                 "checked-out"
               ]
             },
+            "stage": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The stage whose branch was checked out. Checkout is per stage, so a branch name without it leaves the reader matching branch suffixes by hand."
+            },
             "branch": {
               "type": "string"
             },
@@ -1173,6 +1171,14 @@
             "userChoice": {
               "type": "string"
             },
+            "conflictingStages": {
+              "type": "array",
+              "description": "The stages whose head did not merge cleanly into their own PR base. The probe runs per stage, so a bare path list cannot say which PR is affected.",
+              "items": {
+                "type": "integer",
+                "minimum": 1
+              }
+            },
             "conflictingPaths": {
               "type": "array",
               "items": {
@@ -1181,32 +1187,41 @@
             }
           }
         },
-        "pullRequestOutcome": {
-          "type": "object",
-          "required": [
-            "kind"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "kind": {
-              "enum": [
-                "no-action",
-                "created",
-                "reused",
-                "skipped"
-              ]
-            },
-            "url": {
-              "type": "string"
-            },
-            "title": {
-              "type": "string"
-            },
-            "baseBranch": {
-              "type": "string"
-            },
-            "reason": {
-              "type": "string"
+        "pullRequestOutcomes": {
+          "type": "array",
+          "description": "One row per selected stage — one stage is one PR. A single outcome object cannot say which stage was created, reused or skipped.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "stage",
+              "kind"
+            ],
+            "properties": {
+              "stage": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "kind": {
+                "enum": [
+                  "no-action",
+                  "created",
+                  "reused",
+                  "skipped"
+                ]
+              },
+              "url": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "baseBranch": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
             }
           }
         },
@@ -1582,6 +1597,7 @@
               "enum": [
                 "release-handoff",
                 "release-handoff(stage-group)",
+                "final-verification",
                 "error-analysis",
                 "implementation-option-selection",
                 "implementation-planning",
@@ -9839,6 +9855,11 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "stage": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Which stage's PR carries this commit. One stage is one PR, so a flat commit list across several stages cannot be attributed without it."
+        },
         "shortSha": {
           "type": "string",
           "minLength": 7

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