okstra 0.117.0 → 0.119.0

package/docs/container.md

@@ -0,0 +1,124 @@
+# okstra container — CLI Reference
+
+> `okstra container` is a nonlinear tool that launches code from a verified task as a local docker compose group and monitors each container. Because it is a separate entry point from the phase flags in `okstra.sh`, it is documented here rather than in [cli.md](cli.md). See [project-structure-overview](project-structure-overview.md) §4.3 for the module location.
+
+---
+
+## Overview
+
+- **What it is:** Deploys (`up`) the integrated code for a specific task to a task-specific docker compose container group, continuously monitors logs with a watcher for each container, and manages the lifecycle through `status`/`logs`/`stop-watcher`/`down`.
+- **Orchestration only (does not generate files):** **Reuses** the target project's existing `docker-compose.yml`. It does not generate configuration files; if `docker-compose.yml` is missing, it reports what is missing and stops (the same applies if only a `Dockerfile` exists).
+- **Nonlinear:** This is not a phase in `PHASE_SEQUENCE`. Any task key can be launched regardless of whether it has passed verification.
+- **Single entry point:** The `/okstra-container-build` skill, `bin okstra container`, and Python `okstra_ctl.container` all converge on [`scripts/okstra_ctl/container.py`](../scripts/okstra_ctl/container.py) and its `provision_container_group`.
+- **Source of truth (SSOT) for container existence:** Docker labels. `registry.json` is a secondary index containing only tmux sessions/panes/findings.
+
+## Prerequisites
+
+- `docker` / `docker compose` must be installed and operational. `up` fails when they are not installed, but `okstra doctor` emits only `[WARN]` and retains exit code 0 (container functionality is optional).
+- The code for the target task key must be integrated into the task-key worktree HEAD. If there are unintegrated stages, `up` merges them (preserving the stage trees) before continuing; if a conflict occurs, it reports the conflicting files and stops.
+- `docker-compose.yml` must exist at the worktree root.
+
+## Command format
+
+```
+okstra container <up|status|logs|stop-watcher|down> --project-root <PATH> --task-key <KEY> [options]
+```
+
+| sub-command | Behavior | Additional options |
+|---|---|---|
+| `up` | Verify stage integration → validate `docker-compose.yml` → compose env override → `docker compose -p <project> up -d` → poll health checks → start a tail/watcher pane for each container | — |
+| `status` | Show the live container group status by querying Docker labels | — |
+| `logs` | Report `watchersDir` and registered watcher entries as JSON; it does not stream Docker container logs | `--service <NAME>` (filters watcher metadata; all registered watchers when omitted) |
+| `stop-watcher` | Stop the watcher panes for the task (containers remain running) | — |
+| `down` | Tear down the container group and stop attached watchers | `--all` |
+
+## Arguments
+
+### `--project-root` (required)
+Absolute path to the target project root. Required for every sub-command.
+
+### `--task-key` (effectively required)
+Identifier of the task to deploy, in the form `<project-id>:<task-group>:<task-id>`. The default is an empty string, but actual operations require a valid task key.
+
+### `--service` (`logs` only)
+`--service <NAME>` filters the returned watcher metadata by compose service name. When omitted, all registered watcher entries are returned; an unknown name produces an empty `watchers` object.
+
+The actual `logs` output from `logs_container_group()` contains `watchersDir` and registered watcher entries in `watchers`. It does not run `docker compose logs` and does not stream Docker container logs. Inspect each watcher's `findings_path` and the files beneath `watchersDir` for monitoring results.
+
+### `--all` (`down` only)
+Clean up **all** task container groups and watchers within the current project root's `.okstra/` scope. The boundary is limited to the `<project-root>/.okstra/` prefix, so panes belonging to **other projects** in concurrent sessions are never touched. Without `--all`, a single `down` cleans up exactly the panes for the specified task.
+
+## How `up` works
+
+1. **Resolve source tree** — Use the task-key worktree HEAD. Merge unintegrated stages (`teardown=False`, preserving stage worktrees). Stop and identify conflicting files if a conflict occurs (retries are safe because the already-merged operation is idempotent).
+2. **Validate configuration file** — Check for `docker-compose.yml` at the worktree root. If it is missing, stop after identifying the missing filename (do not generate it).
+3. **Scan bind mounts** — If the normalized output of `docker compose config` contains a host path outside the worktree (`../` or an absolute path), **warn and continue** (do not stop; warn that the container may write files to the host).
+4. **Compose env override** — In the okstra-owned worktree, layer task overrides over `.env`, write the result to `env.override`, and pass the files in the order `--env-file <worktree .env> --env-file <env.override>` (the latter takes precedence).
+5. **Deploy** — Run `docker compose -p <project-name> ... up -d`. Obtain the service list from `docker compose config --services` (the canonical source).
+6. **Poll health checks** — Use `docker compose ps` to verify that each service has started. Success means reaching healthy for services with a health check, or `running` for services without one.
+7. **Start monitoring** — If `tmux` is available, start a tail pane and watcher agent for each container in the detached session `okstra-container-<slug>`. If it is unavailable, launch only the containers and state "monitoring disabled (tmux unavailable)" in the result.
+
+### Fixed defaults (not currently exposed as CLI flags)
+
+| Value | Default | Meaning |
+|---|---|---|
+| healthcheck timeout | 120 seconds | Stop and report services that failed to start after this limit |
+| healthcheck interval | 3 seconds | Polling interval for `docker compose ps` |
+| watcher scan interval | 5 seconds | Interval for scanning incremental watcher logs |
+
+> These values exist as named arguments to `provision_container_group`, but because they are not exposed as CLI flags, they currently operate as fixed values.
+
+## watcher (two-stage error trigger)
+
+One watcher per container runs in the detached session.
+
+1. **Lightweight scan** — Fetch incremental logs with `docker compose logs --since` and match only regular expressions (`ERROR`/`FATAL`/`Exception`/`Traceback`/abnormal exit codes, and so on). If there are no matches, proceed to the next interval without an LLM call → zero token cost during healthy periods.
+2. **Deep analysis** — Only when a pattern is detected, the watcher AI analyzes the relevant log window and appends its findings to `findings.md`. Identical error signatures are debounced (meaningful numbers such as HTTP statuses and exit codes are preserved, while only noise such as timestamps and pids is normalized). The watcher **only detects and reports**; it does not modify code or configuration.
+
+Watcher/tail panes carry only the dedicated `@okstra_container_run` tag, so they survive even when a Claude session ends (SessionEnd `--reap`). Stop them with `stop-watcher` or `down`.
+
+## Labels and artifacts
+
+Three labels are attached to deployed containers. The label queries used by `status`/`down` use them to locate the group.
+
+| Label | Value |
+|---|---|
+| `okstra.task-key` | `<project-id>:<task-group>:<task-id>` |
+| `okstra.project-name` | compose project name `okstra-<proj>-<group>-<task>` |
+| `okstra.run-trace` | container session name (`okstra-container-<slug>`) |
+
+All okstra artifacts are stored under `<project-root>/.okstra/tasks/<group>/<task-id>/container/` (the original project files remain unchanged):
+
+```
+container/
+├── env.override            # per-task variables layered over the project .env
+├── registry.json           # tmux sessions/panes/findings (flock-guarded secondary index)
+├── deploy-state.json       # compose project name, running containers, labels
+└── watchers/<service>-findings.md   # per-watcher error analysis log
+```
+
+## Exit behavior/output
+
+Each sub-command writes its result to stdout as JSON and returns exit code 0. Validation failures (missing configuration files, merge conflicts, health check timeouts, and so on) terminate abnormally with a `PrepareError` that identifies what went wrong.
+
+## Usage examples
+
+```bash
+# Deploy and start monitoring
+okstra container up --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# Status
+okstra container status --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# Filter watcher metadata for one service
+okstra container logs --project-root /path/to/proj --task-key proj:auth:login-fix --service api
+
+# Stop only the watcher (keep containers running)
+okstra container stop-watcher --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# Tear down the group
+okstra container down --project-root /path/to/proj --task-key proj:auth:login-fix
+
+# Remove every container group for this project
+okstra container down --project-root /path/to/proj --all
+```

