okstra 0.229.0 → 0.230.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +105 -16
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +11 -18
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/prompts/launch.template.md +5 -5
  16. package/runtime/prompts/lead/convergence.md +4 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  18. package/runtime/prompts/lead/phase-routing.md +1 -1
  19. package/runtime/prompts/lead/report-writer.md +3 -3
  20. package/runtime/prompts/lead/team-contract.md +3 -3
  21. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  22. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  23. package/runtime/python/okstra_ctl/cmux.py +4 -2
  24. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  26. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  27. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  28. package/runtime/python/okstra_ctl/conformance.py +30 -0
  29. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  30. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  31. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  33. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  34. package/runtime/python/okstra_ctl/ids.py +1 -41
  35. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  36. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  37. package/runtime/python/okstra_ctl/locks.py +28 -1
  38. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  39. package/runtime/python/okstra_ctl/paths.py +75 -33
  40. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  41. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  42. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  43. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  44. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  45. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  46. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  48. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  49. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  50. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  53. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  54. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  63. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  64. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  66. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  67. package/runtime/python/okstra_ctl/process_group.py +26 -3
  68. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  69. package/runtime/python/okstra_ctl/recap.py +1 -2
  70. package/runtime/python/okstra_ctl/render.py +10 -2
  71. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  72. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  73. package/runtime/python/okstra_ctl/run.py +24 -20
  74. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  75. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  76. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  77. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  78. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  79. package/runtime/python/okstra_ctl/verification_generation.py +22 -12
  80. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  81. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  82. package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
  83. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  84. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  85. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  86. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  87. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  88. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  89. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  90. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  91. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  92. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  93. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  94. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  95. package/runtime/skills/okstra-run/SKILL.md +6 -6
  96. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  97. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  98. package/runtime/validators/validate-run.py +110 -19
  99. package/docs/cli.md +0 -1060
  100. package/docs/container.md +0 -100
  101. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  102. package/docs/performance-improvement-plan-v2.md +0 -369
  103. package/runtime/python/okstra_ctl/container.py +0 -702
  104. package/runtime/python/okstra_ctl/rollup.py +0 -241
  105. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  106. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  107. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  108. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  109. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  110. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  111. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  112. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  113. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  114. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  115. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  116. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  117. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  118. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  119. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -156,9 +156,10 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
156
156
  - Host and provider registries remain separate: the active registered host owns the native lead session, while non-native providers run through their registered CLI wrappers.
157
157
  - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
158
158
  - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current registered host session and calls `prepare_task_bundle` directly.
159
- - Sixteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-discussion/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-chat/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, `skills/okstra-code-review/SKILL.md`, and `skills/okstra-explain-flow/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, multi-agent discussions that settle requirements before planning, cross-project manager task coordination, global Memory Book storage/search, global chat rooms, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
159
+ - Twelve skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-discussion/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-chat/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, `skills/okstra-code-review/SKILL.md`, and `skills/okstra-explain-flow/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, multi-agent discussions that settle requirements before planning, cross-project manager task coordination, global Memory Book storage/search, global chat rooms, schedule support, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`.
160
+ - Wrapper transcripts are written at `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`.
160
161
  - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
161
- - Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the sixteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-discussion`, `okstra-manager`, `okstra-memory`, `okstra-chat`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-pr-gen`, `okstra-user-response`, `okstra-code-review`, `okstra-explain-flow`).
162
+ - Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the twelve user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-discussion`, `okstra-manager`, `okstra-memory`, `okstra-chat`, `okstra-schedule-gen`, `okstra-pr-gen`, `okstra-user-response`, `okstra-code-review`, `okstra-explain-flow`).
162
163
  - Installation location: `~/.claude/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`.
163
164
  - Release procedure: [`../../RELEASING.md`](../RELEASING.md) — npm publish flow and release-please / manual fallback.
164
165
 
@@ -191,7 +192,7 @@ okstra's prepare stage follows an on-disk authority + single Python entry-point
191
192
 
192
193
  ### JSON ownership and model-facing projections
193
194
 
194
- Project-owned JSON is confined to `<PROJECT_ROOT>/.okstra/`; global indexes and installation metadata remain under `~/.okstra/`. An owned object is read through `okstra_ctl.json_boundary.load_owned_object`, which rejects missing files, invalid UTF-8, non-standard numeric constants, non-object top levels, schema failures, and cross-field failures. The boundary census in `tests/contract/test_json_boundary_census.py` rejects direct JSON parsing and generic atomic-write clones outside the dedicated boundary modules.
195
+ Project-owned JSON is confined to `<PROJECT_ROOT>/.okstra/`; global indexes and installation metadata remain under `~/.okstra/`. An owned object is read through `okstra_ctl.json_boundary.load_owned_object`, which rejects missing files, invalid UTF-8, non-standard numeric constants, non-object top levels, schema failures, and cross-field failures. The boundary census in the retired Python suite rejects direct JSON parsing and generic atomic-write clones outside the dedicated boundary modules.
195
196
 
196
197
  Owned-object writes validate the complete replacement value before publication. `write_owned_object_atomic` writes a temporary sibling, flushes and synchronizes the file, and uses atomic replace so a failed validation or partial write leaves the prior artifact in place. JSON Lines files use the dedicated `okstra_ctl.jsonl` append or rewrite operations because an append-only ledger has a different transaction contract from a replaced object.
197
198
 
@@ -480,7 +481,7 @@ Common constraints:
480
481
  - **Isolated worktree for pre-implementation non-implementation phases (BLOCKING)**: The first pre-implementation non-implementation phase prepare creates a task-key `git worktree`. Pre-implementation non-implementation phases reuse the task-key worktree: `requirements-discovery` → `error-analysis` → `implementation-option-selection` → `implementation-planning` use the same worktree and branch for the same task key. `implementation` does not reuse this task-key worktree; implementation uses a dedicated stage-specific worktree and branch for every stage/run, as described in the next item. The task-key worktree lives at `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (special characters such as `/` and `:` in segments are normalized to `-`), and the branch is named `<work-category-namespace>/<task-id-segment>` (for example, `feature/dev-9436` or `fix/dev-7311`). The namespace is derived from work_category (`feature`·`improvement`→`feature/`, `bugfix`→`fix/`, `refactor`→`refactor/`, `ops`→`ops/`, unspecified→`task/`). The work_category itself is resolved by `work_categories.resolve_work_category` as **explicit `--work-category` → the classification recorded in `task-manifest.json` → `feature`**, so the `task/` fallback is only reached when a task has no recorded classification at all; a run that omits the flag still inherits the namespace `requirements-discovery` classified. The base ref is the commit selected by the user's `--base-ref` during the first phase's prepare. `~/.okstra/worktrees/registry.json` (guarded by flock) manages task-key → path/branch mappings across concurrent runs on the machine. Worktree paths are unique machine-wide; branch names are unique per project id, because a branch only exists inside that project's repository and the same name in another project is a different branch. A real collision inside one repository is caught before the registry, by the branch-existence check in provisioning. Configured sync directories are linked from the main worktree as symlinks to provide filesystem continuity across task checkouts (the sync list can be overridden by `worktreeSyncDirs` in `project.json` or the `OKSTRA_WORKTREE_SYNC_DIRS` environment variable; an empty array disables syncing). This sync does not expand the okstra context/write boundary. Provisioning is skipped when the caller is already inside another worktree or project_root is not a Git repository, and the executor works directly from project_root. The worktree is not automatically deleted after a run; it is the authoritative artifact for later phases, PR authoring, and rollback verification. Manual cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + remove the registry entry. See the *Task worktree* block in `scripts/okstra_ctl/phases/implementation/profile.md` and the *Task worktree (BLOCKING for every task-type)* section in `prompts/lead/okstra-lead-contract.md` for details.
481
482
  - **Isolated implementation-stage worktrees (concurrent parallelism)**: The task-key worktree above is the model for `requirements-discovery` through `implementation-planning`. `implementation` tasks use **stage isolation**: **one run = one stage**, and every run receives an isolated worktree at `.../<task-id-segment>/stage-<N>/` (branch `<work-category-namespace>/<task-id-segment>-s<N>`). The registry reserves task keys and **stage keys** (`<task-key>#stage-<N>`) together under flock. The Stage Lifecycle Snapshot reads `done`/`started` entries in `consumers.jsonl`, carry-sidecar backfills, and reserved registry stages together, and removes them from the ready set (occupancy SSOT = registry). Thus, if the user starts two `implementation` runs simultaneously, they proceed on different independent stages without collision. Base selection: independent = common anchor (HEAD fixed at entry to the first stage); single dependency = predecessor's done commit; multiple dependencies = the predecessors' own commits: the one that already contains the others when there is one, otherwise a branch merging exactly them (`stage_integrate.ensure_stage_merge_branch`, the same primitive release-handoff uses as a PR base). The task branch is not involved, and a predecessor that has not been merged anywhere no longer blocks the stage. The cost-aware-design ready-set batch has been retired because each stage needs an isolated branch and reserving two stage keys on one branch creates a branch-uniqueness collision, so it offers no benefit: sequential work uses the next run after a stage is done, and concurrent work uses separate runs, at equivalent cost. Select a stage with `--stage <auto|N>` or the wizard's `stage_pick`. The wizard's `stage_pick` is a multiselect that labels each stage with its state (`mark_done`/`mark_active`/`mark_ready`/`mark_blocked`), topologically sorts the dependency closure of the selection with Kahn's algorithm (`stage_targets.order_stage_closure`), and exports it as the `chain-stages` CSV in render-args. The `okstra-run` SKILL consumes this queue and sequentially executes N single-stage runs in dependency order as an unattended chain, advancing only after checking the Phase 6 `done` row for each stage. This is an orchestration layer only; the **one run = one stage** isolation invariant of the wizard and prepare remains unchanged. Not only worktrees but also **run artifacts (reports, state, worker results, manifests) are isolated per stage under `runs/implementation/stage-<N>/`**, so reports and state from two concurrently running stages do not mix. In contrast, `consumers.jsonl` and the worktree registry remain at the task-type root (`runs/implementation/`) because they are shared coordination sources of truth across stages.
