okstra 0.26.0 → 0.27.0

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

@@ -40,7 +40,7 @@ parse and reuse it instead of re-resolving in the steps below.
 
 ## Step 1: Overall Project Status
 
-To view the overall project status, first read `.project-docs/okstra/discovery/task-catalog.json`.
+To view the overall project status, read `.project-docs/okstra/discovery/task-catalog.json`. The catalog is the authoritative source — every field listed below (including `workStatus`, `workStatusUpdatedAt`, `workStatusNote`) is projected directly from each `task-manifest.json` by `scripts/okstra_ctl/render.py :: render_task_catalog_discovery`. Do NOT re-open individual manifests for the overview.
 
 Extract the following fields from each task.
 
@@ -68,13 +68,19 @@ Sort by:
 
 출력 형식:
 
+The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, routing, approval gate, last run status, resume path, etc.) tell the user to run `okstra status <task-key>` for the detail view in Step 2.
+
+If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to the `Next` cell as a visual marker and explain the marker once below the table.
+
 ```markdown
 ## okstra Status — <project-id>
 
-| # | Task Key | Category | Phase | Phase State | Task Status | workStatus | Next | Routing | Approval | Last Run |
-|---|----------|----------|-------|-------------|-------------|------------|------|---------|----------|----------|
-| 1 | proj:group:id | bugfix | error-analysis | completed | completed | in-progress | implementation-planning | not-applicable | no | completed |
-| 2 | proj:group:id2 | feature | requirements-discovery | prepared | instruction-set-generated | done | pending-routing-decision | pending | yes | prepared |
+| # | Task Key | Category | Phase | workStatus | Next |
+|---|----------|----------|-------|------------|------|
+| 1 | proj:group:id | bugfix | error-analysis | in-progress | implementation-planning |
+| 2 | proj:group:id2 | feature | requirements-discovery | done | pending-routing-decision* |
+
+`*` = awaiting user approval or pending routing decision. Run `okstra status <task-key>` for details.
 ```
 
 ## Step 2: Specific Task Status
@@ -153,10 +159,12 @@ The status response always includes one of the following options:
 2. **Restart current phase**
 - Indicates whether the task can be re-run with the same `task-key` and the current `taskType`.
 3. **Start next phase**
-- If `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, `final-verification`, or `release-handoff`, that phase is proposed as the next candidate for the Okstra run.
+- If `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, or `release-handoff`, that phase is proposed as the next candidate for the Okstra run.
 - If `nextRecommendedPhase` is `pending-release-handoff`, the prior `final-verification` run completed but its verdict still has to be inspected before entering `release-handoff` — surface this as a verdict-gated next step and present `release-handoff` as a candidate only when the cited verdict is `accepted`.
 4. **Need more information**
 - If `nextRecommendedPhase` is `pending-routing-decision` or `routingStatus` is `pending`, this indicates that additional information is required.
+5. **Task complete (terminal)**
+- If `nextRecommendedPhase` is `done-or-follow-up`, the task lifecycle has reached its terminal signal. 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.
 
 ## Step 4: Update workStatus
 
@@ -195,7 +203,7 @@ Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
      Stop without modifying any file.
    - If no match → output `<TASK-ID>를 찾을 수 없습니다.` and stop.
 
-3. **Open the matching `task-manifest.json`** at `.project-docs/okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`.
+3. **Open the matching `task-manifest.json`** at `.project-docs/okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`. Assemble the path from the catalog entry's `taskGroupPathSegment` and `taskIdPathSegment` fields (these are the filesystem-safe segments emitted by the renderer) — NOT from the raw user-supplied `<task-group>` / `<task-id>` strings, which may differ in case or contain characters that were normalized when the manifest was created. As a defensive shortcut, prefer the `taskManifestPath` field directly when present.
 
 4. **Update fields at the manifest root**:
    - `workStatus` ← new status value
@@ -224,7 +232,7 @@ If `workStatus` is missing or empty in any manifest, infer the display value fro
 
 | Manifest state | Inferred display |
 |---|---|
-| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase` in (`done-or-follow-up`, empty) | `done` (inferred) |
+| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase == "done-or-follow-up"` | `done` (inferred) |
 | `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
 | `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
 | anything else | `in-progress` (default) |
