okstra 0.26.0 → 0.28.0

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

@@ -40,7 +40,8 @@ npx -y okstra@latest install
 This single command populates everything the user needs:
 
 - `~/.okstra/{lib/python, bin, version}` — python + bash runtime
-- `~/.claude/skills/<name>/SKILL.md` — all 11 okstra skills (incl. this one)
+- `~/.claude/skills/<name>/SKILL.md` — all okstra skills (canonical count
+  in `~/.okstra/installed-skills.json`)
 - `~/.okstra/installed-skills.json` — manifest for safe uninstall
 
 The skill should run this even if `~/.okstra/version` already exists —
@@ -72,10 +73,11 @@ them from the env vars.
 ## Step 3: Resolve PROJECT_ROOT
 
 ```bash
-okstra check-project --cwd "$(pwd)"
+PROJECT_ROOT=$(okstra check-project --cwd "$(pwd)" | jq -r '.projectRoot')
 ```
 
-The JSON includes `projectRoot` on success. On failure (`ok: false`,
+The JSON includes `projectRoot` on success. Bind it into the shell so
+Step 4 onwards can expand `$PROJECT_ROOT`. On failure (`ok: false`,
 `stage: "resolve"`) ask the user (`AskUserQuestion`, free text) for an
 absolute project root and rerun with `--cwd <their answer>`.
 
@@ -96,7 +98,11 @@ so overwriting requires manually deleting the file first.
 If the file does NOT exist, ask via `AskUserQuestion`:
 
 - **Question**: `"Project id for okstra (e.g. INV-1234, my-app, okstra)"`
-- **Validate**: slugified must contain at least one alphanumeric character.
+- **Validate**: the answer must be non-empty AND contain at least one
+  alphanumeric character. Re-ask on empty input — `okstra setup --yes`
+  with no `--project-id` exits 1 with
+  `error: --project-id is required (no existing project.json, not a TTY)`,
+  so passing the user's empty answer through is a silent failure path.
 
 Then create the file:
 
@@ -104,6 +110,12 @@ Then create the file:
 okstra setup --yes --project-root "$PROJECT_ROOT" --project-id "$PROJECT_ID"
 ```
 
+> After this, **Steps 4.5–4.8 are all optional**. The built-in defaults
+> work for most projects — skip straight to Step 5 (`doctor`) unless the
+> user explicitly asks to customise worktree sync, declare QA commands,
+> or register a PR-body template. Step 4.7 (settings.local.json symlink)
+> is automatic; it is documented for diagnostic purposes only.
+
 ## Step 4.5 (optional): customise worktree sync dirs
 
 Each okstra run provisions a task-scoped git worktree under
@@ -114,14 +126,14 @@ every task sees the shared state. The built-in default is
 
 To override per-project, add a `worktreeSyncDirs` array to
 `project.json`. Empty array disables the feature; the field is
-preserved across the runtime's auto-upserts (only `projectId`,
-`projectRoot`, `createdAt`, `updatedAt` are runtime-owned).
+preserved across the runtime's auto-upserts (see Step 4.6 for the
+canonical list of runtime-owned fields).
 
 ```json
 {
   "projectId": "...",
   "projectRoot": "...",
-  "worktreeSyncDirs": [".project-docs", ".scratch", ".claude", "my-custom-dir"]
+  "worktreeSyncDirs": [".project-docs", ".scratch", "graphify-out", ".claude", "my-custom-dir"]
 }
 ```
 
@@ -130,7 +142,7 @@ field → built-in default. Only edit when defaults don't cover the
 project's working files (e.g. additional cache or local-config dirs
 that must follow the executor into the worktree).
 
-## Step 4.7 (optional but recommended): declare project QA commands
+## Step 4.6 (optional but recommended): declare project QA commands
 
 `implementation`-phase verifiers run an independent QA gate over the
 executor's diff and need a project-wide baseline of check-only
@@ -178,7 +190,7 @@ The field is preserved across the runtime's auto-upserts of
 `updatedAt` are runtime-owned, so manual edits to `qaCommands`
 survive every subsequent `okstra setup` / `okstra run` invocation.
 
-## Step 4.6 (automatic): project-local Claude settings symlink
+## Step 4.7 (automatic): project-local Claude settings symlink
 
 `okstra setup` (and `okstra run` on its first invocation per project)
 provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
@@ -209,7 +221,7 @@ To opt out (advanced): replace the symlink with a regular file. okstra
 will detect that it is no longer a symlink on its next setup call and
 back it up as `.bak.<timestamp>` rather than overwriting silently.
 
-## Step 4.8 (optional): register a project PR body template
+## Step 4.8 (optional, opt-in): register a project PR body template
 
 `release-handoff` fills the PR body from a template. By default it uses the
 bundled skill template at
@@ -217,6 +229,11 @@ bundled skill template at
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.
 
+**Pre-registration during setup is opt-in.** The same prompt is also
+offered on the first `release-handoff` run in this project, so it is
+safe to defer this step (`나중에`) — most users should skip unless they
+explicitly want to lock the template in now.
+
 Ask the user with `AskUserQuestion` (fixed options, NOT free text — file
 path entry happens in the follow-up plain text prompt per the
 okstra-run prompt convention):
@@ -269,6 +286,8 @@ Inform the user with a short summary:
 |---|---|---|
 | `command not found: npx` | Node missing | Install node 18+. |
 | `okstra ensure-installed` keeps reinstalling | `~/.okstra/version` write fails (permissions) | Check `~/.okstra` ownership and writability. |
-| `ResolverError: project_id required` | empty answer to Step 4 prompt | Re-ask Step 4. |
-| `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually edit the file or pick the existing id. |
+| `error: --project-id is required (no existing project.json, not a TTY)` | `okstra setup --yes` invoked without `--project-id`, or with empty answer to Step 4 prompt | Re-ask Step 4 and pass a non-empty id via `--project-id`. |
+| `projectId mismatch` / `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually delete `<PROJECT_ROOT>/.project-docs/okstra/project.json` to re-register, or re-run with the existing id. |
+| `EACCES` writing under `.project-docs/okstra/` | directory owned by another user (e.g. created by a previous root-shell run) | `chown -R "$USER" <PROJECT_ROOT>/.project-docs` or delete and let setup recreate. |
+| `warning: failed to provision .claude/settings.local.json symlink` | a non-symlink `.claude/settings.local.json` already exists and the backup-and-replace step failed | Inspect `<PROJECT_ROOT>/.claude/settings.local.json{,.bak.*}`; manually merge project-specific rules, then re-run setup. |
 | `npx okstra@latest install` succeeds but `doctor` shows FAIL | runtime/{python,bin,skills} sync not yet performed (pre-release package) | Use dev install: clone the repo and run `node bin/okstra install --link <repo>`. |

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."
@@ -127,19 +132,23 @@ Reading rules:
     large for one read; if you must page, you MUST cover the entire file
     before moving on, and you MUST state the page boundaries you used in your
     Findings section.
-  - For the carry-in clarification response, read sub-section 0 and every
-    row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full,
+  - For the carry-in clarification response, read the conditional
+    `## 0. Clarification Response Carried In From Previous Run` section
+    (rendered only when carry-in is non-empty) and every row of
+    `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full,
     including rows whose `User input` cell is blank. The fact that you
     will write your output into a file with a structurally similar
     section 5 is NOT an excuse to skim — the prior `C-*` rows carry
-    context you cannot reconstruct from the new run alone. If the prior
-    report uses the deprecated `4.5.9 Open Questions` / `5.1` / `5.2`
-    layout with `OQ-*` / `A*` / `Q*` IDs, walk all three blocks the
-    same way (legacy carry-in transitional rule).
-  - Before writing any Findings, state in one sentence per file that you
-    read it end-to-end. Example: "Read task-brief.md end-to-end (147 lines)."
-    If you cannot truthfully say this for a file, do not produce Findings —
-    record a `tool-failure` in the errors sidecar instead.
+    context you cannot reconstruct from the new run alone.
+  - Write the Reading Confirmation block to your **audit sidecar** at
+    `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`
+    (sibling to the main worker-results file). One short line per input
+    file confirming end-to-end reading, e.g. "Read task-brief.md
+    end-to-end (147 lines)." Do NOT include a `## 0. Reading Confirmation`
+    heading in the main worker-results file — the validator now fails
+    worker-results that contain one. If you cannot truthfully confirm a
+    file end-to-end, record a `tool-failure` in the errors sidecar
+    instead of fabricating Findings.
   - Do not collapse multiple input files into a single mental summary before
     reading them all individually. Each file has its own canonical role
     (brief = the user's request, profile = the lead's rules for this phase,
@@ -251,7 +260,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 +354,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 +369,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 +389,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 +438,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.