482
483
  - **Isolation of single-stage final-verification run artifacts (concurrent parallelism)**: Single-stage `final-verification` (`--stage <N>`) also isolates run artifacts under `runs/final-verification/stage-<N>/`, like implementation, with independent sequences per stage, and appends `-fv-s<N>` to the team name. The `-fv-` delimiter prevents collisions with the same stage's implementation team (`-s<N>`) and with the default whole-task verification name. Thus, final-verification for multiple stages can run concurrently without mixing state, worker results, reports, or teams. It does not create a new worktree; it reuses the corresponding implementation stage worktree from the registry read-only and therefore does not reserve a registry stage key. The `-fv-s<N>` suffix on the `teamName` label is only for audit/display distinction. The actual team is the per-session implicit team (`session-<leadSid>`), so the pre-v2.1.178 hard failure caused by a `TeamCreate` name collision no longer occurs. Whole-task verification (empty stage value) retains the existing flat `runs/final-verification/` structure.
483
- - **Final-verification target acquisition seam**: `phases/final_verification/target.py::acquire_final_verification_target()` accepts semantic task identity, the approved plan, the normalized Stage Map, and `stage: int | None`; it derives ledger, registry, worktree, Git, and integration facts behind one task-key `worktree_provision_mutex`. Single-stage acquisition is read-only and whole-task acquisition integrates and tears down completed stage worktrees. `phases/final_verification/entry.py` builds the target request and the render-context fields. `run.py` converts CLI values, computes the diff summary, and writes the snapshot through that entry. The whole-task integration, stage relocation, and containing-stage Git facts it calls stay in `stage_targets.py`, because the container and Phase 7 teardown use them too. The container keeps using the locked `resolve_and_integrate_whole_task()` interface; both interfaces share an internal unlocked implementation so the acquisition path never re-enters the non-reentrant task-key mutex.
484
+ - **Final-verification target acquisition seam**: `phases/final_verification/target.py::acquire_final_verification_target()` accepts semantic task identity, the approved plan, the normalized Stage Map, and `stage: int | None`; it derives ledger, registry, worktree, Git, and integration facts behind one task-key `worktree_provision_mutex`. Single-stage acquisition is read-only and whole-task acquisition integrates and tears down completed stage worktrees. `phases/final_verification/entry.py` builds the target request and the render-context fields. `run.py` converts CLI values, computes the diff summary, and writes the snapshot through that entry. The whole-task integration, stage relocation, and containing-stage Git facts it calls stay in `stage_targets.py`, because Phase 7 teardown uses them too.
484
485
  - Every phase except `implementation` and `release-handoff` prohibits source-code edits, builds, migrations, deployments, and other state-mutating commands (`final-verification` permits read-only test commands only). `implementation` allows edits/commits only within the approved plan's file list; `git push`, publish, deploy, real migration, and third-party write APIs remain prohibited. `release-handoff` does not modify source code and executes only the commit / push / PR commands selected by the user in the menu (force push, direct push to the base branch, hook bypass, and release publication remain prohibited).
485
486
  - Even if the user says something like "continue to the next step," that statement alone does not automatically begin the next phase. The next phase begins only with a new `okstra.sh` execution.
486
487
  - **Authority & permissions assumption (shared by every task type and `okstra-schedule-gen`)**: Assume that the user and team have full authority and approval authority for every anticipated action. Do not include external approvals, third-party access, role/IAM permissions, organizational sign-off, legal/security review, vendor coordination, or questions about whether permission is held in routing decisions, missing inputs, clarification questions, risks, dependencies, open questions, or effort/day estimates. Internal okstra phase handoffs such as the `approved:` frontmatter in `implementation-planning` are gates the user can approve immediately and are unaffected. Forbidden `implementation` actions such as `git push`, production deployment, and shared-DB migration also remain prohibited for **safety reasons**, not permission reasons.
@@ -505,7 +506,7 @@ If a bug is discovered in artifacts after a task has completed release-handoff,
505
506
 
506
507
  ### release-handoff: one stage, one PR
507
508
 
508
- Completed implementation stages no longer retain their worktree directories indefinitely. After successful report validation, Phase 7 reclaims the completed stage's clean worktree while keeping its branch and registry base. Release-ready single-stage verification also reclaims its own worktree; whole-task verification reclaims completed stages without merging during cleanup. Active, failed, dirty, nested, or moved stages are preserved with a reason. Later implementation or verification entry restores the missing directory from the preserved branch. Dependency rebasing therefore does not require a persistent worktree, and a linear whole-task verification restores the containing tip branch rather than creating an extra task-branch merge. Enforcement: `report_finalize._teardown_stage_worktrees`, `stage_targets.teardown_completed_stage_worktrees`, and `tests/worktree/test_stage_rebase.py`.
509
+ Completed implementation stages no longer retain their worktree directories indefinitely. After successful report validation, Phase 7 reclaims the completed stage's clean worktree while keeping its branch and registry base. Release-ready single-stage verification also reclaims its own worktree; whole-task verification reclaims completed stages without merging during cleanup. Active, failed, dirty, nested, or moved stages are preserved with a reason. Later implementation or verification entry restores the missing directory from the preserved branch. Dependency rebasing therefore does not require a persistent worktree, and a linear whole-task verification restores the containing tip branch rather than creating an extra task-branch merge. Enforcement: `report_finalize._teardown_stage_worktrees`, `stage_targets.teardown_completed_stage_worktrees`, and the retired Python suite.
509
510
 
510
511
  `release-handoff` ships stages, not tasks. Each selected stage becomes its own pull request whose head is that stage's stack branch (`<work-category-namespace>/<task-id-segment>-s<N>`), so the PR diff is exactly that stage's commits and nothing is squashed or collected into a bundle branch.
511
512
 
@@ -871,7 +872,7 @@ Checking the following fields first makes it easy to determine the current posit
871
872
  Use `.okstra/discovery/task-catalog.json` to review project-wide state.
872
873
  For the latest state of a specific task, check `.okstra/discovery/latest-task.json`, `task-manifest.json`, the latest `run-manifest`, and `history/timeline.json`, in that order.
873
874
 
874
- In Claude, use the `status` subflow of the seeded `okstra-inspect` skill to answer questions such as:
875
+ Use the task status commands to answer questions such as:
875
876
 
876
877
  - Show all okstra task statuses
877
878
  - Show the current phase and next phase for a specific `task-key`
@@ -893,7 +894,7 @@ New task bundles use `schemas/final-report-v3.0.schema.json` as the final-report
893
894
 
894
895
  - `templates/reports/final-report-v2.template.md` produces the full reading copy Markdown spine in a fixed order: handoff summary, decision context, next-task contract, clarifications, evidence ledger, one task deliverable, cross-verification audit, execution audit, and token/cost audit. The task deliverable body comes from `templates/reports/md/tasks/<task-type>.template.md`, the Markdown sibling of the HTML task template below. Human narrative fields are excluded from this artifact.
895
896
  - Section bodies are rendered as Markdown — headings, tables for uniform row sets, prose for narrative fields — by `scripts/okstra_ctl/report_markdown.py`, never serialized as JSON. Field order within a section comes from the record's versioned schema, whose properties are authored in reading order (a decision draft reads `context → decision → consequences`).
896
- - Each task template names the sections a reading agent should meet first and closes with a `md_rest()` sweep, so a field added to the schema reaches the Markdown without a template edit. **Enforced:** `tests/contract/test_ai_markdown_rendering.py`.
897
+ - Each task template names the sections a reading agent should meet first and closes with a `md_rest()` sweep, so a field added to the schema reaches the Markdown without a template edit. **Enforced:** the retired Python suite.
897
898
  - `templates/reports/html/tasks/<task-type>.template.html` produces the task-specific human-facing HTML. It leads with a plain-language decision summary and presents the selected task's findings, diagrams, tables, evidence, and actions. Worker execution and convergence detail stays in a visually subordinate audit section.
898
899
 
899
900
  The `## 0. Reading Confirmation` block from worker output is written to the sidecar at the resolved `<run-dir>/worker-results/<worker>-audit-<task-type>-<seq>.md`, not included in the report body (enforced by the validator).
@@ -921,7 +922,7 @@ The Phase 7 `render-views` step accepts either a final-report data.json or its M
921
922
  - **Human summary**: `humanSummary` is the sole v2 top-level human summary contract. It is not copied into AI Markdown. Each task view decides how to present it together with the task deliverable instead of sharing a generic dashboard body.
922
923
  - **Audit isolation**: worker execution, convergence, and token/cost material remain available for traceability but are subordinate to the user's findings and decisions. They never replace the task analysis narrative.
923
924
  - **Implementation-planning activity**: activity-contract reports show each agent's task, summary, and outcome in the default view. Commands, exit codes, file-and-line evidence, and result paths remain inside expandable detail. Approval decision cards link to the relevant `id-A-NNN` activity anchors and preserve each option's disposition in the exported user response.
