okstra 0.2.0 → 0.4.0

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

@@ -0,0 +1,402 @@
+---
+name: okstra-team-contract
+description: Use when okstra is in Phases 2–5 and needs team operating rules for the Claude lead + worker structure, or when verifying worker roster and model assignments.
+user-invocable: false
+---
+
+# OKSTRA Team Contract
+## When to Use
+
+- During okstra Skill Phases 2–5 (prompt preparation and execution)
+- When verifying worker team composition and operational rules
+- When applying model assignment rules
+
+## Team Structure
+
+okstra tasks are always operated using the `Claude lead` + required worker team structure.
+
+### Role Definitions
+
+| Role | Responsibilities | 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 | Inference quality, hidden assumptions, execution risks | sonnet | claude-worker | `agents/claude-worker.md` |
+| Codex worker | Implementation feasibility, code paths, edge cases | gpt-5.5 | codex-worker | `agents/codex-worker.md` |
+| Gemini worker | Requirement interpretation, consistency, safety, alternatives | 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 |
+
+### 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.
+
+### Dynamic Worker Role Determination
+
+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."
+- If two or more workers are selected: "`<role1>`, `<role2>`, and `<role3>` are required worker roles."
+- If Gemini is selected: "`Gemini worker` must be attempted in this workflow."
+- If Gemini is not selected: "`Gemini worker` is not selected for this run, so it does not need to be attempted."
+
+## Operating Rules
+
+1. `Claude lead` is responsible for orchestration, convergence supervision, and final-report review/approval. It never overrides worker analysis results, and it never authors the final-report file when `Report writer worker` is in the roster.
+2. `Report writer worker` is NOT an analysis worker. It is excluded from Phase 4/5 (initial analysis) and Phase 5.5 (convergence re-verification). It is spawned only in Phase 6 and is the **author** of the final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`.
+3. When `Report writer worker` is in the roster, Lead MUST dispatch it in Phase 6. The only legal lead-authored fallback is when a dispatch was attempted and recorded a terminal status of `error` / `timeout` / `not-run` with a concrete logged reason. Speculative reasons such as "session resume constraint" or "team is no longer alive" are NOT valid — Lead can always dispatch a fresh subagent (omit `team_name` if the team is gone).
+4. The assigned model for each role is maintained based on `resultContract.requiredWorkerRoles` in task-manifest.json and the lead model metadata.
+5. Required roles must not be replaced by unnamed generic parallel workers.
+6. Before dispatching any required worker, persist the exact worker prompt to the assigned current-run prompt history path under `runs/<task-type>/prompts/`.
+7. Before the final decision, collect results or explicit terminal statuses for each required worker role.
+8. If a worker is attempted with status `completed`, `timeout`, or `error`, the corresponding worker prompt history file must actually exist.
+9. If a worker result is `completed`, the corresponding worker result file must actually exist.
+10. Treat `team-state` as the canonical source; if it differs from the report's role label, follow `team-state`.
+11. A validator success status is required before the final completion determination.
+
+## Worker Prompt Composition
+
+Every worker prompt MUST start with the following anchor headers, in this exact order, before any other content:
+
+1. `**Project Root:** <absolute-path>` — absolute target project root (from `{{PROJECT_ROOT}}` in the lead's prompt). Required so the worker can self-anchor without relying on inherited cwd.
+2. `**Prompt History Path:** <project-relative-path>`
+3. `**Result Path:** <project-relative-path>`
+4. `Assigned worker prompt history path: <absolute-path>` — same as the prompt-history path but resolved against `Project Root`. Codex/Gemini wrapper subagents extract this exact line.
+
+The body must include: role name, task type, task key, required bundle paths, assigned model, output contract, evidence handling rules, and any relevant config/deployment expectations from `reference-expectations.md`.
+
+When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
+
+If the task brief contains an `## Available MCP Servers` section, copy that section verbatim into every analysis worker's prompt (and into the report-writer prompt when it is dispatched in Phase 6). Codex/Gemini workers run external CLIs whose MCP availability is governed by their own CLI configs; still forward the section so they can record `MCP not available in this CLI` cleanly when their CLI lacks the matching server.
+
+Before dispatching any required worker, lead persists the exact worker prompt to the assigned current-run prompt history path under `runs/<task-type>/prompts/`. Do not use `/tmp/*prompt*.txt` as the canonical artifact path.
+
+Do not send identical undifferentiated prompts to every worker unless that is clearly the best option. Role-specific emphasis (Phase 2 of `okstra` skill) is the canonical guidance.
+
+### Required reading clause (analysis workers + report-writer worker)
+
+Inject the following clause verbatim into every analysis worker's prompt and into the report-writer worker's prompt. Workers tend to skim long input documents — especially when the carry-in clarification response is structurally similar to the file they will write into next. This clause is the single biggest lever against that failure mode; do not paraphrase it, do not move it lower in the prompt, and do not omit any input file path.
+
+Replace placeholder file paths in the `[Required reading]` block with the actual project-relative paths derived from the run's `instruction-set/` and (if applicable) the carry-in clarification response.
+
+**Audience-scoped enumeration (BLOCKING — performance optimization):**
+
+Different recipients need different files. Do NOT include `final-report-template.md` in analysis worker prompts: analysis workers produce findings (not the final report), and forcing them to read the template inflates token usage without changing finding quality.
+
+| Recipient | Files included in `[Required reading]` |
+|---|---|
+| Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
+| Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
+| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject the `[Required reading]` clause at all** — see [okstra-convergence](../okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
+
+**Asymmetry between claude-worker and codex/gemini-worker prompts (NOT a bug):**
+
+The dispatch prompt the lead constructs for `claude-worker` is intentionally shorter than for `codex-worker` / `gemini-worker`. Do NOT "fix" this by re-injecting `[Required reading]` / `[Error reporting]` / `[Output Contract]` blocks into the claude-worker prompt:
+
+- `claude-worker` is an in-process Claude subagent. The Agent SDK auto-loads `agents/claude-worker.md`, which already contains `## Required Reading Before Any Analysis`, `## Worker Output Structure`, and `## Error reporting`. Re-injecting them is redundant and wastes tokens.
+- `codex-worker` / `gemini-worker` shell out to a CLI. The CLI never sees the agent definition file — it only sees the prompt body passed via stdin. Therefore the lead MUST inject those three blocks into the dispatch prompt for those two workers.
+
+Worker definition file size (claude-worker ~106 lines vs codex/gemini ~175–179 lines) is NOT evidence of incompleteness — it reflects the in-process vs CLI-wrapper distinction.
+
+```
+[Required reading]
+You are required to read every input file listed below from the very first
+character to the very last character before you produce any analysis output.
+Skimming, partial reads, jumping to a single section, or relying on prior
+knowledge of a similar file's structure is not acceptable. Each file may
+contain decisive context that is not surfaced in its summary or first page.
+
+Required files for this run (read in this order, end-to-end, no exceptions):
+
+  1. <Project Root>/<instruction-set>/task-brief.md
+  2. <Project Root>/<instruction-set>/analysis-profile.md
+  3. <Project Root>/<instruction-set>/analysis-material.md   (only if present)
+  4. <Project Root>/<instruction-set>/reference-expectations.md
+  5. <Project Root>/<instruction-set>/clarification-response.md   (only if a carry-in was provided for this run)
+  6. <Project Root>/<instruction-set>/final-report-template.md   (REPORT WRITER ONLY — omit for analysis workers and reverify dispatches)
+
+Reading rules:
+
+  - Use a single Read tool call per file with no offset and no limit. Do not
+    page through the file with offset/limit unless the file is genuinely too
+    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, sub-section
+    5.1 (`A1`, `A2`, ... — material requests), and sub-section 5.2 (`Q1`,
+    `Q2`, ... — user questions) in full, including every row of every table,
+    even if the answer column appears 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 `A*` and `Q*` rows carry context you cannot
+    reconstruct from the new run alone.
+  - 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.
+  - 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,
+    reference-expectations = ground-truth config/deployment values,
+    clarification-response = prior run's open questions and the user's
+    answers, final-report-template = the structure your eventual writeup
+    must conform to). Conflating them loses signal.
+```
+
+### Error reporting clause (analysis workers)
+
+Inject the following clause verbatim into every analysis worker's prompt
+(Claude / Codex / Gemini). All three workers' subagent definitions already
+include the same contract — the prompt clause exists as a redundant safety
+net so any worker dispatched without its custom definition still receives
+identical instructions.
+
+```
+[Error reporting]
+If any tool call you make (Bash, Read, Edit, MCP, etc.) returns a non-zero
+exit code, raises an exception, or otherwise fails its intended effect,
+append a single entry to your worker errors sidecar at:
+
+  runs/<task-type>/worker-results/<role-slug>-errors-<task-type>-<seq>.json
+
+Schema (create the file with {"schemaVersion": 1, "errors": []} if absent):
+
+  {
+    "ts": "<ISO 8601 UTC>",
+    "phase": "<current okstra phase>",
+    "errorType": "tool-failure",
+    "command": "<failed command/tool signature>",
+    "commandKind": "bash | tool:Read | tool:Edit | mcp | ...",
+    "exitCode": <int or null>,
+    "durationMs": <int or null>,
+    "message": "<one-line human summary>",
+    "stderrExcerpt": "<first ~2KB of stderr, or null>",
+    "context": { ... or null }
+  }
+
+Do NOT include source / recordedAt / agent / agentRole / model / taskKey —
+Lead will fill those in. Do NOT use errorType values other than
+"tool-failure" in the sidecar. Continue your task after recording; do not
+abort unless the failure makes the task impossible.
+```
+
+The substituted `<role-slug>` is `claude-worker`, `codex-worker`, or
+`gemini-worker` matching the receiving role.
+
+## Terminal Statuses
+
+Terminal statuses that can be recorded for a worker:
+
+| Status | Meaning |
+|--------|------|
+| `completed` | Normal completion; prompt history file and result file must exist |
+| `timeout` | Timeout, reason recorded; prompt history file must exist |
+| `error` | Execution error, reason recorded; prompt history file must exist |
+| `not-run` | Not executed, reason recorded |
+
+## Worker Output Contract
+
+**Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
+
+A successful worker result must include the following sections in this exact order:
+
+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.
+1. Findings
+2. Missing Information or Assumptions
+3. Safe or Reasonable Areas
+4. Uncertain Points
+5. Recommended Next Actions
+
+Code evidence must include file paths and line numbers.
+
+### Optional errors sidecar (worker-reported)
+
+A worker MAY produce an errors sidecar file at:
+
+```
+runs/<task-type>/worker-results/<role-slug>-errors-<task-type>-<seq>.json
+```
+
+This sidecar collects tool failures observed inside the worker's session
+(non-zero Bash exits, MCP errors, tool exceptions). It is optional — its
+absence does not invalidate a worker result.
+
+Schema:
+
+```json
+{
+  "schemaVersion": 1,
+  "errors": [
+    {
+      "ts": "<ISO 8601 string>",
+      "phase": "<okstra phase 1..7>",
+      "errorType": "tool-failure",
+      "command": "<failed command or tool signature>",
+      "commandKind": "bash | mcp | tool:Read | tool:Edit | ...",
+      "exitCode": <int|null>,
+      "durationMs": <int|null>,
+      "message": "<one-line human summary>",
+      "stderrExcerpt": "<first ~2KB of stderr or null>",
+      "context": { "<freeform>": "..." }
+    }
+  ]
+}
+```
+
+Workers MUST omit `source` / `recordedAt` / `agent` / `agentRole` / `model` /
+`taskKey`. Claude lead fills those in when dumping the sidecar to
+`runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl` via
+`scripts/okstra-error-log.py append-from-worker`.
+
+Workers MUST use only `errorType: "tool-failure"` in the **sidecar file**.
+
+- `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.
+- `contract-violation` events (C) are recorded by Lead via `okstra-error-log.py append-observed --error-type contract-violation ...` after inspecting worker outputs.
+- Lead's responsibility regarding the sidecar is to dump it to the run-level error log via `okstra-error-log.py append-from-worker` after each worker terminates; Lead does not write into the sidecar.
+
+## Convergence Phase Rules
+
+1. Re-verification uses the same worker roles and model assignments as the initial run.
+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).
+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.
+
+## Re-verification Terminal Statuses
+
+| Status | Meaning |
+|--------|------|
+| `verification-completed` | Re-verification vote completed |
+| `verification-timeout` | Re-verification timeout |
+| `verification-error` | Re-verification error |
+
+## Worker Result Header Standard
+
+Every worker result file under `worker-results/` must begin with a standardized header:
+
+```markdown
+# <Role> Analysis — <task-key>
+
+**Task:** <task-type>
+**Date:** <YYYY-MM-DD>
+**Model:** <Role>, <AI model>
+```
+
+Examples:
+
+```markdown
+# Claude Worker Analysis — jobs:tasks:8852
+
+**Task:** error-analysis
+**Target:** server/auth.ts
+**Date:** 2026-04-06
+**Model:** Claude worker, sonnet
+```
+
+```markdown
+# Codex Worker Analysis — jobs:tasks:8852
+
+**Task:** error-analysis
+**Target:** server/auth.ts
+**Date:** 2026-04-06
+**Model:** Codex worker, <codex-model-id>
+```
+
+```markdown
+# Report Writer Worker Analysis — jobs:tasks:8852
+
+**Task:** error-analysis
+**Target:** server/auth.ts
+**Date:** 2026-04-06
+**Model:** Report writer worker, opus
+```
+
+Use the actual model identifier recorded in team-state (never invent a model ID — read it from `resultContract.requiredWorkerRoles[*].modelExecutionValue` or the tool response metadata).
+
+The header is followed by the standard worker output contract sections (Findings, Missing Information, etc.).
+
+## Usage Tracking
+
+Token usage is collected from agent session transcripts after the run, NOT from any in-band Agent-tool response. Neither the Agent tool nor the running session exposes token counts to the lead in real time, so any "estimate" is unreliable. Use the script.
+
+### How to Collect
+
+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 \
+  <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 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`).
+- `~/.codex/sessions/Y/M/D/rollout-*.jsonl` for the underlying Codex CLI session (matched by `cwd` and timestamp window of the wrapper subagent). Last `event_msg.token_count.total_token_usage.total_tokens` is the session total.
+- `~/.gemini/tmp/<project>/chats/session-*.json` for the underlying Gemini CLI session. Sum of per-message `tokens.total`.
+
+### Resulting team-state shape
+
+```json
+{
+  "leadUsage": {
+    "totalTokens": 10479327,
+    "inputTokens": 18,
+    "outputTokens": 24360,
+    "cacheCreationTokens": 612000,
+    "cacheReadTokens": 9842949,
+    "toolUses": 47,
+    "durationMs": 7253000,
+    "source": "claude-jsonl",
+    "sessionId": "<lead-session-id>",
+    "collectedAt": "<utc>"
+  },
+  "workers": [
+    {
+      "workerId": "codex",
+      "usage": {
+        "totalTokens": 2274011,
+        "source": "claude-jsonl",
+        "sessionId": "<wrapper-session-id>",
+        "cliSessionPath": "/Users/.../.codex/sessions/.../rollout-*.jsonl",
+        "cliTotalTokens": 5261833,
+        "cliModel": "gpt-5.5"
+      }
+    }
+  ],
+  "usageSummary": {
+    "leadTotalTokens": 10479327,
+    "workerTotalTokens": 7988699,
+    "grandTotalTokens": 18468026,
+    "sessionsFound": 5,
+    "teamName": "okstra-DEV-9045"
+  }
+}
+```
+
+### Notes
+
+- `totalTokens` in Claude usage blocks is the sum of input + output + cache_creation + cache_read tokens (the cache figures dominate in long sessions).
+- For Codex/Gemini workers, `usage.totalTokens` reflects the **Claude wrapper subagent** spend (the Claude tokens consumed by the codex-worker / gemini-worker subagent itself). The optional `cliTotalTokens` is the underlying CLI's own tokens. They are NOT additive in any meaningful way (different providers, different prices) — keep them separate.
+- If a worker has status `not-run`, the script records an "unavailable" block.
+- If the lead jsonl is missing (e.g. if `lead.sessionId` was never persisted), the script records an "unavailable" block with the searched path. Always populate `lead.sessionId` in team-state at Phase 3 — the okstra.sh launcher already passes it as `CLAUDE_SESSION_ID`.
+- Convergence re-verification agents are dispatched as fresh subagents under the same `teamName` and will be discovered automatically. If you want them split out, set a distinct `agentName` on dispatch and post-process.
+
+### Lead Duration
+
+`durationMs` for the lead is computed from the first to last timestamp in the lead jsonl. If you need wall-clock from run-start to report-completion instead, override `leadUsage.durationMs` after running the script.
+
+## Team State Persistence
+
+Information to be recorded in the team-state JSON file:
+- Current status of each worker role
+- Start/end times for each worker
+- Prompt history path for each worker
+- Path to the result file for each worker
+- Usage metadata for each worker (totalTokens, toolUses, durationMs)
+- Lead usage metadata (totalTokens, toolUses, durationMs) under `leadUsage`
+- Current status of the entire run
+- Path to the run-level error log file (`runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`) under `errorsLogPath`
+- Per-worker errors sidecar path under `workers[].errorsSidecarPath`

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