@@ -244,3 +252,7 @@ This skill updates `task-manifest.json` only. `discovery/task-catalog.json` may
 - If there is no recent report, display `--`.
 - If a specific task does not exist, explicitly state that it cannot be found based on `task-catalog.json`.
 - If `awaitingApproval` is true, clearly indicate that the task is awaiting user approval.
+
+## Out-of-Scope Backlog
+
+- **Step 0 boilerplate duplication.** The `ensure-installed` + `paths --shell` + `check-project --json` preamble is byte-identical across every user-facing okstra skill. The Claude Code skill framework has no include/snippet mechanism today, so each skill duplicates the block. A future change should either (a) extract the preamble into a single `okstra preflight` subcommand the skill can call in one line, or (b) ship the block as a shared SKILL fragment if the framework gains include support. Not actionable inside this skill alone.

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -11,6 +11,8 @@ user-invocable: false
 - When verifying worker team composition and operational rules
 - When applying model assignment rules
 
+**Not applicable to `release-handoff`** — that profile is lead-only and intentionally has no `Required workers:` block (see `prompts/profiles/release-handoff.md`). The worker-dispatch contract in this document does not engage during `release-handoff` runs.
+
 ## Team Structure
 
 okstra tasks are always operated using the `Claude lead` + required worker team structure.
@@ -19,24 +21,27 @@ okstra tasks are always operated using the `Claude lead` + required worker team
 
 **All analysis workers (Claude / Codex / Gemini) share an identical core responsibility.** Specialization is additive — it lives in optional Section 6 of the worker output, NOT in differentiated core questions. This is intentional: cross-verification only converges if all three workers are answering the same questions against the same brief. Disjoint per-worker scopes produce union-of-perspectives, not triangulation.
 
-| Role | Core responsibility | Specialization lens (Section 6 only) | Default Model | subagent_type | Notes |
-|------|------|------|-----------|---------------|------|
-| Claude lead | orchestration + convergence supervision + final-report review/approval | — | opus | -- | Does NOT author the final-report file when `Report writer worker` is in the roster |
-| Claude worker | Answer every brief question across feasibility, requirement interpretation, hidden assumptions, and alternatives — with file:line evidence | broad reasoning depth, hidden assumptions, execution-risk surfacing | sonnet | claude-worker | `agents/claude-worker.md` |
-| Codex worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | implementation realism, code-path implications, edge cases, technical trade-offs | gpt-5.5 | codex-worker | `agents/codex-worker.md` |
-| Gemini worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | requirement interpretation, consistency, safety, alternative viewpoints | auto | gemini-worker | `agents/gemini-worker.md` |
-| Report writer worker | **Authors** the final-report file in Phase 6. NOT an analysis worker. | — | opus | report-writer-worker | `agents/report-writer-worker.md`. Excluded from Phase 4/5 and convergence |
+| Role | Core responsibility | Specialization lens (Section 6 only) | subagent_type | Notes |
+|------|------|------|---------------|------|
+| Claude lead | orchestration + convergence supervision + final-report review/approval | — | -- | Does NOT author the final-report file when `Report writer worker` is in the roster |
+| Claude worker | Answer every brief question across feasibility, requirement interpretation, hidden assumptions, and alternatives — with file:line evidence | broad reasoning depth, hidden assumptions, execution-risk surfacing | claude-worker | `agents/claude-worker.md` |
+| Codex worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | implementation realism, code-path implications, edge cases, technical trade-offs | codex-worker | `agents/codex-worker.md` |
+| Gemini worker | Same core responsibility as Claude worker — identical questions, identical sections 1–5 | requirement interpretation, consistency, safety, alternative viewpoints | gemini-worker | `agents/gemini-worker.md` |
+| Report writer worker | **Authors** the final-report file in Phase 6. NOT an analysis worker. | — | report-writer-worker | `agents/report-writer-worker.md`. Excluded from Phase 4/5 and convergence |
+
+**Model assignment has no default.** The model for every role comes from `resultContract.requiredWorkerRoles[*].modelExecutionValue` in `task-manifest.json` (and lead model metadata). There is no per-role hard-coded fallback — see "Model Assignment Rules" below.
 
 **Dispatch-prompt invariant (BLOCKING).** Lead's dispatch prompt body for Claude / Codex / Gemini workers MUST be byte-identical except for the role label and any wrapper-specific path headers (e.g. `**Worktree:**`, `**Errors sidecar path:**`). Lead MUST NOT bias the brief by inserting per-worker emphasis sentences ("you focus on X") into the body. Bias-by-prompt reproduces the historical failure mode where Claude commented only on assumptions, Codex only on code paths, and Gemini only on requirements — leaving convergence with nothing to converge on.
 
 ### Model Assignment Rules
 