924
- - **Cited ids resolve to a home**: every id the record defines is reachable — a page-global anchor (`#id-<id>`; cross-check consensus and dissent cards are `#id-xv-<id>`) for the rows a view declares in `HumanReportView.anchored_fields`, for the clarification articles, the activity table and the end-state section; a card-scoped anchor (`#id-<parent>-<id>`, `scoped_anchor_fields`) for rows that repeat under every parent, such as a direction's scope commitments; and the evidence ledger for every other row with an id — so prose, citation lists, and table cells link to it (`report_html/common.py` `anchor_index`, `report_html/filters.py`). Enforced by `tests/report/test_report_index.py` over every fixture (every indexed id anchored, every in-page link landing, every defined id reachable) and by `validators/validate-report-views.py` check 7 (no dead in-page link) at Phase 7. Two id families are cited everywhere and defined nowhere in the record, so the renderer follows the two pointers the run pinned (`report_html/context_links.py`): the brief's end-state rows (`EB`/`PB`/`EO`) are read from `<task>/instruction-set/task-brief.md` and rendered once, each joined with this run's `endStateCoverage` verdict (and rendered from the verdicts alone when the task has no brief file), as the "End states" section with `#id-EB-001` anchors, and the clarification ids a previous run settled link to that run's page through `clarificationCarryIn.sourceFile` (`../../<type>/reports/final-report-<type>-<seq>.html#id-C-005`). A missing file yields no rows and no links, never a render failure. Rows that repeat under every parent — a direction's `IC-`/`PI-` rows are numbered from 001 inside each direction — anchor inside their parent's card as `#id-<parent>-<id>` and are linked only from that card's own prose (`common.scoped_anchor_map`, the view's `cardLinks`). Four more link sources fill ids the page defines nowhere: a planning report's selected direction (`selectedDirectionRef.optionId`) links to its card on the option-selection page named by `sourceReport` when that record exists; an implementation report's plan ids (`VC-`, `PI-`, plan items) link to the approved plan's page named by `approvedPlanReference.planFile` when that record exists (`context_links.approved_plan_links`); a worker finding number (`F-NNN`) links to the one `evidence.primary[]` row whose `sourceItems` cite it, and stays text when two rows share it or none does (`common.worker_finding_links`); and a `summary[]` row some field cites by id lands in the ledger as a summary point, while uncited digest rows stay out. Clarification option text (answer, rationale, added work, direction change) goes through the same link filter; the option's `data-option-value` and `<option>` text stay verbatim because they are the response-matching values.
925
+ - **Cited ids resolve to a home**: every id the record defines is reachable — a page-global anchor (`#id-<id>`; cross-check consensus and dissent cards are `#id-xv-<id>`) for the rows a view declares in `HumanReportView.anchored_fields`, for the clarification articles, the activity table and the end-state section; a card-scoped anchor (`#id-<parent>-<id>`, `scoped_anchor_fields`) for rows that repeat under every parent, such as a direction's scope commitments; and the evidence ledger for every other row with an id — so prose, citation lists, and table cells link to it (`report_html/common.py` `anchor_index`, `report_html/filters.py`). Enforced by the retired Python suite over every fixture (every indexed id anchored, every in-page link landing, every defined id reachable) and by `validators/validate-report-views.py` check 7 (no dead in-page link) at Phase 7. Two id families are cited everywhere and defined nowhere in the record, so the renderer follows the two pointers the run pinned (`report_html/context_links.py`): the brief's end-state rows (`EB`/`PB`/`EO`) are read from `<task>/instruction-set/task-brief.md` and rendered once, each joined with this run's `endStateCoverage` verdict (and rendered from the verdicts alone when the task has no brief file), as the "End states" section with `#id-EB-001` anchors, and the clarification ids a previous run settled link to that run's page through `clarificationCarryIn.sourceFile` (`../../<type>/reports/final-report-<type>-<seq>.html#id-C-005`). A missing file yields no rows and no links, never a render failure. Rows that repeat under every parent — a direction's `IC-`/`PI-` rows are numbered from 001 inside each direction — anchor inside their parent's card as `#id-<parent>-<id>` and are linked only from that card's own prose (`common.scoped_anchor_map`, the view's `cardLinks`). Four more link sources fill ids the page defines nowhere: a planning report's selected direction (`selectedDirectionRef.optionId`) links to its card on the option-selection page named by `sourceReport` when that record exists; an implementation report's plan ids (`VC-`, `PI-`, plan items) link to the approved plan's page named by `approvedPlanReference.planFile` when that record exists (`context_links.approved_plan_links`); a worker finding number (`F-NNN`) links to the one `evidence.primary[]` row whose `sourceItems` cite it, and stays text when two rows share it or none does (`common.worker_finding_links`); and a `summary[]` row some field cites by id lands in the ledger as a summary point, while uncited digest rows stay out. Clarification option text (answer, rationale, added work, direction change) goes through the same link filter; the option's `data-option-value` and `<option>` text stay verbatim because they are the response-matching values.
925
926
  - **Implementation-option-selection cards**: each ranked direction reads as four blocks — what it changes (goal, expected change areas, scope commitments), how it is done (core mechanism, architecture boundaries), why it ranks where it does (criterion scores beside the criterion weights, feasibility votes with counterevidence, safety blockers, unresolved facts), and the expected outcome (coverage count and verdict, requirement coverage, planning invariants). The evaluation criteria and their weights render as their own section before the ranking, the direction picker shows each option's goal, and the candidate audit shows each rejected candidate's goal.
926
927
  - **Schema v1 compatibility**: existing v1 data and quick Markdown reports keep the legacy conditional renderer, including `readerSummary`, reader modes, and the original Markdown-parsing path.
927
928
  - **`C-*` select option order (schema v1)**: the legacy renderer parses `Expected form`, puts the `Recommended:` answer **first**, and relabels the `Alternatives:` items consecutively as `(a)`, `(b)`, and so on (the original character labels are not retained). Schema v2 parses nothing here — a `Kind=decision` row carries `options[]`, and the presentation order is the array order with the `role: recommended` entry first.
@@ -962,12 +963,12 @@ Errors that occur while provider workers, the report writer, or the Okstra lead
962
963
  - **Memory cap and leftover processes** (`scripts/okstra_ctl/process_group.py`): every 2 seconds the runner sums the RSS of the worker's process group, which includes the builds, servers and test harnesses the worker started. Above the cap it SIGKILLs the whole group, returns exit code 71, and marks the status sidecar `{terminated_by: "memory-cap", failure: "memory-cap exceeded: …"}`. The cap is `workerMemoryCapMb` (MB, `0` disables it), read from the project's `.okstra/project.json` first and then `~/.okstra/config.json`; without either the cap is 8 GB or half of physical memory, whichever is smaller. When the worker process ends, the runner SIGKILLs whatever is still in its group and records `leftoverProcessesKilled: true`, so a build worker orphaned by the worker cannot keep growing. A process that starts its own session leaves the group and is not covered, and native-session workers are not spawned by the runner.
963
964
  - The `.log` is an execution transcript containing wrapper/CLI output, not the original prompt. `okstra log-report` pairs it with the sibling persisted `.md` prompt and reports `transcriptBytes`, `promptBytes`, and their ratio separately. The compatibility fields `path`, `sizeBytes`, and `totalBytes` continue to mean transcript data, so existing consumers and transcript-size ordering remain stable.
964
965
  - **Run-wide cap on the progress copy in the log** (`_LOG_PROGRESS_LINE_CAP` in `scripts/okstra_ctl/worker_runner.py`): workers read their required inputs end-to-end per the Worker Preamble's *Reading rules*, so a single report read can dump 170KB+ into the log and observed sidecars reach 8MB. The runner archives the first 5000 progress lines of the run and replaces the rest with a `[okstra log-cap] N progress line(s) elided` marker, emitted every 500 elided lines so a reader tailing the log can see the run is still producing. The cap is run-wide rather than per-block because a block boundary is a provider's own vocabulary and the shared runner has none; the cost is that a very long run keeps its opening rather than a sample throughout, which the elision notices make visible. **Only the log copy is capped** — never the screen, and never the result stream, because a truncated tool echo costs detail while a truncated answer costs the whole post-mortem.
965
- - **Progress lands in the worker's own pane, not in a sibling tail pane.** The presentation is passed to the entrypoint as `--presentation live|quiet`; `live` is claimed only by a backend that opened a pane, and the default is `quiet`. Under `live` the runner renders each event into one readable row on the caller's own streams (`→ Bash: …` for a tool call, ` ← ok (N bytes)` for its result, `!! PERMISSION DENIED — <tool>: <reason>` for a refusal); thinking events are dropped. Under `quiet` progress is withheld and only the worker's closing text is printed, which is what a `cli-wrapper` dispatch on a machine with no pane surface needs. `scripts/okstra_ctl/domain/worker_stream.py` owns all three projections (`format_live`, `format_log`, `final_text`) as pure functions over *normalised* events — `Text`, `ToolCall`, `ToolResult`, `Denial`, `Result`. Providers do not share a wire format and this layer may not name one, so each adapter supplies the function that turns its own events into those, declared on `ExecCommand.normalise` beside the stream format it belongs to. Adding a provider whose stream is shaped differently is that one function; a provider that declares `stream-json` without one is failed by `tests/contract/test_provider_execution_contract.py`, which runs the schema each provider claims through its own normaliser and requires rows out.
966
+ - **Progress lands in the worker's own pane, not in a sibling tail pane.** The presentation is passed to the entrypoint as `--presentation live|quiet`; `live` is claimed only by a backend that opened a pane, and the default is `quiet`. Under `live` the runner renders each event into one readable row on the caller's own streams (`→ Bash: …` for a tool call, ` ← ok (N bytes)` for its result, `!! PERMISSION DENIED — <tool>: <reason>` for a refusal); thinking events are dropped. Under `quiet` progress is withheld and only the worker's closing text is printed, which is what a `cli-wrapper` dispatch on a machine with no pane surface needs. `scripts/okstra_ctl/domain/worker_stream.py` owns all three projections (`format_live`, `format_log`, `final_text`) as pure functions over *normalised* events — `Text`, `ToolCall`, `ToolResult`, `Denial`, `Result`. Providers do not share a wire format and this layer may not name one, so each adapter supplies the function that turns its own events into those, declared on `ExecCommand.normalise` beside the stream format it belongs to. Adding a provider whose stream is shaped differently is that one function; a provider that declares `stream-json` without one is failed by the retired Python suite, which runs the schema each provider claims through its own normaliser and requires rows out.
966
967
  - **No okstra pane carries a tag any more, and the tag scan is gone with them.** Two writers disappeared at different times. The wrappers stopped splitting a `tail -F` sibling, so **nothing spawns a trace pane** and `@okstra_trace_run` / `@okstra_status` lost their writer — the operator watches the worker pane itself instead. Then the pane-tagging dispatch backend was removed, so `@okstra_worker_run` went with it: a worker now gets a cmux surface or a cli-wrapper subprocess, and okstra tags neither. `okstra-trace-cleanup.sh` therefore no longer scans tags at all, and the two modes that existed only for that scan were removed — `--reclaim-completed` (with the `okstra-subagent-reclaim.sh` entry that drove it from `SubagentStop` / `TaskCompleted`) and `--reap` (with its `SessionEnd` entry). Both hooks are gone from `templates/reports/settings.template.json`, which now seeds only the `SessionStart(compact)` reminder.