package/docs/contributor-change-matrix.md

@@ -4,12 +4,13 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 
 | Change | Must update | Tests |
 |---|---|---|
-| Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/kr/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
-| Add Node subcommand | `src/cli-registry.mjs`, `src/commands/`, `docs/kr/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
-| Add public skill | `src/lib/skill-catalog.mjs`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README*` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
-| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/kr/cli.md`, `docs/kr/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.py` |
+| Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
+| Add Node subcommand | `src/cli-registry.mjs`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
+| Add public skill | `src/lib/skill-catalog.mjs`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
+| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.py` |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
+| Change Markdown publication policy | `config/docs-publication.json`, `tools/docs_publication/`, affected public Markdown paths | `tests/docs_publication/`, `tests/contract/test_repo_contracts.py` |
 
 `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/follow-ups/2026-07-10-final-report-option-3.md

@@ -0,0 +1,51 @@
+# Final Report Readability Follow-up: Revisit Option 3
+
+Status: On hold
+Date: 2026-07-10
+
+## Background
+
+This initial readability improvement kept the scope narrow.
+
+- Add `readerSummary` at the beginning of the Markdown final report as an entry point for the summary people should read first.
+- Add a Reader Summary dashboard and reader mode to the HTML report view.
+- Keep existing `final-report` data compatible through the `verdictCard` fallback.
+
+This document keeps the larger Option 3 out of the current change and records it as a candidate to reconsider separately later.
+
+## Option 3 on Hold
+
+Reconsider whether to split the `final-report` artifact itself by purpose.
+
+The current structure retains one canonical Markdown document and the view generated from it. Option 3 would compare whether summary blocks and HTML filtering are sufficient, or whether dividing the report into purpose-specific artifacts would be better.
+
+Candidates to compare:
+
+- A short human handoff report and a separate audit appendix.
+- From the same `data.json`, a generated `summary` view and `audit` view.
+- Phase-specific slim report templates that retain only the sections on which people act first.
+- Role-specific view sets such as reporter handoff, implementer handoff, verifier audit, and release handoff.
+
+## Reconsideration Triggers
+
+Reopen this document if any of the following recurs.
+
+- Even after `readerSummary` and HTML reader mode are deployed, users still say that `final-report` is difficult to read.
+- Reviewers consistently skip the same audit sections or request a smaller handoff artifact.
+- The same evidence is repeated across multiple sections when generating `final-report`.
+- A future schema migration requires changing the report artifact contract anyway.
+
+## Questions to Decide
+
+- Should Markdown remain the primary human artifact, or should `data.json` be the sole canonical source with generated views?
+- Which artifact should be attached to follow-up tasks by default?
+- Which sections are human-action material, and which are audit-only material?
+- Should a validator enforce the split, or should it remain a renderer convention?
+- How would the split affect existing `render-views`, follow-up spawning, and approval sidecars?
+
+## References
+
+- Current schema: `schemas/final-report-v1.0.schema.json`
+- Current Markdown template: `templates/reports/final-report.template.md`
+- Current HTML renderer: `scripts/okstra_ctl/report_views.py`
+- Current report UI assets: `templates/reports/report.css`, `templates/reports/report.js`

package/docs/performance-improvement-plan-v2.md

@@ -0,0 +1,374 @@
+# okstra-run Performance Improvement Plan v2
+
+## Index
+
+- [1. Purpose](#1-purpose)
+- [2. Summary of the Current Architecture](#2-summary-of-the-current-architecture)
+  - [2.1 Entry Points](#21-entry-points)
+  - [2.2 Distinguish the Two Kinds of Phase](#22-distinguish-the-two-kinds-of-phase)
+  - [2.3 Cost Characteristics of the Prepare Step](#23-cost-characteristics-of-the-prepare-step)
+  - [2.4 Worker Structure](#24-worker-structure)
+- [3. Performance Bottleneck Hypotheses](#3-performance-bottleneck-hypotheses)
+- [4. Measurement Criteria](#4-measurement-criteria)
+  - [4.1 Measured Results (2026-06-11)](#41-measured-results-2026-06-11-fontradar-v2-api-dev-9186)
+- [5. Improvement Priorities](#5-improvement-priorities)
+  - [P0. Baseline Measurement and Terminology](#p0-baseline-measurement-and-terminology)
+  - [P1. Reduce the Scope of Convergence Reverification](#p1-reduce-the-scope-of-convergence-reverification)
+  - [P2. Prompt Diet: Reduce Analysis Worker Input](#p2-prompt-diet-reduce-analysis-worker-input)
+  - [P3. Fast-track Routing](#p3-fast-track-routing)
+  - [P4. Evaluate Prompt Caching Feasibility](#p4-evaluate-prompt-caching-feasibility)
+  - [P5. Parallelize Prepare Rendering](#p5-parallelize-prepare-rendering)
+  - [P6. Incremental Token Usage Collection](#p6-incremental-token-usage-collection)
+- [6. Parallel Work Plan](#6-parallel-work-plan)
+- [7. P1 Implementation Checklist](#7-p1-implementation-checklist)
+- [8. Risks and Guardrails](#8-risks-and-guardrails)
+- [9. Conclusion](#9-conclusion)
+
+## 1. Purpose
+
+Reduce the perceived cost of cross-verification runs started through the `okstra-run` skill or `scripts/okstra.sh`. This document separates the current architecture into its correct layers and defines improvement priorities, measurement criteria, opportunities for parallel work, and the initial implementation scope.
+
+Key conclusions:
+
+- The largest costs occur after worker dispatch, in repeated verification and long prompt consumption, rather than in the prepare step.
+- First reduce the scope of convergence reverification to lower the number of worker calls and wall-clock time.
+- Fast-track routing, prompt caching, and reductions to templates or worker definitions affect different layers and should be handled as separate work.
+
+## 2. Summary of the Current Architecture
+
+### 2.1 Entry Points
+
+Both `scripts/okstra.sh` and `skills/okstra-run/SKILL.md` call `prepare_task_bundle()` in `scripts/okstra_ctl/run.py`. This single reference point must be preserved.
+
+- `scripts/okstra.sh`: parses CLI arguments, calls `prepare_task_bundle()`, and runs `claude` for non-render-only executions.
+- `okstra-run` skill: collects input in the current Claude session, calls the same Python entry point, and takes over the lead role.
+- Shared prepare logic: `scripts/okstra_ctl/run.py`.
+
+### 2.2 Distinguish the Two Kinds of Phase
+
+The current documentation and code contain two layers with similarly named phases. Performance work must not conflate them.
+
+#### Task-type lifecycle
+
+`PHASE_SEQUENCE` in `scripts/okstra_ctl/workflow.py` contains only the following six task types.
+
+| Order | task-type | Responsibility |
+|---|---|---|
+| 1 | `requirements-discovery` | Classify the work category, route safely to the next phase, and identify missing inputs |
+| 2 | `error-analysis` | Analyze symptoms, root-cause hypotheses, reproduction gaps, and verification paths |
+| 3 | `implementation-planning` | Provide at least two implementation options, trade-offs, execution order, validation/rollback, and an approval request |
+| 4 | `implementation` | Execute the approved plan, commit, run verifier checks, and capture rollback evidence |
+| 5 | `final-verification` | Verify acceptability and residual risk, and decide whether to enter release handoff |
+| 6 | `release-handoff` | Perform the commit/push/PR handoff action selected by the user |
+
+Each okstra invocation performs exactly one task type. Moving to the next task type requires a new invocation.
+
+#### Claude lead operating phases
+
+Phases 1–7 in `prompts/lead/okstra-lead-contract.md` are operating steps that the lead performs within one task-type run.
+
+| Operating phase | Name | Responsibility |
+|---|---|---|
+| 1 | Intake | Read the task bundle |
+| 2~5 | Prompt / Team / Execution / Fallback | Prepare worker prompts, establish the team context, and dispatch workers |
+| 5.5 | Convergence | Reverify worker findings and classify consensus |
+| 6 | Synthesis | Dispatch the report writer or use the lead fallback |
+| 7 | Persist | Collect token usage, substitute final-report placeholders, and finalize manifests/status |
+
+Therefore, "P1 convergence improvement" in this document does not change the task-type lifecycle. It reduces the cost of the lead operating phase defined by `prompts/lead/okstra-lead-contract.md` and `prompts/lead/convergence.md`.
+
+### 2.3 Cost Characteristics of the Prepare Step
+
+`prepare_task_bundle()` writes the instruction set and manifest-related files sequentially.
+
+- Instruction set: `analysis-profile.md`, `analysis-material.md`, `task-brief.md`, optional carry-in/directive, `reference-expectations.md`, `final-report-template.md`, `claude-execution-prompt.md`, and the prompt snapshot.
+- Manifest/discovery: `team-state`, `task-manifest`, `task-index`, `run-manifest`, `timeline`, task catalog, and latest task.
+
+This serial rendering has room for improvement, but it is generally cheaper than external worker dispatch. Render parallelization is therefore not the first priority.
+
+### 2.4 Worker Structure
+
+The four default worker definitions are under `agents/workers/`.
+
+- `claude-worker.md`: Claude subagent.
+- `codex-worker.md`: invokes the Codex CLI through the `okstra-codex-exec.sh` wrapper.
+- `antigravity-worker.md`: invokes the Antigravity CLI through the `okstra-antigravity-exec.sh` wrapper.
+- `report-writer-worker.md`: final-report author. It is not an analysis worker and does not vote in convergence.
+
+## 3. Performance Bottleneck Hypotheses
+
+| ID | Bottleneck | Impact | Evidence / location | Assessment |
+|---|---|---:|---|---|
+| B1 | Each convergence reverify round creates another dispatch per worker | High | `prompts/lead/convergence.md` Round 1-N | **Resolved** — P1 queue pruning implemented and critic serialization parallelized (§4.1 item 2) |
+| B2 | Analysis worker prompts and required reading are long | High | `prompts/lead/okstra-lead-contract.md`, `team-contract`, worker definitions | **Mostly resolved** — analysis-packet-primary measured at 22 KB/worker (§4.1) |
+| B3 | The report writer rereads worker results, convergence, and the final-report template | ~~Medium~~ Low | `prompts/lead/report-writer.md` | **Input compression rejected** — measured reading time is 1–2 minutes and generation dominates (§4.1 item 3) |
+| B4 | Multiple renders/writes run serially during prepare | Low–medium | `scripts/okstra_ctl/run.py` render block | Lower priority |
+| B5 | The token usage collector scans session JSONL linearly | Low–medium | `scripts/okstra_token_usage/` | **Resolved** — P6 incremental cache implemented |
+| B6 | Simple work uses the same full workflow | Medium | task-type lifecycle / requirements routing | Fast-track design needed — largest remaining lever |
+| B7 | The report writer's final-report/data.json **output volume itself** is large (90–140 KB) | High | Measurements in §4.1 item 3 — 8–19 minutes of generation per run | Slim the report contract or select a report-writer model — **user decision required** |
+
+Established assumptions:
+
+- `contested` is not a classification that exists before entry into Round 2. In the current algorithm, `contested` is the final classification assigned to unresolved findings after the maximum round is reached.
+- Therefore, the correct rule is not "Round 2 for contested items only," but "Round 2 only for the verification queue that remains mixed/unresolved after Round 1."
+
+## 4. Measurement Criteria
+
+At minimum, improvement work compares the following metrics before and after the change.
+
+| Metric | Collection method | Target |
+|---|---|---|
+| Worker dispatch count | team-state `workers[]`, convergence state round history, number of prompt files | Fewer reverify dispatches in runs with P1 applied |
+| Wall-clock | team-state worker usage `durationMs`, run start/end timestamps | 20–40% reduction in convergence-heavy runs |
+| Raw tokens | Lead/worker totals from the token usage collector | Fewer worker tokens associated with reverify prompts |
+| Billable equivalent | `usageSummary.*BillableEquivalentTokens` | Confirm a cost reduction |
+| Quality regression | Missing contested/worker-unique items in the final report and validator results | Preserve the existing contract |
+
+Minimum fixtures before implementing P1:
+
+1. Early convergence: a run whose verification queue becomes empty in Round 0 or Round 1.
+2. Mixed/unresolved: a run in which some findings remain after Round 1 and require selective Round 2 processing.
+3. Worker failure: a run in which some reverify dispatches end in `timeout`/`error`.
+
+### 4.1 Measured Results (2026-06-11, fontradar-v2-api dev-9186)
+
+Measurements came from artifact mtimes, team-state `phaseTimeline`, and report-writer session JSONL tool-call timelines for three real runs (requirements discovery, implementation planning, and implementation stage 1).
+
+1. **Wall-clock breakdown by run phase** — In analysis runs, "core analysis" accounts for only 17–24% of wall time: setup 4–6 minutes, analysis 16–24 minutes, convergence plus critic 23 minutes, and report writer 12–24 minutes.
+
+2. **Critic serialization** — The critic was dispatched only after reverification finished, wasting 6–12 serial minutes per run. Because the critic input is fixed to the integrated Round 0 results, dispatch now runs in parallel with the first reverify round (`prompts/lead/convergence.md` §When).
+
+3. **Report-writer generation dominates** — Session tool-call measurements show that reading all input (~404 KB, 16 files) takes **1–2 minutes**, generating data.json (skeleton Write followed by incremental Edit operations per section) takes **8–19 minutes**, and self-verification/audit takes about 3 minutes. B3 input compression would therefore save only about one wall-clock minute and was **rejected**. The remaining output-side lever is B7: slim the report contract (a quality trade-off requiring a user decision) or lower `--report-writer-model` using the existing knob.
+
+4. **Automated measurement** — The Phase 7 collector extracts the lead's `PROGRESS: phase-*` markers and persists them as team-state `phaseTimeline` (`scripts/okstra_token_usage/collect.py :: phase_timeline`). Subsequent runs can measure item 1 through `/okstra-inspect time` instead of manual mtime analysis. The reportWriter surface of `okstra context-cost` was also aligned with the actual dispatch contract (current sequence plus analysis packet).
+
+## 5. Improvement Priorities
+
+### P0. Baseline Measurement and Terminology
+
+Goals:
+
+- Prevent documentation and code from conflating the task-type lifecycle with lead operating phases.
+- Define the P1 baseline by requiring convergence state to expose `effectiveMaxRounds`, `roundsExecuted`, `dispatchCount`, `queueSizeByRound`, and `finalClassificationCounts`.
+
+Primary change candidates:
+
+- `prompts/lead/convergence.md`
+- `prompts/lead/okstra-lead-contract.md`
+- Convergence state schema documentation, if needed
+
+Completion criteria:
+
+- Documentation does not use `contested` as the name of an intermediate queue.
+- The metrics required for before/after comparison are available in the final report or state artifact.
+
+### P1. Reduce the Scope of Convergence Reverification
+
+Goals:
+
+- Immediately finalize findings that can be resolved in Round 1 under the default behavior.
+- Run Round 2 only for the verification queue that remains `mixed` or `unresolved` after Round 1.
+- Do not send findings already finalized as `full-consensus`, `partial-consensus`, or `worker-unique` back to workers.
+
+Current problem:
+
+- For task types with `maxRounds=2`, the documentation does not draw a sufficiently strong boundary between items remaining after Round 1 and already finalized items.
+- If operators interpret the process as "reverify every item," unnecessary redispatches grow in proportion to the worker count.
+
+Improved algorithm:
+
+```text
+Round 0:
+  Parse and group worker results.
+  If two or more workers agree on the same semantics and ticket set, classify it as full-consensus.
+  Put only single-worker findings into the verification queue.
+
+Round 1:
+  Reverify only queued items, batched by worker.
+  all agree/supplement -> classify as full-consensus and remove from the queue.
+  majority agree/supplement -> classify as partial-consensus and remove from the queue.
+  all disagree -> classify as worker-unique and remove from the queue.
+  mixed/error/insufficient evidence -> leave in the unresolved queue.
+
+Optional Round 2:
+  Skip when the unresolved queue is empty.
+  If the unresolved queue is non-empty, reverify only those items.
+  Finally classify items that remain after Round 2:
+    majority agreement -> partial-consensus
+    otherwise -> contested
+```
+
+Round 2 entry conditions:
+
+- `effectiveMaxRounds >= 2`
+- The unresolved queue is non-empty after Round 1.
+- The unresolved cause is not solely worker failure. If every reverify worker returns a terminal non-result, record `verification-error`/blocked evidence instead of dispatching again.
+
+Change targets:
+
+- `prompts/lead/convergence.md`: specify queue pruning after Round 1, the Round 2 gate, and state artifact fields.
+- `prompts/lead/okstra-lead-contract.md`: align the description of `convergence.maxRounds` with queue-pruned behavior.
+- `prompts/lead/report-writer.md`: confirm that the final report records round history and why Round 2 was skipped.
+- Validator or tests only if new convergence state fields become required.
+
+Completion criteria:
+
+- Findings finalized in Round 1 do not appear again in the Round 2 prompt.
+- State contains `skippedReason` when Round 2 does not run.
+- The final report continues to represent all four classifications: `Full Consensus`, `Partial Consensus`, `Contested`, and `Worker-Unique`.
+
+### P2. Prompt Diet: Reduce Analysis Worker Input
+
+Goals:
+
+- Preserve the current rule that analysis workers do not read the final-report template, and keep report-writer-only material out of actual dispatch prompts.
+- Reduce repeated wording in worker definitions while preserving blocking contracts such as path extraction, the model line, and the error sidecar.
+
+Cautions:
+
+- Before extracting `agents/workers/_common.md`, confirm that install/packaging paths and skill/agent loaders support includes.
+- Merely moving text into a separate file can increase cost if the runtime does not inline it and the worker must read another file.
+
+Change targets:
+
+- `agents/workers/codex-worker.md`
+- `agents/workers/antigravity-worker.md`
+- `prompts/lead/team-contract.md`
+- Install/build packaging
+
+### P3. Fast-track Routing
+
+Goal:
+
+- Route work for which the full lifecycle is excessive—such as docs-only changes, typos, and clear one-file fixes—through a shorter path.
+
+Recommended design:
+
+- Rather than arbitrarily skipping the task-type lifecycle, have `requirements-discovery` record an explicit routing token such as `route=lite-implementation-planning` or `route=direct-implementation-planning`.
+- Source edits still occur only in the `implementation` task type.
+- Retain minimum verification through `final-verification` or an equivalent read-only check.
+
+Change targets:
+
+- `prompts/profiles/requirements-discovery.md`
+- `scripts/okstra_ctl/workflow.py`
+- Next-phase selection UI in `skills/okstra-run/SKILL.md`
+- `skills/okstra-status/SKILL.md`
+- Validator expectations
+
+Caution:
+
+- If "fast-track" bypasses the implementation-planning approval gate, it breaks the single reference point and approval contract. Whether to reduce or remove the approval gate requires a separate user decision.
+
+### P4. Evaluate Prompt Caching Feasibility
+
+Goal:
+
+- Use prompt caching only on transports that support it.
+
+Current uncertainty:
+
+- `render.py` renders Markdown files.
+- Codex/Antigravity wrappers pass prompt files to CLI stdin.
+- It is unclear whether API-level metadata such as `cache_control: ephemeral` is actually carried through this path.
+
+Therefore, begin P4 with a spike rather than immediate implementation.
+
+Validation items:
+
+- Whether cache hints can be expressed in Claude Agent dispatch prompts.
+- Whether cache hints have meaning in Codex CLI stdin prompts.
+- Whether Antigravity CLI has a corresponding feature.
+- Whether the token usage collector can observe changes in cache reads/creation.
+
+### P5. Parallelize Prepare Rendering
+
+Goal:
+
+- Parallelize independent file renders/writes in the prepare step.
+
+Cautions:
+
+- `prepare_task_bundle()` remains the single authority, so callers stay unchanged even if work is parallelized.
+- Manifest/discovery rendering shares context and file-order dependencies, so do not combine those operations aggressively.
+- First examine only independent instruction-set writes.
+
+Expected effect:
+
+- Small relative to worker dispatch cost.
+- Potentially noticeable in environments with many render-only smoke tests.
+
+### P6. Incremental Token Usage Collection
+
+Goal:
+
+- Reuse a previous offset or session-summary cache instead of scanning the entire session JSONL every time.
+
+Cautions:
+
+- Accuracy is more important than speed because this connects to final-report placeholder substitution in Phase 7.
+- Do not break aggregation across reruns, retries, or multiple subagent sessions.
+
+## 6. Parallel Work Plan
+
+| Track | Work | Primary files | Parallelism | Prerequisite |
+|---|---|---|---|---|
+| A | P1 convergence queue pruning | `prompts/lead/convergence.md`, `prompts/lead/okstra-lead-contract.md`, report-writer contract | High | P0 terminology cleanup |
+| B | P3 fast-track routing | Requirements profile, workflow/status/run UI | Medium | P0 complete; approval-gate policy decided |
+| C | P5 prepare render parallelization | `scripts/okstra_ctl/run.py`, render tests | High | None |
+| D | P2 prompt diet | Worker definitions, team contract, packaging | Medium | Recommended after P1 |
+| E | P4 prompt-cache spike | Experiments for each wrapper/dispatch path | High | None |
+| F | P6 incremental token usage | `scripts/okstra_token_usage/` | High | Collector fixtures required |
+
+Recommended order:
+
+1. Start with Track A (P1). It directly reduces the largest cost and confines contract changes to documentation and lead operating phases.
+2. Track C (P5) or E (P4 spike) can proceed in parallel.
+3. Track B (P3) changes approval gates and lifecycle semantics, so it requires a separate design review first.
+4. Start Track D (P2) after the prompt contract stabilizes following P1.
+
+## 7. P1 Implementation Checklist
+
+1. Update the Round 1-N pseudocode in `prompts/lead/convergence.md` to use queue pruning.
+2. Do not use `contested` as an intermediate state; use `unresolved` or `mixed-after-round-1` for Round 2 candidates.
+3. Specify the following fields in the convergence state artifact:
+   - `config.effectiveMaxRounds`
+   - `rounds[].inputQueueSize`
+   - `rounds[].resolvedCount`
+   - `rounds[].carriedForwardCount`
+   - `rounds[].dispatches[]`
+   - `rounds[].skippedWorkers[]`
+   - `finalClassificationCounts`
+   - `round2SkippedReason`
+4. Verify that the report-writer contract includes round history and final classification counts in the final report.
+5. Create simple early-convergence and mixed/unresolved fixtures and run a dry run or contract-level test.
+6. Use the token usage collector to record before/after dispatch, token, and wall-clock measurements.
+
+## 8. Risks and Guardrails
+
+- **Correlated hallucination risk**: if a majority of workers reach the same incorrect conclusion in Round 1, less additional verification occurs. The guardrails are opt-in `verificationMode=full-reanalysis` and an evidence quality check.
+- **Worker-failure misclassification risk**: treating a worker timeout/error as disagreement distorts `contested`. Separate terminal non-results into `verification-error` evidence rather than votes.
+- **Fast-track misclassification risk**: incorrectly classifying work as simple can leave approval or verification insufficient. P3 requires a separate policy decision about bypassing the approval gate.
+- **False caching benefit risk**: API-level cache hints may be ignored on CLI stdin paths. P4 requires a spike before implementation.
+- **Validator failure from template reduction**: removing final-report headings or token placeholders can break `validate-run.py` and Phase 7 substitution. P2/P4 must inventory validator contracts first.
+
+## 9. Conclusion
+
+The current plan correctly makes P1 the top priority, but the earlier phrases "7-phase lifecycle" and "contested-only Round 2" did not match the code. The revised plan is ordered as follows.
+
+1. Use P0 to establish terminology and measurement criteria.
+2. Implement convergence queue pruning in P1.
+3. Keep P3 fast-track and P4 prompt caching as follow-up work requiring separate design and verification.
+4. Treat prepare-render parallelization and incremental token usage collection as smaller or end-of-run costs that can proceed as parallel supporting work after P1.
+
+**2026-06-11 update** — Measurements in §4.1 confirm that P0/P1/P6, critic parallelization, and phaseTimeline instrumentation are complete, while B3 (report-writer input compression) was rejected. Only two priorities remain, and both require a user decision first:
+
+1. **B7 — reduce report-writer output-side cost**: slim the report contract (reduce the template/schema and change validator contracts) or lower the default report-writer model. Estimated saving: 5–12 minutes per run.
+2. **B6/P3 — fast-track routing**: shorten the lifecycle for simple work. Requires an approval-gate policy decision.
+
+### Implementation Plan Links
+
+- P0 + P1: implemented in convergence state v1.2
+- P6: implemented in incremental token-usage scanning
+- Critic parallelization + phaseTimeline instrumentation: implemented directly without a plan (2026-06-11; see the corresponding `CHANGES.md` entry)
+- P3 / P4 / P5 / B7: not written; each track requires a separate plan