-1. If there is an explicit assignment in `resultContract.requiredWorkerRoles` in `task-manifest.json` and in the lead model metadata, that is the canonical assignment.
-2. If there is no explicit assignment, use the default model above.
-3. If `modelExecutionValue` differs from `model`, use `modelExecutionValue` during execution.
+1. `resultContract.requiredWorkerRoles` in `task-manifest.json` (and the lead model metadata) is the canonical source. There is no role-level fallback — a missing assignment is a manifest defect, not a license to invent one.
+2. If `modelExecutionValue` differs from `model`, use `modelExecutionValue` during execution.
 
 ### Dynamic Worker Role Determination
 
+**Roster canonical-source rule.** The profile's `Required workers:` block (in `prompts/profiles/<phase>.md`) is the **static roster definition** — the set of roles legal for that phase. `resultContract.requiredWorkerRoles` in `task-manifest.json` is the **per-run instance** — the actual roster materialized for this run, after recommendation, user selection, and any post-recommendation overrides. **On conflict, the task-manifest wins** — it is what the run was actually launched with, and what lead must dispatch against.
+
 Only workers selected from `recommendedWorkers` in `task-manifest.json` and `resultContract.requiredWorkerRoles` become required roles.
 
 - If one worker is selected: "`<role>` is the required worker role for this run."
@@ -251,7 +256,11 @@ The same frontmatter contract applies to the `Report writer worker`'s final-repo
 
 A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
 
-0. **Reading Confirmation** — one short line per input file (`task-brief.md`, `analysis-profile.md`, `analysis-material.md` if present, `reference-expectations.md`, `clarification-response.md` if a carry-in was provided, `final-report-template.md`) stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
+0. **Reading Confirmation** — one short line per input file stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. The enumerated files are audience-scoped — they MUST match the recipient's row in the "Audience-scoped enumeration" table above:
+   - **Claude / Codex / Gemini analysis workers**: `task-brief.md`, `analysis-profile.md`, `analysis-material.md` (if present), `reference-expectations.md`, `clarification-response.md` (if a carry-in was provided). Analysis workers MUST NOT include `final-report-template.md` — it is not in their `[Required reading]` block.
+   - **Report writer worker (Phase 6)**: all of the above **plus** `final-report-template.md`.
+
+   If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
 1. Findings
 2. Missing Information or Assumptions
 3. Safe or Reasonable Areas
@@ -341,7 +350,7 @@ without proceeding — this is the contractual replacement for the previous
 empty run-level error logs in production.
 
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra-error-log.py append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
-- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four positional arguments: `<project-root> <model> <prompt-path> [<worktree-path>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt.
+- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is the trace-pane label suffix (e.g. `codex-<role>-trace`); always pass the literal string `worker` so the dispatch is self-describing (the wrapper defaults to `worker` if omitted).
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, so there is no regression for short jobs). Recording responsibilities:
   - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
   - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.
@@ -356,7 +365,7 @@ empty run-level error logs in production.
 2. Re-verification workers follow a constrained response format (verdict + brief explanation).
 3. Workers cannot vote on their own findings (only verify other workers’ work).
 4. The `report writer worker` does not participate in re-verification voting. It is responsible only for generating the final report.
-5. The Claude lead determines the semantic equivalence of findings (this is not delegated to workers).
+5. Division of labor: the Claude lead performs **finding-to-finding matching** (deciding which worker-A finding maps to which worker-B finding for cross-review) and mediates the round protocol; **workers cast the AGREE / DISAGREE / SUPPLEMENT votes** that determine consensus. The lead does NOT vote on substance and does NOT collapse worker disagreements by fiat — disagreements flow into the `contested` / `partial-consensus` classifications defined in `skills/okstra-convergence/SKILL.md`.
 6. Batch processing is performed with one spawn per worker per round (not one spawn per finding).
 7. These rules do not apply if Convergence is disabled.
 
@@ -376,10 +385,13 @@ Every worker result file under `worker-results/` must begin with a standardized
 # <Role> Analysis — <task-key>
 
 **Task:** <task-type>
+**Target:** <path or scope>   <!-- OPTIONAL: include when the run is scoped to a specific file/module -->
 **Date:** <YYYY-MM-DD>
 **Model:** <Role>, <AI model>
 ```
 