967
968
  - **What cleanup does — okstra's own worker panes**: `okstra team reclaim --project-root <root> --run-manifest <path>` closes the cmux panes this run opened for its workers, and only those whose dispatch has reached a terminal status. The candidates are the `paneId` values recorded in `team-state.workerDispatches[]`, so nothing is discovered by scanning: a title sweep would be worse than nothing, because cmux labels its own agent surfaces with the same glyph the harness uses for a teammate pane and a sweep could close the lead (`team._reclaimable_panes`). A pane the harness opened for its own teammate (`runner: native-session`, which okstra's dispatcher refuses and hands to the host) carries no recorded id and is not okstra's to close. `--dry-run` prints the same `<paneId>\t<kind>` set without closing. At every worker round boundary — after collecting that round's results and token usage, immediately before the next dispatch — the lead runs the closing pass, which records `phase-batch-cleanup panes=<n>` with the number it closed and prints the line for the lead to emit. Closing also gives the lead its width back: cmux hands freed width to a neighbour it picks, and that neighbour is not always the lead. See [ADR-0012](../.project-docs/adr/0012-pane-reclaim-scope.md).
968
969
  - **Cleanup survives compaction and precedes user gates**: A `SessionStart` hook with matcher `compact` (`okstra-compact-reminder.sh`, seeded in `settings.template.json`) fires after every `/compact` or auto-compaction. It reads `cwd` from the hook's stdin JSON and asks `pane_reclaim.in_flight_run_dirs` for that project's runs that still hold a non-terminal dispatch — the newest `team-state` per run directory decides, because sequences accumulate and an earlier round's `in-progress` rows stay on disk. If one exists it prints a factual reminder naming the run dir and the `okstra team reclaim` call, restoring the boundary/gate obligation that a compaction summary can otherwise drop. The hook never closes a pane itself; the closing stays with the lead, which holds the run manifest. The signal is the run directory rather than `~/.okstra/active.jsonl`: an in-session run is registered `prepared` (because `render-bundle` forces `--render-only`), `prepared` routes to `recent.jsonl` as terminal, and that ledger was measured empty while 310 runs sat in `recent.jsonl` — see [ADR-0011](../.project-docs/adr/0011-in-flight-run-source-of-truth.md). Separately, the lead runs `okstra team reclaim --gate` immediately before any user approval/clarification/decision gate; it prints `PROGRESS: phase-gate-cleanup panes=<n>` and records no batch cleanup. At every cleanup point the pane close and the task stop (`TaskStop`) are paired — a `TaskStop` alone idles the roster task and closes no pane.
969
970
  - **User confirmation at phase end**: At the final step of the run, the lead calls `okstra team teardown --project-root <root> --run-manifest <path> --dry-run` to show the panes this run recorded, then asks once whether to "close all and clean up teammates / keep them." Unlike the round boundary, teardown's set is every recorded pane regardless of status — the run is ending, so none is expected to continue — and it also writes off any dispatch that never reached a terminal status. If approved, the lead runs the same command without `--dry-run`, then sends each completed teammate a `SendMessage` shutdown_request (`TeamDelete` was removed in v2.1.178; the implicit team disappears with the session). A `cli-wrapper` run recorded no pane, so the command safely reports an empty set.
970
- - Disk accumulation is handled by the `okstra-inspect logs` flow, which offers a read-only inventory and suggests cleanup commands for the user to copy and paste.
971
+ - Use `okstra log-report` to inspect disk accumulation.
971
972
 
972
973
  ### Linked-worktree `.git/` write permissions
973
974
 
@@ -992,9 +993,8 @@ Tokens used in each run are collected from lead/worker session transcripts and w
992
993
  - CLI providers (codex, grok, kimi) report cache reads inside their input count (`cached_input_tokens ⊂ input_tokens`). Their usage blocks carry the same keys as a Claude block — `totalTokens` with the cached part removed, `cacheReadTokens`, and `billableEquivalentTokens` normalized by that model's own rate ratios (`provider_billable_equivalent`) — so the report's cache-read and billable columns are filled for every agent. Their cost stays in `cliEstimatedCostUsd` and on the report's separate CLI row.
993
994
  - Pricing is centrally managed in `scripts/okstra_token_usage/pricing.py` (Claude and Gemini rate tables) and in each provider catalog's `ModelSpec(pricing=...)` (codex, grok, kimi — merged through `catalog_pricing`). Update it when model prices change. Model IDs that fail price matching are exposed to the user in `usageSummary.unmatchedModels`, preventing silent-zero incidents.
994
995
  - **Cost is always the public list price, regardless of how the account is billed.** The report answers "how much was consumed", not "what the invoice says": a model served under a ChatGPT/Claude subscription is still priced at its API rate, so every selectable catalog row must carry a price. The one row without a price is `codex-auto-review`, for which no public rate exists.
995
- - Project-wide historical usage is exposed through the read-only `okstra usage-report` command (`scripts/okstra_ctl/usage_report.py`) and the `okstra-usage` skill. It defaults to the whole current project's last 30 days and returns run coverage, raw and billable-equivalent tokens, known USD cost, CPU-sum milliseconds, and wall-clock milliseconds grouped by task type. Runs without usable Phase 7 usage are excluded from resource totals and reported through unavailable reason counts rather than treated as zero usage; unmatched model names remain visible when their tokens and time are included but their cost is not. Use `okstra-inspect` for one task's elapsed/context detail and `okstra-rollup` for task-group or project status/report digests.
996
996
  - **Incremental scan cache (P6)**: To avoid rescanning session jsonl files, a per-file byte cursor and the extracted usage events before windowing are stored in `$OKSTRA_HOME/cache/token-usage/<transcript-dir>/<sessionId>.json` (`scripts/okstra_token_usage/cursor.py`). The run window (since/until) is reevaluated over events on every invocation, so even if a rerun narrows the window, the total matches a full scan. The cache is derived data; identifier mismatch, truncation, or corruption automatically falls back to a full rescan, and `okstra-token-usage.py --no-cache` forces a bypass.
997
- - **Phase timeline (P0 instrumentation)**: The collector extracts `PROGRESS: phase-*` checkpoint lines (see "Progress reporting" in prompts/lead/okstra-lead-contract.md) from the lead session jsonl scoped to the run window, and records them in team-state as a `phaseTimeline` block (`{source, phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`) (`scripts/okstra_token_usage/collect.py :: phase_timeline`). This provides measurement points for per-phase wall-clock time within the run and is consumed by the "Per-run phase breakdown" in the `okstra-inspect` time facet. Runs without markers explicitly report that measurement is unavailable with `phases: []`.
997
+ - **Phase timeline (P0 instrumentation)**: The collector extracts `PROGRESS: phase-*` checkpoint lines (see "Progress reporting" in prompts/lead/okstra-lead-contract.md) from the lead session jsonl scoped to the run window, and records them in team-state as a `phaseTimeline` block (`{source, phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`) (`scripts/okstra_token_usage/collect.py :: phase_timeline`). This provides measurement points for per-phase wall-clock time within the run and is available to `okstra time-report`. Runs without markers explicitly report that measurement is unavailable with `phases: []`.
998
998
 
999
999
  ## Validators
1000
1000
 
@@ -1013,7 +1013,7 @@ The split is not made by the individual checks. Every check appends to one flat
1013
1013
 
1014
1014
  The registration test is a sentence, not a severity feeling: **which consumer outside the validator breaks when this value is wrong?** Registered fragments name one — a renderer with no input (`final-report data.json is missing`), a gate whose result cannot be read (`conformance gate BLOCKING`, `self-mock gate BLOCKING:`), a release path opened on an unverified value (`final-verification report declares`, `` `verdict: FAIL` but `finalVerdict.verdictToken` is ``), a successor stage that cannot be prepared (`implementation run declares stage-`). Where the only reader is the validator itself or the report projection — a cross-reference link, an `Evidence checked:` line, a heading that reads differently — the finding is advisory by construction. ADR-0024 states the same rule from the other side: a display title is never a blocking reason.
1015
1015
 