@@ -0,0 +1,138 @@
+---
+name: okstra-time-summary
+description: Use when the user asks how long an okstra task took, time spent per task type, per-worker elapsed time, or for a duration/runtime breakdown of a specific task-id. Trigger words include "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석".
+---
+
+# 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).
+
+## When to Use
+
+- The user provides a `task-id` (or `task-key`) and asks how long the task took.
+- The user wants to see time spent per phase / task type for a single task.
+- The user wants a per-worker time breakdown for a task's runs.
+
+## Data Sources
+
+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`.
+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}`
+   - `workers[].{workerId, agent, usage.{startedAt, endedAt, durationMs}}`
+
+If a run never reached Phase 7, its `team-state` will not have `durationMs` filled in. Mark such runs as `unavailable` rather than guessing.
+
+## Step 0: Verify okstra runtime + project setup
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` (JSON `{ok, projectRoot, projectJsonPath, projectId}`)
+gives `projectRoot` for locating `.project-docs/okstra/discovery/task-catalog.json`.
+
+## Step 1: Resolve task-id → timeline path
+
+1. If the user gave a full `task-key` (`<project-id>:<task-group>:<task-id>`), use it directly.
+2. Otherwise read `.project-docs/okstra/discovery/task-catalog.json` and find the entry whose `taskId` matches.
+3. If multiple entries match, list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
+4. From the chosen entry, read `historyTimelinePath`.
+
+If `task-catalog.json` is missing, respond: "No okstra history found. Run `scripts/okstra.sh` first."
+
+## Step 2: Walk runs and collect durations
+
+For each entry in `timeline.json`'s `runs` array:
+
+1. Read the `team-state` file at `teamStatePath` (relative to the project root).
+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`.
+
+## Step 3: Aggregate
+
+Build two tables:
+
+### A. Per task-type summary
+
+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 |
+| `Lead` | sum of `leadUsage.durationMs` |
+| `Workers` | sum of all `workers[].usage.durationMs` |
+
+Add a final `Grand total` row.
+
+### 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.
+
+| 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)`).
+
+## Step 4: Format output
+
+- Convert `durationMs` to `HH:MM:SS` (zero-pad). Example: `7384000ms` → `02:03:04`.
+- Sort task types by their order of first appearance in the timeline (chronological, not alphabetical).
+- If any runs were `unavailable`, append a final note listing them with reason (`team-state missing`, `Phase 7 not reached`, etc.).
+
+### Output template
+
+```markdown
+## Time summary — <task-key>
+
+### 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 |
+
+### 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 |
+| report-writer  | 2    | 00:01:00 | 00:00:30 |
+
+### Per worker — error-analysis
+...
+
+> 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.
+- Never invent or estimate `durationMs`. Missing → `--`.
+- Never sum across `unavailable` runs into the totals — those are reported only in the trailing note.
+- Show the resolved `<task-key>` in the heading so the user can confirm disambiguation.