+The `Target:` line is optional. Include it when the run is scoped to a specific path or module; omit it when the run spans the whole project. When included, place it between `Task:` and `Date:` as shown.
+
 Examples:
 
 ```markdown
@@ -422,12 +434,12 @@ Token usage is collected from agent session transcripts after the run, NOT from
 At the **start of Phase 7** (persistence), run the helper script with the path to this run's `team-state.json`:
 
 ```bash
-python3 scripts/okstra-token-usage.py \
+python3 "$HOME/.okstra/lib/python/okstra-token-usage.py" \
   <runDirectoryPath>/state/team-state-<task-type>-<seq>.json \
   --write --summary
 ```
 
-(Use the absolute path to `scripts/okstra-token-usage.py` — it lives in `Okstra/scripts/`.)
+The script is installed at `$HOME/.okstra/lib/python/okstra-token-usage.py` by `okstra install`. The previous repo-relative path (`scripts/okstra-token-usage.py`) only exists in a working clone of the okstra repo and is not appropriate for end-user-deployed runs.
 
 The script reads:
 - `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`).

package/runtime/skills/okstra-time-summary/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: false
 
 # OKSTRA Time Summary
 
-Aggregate elapsed work time for a given task, grouped by **task type** and broken down by **worker** (lead, intake, claude-worker, codex-worker, gemini-worker, report-writer).
+Aggregate elapsed work time for a given task, grouped by **task type** and broken down by **worker** (lead, claude, codex, gemini, report-writer).
 
 ## When to Use
 
@@ -19,7 +19,7 @@ Aggregate elapsed work time for a given task, grouped by **task type** and broke
 Two sources, both already collected by `okstra`:
 
 1. `.project-docs/okstra/tasks/<task-group>/<task-id>/history/timeline.json`
-   — lists every run with `runTimestamp`, `taskType`, `status`, `teamStatePath`.
+   — lists every run with `runTimestamp`, `taskType`, `status`, `teamStatePath`, and `taskRootPath`. Both path fields may be either project-root-relative or task-root-relative depending on which version of `render.py` wrote the manifest.
 2. Each run's `.../runs/<task-type>/state/team-state-<suffix>.json`
    — populated by `scripts/okstra-token-usage.py` at Phase 7. Contains:
    - `leadUsage.{startedAt, endedAt, durationMs}`
@@ -64,12 +64,20 @@ If `task-catalog.json` is missing, respond: "No okstra history found. Run `scrip
 
 For each entry in `timeline.json`'s `runs` array:
 