1016
- Fragments are substrings, so an over-broad fragment silently promotes neighbouring checks that happen to share a prefix. Each entry therefore carries a written consumer sentence next to it, and the fragment is chosen from a message string that actually exists. **Enforced:** `tests/contract/test_validate_run_conformance.py::test_every_blocking_fragment_is_producible` reconstructs every string expression in `validators/` and `scripts/okstra_ctl/` from the AST (excluding the allowlist module itself, so the check cannot pass by finding its own copy) and rejects a fragment no validator can emit; `::test_report_bookkeeping_failures_do_not_block` and `::test_a_broken_or_missing_artifact_still_blocks` pin the two sides of the partition.
1016
+ Fragments are substrings, so an over-broad fragment silently promotes neighbouring checks that happen to share a prefix. Each entry therefore carries a written consumer sentence next to it, and the fragment is chosen from a message string that actually exists. **Enforced:** the retired Python suite reconstructs every string expression in `validators/` and `scripts/okstra_ctl/` from the AST (excluding the allowlist module itself, so the check cannot pass by finding its own copy) and rejects a fragment no validator can emit; `::test_report_bookkeeping_failures_do_not_block` and `::test_a_broken_or_missing_artifact_still_blocks` pin the two sides of the partition.
1017
1017
 
1018
1018
  `contractValidation.status=failed` means the run artifact contract failed; it does not necessarily mean the implementation itself is incomplete. An implementation run derives `phaseOutcome.implementation` from `runs/implementation/carry/stage-<N>.json`, `runs/implementation-planning/consumers.jsonl`, and the approved Stage Map together. If every Stage Map stage has pass-grade carry evidence, it can retain the contract failure as audit information while raising `workflow.nextRecommendedPhase.status` to `ready`. It does not choose the phase: the reconciler's fact is that every stage finished, and the destination was already settled by the last stage's report routing, so it leaves `phase` untouched and raises the status only when `phase` is non-empty.
1019
1019
 
@@ -1044,7 +1044,6 @@ Fragments are substrings, so an over-broad fragment silently promotes neighbouri
1044
1044
  - Token-usage and cost accounting are handled by `scripts/okstra-token-usage.py` and the Node wrapper `okstra token-usage`.
1045
1045
  - `okstra.sh` requires an absolute projectRoot to anchor worker CLI calls.
1046
1046
  - `okstra wizard step` **requires** `--answer <val>`. To peek at the next prompt when it is not time to respond, use `--no-submit`.
1047
- - `/okstra-inspect history` supports task-manifest fallback / pagination / filters, and resolves `--base-ref` from the worktree registry.
1048
1047
  - All writes to the user's project occur only inside `<PROJECT_ROOT>/.okstra/` (see the Artifact-home rule).
1049
1048
 
1050
1049
  ## Related documents
@@ -6,12 +6,12 @@ Use this matrix before changing high-risk repo contracts. Update the source file
6
6
  |---|---|---|
7
7
  | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
8
8
  | Add Node subcommand | `src/cli-registry.mts`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
9
- | Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/skills/<name>.md`, `docs/skills/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
9
+ | Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/skills/<name>.md`, `docs/skills/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs` |
10
10
  | Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/cli-wrapper-contract.test.mjs`, `tests/test_okstra_manager_*.py` |
11
- | Change a skill's behaviour | `skills/<name>/SKILL.md`, `docs/skills/<name>.md` (every Guarantees row names its enforcement or says `unenforced`) | `tests/contract/test_skill_specs.py` |
12
- | Add phase | `scripts/okstra_ctl/phases/catalog.py`, `scripts/okstra_ctl/workflow.py`, `scripts/okstra_ctl/phases/<package>/` (`profile.md`, `profile.json`, `spec.md`, policy, report assets and tests), common assembly in `validators/`, `tests/contract/test_phase_catalog.py` | workflow and validation contract tests |
13
- | Change role requirements | `scripts/okstra_ctl/phases/<package>/profile.json`, `scripts/okstra_ctl/role_requirements.py`, `tests/contract/test_repo_contracts.py` | role requirement contract tests |
14
- | Change phase policy | `scripts/okstra_ctl/phases/<package>/`, its `spec.md`, and the common caller; continuation decisions belong in `prompts/lead/phase-routing.md` | phase-local tests, `tests/contract/test_phase_catalog.py`, `tests/contract/test_skill_specs.py` |
11
+ | Change a skill's behaviour | `skills/<name>/SKILL.md`, `docs/skills/<name>.md` (every Guarantees row names its enforcement or says `unenforced`) | unenforced |
12
+ | Add phase | `scripts/okstra_ctl/phases/catalog.py`, `scripts/okstra_ctl/workflow.py`, `scripts/okstra_ctl/phases/<package>/` (`profile.md`, `profile.json`, `spec.md`, policy, report assets and tests), common assembly in `validators/` | workflow and validation contract tests |
13
+ | Change role requirements | `scripts/okstra_ctl/phases/<package>/profile.json`, `scripts/okstra_ctl/role_requirements.py` | role requirement contract tests |
14
+ | Change phase policy | `scripts/okstra_ctl/phases/<package>/`, its `spec.md`, and the common caller; continuation decisions belong in `prompts/lead/phase-routing.md` | phase-local tests |
15
15
  | Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
16
16
  | Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`cli.mjs`, `baseline.mjs`, `config.mjs`, `markdown.mjs`, and the shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`cli`, `config`, `markdown`, and `skill`) |
17
17
 
@@ -93,7 +93,6 @@ okstra/
93
93
  - `docs/architecture.md`
94
94
  - `docs/architecture/`
95
95
  - `docs/cli.md`
96
- - `docs/container.md`
97
96
  - `docs/performance-improvement-plan-v2.md`
98
97
  - selected contributor and follow-up documentation paths
99
98
  - `README.md`
@@ -207,11 +206,9 @@ The Module column below is where the command's behaviour lives — a `src/` modu
207
206
  | `spawn-followups`, `error-log` | `scripts/okstra-spawn-followups.py`, `scripts/okstra-error-log.py` | Follow-up task bundle creation and run error-log append helpers |
208
207
  | `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
209
208
  | `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (default `templates/pr/pr-body.template.md`, shared with release-handoff), base-branch recommendation, and a fixed-text generation bundle — template, `<base>..<head>` commits, `<base>...<head>` diffstat and the `templates/pr/drafting-rules.md` drafting rules — used by the okstra-pr-gen skill and the release-handoff lead; `check` lists okstra identifiers left in a drafted body. `--json` preserves the same fields as a machine contract. Git-only; no project registration required |
210
- | `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` is a read-only phase-transition summary for a task or, with `--task-group`, the group's start order plus each task's latest conclusion; `record` appends one line to `recap/recap-log.jsonl` (task) or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (`--task-group`); `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
209
+ | `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper for task and group recaps — `assemble` is a read-only phase-transition summary for a task or, with `--task-group`, the group's start order plus each task's latest conclusion; `record` appends one line to `recap/recap-log.jsonl` (task) or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (`--task-group`); `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
211
210
  | `stage-map` | `scripts/okstra_ctl/stage_map_cli.py` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
212
211
  | `design-prep` | `scripts/okstra_ctl/design_prep.py` | `okstra design-prep <list\|show\|write>` thin shim into `scripts/okstra_ctl/design_prep.py` — queries (`list`/`show`) the design items that implementation-planning pre-authored with AI, and records the user-confirmed responses as an append-only sidecar under `design-prep-inputs/` (`write`, `--confirmed` required). It never modifies the report snapshot |
213
- | `rollup` | `scripts/okstra_ctl/rollup.py` | Read-only roll-up; `--text` is the fixed model projection and machine mode remains JSON |
214
- | `usage-report` | `scripts/okstra_ctl/usage_report.py` | Read-only usage snapshot; `--text` is the fixed model projection and machine mode remains JSON |
215
212
  | `container` | `scripts/okstra_ctl/container.py` | Container lifecycle shim; `--text` is the command-specific model projection and machine mode remains JSON |
216
213
  | `code-review` | `scripts/okstra_ctl/code_review_target.py` | `okstra code-review target` thin shim into `scripts/okstra_ctl/code_review_target.py` — resolves what one implementation stage's or one branch's review reads (worktree, branch, base/head commits) and where its result file goes, for the okstra-code-review skill. Read-only; creates no directory or file |
217
214
  | `manager` | `scripts/okstra_ctl/manager_cli.py` | Cross-project manager; fixed text is the default and `--json` selects machine output |
@@ -271,7 +268,7 @@ Important modules:
271
268
  | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
272
269
  | `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it raises `workflow.nextRecommendedPhase.status` to `ready` (keeping the `contract-violated` audit information). It never picks the phase — `phase` is left as the last stage's report routing settled it, and the status is raised only while `phase` is non-empty |
273
270
  | `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
274
- | `recap.py` | deterministic backend for the okstra-inspect `recap` facet — `assemble` builds the cross-run phase transitions from the timeline overlaid with each run-manifest's current facts (`timeline_runs.py`); `assemble_group_recap` joins a task-group's briefs (start order, `group_context.group_queue`), catalog task-manifests (status, run count, next phase, report), and the group document's Task Memory (each task's conclusion); `record` append-only writes a summary/Q&A to `<task-root>/recap/recap-log.jsonl` or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (other artifacts unchanged) |
271
+ | `recap.py` | deterministic backend for task recaps — `assemble` builds the cross-run phase transitions from the timeline overlaid with each run-manifest's current facts (`timeline_runs.py`); `assemble_group_recap` joins a task-group's briefs (start order, `group_context.group_queue`), catalog task-manifests (status, run count, next phase, report), and the group document's Task Memory (each task's conclusion); `record` append-only writes a summary/Q&A to `<task-root>/recap/recap-log.jsonl` or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (other artifacts unchanged) |
275
272
  | `timeline_runs.py` | read-side overlay of a `history/timeline.json` entry with its run-manifest's current facts (`current_run_facts`) — the entry is a prepare-time snapshot (`status`, `workflowSnapshot`, reserved `reportRecordPath`) and `validate-run` writes the end state to the run-manifest only; a run whose `validation.status` is `not-run` projects no report path. Shared by `recap.py` and the `history-input` / overview projections in `model_io/renderers.py` |
276
273
  | `render.py` | task manifest, run manifest, timeline, task index, discovery, team-state, prompt/template render |
277
274
  | `group_context.py` | task-group context document (`.okstra/briefs/<task-group>/group-context.md`): the skeleton writer behind `okstra group-context init` (template `templates/reports/group-context.template.md`), `validate_group_context` (four required sections, no template placeholder left, directory slug matches the frontmatter `task-group`) that `validators/validate-brief.py` dispatches to on frontmatter `type: group-context`, and the path helpers `run.py` uses to validate the file at preflight and copy it to `instruction-set/task-group-context.md` for the analysis packet's `## Task-Group Context` section |
@@ -287,6 +284,9 @@ Important modules:
287
284
  | `qa_procedures.py` | Project-relative procedure loading, content and related-source digests, shared source-status observations with per-operation digest readers, fixed inspection rows, and serialized atomic QA registration |
288
285
  | `verification_inputs.py` | Immutable per-run QA declaration, procedure and source-observation snapshots, strict schema and digest checks, and serialized publication inside the project artifact tree |
289
286
  | `verification_generation.py` | Immutable generation seals for observed source, Git head and inspection files, with frozen-input binding and strict readers |
287
+ | `verification_invocation.py` | Explicit verifier generation references, same-run frozen-input checks, and canonical generation headers |
288
+ | `verification_dispatch.py` | Seals the verification generation a verifier dispatch binds to, from the dispatch round, executor results and verification target |
289
+ | `verification_capture.py` | Runs one verification command in its own process group: drains stdout and stderr concurrently into exclusive files, forwards them only as fast as the destination accepts (a destination that stops reading loses its copy, not the saved one), bounds the drain once the main process exits, stops the group on interruption with a grace that outlasts an early leader exit, kills the group before reaping the main process, then confirms with `ps` that no live member remains. Not wired to a command yet |
290
290
  | `verification_conformance.py` | Frozen-plan conformance scope selection and actual manifest/script validation for generation seals |
291
291
  | `verification_input_ref.py` | Optional verification input path and digest references shared by manifest rendering and compact context hydration |
292
292
  | `verification_input_types.py` | Pure snapshot payload types and version constants shared by storage and its port |
@@ -308,7 +308,7 @@ Important modules:
308
308
  | `design_snapshot.py` | Builds the design-surface-detector-owned snapshot from the report narrative — reproducible design surfaces plus conservative `PREP-NNN` preparation items (delegates surface detection to `design_surfaces.py`) |
309
309
  | `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the full reading copy — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
310
310
  | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
311
- | `wizard/` | `okstra-run` prompt state machine as a package; user-facing Korean strings live in `prompts/wizard/prompts.ko.json`. Modules import only the modules listed before them (`tests/contract/test_no_import_cycles.py`): |
311
+ | `wizard/` | `okstra-run` prompt state machine as a package; user-facing Korean strings live in `prompts/wizard/prompts.ko.json`. Modules import only the modules listed before them (): |
312
312
  | `wizard/ids.py` | constants, `S_*` step ids, pick tokens, multi-tab prompt groups |
313
313
  | `wizard/state.py` | `WizardState` / `Prompt` / `Option` / `Step` dataclasses, previous run-inputs → role-selection conversion, state predicates |
314
314
  | `wizard/prompts.py` | `prompts.ko.json` loader and placeholder interpolation (`_p`, `_msg`, `_static_options`) |
@@ -325,14 +325,12 @@ Important modules:
325
325
  | `wizard_stage_intent.py` | stage-related intent projection of the `okstra-run` wizard output — normalizes whole-task (`__whole_task__`) vs single/multi stage selection into render-args (`resolve_wizard_stage_intent`) |
326
326
  | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `backfill.py` | `~/.okstra` run index and history operations — `record_start` (index.py) writes a run's start; the end is closed either by `settle_run_row` (reconcile.py, records a verdict the caller already knows — used by `validate-run.py`) or by `reconcile_home` (infers one from disk — used by `run._reconcile_prior_runs` as the backstop for runs that died before validation) |
327
327
  | `run_index_row.py` | single reference point for creating / slimming / hydrating a `~/.okstra` run-index row — runId SSOT, preserves projectId raw |
328
- | `error_report.py`, `error_log_core.py`, `error_zip.py` | backend for the okstra-inspect errors/error-zip facets — `error_log_core` is the read-only core that globs/parses/aggregates `errors-*.jsonl`, `error_report` renders the errors facet, and `error_zip` collects cross-project run directories, allowlist-anonymizes, aggregates clusters, and produces a zip |
328
+ | `error_report.py`, `error_log_core.py`, `error_zip.py` | backend for error reports and archives — `error_log_core` is the read-only core that globs/parses/aggregates `errors-*.jsonl`, `error_report` renders the errors facet, and `error_zip` collects cross-project run directories, allowlist-anonymizes, aggregates clusters, and produces a zip |
329
329
  | `error_log_write.py` | the single writer for `errors-*.jsonl`, shared by the `okstra error-log` CLI and by `dispatch_core`, which records a wrapper's non-zero exit as a `cli-failure` in-process. Owns the agent/role/error-type allow-lists (agents derived from the provider registry) and the cause-evidence gate |
330
- | `run_audit.py` | backend for the okstra-inspect run-audit facet — reads run-manifest / final-report / team-state artifacts and reports invariant violations (read-only, never the lead's self-report) |
330
+ | `run_audit.py` | backend for run audits — reads run-manifest / final-report / team-state artifacts and reports invariant violations (read-only, never the lead's self-report) |
331
331
  | `worker_heartbeat.py`, `worker_liveness.py` | `worker_heartbeat` is the single definition of the `- PROGRESS:` heartbeat line shape and its 5-minute (+60s grace) cadence budget, shared by the Phase 7 audit (`validators/validate_session_conformance.py`) and the live probe; `worker_liveness` backs `okstra worker-liveness`, resolving each pending worker from its team-state row (`livenessMode` picks the artifact, `startedAt` anchors the grace) and reporting `stalled` (heartbeat past the budget, or none yet for this dispatch past the grace) or `did-not-launch` (no wrapper `.log`/`.status.json` past the launch grace) |
332
332
  | `run_artifact_prune.py` | finds `node_modules` / `.next` directories under a root without following symbolic links, and the `mutationAuditSnapshotPath` / `<promptPath>.publish.lock` files recorded in the team state of runs whose validation passed or that precede a passed run in the same `manifests/`, and removes them; shared by the Phase 7 `prune-run-artifacts` step and `okstra prune-run-artifacts` |
333
- | `log_report.py`, `time_report.py` | read-side backend for the okstra-inspect logs/time facets (`okstra log-report` pairs each wrapper transcript `.log` with its sibling prompt `.md` and reports both byte counts without changing legacy transcript-size fields; `okstra time-report` is per-task time aggregation) |
334
- | `rollup.py` | read-side backend for the okstra-rollup skill — fans the catalog out per task-group (or the whole project) and deterministically aggregates each task's run count, elapsed time (raw ms), error count, and latest report path, plus group-level totals/status, category, and phase distribution. Reuses the `time_report`/`error_log_core` functions and delegates report-body synthesis to the skill |
335
- | `usage_report.py` | Read-only okstra-usage backend — scans the whole current project's recent run timelines, defaults to 30 days, and returns task-type coverage, raw/billable tokens, known USD cost, CPU-sum and wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
333
+ | `log_report.py`, `time_report.py` | read-side backend for logs and time reports (`okstra log-report` pairs each wrapper transcript `.log` with its sibling prompt `.md` and reports both byte counts without changing legacy transcript-size fields; `okstra time-report` is per-task time aggregation) |
336
334
  | `json_registry.py` | shared flock + atomic JSON persistence for small okstra registries (`registry_lock`/`load_registry_json`/`save_registry_json`) — used by `worktree_registry` |
337
335
  | `stage_integrate.py` | whole-task stage integration (merge) + worktree teardown core (`integrate_stages`) — shared by whole-task final-verification entry, `okstra integrate-stages`, and container up |
338
336
  | `file_size_cap.py` | Stage-diff file-size thresholds for the correction round and `stage-done` (`okstra correction file-size` backend) — a 300-line target (advisory) and a 500-line limit (blocking), measured on the stage diff in physical lines for the source/test extensions okstra's coding preflight covers; vendored, fixture, snapshot, generated and `.okstra` paths, and files whose head declares itself generated, are exempt |
@@ -343,7 +341,6 @@ Important modules:
343
341
  | `session.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
344
342
  | `pane_reclaim.py` | resolves which runs of the current project still hold a non-terminal dispatch, so the `SessionStart(compact)` hook can re-inject the pane-cleanup obligation for them. The signal is the newest `team-state` per run directory, not the central run index — an in-session run never appears there (ADR-0011). Imports the status split from the `dispatch_state.NON_TERMINAL_WORKER_STATUSES` SSOT |
345
343
  | `phases/improvement_discovery/lenses.py` | lens enum SSOT + cap constants for the improvement-discovery phase (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
346
- | `container.py` | the `okstra container` convergence entrypoint of the okstra-container-build public skill — `provision_container_group` + `up`/`status`/`down` dispatch, env-override synthesis, compose argv assembly, and healthcheck polling |
347
344
  | `plan_run_root.py` | shared helper deriving `approved_plan_path` → `plan_run_root` and back-tracing the task-key |
348
345
  | `manager_cli.py` | `okstra manager` Python entrypoint — purpose-specific fixed text by default, machine JSON with `--json` |
349
346
  | `manager_paths.py` | Manager state path SSOT under `~/.okstra/managers/<manager-id>/`; slug fallback uses `u-<sha1-prefix>` when a safe segment would be empty |
@@ -424,7 +421,7 @@ Important modules:
424
421
  | `model_defaults.py` | pure replacement of role-model default scopes |
425
422
  | `legacy_model_selection.py` | normalises canonical role selections and legacy provider CLI flags into one selection |
426
423
  | `validation_contract.py` | the validation contract version pinned at prepare time (`CURRENT_VALIDATION_CONTRACT_VERSION`) |
427
- | `usage_identity.py` | projects usage rows from stored execution-identity refs; shared by usage-report, time-report, error-report, and the token collector |
424
+ | `usage_identity.py` | projects usage rows from stored execution-identity refs; shared by time-report, error-report, and the token collector |
428
425
  | `user_response_values.py` | value types and parsers of the `user-responses/` sidecar |
429
426
  | `stage_map_view.py` | read-side Stage Map view behind `okstra stage-map` |
430
427
  | `lead_progress.py` | `okstra lead-progress append` — records the lead's `PROGRESS:` checkpoints in the lead-events ledger |
@@ -542,7 +539,7 @@ Optional (v1.0 backward-compatible) top-level keys:
542
539
 
543
540
  14 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mts`; the Claude plugin manifest and the installer both derive from it.
544
541
 
545
- Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflight, python bootstrap note) is kept canonical in `skills/_fragments/*.md` and expanded in place inside each `SKILL.md` between `<!-- BEGIN FRAGMENT: <name> -->` / `<!-- END FRAGMENT: <name> -->` markers by `tools/sync-skill-fragments.mjs` (`--check` fails on drift). Sources stay fully expanded, so `runtime/` and installed copies remain self-contained; the guards are `tests-js/skill-fragments.test.mjs` and `tests/contract/test_prompt_fragment_ownership.py`.
542
+ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflight, python bootstrap note) is kept canonical in `skills/_fragments/*.md` and expanded in place inside each `SKILL.md` between `<!-- BEGIN FRAGMENT: <name> -->` / `<!-- END FRAGMENT: <name> -->` markers by `tools/sync-skill-fragments.mjs` (`--check` fails on drift). Sources stay fully expanded, so `runtime/` and installed copies remain self-contained; the guards are `tests-js/skill-fragments.test.mjs` and the retired Python suite.
546
543
 
547
544
  | Skill | User-invocable | Role |
548
545
  |---|---:|---|
@@ -551,11 +548,7 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
551
548
  | `okstra-discussion` | yes | Start or continue a `discussion` task through the same wizard and `prepare_task_bundle()` call as `okstra-run`, then facilitate one research cycle per run, the user's completion, follow-up briefs and Memory Book recovery |
552
549
  | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
553
550
  | `okstra-chat` | yes | Global rooms under `~/.okstra/chat` so host sessions from different providers can send and read addressed messages |
554
- | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost), `errors` (error-log aggregation), `error-zip` (anonymized cross-project error bundle), `run-audit` (progress-invariant audit over run artifacts), `recap` (cross-run phase recap). `SKILL.md` is a thin core (preflight + dispatch table + shared rules) and each sub-command body lives in `skills/okstra-inspect/facets/<sub-command>.md`, lazily read only after dispatch resolves; the 1:1 match between dispatch rows and facet files is enforced by `tests/contract/test_okstra_inspect_facets.py` |
555
- | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
556
- | `okstra-usage` | yes | Read-only project usage snapshot — aggregate recent run coverage, tokens, known cost, CPU, and wall-clock time by task type (default: 30 days) |
557
551
  | `okstra-schedule-gen` | yes | Generate task-group schedule |
558
- | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group (sub-commands `up` / `status` / `down`) |
559
552
  | `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |
560
553
  | `okstra-manager` | yes | Coordinate cross-project okstra tasks through manager-owned plans, assignments, sync snapshots, status, and child launch context packets |
561
554
  | `okstra-setup` | yes | Install/check runtime and register project |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.229.0",
3
+ "version": "0.230.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -20,7 +20,6 @@
20
20
  "docs/architecture/",
21
21
  "docs/cli.md",
22
22
  "docs/coding-rules.md",
23
- "docs/container.md",
24
23
  "docs/contributor-change-matrix.md",
25
24
  "docs/follow-ups/2026-07-10-final-report-option-3.md",
26
25
  "docs/performance-improvement-plan-v2.md",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.229.0",
3
- "builtAt": "2026-11-02T05:32:06.274Z",
2
+ "package": "0.230.0",
3
+ "builtAt": "2026-11-02T16:29:00.133Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -127,6 +127,7 @@ autofill_from_manifest() {
127
127
  # 이라 이 평범한 대입 하나가 run 을 통째로 중단시킨다. 위 reconcile 호출이 같은
128
128
  # 이유로 `|| true` 를 달고 있다.
129
129
  autofill_output="$(_okstra_interactive_cli autofill --manifest "$manifest_path" \
130
+ --project-root "$manifest_project_root" --task-key "$PROJECT_ID:$TASK_GROUP:$TASK_ID" \
130
131
  $( [[ -z "$BRIEF_PATH" ]] && printf -- "--need-brief" ) \
131
132
  $( [[ -z "$TASK_TYPE" ]] && printf -- "--need-type" ))" || true
132
133
 
@@ -145,7 +146,7 @@ autofill_from_manifest() {
145
146
  fi
146
147
  # release-handoff 는 brief 입력이 없다 (prepare 가 검증 보고서 인용 input 을
147
148
  # 생성) — task-type autofill 이후에 판정해야 하므로 순서가 위와 바뀌면 안 된다.
148
- # discussion 의 매니페스트 brief 는 prepare 가 만든 입력 문서라 다시 넘기지 않는다.
149
+ # discussion takes a start input instead of a brief, so it gets none either.
149
150
  if [[ -z "$BRIEF_PATH" && -n "$manifest_brief" && "$TASK_TYPE" != "release-handoff" \
150
151
  && "$TASK_TYPE" != "discussion" ]]; then
151
152
  BRIEF_PATH="$manifest_brief"
@@ -53,7 +53,7 @@ At each phase or implementation-stage boundary, at task completion, and before a
53
53
 
54
54
  During an authorized continuous run, put the update beside the existing progress checkpoint and continue to the next queued step without asking for confirmation merely to deliver this update. At a controlled session pause or handoff, distinguish persisted results from in-progress work and include the available resume reference. At task completion, distinguish remaining work in this task from follow-ups or the next task in its group. If there is no recorded next action, say none is recommended. These updates do not replace checkpoints or authorize another task.
55
55
 
56
- Prompt delivery is checked by `tests/contract/test_next_phase_authoring_delivery.py::test_lead_closeout_names_a_command_the_user_can_run`; this is guidance for the lead's prose, not runtime validation of the emitted message.
56
+ Prompt delivery is checked by the retired Python suite; this is guidance for the lead's prose, not runtime validation of the emitted message.
57
57
 
58
58
  Before asking again about provider data transfer, read the user's actual authorization in the conversation or carried confirmation record and compare its recipients and material with this dispatch. Reuse authorization that covers the same scope; a retry, translation, or technical experiment does not by itself require renewed consent. Name and ask only about a missing or expanded scope. Model selection alone is not blanket consent. Keep host execution permission separate: submit existing authorization evidence through the host's permitted approval mechanism, and report an actual rejection with its stated reason rather than inventing a new data-transfer gate. This is lead guidance; it does not override host approval decisions.
59
59
 
@@ -67,15 +67,15 @@ Close with one command the user can run now. The first matching row wins:
67
67
 
68
68
  - Open `blocks: approval` rows, or a `blocked-by-disagreement` gate whose approval rows carry no progress disposition → `/okstra-user-response` (name the `C-NNN` ids). An `accept-risk` / `select` / `answer` already recorded is not an open blocker. A report published with those rows open is not a failed run — the answers are the missing input, and a planning re-run without them reproduces the same block.
69
69
 
70
- After a successful `implementation-planning` finalization, stop on the approval row above. No open approval blocker → `/okstra-run` → `implementation` or `--approve`. Do not propose another planning run. Do not say `/okstra-inspect`. A blocking `validate-run` failure follows the recovery row first; a `validate-run` advisory is named in one line and nothing else — it did not fail the run.
70
+ After a successful `implementation-planning` finalization, stop on the approval row above. No open approval blocker → `/okstra-run` → `implementation` or `--approve`. Do not propose another planning run. A blocking `validate-run` failure follows the recovery row first; a `validate-run` advisory is named in one line and nothing else — it did not fail the run.
71
71
 
72
72
  For every other task type:
73
73
 
74
74
  - Pointer `status: ready` → `/okstra-run` for that `phase`. Quote the pointer's `rationale` — that sentence is this run's report saying why that phase comes next, and it is the analysis the user asked for.
75
- - Pointer `status: terminal` → the lifecycle ends here. Say the task is finished and quote the pointer's `rationale`. Do not propose a run and do not send the user to `/okstra-inspect`: the decision is already made, so there is nothing to inspect. If this run registered follow-up tasks, name them and the command that starts one.
75
+ - Pointer `status: terminal` → the lifecycle ends here. Say the task is finished and quote the pointer's `rationale`. Do not propose a run; the decision is already made. If this run registered follow-up tasks, name them and the command that starts one.
76
76
  - Pointer `status: blocked` → the pointer's `rationale` names what is in the way and what to run. Quote it and issue that command — `/okstra-user-response` for the `C-NNN` ids it lists, or `/okstra-run` for the phase it names.
77
- - Pointer `status: pending` with a `rationale` → the user's own input is what comes next. Quote the `rationale` and issue the command it names. Do not re-run the phase that just completed, and do not send the user to `/okstra-inspect`: a finished phase has nothing to inspect, and re-running it discards the result the user is being asked to act on.
78
- - Otherwise → `/okstra-inspect status` for this task.
77
+ - Pointer `status: pending` with a `rationale` → the user's own input is what comes next. Quote the `rationale` and issue the command it names. Do not re-run the phase that just completed,; re-running it discards the result the user is being asked to act on.
78
+ - Otherwise → `okstra task-show <task-key>` for this task.
79
79
 
80
80
  For file links in progress updates and closeout, use a short descriptive label in the Report Language, such as `[<선택 언어> 보고서 열기](<absolute-report-path>)`, replacing `<선택 언어>` with the run's selected report language name. The destination is always an absolute path: a project-relative destination does not open when the host's working directory differs or the user opens the file in an external program. `reportPaths.markdown` destinations are already absolute; for a project-relative path from this prompt, prefix `{{PROJECT_ROOT}}/`. Wrap a destination that contains spaces in `<...>`. Put each link on its own line. Keep the complete destination on one source line without inserted newlines; never abbreviate the destination or repeat the long path beside the label. Change only the display label. Commands stay in backticks.
81
81
 
@@ -126,7 +126,7 @@ Follow this protocol exactly:
126
126
 
127
127
  0. Version-selected schemas describe what the reducer reads: `schemas/convergence-groups-v1.0.schema.json` accepts only legacy groups, `schemas/convergence-groups-v2.0.schema.json` accepts only explicit v2 execution identity, and `schemas/convergence-round-results-v1.0.schema.json` feeds step 4's `apply-round --results`. `schemas/convergence-critic-results-v1.0.schema.json` is a fourth shape but **not** a reducer input — it describes the critic worker's own result document. Step 6's `apply-critic-gaps --results` takes the coverage batch you assemble from those candidates plus each analyser's vote (`{schemaVersion, taskKey, mode, provider, modelExecutionValue, dispatches[], gaps[]}`, spelled out in §"Coverage critic pass" §"State"); feeding the critic document straight in is rejected, by design. `okstra convergence example --kind <groups|round-results|critic-results>` prints a deterministic valid v1 instance of each and writes only JSON to stdout.
128
128
  1. Run `okstra convergence seed --groups <groups> --run-manifest <current-run-manifest> --work-state <work> --final-state <final> --migration-dir <state/migrations>` for a v2 worker roster. `--run-manifest` must be the exact current manifest named by the groups document's `runManifestPath`; a previous run from the same task is not interchangeable. `seed` refuses a grouping that cites a worker whose initial attempt the mutation audit discarded (`contract-failed-unattributed`, `mutation-present-unresolved`) — the result file is still on disk, but the ledger says it was never accepted. Re-dispatch that worker as a new invocation and cite the new result, or leave it out of the grouping. **Enforced:** `discarded_worker_errors` in `scripts/okstra_ctl/convergence_provenance.py`, called by `_seed`. Omit the flag for a legacy v1 roster. A `reuse-final` action means validate the existing final and continue to Phase 6. `create-work`, `resume-work`, and `restart-round0` continue with planning.
129
- 2. Run `okstra convergence plan-round --work-state <work> --plan <round-plan>`. This is read-only with respect to the working state. Its stdout JSON carries `round` and `inputQueueSize`; on a `dispatch` plan the round's `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` line copies those two values — never count the queue by hand. **Enforced:** `_plan_round` in `scripts/okstra_ctl/convergence.py`, `tests/run/test_convergence_cli.py`.
129
+ 2. Run `okstra convergence plan-round --work-state <work> --plan <round-plan>`. This is read-only with respect to the working state. Its stdout JSON carries `round` and `inputQueueSize`; on a `dispatch` plan the round's `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` line copies those two values — never count the queue by hand. **Enforced:** `_plan_round` in `scripts/okstra_ctl/convergence.py`, the retired Python suite.
130
130
  3. Every plan carries `dispatchable`: `true` on an `action: "dispatch"` plan, `false` on an `action: "finalize"` plan. When the plan action is `dispatch`, create exactly one reverify prompt for each `dispatches[]` row and dispatch it through the selected runtime adapter. Its findings are exactly that row's `findingIds`.
131
131
  4. Run `okstra convergence collect-results --plan <round-plan> --result <worker>=<path>… --run-manifest <current-run-manifest> --output convergence-round-<N>-results-<task-type>-<seq>.json`. Each planned worker's terminal outcome and `durationMs` come from the manifest's attempt ledger, not from the lead: an attempt still `started` refuses the collect — run `okstra team await` first so the attempt closes — and a worker whose attempt did not close `ok` cannot contribute a vote even if its result file exists. **Enforced:** `_dispatch_rows_from_manifest` in `scripts/okstra_ctl/convergence.py`. Then run `okstra convergence apply-round --work-state <work> --plan <round-plan> --results <round-results>`.
132
132
  5. Repeat `plan-round` and `apply-round` until the plan action is `finalize`. A `finalize` plan is **never dispatched**: it carries `dispatchable: false`, an empty `dispatches[]`, and a `note` naming the next command. Its `round` is only the `<N>` in `convergence-round-<N>-plan-<task-type>-<seq>.json` — not a round to run — so do not open reverify workers for it. **Enforced:** `okstra convergence apply-round` refuses a non-dispatch plan and returns the gate's closing reason with the remedy (`scripts/okstra_ctl/convergence_engine.py` `apply_round_results`).
@@ -573,7 +573,7 @@ For `runner=native-session`, use only `hostModelValue`; for
573
573
  `enforcementMode=host-native-spec-link-gate` and the metadata path. If the
574
574
  persisted assignment or either model value required by its runner is absent,
575
575
  record `critic-skipped: model-unresolved`; never resolve a replacement model.
576
- Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`, where `<seq>` is the run manifest's `runSequencesByCategory.workerResults` — the analysers' result seq, which differs from the run sequence after a run that never dispatched. `okstra convergence critic-verify-prompt` reads the critic result from the latest `ok` attempt of the `critic` dispatch in the run manifest and falls back to this name only when no such attempt is recorded (`_settled_critic_result` in `scripts/okstra_ctl/convergence.py`).
576
+ Result path: `runs/<task-type>/worker-results/<provider>-worker-critic-<task-type>-<seq>.md`, where `<seq>` is the run manifest's `runSequencesByCategory.workerResults` — the analysers' result seq, which equals the run sequence for a run prepared with one seq for all categories and may differ for an older run. `okstra convergence critic-verify-prompt` reads the critic result from the latest `ok` attempt of the `critic` dispatch in the run manifest and falls back to this name only when no such attempt is recorded (`_settled_critic_result` in `scripts/okstra_ctl/convergence.py`).
577
577
 
578
578
  **What the generated critic task-instructions file contains.** A critic dispatch
579
579
  is not a reverify dispatch: `dispatchKind = "critic"` keeps
@@ -597,7 +597,7 @@ dispatch will reject). The rest of the body is:
597
597
  - the two mandates below, including the `duplicateOf` declaration rule.
598
598
 
599
599
  The lead writes none of it and edits none of it. **Enforced:**
600
- `tests/contract/test_critic_prompt_equality_exemption.py`
600
+ the retired Python suite
601
601
  `test_generated_critic_seed_satisfies_the_real_dispatch_checks` runs the
602
602
  generated body through the same two checks the dispatch runs. A hand-edited file
603
603
  that drops either line fails `okstra team dispatch --dispatch-kind critic ...`
@@ -609,7 +609,7 @@ gate") rather than editing the published prompt.
609
609
 
610
610
  The `-worker-` token is load-bearing, not decoration: the critic prompt carries the same generated anchor headers as every other worker ([team-contract](./team-contract.md) §"Worker prompts"), and its `**Audit sidecar path:**` comes from passing that result path through `okstra_ctl.worker_artifact_paths.audit_sidecar_rel()`, which inserts `-audit-` after the token and raises without it. A `<provider>-critic-...` name leaves the lead choosing between breaking the contract and hand-inventing the sidecar name. Note that `originWorker` stays `"<provider>-critic"` — that is a worker id in the convergence state, not a filename, and the two do not have to match.
611
611
 
612
- The critic prompt carries the full analysis contract those anchor headers belong to — worker preamble, error-contract path, audit sidecar, packet boundary — but it is **exempt from the initial-analysis equality group**. Initial analysis workers must receive byte-identical normalized bodies (`worker_prompt_contract.validate_analysis_prompt_set`), and a critic body is deliberately unlike them, so `okstra_ctl.worker_prompt_policy.resolve_prompt_plan` resolves `dispatchKind = "critic"` to `equality_group = None` while keeping `audience = "analysis"`. Never reshape a critic prompt to match the initial one to satisfy that check — matching it would delete the pass. **Enforced:** `tests/contract/test_critic_prompt_equality_exemption.py` pins both directions — the critic is exempt, and two mismatched *initial* prompts still fail.
612
+ The critic prompt carries the full analysis contract those anchor headers belong to — worker preamble, error-contract path, audit sidecar, packet boundary — but it is **exempt from the initial-analysis equality group**. Initial analysis workers must receive byte-identical normalized bodies (`worker_prompt_contract.validate_analysis_prompt_set`), and a critic body is deliberately unlike them, so `okstra_ctl.worker_prompt_policy.resolve_prompt_plan` resolves `dispatchKind = "critic"` to `equality_group = None` while keeping `audience = "analysis"`. Never reshape a critic prompt to match the initial one to satisfy that check — matching it would delete the pass. **Enforced:** the retired Python suite pins both directions — the critic is exempt, and two mismatched *initial* prompts still fail.
613
613
 
614
614
  The critic prompt seeds the consolidated findings and asks for two things only — coverage gaps and unrequested work. The second half exists because every other scope check in the lifecycle runs *later*: the plan-body `P-Opt-*` verdict judges options this phase has not authored yet (report-writer writes the plan in Phase 6), and the `implementation` verifier judges a diff. Here the unit is a **finding**, which is the input those stages build on — catching unrequested work while it is still a finding is the cheapest place to catch it at all.
615
615