-1. Read the `team-state` file at `teamStatePath` (relative to the project root).
+1. Resolve the `team-state` file using a two-step lookup:
+   a. First try `<projectRoot>/<teamStatePath>`.
+   b. If that file does not exist, fall back to `<projectRoot>/<taskRootPath>/<teamStatePath>` (the manifest's `taskRootPath` field is the task-root relative to project root; `teamStatePath` written by `render.py` is task-root-relative in many runs).
+   Either path satisfies the lookup. If neither resolves to an existing file, treat the run as `unavailable`.
 2. Extract:
    - `taskType` from the timeline entry (authoritative).
    - `leadUsage.durationMs` and `leadUsage.{startedAt,endedAt}`.
    - For each `worker` in `workers[]`: `workerId`, `agent`, `usage.durationMs`.
-3. If the team-state file is missing, or all `durationMs` values are 0/absent, record the run under `unavailable` with its `runTimestamp` and `taskType`.
+   Read defensively. `usage` (and `leadUsage`) may be:
+   - a normal `usage_block` with `durationMs >= 0`,
+   - a `na_block` with `{"source": "unavailable", "durationMs": 0, "note": ...}` when Phase 7 collection failed,
+   - missing entirely (older team-state files), or `None`.
+   Always normalize via `(block or {}).get("durationMs", 0) or 0`, and treat a `source == "unavailable"` block as zero contribution.
+3. If the team-state file is missing, or every `durationMs` for the run is `0`/absent (i.e. `leadUsage` and every `workers[].usage` are zero or unavailable), record the run under `unavailable` with its `runTimestamp` and `taskType`.
 
 ## Step 3: Aggregate
 
@@ -82,20 +90,50 @@ For each distinct `taskType` across runs:
 | Column | Computation |
 |--------|-------------|
 | `Runs` | count of runs of that task type that contributed any duration |
-| `Total` | sum of (lead + all workers) across those runs |
+| `CPU sum` | sum of (lead + all workers) across those runs — see note below |
 | `Lead` | sum of `leadUsage.durationMs` |
 | `Workers` | sum of all `workers[].usage.durationMs` |
 
 Add a final `Grand total` row.
 
+**Note on `CPU sum` vs wall-clock**: workers run as children of the lead session, so the lead's `durationMs` window OVERLAPS its workers' windows. `CPU sum = Lead + Workers` is therefore an additive CPU-style sum, not the wall-clock elapsed time the user actually waited.
+
+Worked example for one run with three concurrent workers:
+
+```
+lead       [================================]  durationMs = 1800000 (30:00)
+claude       [============]                     durationMs =  720000 (12:00)
+codex        [==============]                   durationMs =  840000 (14:00)
+gemini       [========]                         durationMs =  480000 (08:00)
+```
+
+- `CPU sum` for the run = `1800000 + 720000 + 840000 + 480000` = `3840000` (`01:04:00`)
+- Wall-clock for the run = `max(endedAt) − min(startedAt)` ≈ `30:00`
+
+Always report `CPU sum` in the by-task-type table. If the user explicitly asks for wall-clock, compute it per run as `max(leadUsage.endedAt, max(workers[].usage.endedAt)) − min(leadUsage.startedAt, min(workers[].usage.startedAt))` and surface it separately — never silently substitute it for `CPU sum`.
+
 ### B. Per worker breakdown (per task type)
 
-For each task type, list one row per `workerId` actually present, plus `lead` and (if non-zero) `intake`. Aggregate `durationMs` across all runs of that task type.
+For each task type, list one row per `workerId` actually present, plus `lead`. Aggregate `durationMs` across all runs of that task type.
 
 | Worker | Runs | Total | Avg/run |
 |--------|------|-------|---------|
 
-Use the `workerId` from team-state (e.g. `claude`, `codex`, `gemini`, `report-writer`). When the same `workerId` ran with different `agent` values across runs, append the agent in parentheses (`claude (claude)`, `codex (codex)`).
+- `Runs` denominator = number of runs of this task type in which this worker recorded a **nonzero** `durationMs`. A run where the worker's block was `na_block`, missing, or `0` does NOT count.
+- If `Runs == 0` for a worker, **omit the row entirely** rather than dividing by zero.
+- `Avg/run = Total / Runs` (integer ms, then format to `HH:MM:SS`).
+
+Use the `workerId` from team-state. The valid worker enum is `lead, claude, codex, gemini, report-writer`.
+
+Display rule for `workerId` vs `agent`:
+- If every run of this task type used `agent == workerId` for this row, display the bare `workerId` (e.g. `claude`).
+- If `agent` differs from `workerId` (e.g. a `claude` worker slot ran with `agent == "sonnet-eval"`), display `workerId (agent)` — and if multiple distinct agents were used across runs, comma-join them: `claude (sonnet-eval, opus-eval)`.
+
+Never write `claude (claude)` — the parenthesized agent is shown only when it adds information.
+
+### Timestamp parsing
+
+When you need `startedAt` / `endedAt` (e.g. for wall-clock or chronological sort within a task type), normalize the ISO-8601 string before comparing: replace a trailing `Z` with `+00:00`, accept explicit offsets as-is, and parse via `datetime.fromisoformat(s.replace("Z", "+00:00"))`. Strings without an offset are assumed UTC. Mixed-form comparisons must be done as `datetime` objects, never as raw strings.
 
 ## Step 4: Format output
 
@@ -110,19 +148,20 @@ Use the `workerId` from team-state (e.g. `claude`, `codex`, `gemini`, `report-wr
 
 ### By task type
 
-| Task type              | Runs | Total     | Lead     | Intake   | Workers  |
-|------------------------|------|-----------|----------|----------|----------|
-| requirements-discovery | 2    | 00:34:12  | 00:12:08 | 00:01:00 | 00:21:04 |
-| error-analysis         | 1    | 00:18:45  | 00:08:11 | --       | 00:10:34 |
-| implementation         | 3    | 02:11:09  | 00:45:30 | --       | 01:25:39 |
-| **Grand total**        | 6    | **03:04:06** | 01:05:49 | 00:01:00 | 01:57:17 |
+| Task type              | Runs | CPU sum   | Lead     | Workers  |
+|------------------------|------|-----------|----------|----------|
+| requirements-discovery | 2    | 00:33:12  | 00:12:08 | 00:21:04 |
+| error-analysis         | 1    | 00:18:45  | 00:08:11 | 00:10:34 |
+| implementation         | 3    | 02:11:09  | 00:45:30 | 01:25:39 |
+| **Grand total**        | 6    | **03:03:06** | 01:05:49 | 01:57:17 |
+
+`CPU sum` adds the lead window to each worker window even though they overlap; it is not a wall-clock total.
 
 ### Per worker — requirements-discovery
 
 | Worker         | Runs | Total    | Avg/run  |
 |----------------|------|----------|----------|
 | lead           | 2    | 00:12:08 | 00:06:04 |
-| intake         | 1    | 00:01:00 | 00:01:00 |
 | claude         | 2    | 00:09:12 | 00:04:36 |
 | codex          | 2    | 00:07:40 | 00:03:50 |
 | gemini         | 2    | 00:03:12 | 00:01:36 |
@@ -134,8 +173,6 @@ Use the `workerId` from team-state (e.g. `claude`, `codex`, `gemini`, `report-wr
 > Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — team-state has no durationMs (Phase 7 not reached)
 ```
 
-If the `Intake` column is all zero across every task type, omit that column entirely.
-
 ## Output Rules
 
 - Always render durations as `HH:MM:SS`; never raw milliseconds.

package/runtime/templates/reports/settings.template.json

@@ -131,14 +131,14 @@
       "Bash(codex exec:*)",
       "Bash(okstra)",
       "Bash(okstra:*)",
+      "Bash(npx okstra@latest:*)",
+      "Bash(npx -y okstra@latest:*)",
       "Bash($HOME/.okstra/bin/:*)",
+      "Bash(STATE_FILE=:*)",
 
       "Bash(gemini)",
       "Bash(gemini:*)",
 
-      "Bash($HOME/.okstra/bin/okstra-trace-cleanup.sh)",
-      "Bash($HOME/.okstra/bin/okstra-trace-cleanup.sh:*)",
-
       "Bash(claude)",
       "Bash(claude:*)",
 
@@ -150,7 +150,10 @@
     "SessionEnd": [
       {
         "hooks": [
-          { "type": "command", "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh" }
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh"
+          }
         ]
       }
     ]

package/runtime/validators/lib/fixtures.sh

@@ -51,8 +51,7 @@ write_validation_brief() {
 
 - Config file: \`.claude/settings.json\`
   - Expected values:
-    - project-local okstra Claude assets must remain discoverable under \`.claude/skills/\` and \`.claude/agents/\`
-    - refresh should occur only when \`--refresh-assets\` is used
+    - installed okstra Claude assets must remain discoverable under \`~/.claude/skills/\` and \`~/.claude/agents/\` (managed by \`okstra install\`)
 - Config file: \`.project-docs/okstra/discovery/latest-task.json\`
   - Expected values:
     - latest prepared task pointer must include the current task key
@@ -257,6 +256,15 @@ if isinstance(lead, dict):
     lead["status"] = "completed"
 team_state["workflowState"] = "worker-results-collected"
 
+# validate-run.py requires team-state.teamCreate.attempted=true with a
+# status of ok|error once any worker has been dispatched (see
+# validators/validate-run.py:334-337). Mirror that here so the fixture
+# represents a valid post-Phase-3 state.
+team_state["teamCreate"] = {
+    "attempted": True,
+    "status": "ok",
+}
+
 # Phase 7 token-usage collection is normally produced by okstra-token-usage.py.
 # The validator (`team-state.usageSummary is empty`) treats absence as a contract
 # violation, so the fixture must mirror that step with a synthetic-but-valid object.

package/runtime/validators/lib/validate-assets.sh

@@ -1,40 +1,66 @@
 # shellcheck shell=bash
 
+# Verify that the npm build output under `runtime/` is fresh and matches the
+# source files that `okstra install` (src/install.mjs) copies into the user's
+# `~/.claude/skills/`, `~/.claude/agents/`, and `~/.okstra/` directories.
+#
+# Historically this validator checked a *project-local* `.claude/skills/` +
+# `.claude/agents/` tree that `okstra.sh` seeded into the project root on
+# every run. That seeding step was removed when install moved into
+# `src/install.mjs`; install now writes only to the user's
+# `$HOME/.claude` + `$HOME/.okstra`, never to the project root. The runtime/
+# tree is the canonical staging area that `okstra install` rsyncs from, so we
+# validate parity there instead.
 validate_seeded_assets() {
   local validation_mode="$1"
+  local runtime_root="$WORKSPACE_ROOT/runtime"
 
-  python3 - "$SOURCE_ASSET_ROOT" "$PROJECT_ROOT/.claude" "$validation_mode" <<'PY'
+  if [[ ! -d "$runtime_root" ]]; then
+    printf 'runtime/ build output is missing — run `npm run build` before validating.\n' >&2
+    return 1
+  fi
+
+  python3 - "$SOURCE_ASSET_ROOT" "$WORKSPACE_ROOT/skills" "$runtime_root" "$validation_mode" <<'PY'
 from pathlib import Path
 import sys
 
-source_root = Path(sys.argv[1])
-target_root = Path(sys.argv[2])
-validation_mode = sys.argv[3]
+agents_source_root = Path(sys.argv[1])      # <repo>/agents
+skills_source_root = Path(sys.argv[2])      # <repo>/skills
+runtime_root = Path(sys.argv[3])            # <repo>/runtime
+validation_mode = sys.argv[4]
 errors = []
 
-for source_path in sorted(source_root.rglob("*.md")):
-    relative_path = source_path.relative_to(source_root)
-    parts = relative_path.parts
-
-    if relative_path.as_posix() == "SKILL.md":
-        target_path = target_root / "skills" / "okstra" / "SKILL.md"
-    elif parts[0] == "skills":
-        target_path = target_root / "skills" / Path(*parts[1:])
-    elif parts[0] == "workers":
-        # `agents/workers/<name>.md` 는 `.claude/agents/<name>.md` 로 시드된다.
-        # seeding.sh 의 분기와 동일하게 유지해야 한다.
-        target_path = target_root / "agents" / Path(*parts[1:])
-    elif parts[0] == "agents":
-        target_path = target_root / "agents" / Path(*parts[1:])
-    else:
-        target_path = target_root / "skills" / "okstra" / relative_path
 
+def check(source_path: Path, target_path: Path) -> None:
     if not target_path.is_file():
-        errors.append(f"missing seeded asset: {target_path}")
-        continue
-
+        errors.append(f"missing build-output asset: {target_path}")
+        return
     if validation_mode == "match" and target_path.read_bytes() != source_path.read_bytes():
-        errors.append(f"seeded asset content does not match source: {target_path}")
+        errors.append(f"build-output asset does not match source: {target_path}")
+
+
+# 1. Worker agent files: agents/workers/*-worker.md -> runtime/agents/workers/*-worker.md
+workers_source = agents_source_root / "workers"
+workers_target = runtime_root / "agents" / "workers"
+if not workers_source.is_dir():
+    errors.append(f"missing agents/workers source directory: {workers_source}")
+else:
+    for source_path in sorted(workers_source.glob("*.md")):
+        check(source_path, workers_target / source_path.name)
+
+# 2. Lead agent SKILL.md: agents/SKILL.md -> runtime/agents/SKILL.md
+lead_source = agents_source_root / "SKILL.md"
+if lead_source.is_file():
+    check(lead_source, runtime_root / "agents" / "SKILL.md")
+
+# 3. Skill packages: skills/<name>/SKILL.md -> runtime/skills/<name>/SKILL.md
+if not skills_source_root.is_dir():
+    errors.append(f"missing skills source directory: {skills_source_root}")
+else:
+    for skill_dir in sorted(p for p in skills_source_root.iterdir() if p.is_dir()):
+        for source_path in sorted(skill_dir.rglob("*.md")):
+            relative = source_path.relative_to(skills_source_root)
+            check(source_path, runtime_root / "skills" / relative)
 
 if errors:
     for error in errors: