okstra 0.232.0 → 0.233.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 (183) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +8 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +36 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +279 -2
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +31 -41
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  77. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  78. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  79. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  80. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  81. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  82. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  83. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  84. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  85. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  86. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  87. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  88. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  89. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  90. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  91. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  92. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  93. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  94. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  95. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  96. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  97. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  98. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  99. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  100. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  101. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  102. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  103. package/runtime/python/okstra_ctl/material.py +2 -0
  104. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  105. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  106. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  107. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  108. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  109. package/runtime/python/okstra_ctl/paths.py +6 -1
  110. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  111. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  112. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  113. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  114. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  115. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  116. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  117. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  118. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  119. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  120. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  121. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  122. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  123. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  124. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  125. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  126. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  127. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  128. package/runtime/python/okstra_ctl/render.py +28 -2
  129. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  130. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  131. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  132. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  133. package/runtime/python/okstra_ctl/report_language.py +4 -1
  134. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  135. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  136. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  137. package/runtime/python/okstra_ctl/run.py +43 -35
  138. package/runtime/python/okstra_ctl/run_context.py +10 -1
  139. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  140. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  141. package/runtime/python/okstra_ctl/task_query.py +239 -0
  142. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  143. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  144. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  145. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  146. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  147. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  148. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  149. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  150. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  151. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  152. package/runtime/python/okstra_project/state.py +20 -0
  153. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  154. package/runtime/python/okstra_token_usage/cli.py +23 -10
  155. package/runtime/python/okstra_token_usage/collect.py +25 -22
  156. package/runtime/python/okstra_token_usage/policy.py +193 -0
  157. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  158. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  159. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  160. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  161. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  162. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  163. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  164. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  165. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  166. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  167. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  168. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  169. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  170. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  171. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  172. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  173. package/runtime/skills/okstra-run/SKILL.md +55 -183
  174. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  175. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  176. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  177. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  178. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  179. package/runtime/templates/manager/view.template.html +4 -0
  180. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  181. package/runtime/templates/trace/trace.template.md +42 -0
  182. package/runtime/validators/checks/fixtures-02.py +25 -33
  183. package/runtime/validators/validate-run.py +93 -36
@@ -54,8 +54,7 @@ as the literal `<host-runtime>` value instead of detecting again at each step.
54
54
  Replace `<host-runtime>` with the resolved literal value before executing each
55
55
  command. Keep the same resolved host for installation, preflight, diagnostics,
56
56
  and retries, including retries against another project or npm cache directory.
57
- The runtime registry validates host IDs; the skill command contract is checked
58
- by the former Python suite; that regression check is now retired.
57
+ The runtime registry validates host IDs.
59
58
 
60
59
  ```bash
61
60
  npx -y okstra@latest install --runtime <host-runtime>
@@ -179,6 +178,8 @@ matching section:
179
178
  - **F. declared architecture style** (`architecture.style`) — `hexagonal` /
180
179
  `layered` / `none`; hand-added, default `none`. Declaring one makes that
181
180
  architecture's placement rules binding in planning + verification.
181
+ - **G. review rule packs** (`reviewRulePacks`) — absolute paths to team review
182
+ standards every run reads; hand-added, checked by `okstra doctor --phase <phase>`.
182
183
  - **H. MCP servers** (`mcpServers`) — `okstra mcp add` declares a server,
183
184
  `okstra mcp check` shows which provider CLIs reach it.
184
185
 
@@ -140,10 +140,8 @@ and `validators/validate-run.py::_validate_conformance`.
140
140
  `okstra setup` (and every `okstra run` prepare that is not render-only)
141
141
  provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
142
142
  `~/.okstra/templates/settings.local.json`. The template contains the Bash
143
- permission rules required for the codex/antigravity worker wrappers:
144
-
145
- - `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`
146
- - `Bash($HOME/.okstra/bin/okstra-antigravity-exec.sh:*)`
143
+ permission rules the worker wrappers need: `Bash($HOME/.okstra/bin/:*)` covers
144
+ every `okstra-*-exec.sh` wrapper, alongside the provider CLI rules.
147
145
 
148
146
  Claude Code loads `.claude/settings.local.json` inside that project after the
149
147
  project has been trusted. When setup creates this file during an already-open
@@ -0,0 +1,187 @@
1
+ ---
2
+ name: okstra-tdd
3
+ description: Guide one agent through requirements, independently reviewed specification and interfaces, RED tests, implementation and integration GREEN in one resumable Implementation Trace. Use when the user requests okstra-tdd or a single-session test-driven implementation record; resume a task registered by okstra-run through its trace path and task key; cross-verification runs use okstra-run.
4
+ ---
5
+
6
+ # OKSTRA TDD
7
+
8
+ Keep one feature's analysis, review decisions, approvals and test evidence in one
9
+ Implementation Trace. `okstra trace` owns state transitions; this session writes
10
+ the Markdown body. One agent writes every section without a worker roster or run
11
+ lifecycle; review steps are judged by separate reviewer agents.
12
+
13
+ ## Open an attempt
14
+
15
+ 1. Resolve the target project from the user's request. Check for
16
+ `<project-root>/.okstra/project.json`. If absent, direct the user to
17
+ `okstra-setup` and stop.
18
+ 2. Honor a task key and trace path passed by `okstra-run` or the user. Otherwise
19
+ read `projectId` from project configuration and use
20
+ `<project-id>:implementation:<slug>` for linked creation. Keep the same key
21
+ for a new attempt of the same task. Ask for a feature slug if the user has not supplied one. Use lowercase letters,
22
+ digits and single hyphens between words. Run from the project root:
23
+
24
+ ```bash
25
+ okstra trace status --slug <slug>
26
+ ```
27
+
28
+ 3. On `TRACE_NOT_FOUND`, confirm the slug with the user, then run
29
+ `okstra trace new --slug <slug> --task-key <full-task-key> --project-root <project-root>`. If an attempt
30
+ exists, offer to resume that file or create a new attempt. Resume is the
31
+ recommendation; creating another attempt leaves earlier files unchanged.
32
+ If `new` reports an error, query `status --slug <slug>` before creating again:
33
+ cleanup can fail after a new attempt has been saved. If an attempt exists,
34
+ use the same resume-or-new choice and preserve earlier files. If status
35
+ returns `TRACE_NOT_FOUND`, repair the creation error before retrying. If status
36
+ itself fails otherwise, report the blocker and stop without changing files.
37
+ 4. Read the returned `path`, including its body and JSON frontmatter. Preserve
38
+ the frontmatter and CLI-rendered evidence blocks when editing the body.
39
+ Write prose in its `language`; keep step headings, table keys and IDs fixed.
40
+
41
+ ## Task registration and recovery
42
+
43
+ The linked task shares ordinary task history without a verification run. Supply
44
+ `--metadata <json-file>` on creation or advance to update `title`, `summary`,
45
+ `tags`, `changedFiles`, `references` and explicit `relatedTasks`. Before final
46
+ integration, record a functional summary and the actual changed file paths;
47
+ the test evidence summary is separate. These fields belong to the same task;
48
+ an attempt's task key cannot change. A new attempt retains earlier records and
49
+ starts with fresh approvals.
50
+
51
+ For an older unlinked trace, use
52
+ `okstra trace sync --path <file> --task-key <full-task-key> --metadata <json-file>`.
53
+ After `TASK_SYNC_FAILED`, the trace may already be saved. Read status and retry
54
+ `okstra trace sync --path <file>` until `taskSync` is `synced`; do not repeat an
55
+ already completed transition. Status reports `pending` without repairing state.
56
+ Report a completed trace with pending synchronization as such, rather than
57
+ claiming task history is current. CLI synchronization and regression tests
58
+ validate projection; the agent supplies truthful metadata and evidence.
59
+
60
+ ## Follow the current action
61
+
62
+ After each operation, use the returned `currentStep` and `nextAction`. On resume,
63
+ call `status --path <file>` rather than reconstructing state from prose.
64
+
65
+ - `write`: complete the current section below, then call
66
+ `advance --path <file> --step <currentStep>`.
67
+ - `review`: run the step's [independent reviewers](#run-independent-reviewers)
68
+ and advance with `--review <completion>` for each verified completion. Use
69
+ approval mode instead only when the user asked to approve this step: present
70
+ the section and its review notes, wait for a chat reply, and advance with
71
+ `--verdict pass --approve "<verbatim user reply>"` only after explicit approval.
72
+ A requested revision is a failed review; advance with `--verdict fail`.
73
+ - `ask-user-decision`: show the three consecutive failed reviews and remaining
74
+ omissions. Wait for the user's choice to continue revising, narrow scope or
75
+ stop. Record the choice in the review section. For an authorized retry, finish
76
+ the current writing step and repeat its review once, using the actions for
77
+ those step IDs even while status still reports the failure streak. A passing
78
+ review resets the streak. If narrowing scope changes approved requirements,
79
+ confirm a new attempt with the user and preserve the existing attempt.
80
+ - `run-tests`: implement the current step's work, run the commands recorded in
81
+ `analysis`, and supply their actual evidence as described below.
82
+ - `done`: report the trace path, the passing integration result and any
83
+ explicitly unverified limitation. End the trace workflow.
84
+
85
+ Use `okstra trace advance --path <file> --step <id> [options]` for transitions.
86
+ After any failed `advance`, read its JSON error and call `status --path <file>`:
87
+ an error can occur after the state has been saved. Repair the input and retry
88
+ the original step only if status still names that step as `currentStep`. If the
89
+ step changed, follow the persisted `nextAction` instead. If status fails, report
90
+ the blocker and stop without changing state. Preserve approval waits and quote
91
+ provenance when following the persisted action; do not infer approval from an
92
+ earlier failed command or edit state to bypass a rejection.
93
+
94
+ ## Section outcomes
95
+
96
+ | Step | Body outcome before advancing |
97
+ |---|---|
98
+ | `analysis` | Preserve the request; map every requirement to `R-NNN` with its source sentence. Fill the `Key` / `Value` table for `language`, `unitTestCommand`, `integrationTestCommand`, `typecheckCommand`. For languages without a type checker, use a command checking that tests import. |
99
+ | `analysis-review` | Reviewers compare every request sentence with the requirement list. Record each reviewer's omissions and verdict. |
100
+ | `spec` | Put each specification item in a `Spec item` / `Requirement` table and link it to existing R-IDs. |
101
+ | `spec-review` | Reviewers check for missing R-IDs, specification items lacking R-IDs, unauthorized scope and overdesign. Record their findings and verdicts. |
102
+ | `interface-design` | Record domain boundaries and public signatures. Add a `Use case` / `Requirement` table with `UC-NNN` IDs and each use case's R-IDs. |
103
+ | `interface-review` | Reviewers check that every R-ID has a use case and the boundaries and signatures serve those cases. Record their findings and verdicts. |
104
+ | `interface-code` | Write interface code, record code paths and pass type checking, compilation or the recorded import check. |
105
+ | `tests-red` | Write unit and integration tests. Record `Test` / `Use case` / `Kind` / `Path` rows, using `integration` for integration rows; every UC needs an integration test. Establish both unit and integration RED caused by missing implementation. |
106
+ | `implementation` | Implement the interfaces and reach unit GREEN. Record the integration result even when it remains RED. |
107
+ | `integration` | Reach integration GREEN for every use case. Record paths and results. |
108
+
109
+ All written artifacts stay in this trace; reference code and test files by path.
110
+ Follow the project's language and test tools rather than adding a new framework.
111
+ The CLI translates template guidance for `en` and `ko`; other language tags start
112
+ with structural markers only. Author their prose in the frontmatter language.
113
+
114
+ ## Run independent reviewers
115
+
116
+ The writing session never judges its own section. For the current review step:
117
+
118
+ <!-- BEGIN FRAGMENT: host-runtime-selection -->
119
+ Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
120
+ <!-- END FRAGMENT: host-runtime-selection -->
121
+
122
+ 1. Run `okstra trace reviewers --path <file> --host-runtime <host-runtime>`.
123
+ Keep its `dutyId`, `roleId`, `binding`, `independence` and `slots`; do not
124
+ choose a provider, model or duty yourself. Pass `--count <n>` only when the
125
+ user asks for more reviewers.
126
+ 2. For each slot, write
127
+ `<projectRoot>/.okstra/agent-invocations/trace-review/<invocation-id>.instructions.md`
128
+ with a unique invocation ID. Include the `binding` text verbatim, the request
129
+ and the sections the review compares (`analysis` for `analysis-review`;
130
+ `analysis` and `spec` for `spec-review`; `spec` and `interface-design` for
131
+ `interface-review`), the trace path, and the existing source paths the design
132
+ touches. Do not include the writing session's reasoning or a proposed verdict.
133
+ Ask for findings with evidence, then exactly one final line
134
+ `Trace review verdict: pass` or `Trace review verdict: fail`.
135
+ 3. Materialize and verify the prompt, then run the slot's provider wrapper:
136
+
137
+ ```bash
138
+ okstra agent-prompt materialize --project-root <projectRoot> --invocation-id <invocation-id> --host-runtime <host-runtime> --execution-runner cli-wrapper --provider <provider> --model <modelRef> --model-role <roleId> --audience <dutyId> --purpose trace-review --instruction <instructions-path> --prompt <projectRoot>/.okstra/agent-invocations/trace-review/<invocation-id>.prompt.md --json
139
+ okstra agent-prompt verify --project-root <projectRoot> --metadata <metadataPath> --text
140
+ ~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path> "" <roleId> --invocation-metadata <metadataPath>
141
+ ```
142
+
143
+ `metadataPath`, `promptPath` and `modelAssignment.modelExecutionValue` come
144
+ from the materialize output. A slot from the host's own provider still runs
145
+ through this wrapper, as a fresh process.
146
+ 4. Capture the model's returned body under
147
+ `<projectRoot>/.okstra/agent-invocations/trace-review/.tmp/` from the wrapper
148
+ output only, then run `okstra agent-prompt materialize-result`, `complete` and
149
+ `verify-completion` with `--purpose trace-review`. Record each reviewer's
150
+ findings and verdict in the review section of the trace.
151
+ 5. Advance with `--host-runtime <host-runtime>` and one
152
+ `--review <completion-path>` per reviewer. `REVIEW_STALE` means the prompt
153
+ lacks the current binding: the reviewed section, round, step, trace or host
154
+ changed after dispatch, or the binding was not copied verbatim. Review the
155
+ current text again under a new binding rather than editing the trace back.
156
+ `REVIEWER_NOT_INDEPENDENT` means a registered model from another provider was
157
+ skipped. A failed reviewer execution is retried once with a new invocation ID;
158
+ report a repeated failure as a blocker instead of judging the section yourself.
159
+
160
+ ## Record evidence
161
+
162
+ Write an evidence JSON file containing one object or an array of objects:
163
+
164
+ ```json
165
+ {
166
+ "kind": "unit",
167
+ "command": "npm run test:unit",
168
+ "exitCode": 1,
169
+ "summary": "Export is not implemented",
170
+ "failureCause": "not-implemented"
171
+ }
172
+ ```
173
+
174
+ Use `typecheck`, `unit` or `integration` for `kind`. Include the executed command,
175
+ numeric exit code and nonempty result summary. RED failure causes are
176
+ `not-implemented`, `assertion`, `compile-error`, `import-error` or `other`.
177
+ Classify the observed failure; an import or compilation problem is not evidence
178
+ of missing implementation. The CLI supplies `recordedAt` and renders evidence
179
+ into the trace.
180
+
181
+ Advance with `--evidence <json-file>`. `interface-code` requires passing
182
+ `typecheck`; `tests-red` requires failing `unit` and `integration` entries both
183
+ classified `not-implemented`; `implementation` requires passing `unit`;
184
+ `integration` requires passing `integration`.
185
+
186
+ When a returned `commitPoint` is true, tell the user that this is a commit point.
187
+ This skill records that point only: it does not commit, push or create a PR.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: okstra-user-response
3
3
  description: >-
4
- Use this to answer an okstra task's open clarification questions in-session without hand-editing a report or sidecar. It projects the available tasks and one report as fixed text, reads cited context before asking, asks one question at a time in the user's language with each option's outcome, confirms the user's exact answers, and publishes only the user-owned user-responses sidecar through a typed transaction. NOT for starting a run, inspecting a finished task, or generating a brief.
4
+ Use to answer an okstra task's open clarification questions, record an explicit plan decision, or pick the implementation direction a finished option comparison awaits, in-session, publishing the user-responses sidecar without hand-editing reports. NOT for starting a run, inspecting a finished task, or generating a brief.
5
5
  ---
6
6
 
7
7
  # OKSTRA User Response
@@ -29,7 +29,9 @@ Do not use the automation-oriented `list` or `show` commands. Do not open a repo
29
29
 
30
30
  ## Step 0: Preflight
31
31
 
32
- Use the registered host ID that the current harness declares for this session. Do not infer it from an executable or `PATH`. Do not substitute `claude-code`.
32
+ <!-- BEGIN FRAGMENT: host-runtime-selection -->
33
+ Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
34
+ <!-- END FRAGMENT: host-runtime-selection -->
33
35
 
34
36
  <!-- BEGIN FRAGMENT: bash-invocation-rule -->
35
37
  Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):
@@ -120,6 +120,10 @@ a { color: var(--running); }
120
120
  {{SUMMARY}}
121
121
  </section>
122
122
  <section>
123
+ <h2>Manager activity</h2>
124
+ {{ACTIVITY}}
125
+ </section>
126
+ <section>
123
127
  <h2>Projects</h2>
124
128
  {{PROJECTS}}
125
129
  </section>
@@ -4,11 +4,11 @@ This file is the audience-specific contract for `report-writer`. Read it and the
4
4
 
5
5
  ## Output ownership
6
6
 
7
- Write only the report narrative Markdown at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`.
7
+ Write only the report authoring input at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`.
8
8
 
9
9
  A correction-only prompt may additionally name a replacements JSON output. In that mode, the supplied `apply-corrections` command owns the narrative update.
10
10
 
11
- The report narrative Markdown contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
11
+ The report authoring input contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
12
12
 
13
13
  The following fields belong to other owners and must not appear in the narrative: `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, and `planBodyVerification`.
14
14
 
@@ -22,6 +22,16 @@ Write the audit sidecar before synthesis with one `- PROGRESS: <stage> <ISO-8601
22
22
 
23
23
  ## Narrative format
24
24
 
25
+ Use the format declared by the synthesis packet's Authoring Contract, selected from this run's `reportAuthoringFormat`. `json-v1` uses standard JSON; a manifest without the field retains `markdown-v1` and the packet's legacy `report-narrative-v3.0` format. Do not infer the format from the filename or convert an existing run to a different format. `reportNarrativePath` retains its name and means the writer's authoring input path; assembly derives the reader's Markdown and HTML from the final record.
26
+
27
+ ### JSON authoring (`json-v1`)
28
+
29
+ Write one standard JSON object with exact schema keys, native arrays, objects, numbers, booleans and `null`. Do not add a heading, preamble, Markdown fence, duplicate keys, or non-standard numeric values. Description strings may contain ordinary Markdown, including newlines, tables and code blocks. Use the packet's exact required and allowed top-level JSON keys and its writer-owned schema excerpt for nested fields. Do not translate keys into Title Case, use `- Item N` or `> value` lines, or encode empty values as `_none_`.
30
+
31
+ Write prose strings directly in the language named by `**Report Language:**`. A host, project or global instruction file (`CLAUDE.md`, `AGENTS.md`) does not change that language for report artifacts. Schema keys, enum and status values, finding and requirement ids, paths, symbols, commands, and model names keep their schema and source spelling. Only writer-owned fields belong in this object; standard JSON does not grant ownership of the assembled report or another role's input.
32
+
33
+ ### Legacy Markdown authoring (`markdown-v1`)
34
+
25
35
  The narrative is not free-form Markdown. A narrative file is the line `# OKSTRA Report Narrative`, then lines of exactly three shapes and nothing else:
26
36
 
27
37
  - `- **Humanised Field Name**` — one field. Nest a child field by indenting two more spaces.
@@ -32,7 +42,7 @@ Blank lines are ignored. **Every other line is rejected**, including Markdown he
32
42
 
33
43
  Follow the task-specific schema order. Write every `> ` prose value directly in the language named by `**Report Language:**`; do not draft in English first, because no translation step follows. A host, project or global instruction file (`CLAUDE.md`, `AGENTS.md`) does not change that language for report artifacts. Field names, `Verdict Token` and other enum or status values, finding and requirement ids, paths, symbols, commands, and model names stay exactly as the schema and sources spell them.
34
44
 
35
- ### Top-level fields you may author
45
+ ### Legacy top-level field labels
36
46
 
37
47
  These are the only names allowed at the top level:
38
48
 
@@ -42,6 +52,8 @@ The synthesis packet's Authoring Contract names which of these are **required**
42
52
 
43
53
  Any other top-level name is rejected however reasonable it reads — a section title copied out of a lead procedure document (`Clarification Response Carried In`, `Stage Map`, `Rollback Strategy`) is a heading in that document, not a top-level field here. Nested names come from the task's block in `schemas/final-report-v3.0.schema.json`; when a name is refused, the parser's message lists the names allowed at that exact position, so correct against that list rather than guessing a second time.
44
54
 
55
+ ## Task-specific content rules (both formats)
56
+
45
57
  **Implementation-planning direction branch.** A selected-direction narrative carries `selectedDirectionRef` and `directionRealization`; the `P-Dir-1` verifier checks that realization against the selected core mechanism, architecture boundaries, planning invariants, and any hidden direction change. A legacy candidate-comparison narrative retains `P-Opt-*` option comparison semantics. These are plan-body judgments, not frontmatter fields owned by the writer. Four `directionRealization` fields — `coreMechanism`, `architectureBoundaries`, `planningInvariants`, `userConstraints` — are verbatim copies of the selected-direction snapshot and report assembly overwrites them from that snapshot at publication: do not paraphrase them; spend the writing on the fields the writer actually owns (`fileStructure` and the other realization fields).
46
58
 
47
59
  **Implementation-option-selection comparison.** Candidate details remain direction-level and must not claim planning precision:
@@ -0,0 +1,42 @@
1
+ # Implementation Trace: {{slug}}
2
+
3
+ {{guidance}}
4
+
5
+ ## analysis
6
+
7
+ | Requirement | {{description}} | {{source}} |
8
+ |---|---|---|
9
+
10
+ | Key | Value |
11
+ |---|---|
12
+ | language | |
13
+ | unitTestCommand | |
14
+ | integrationTestCommand | |
15
+ | typecheckCommand | |
16
+
17
+ ## analysis-review
18
+
19
+ ## spec
20
+
21
+ | Spec item | Requirement | {{content}} |
22
+ |---|---|---|
23
+
24
+ ## spec-review
25
+
26
+ ## interface-design
27
+
28
+ | Use case | Requirement | {{description}} |
29
+ |---|---|---|
30
+
31
+ ## interface-review
32
+
33
+ ## interface-code
34
+
35
+ ## tests-red
36
+
37
+ | Test | Use case | Requirement | Kind | Path |
38
+ |---|---|---|---|---|
39
+
40
+ ## implementation
41
+
42
+ ## integration
@@ -2,16 +2,19 @@
2
2
 
3
3
  호출부: validators/lib/fixtures.sh:110
4
4
  규칙 R1 은 실행될 소스를 문자열/heredoc 이 아니라 실파일에 두게 한다.
5
- 이 파일의 내용은 꺼내기 전과 같다 — 옮기기만 했다.
6
5
  """
7
6
  from datetime import datetime, timezone
8
7
  from pathlib import Path
9
8
  import json
9
+ import os
10
10
  import sys
11
11
 
12
12
  project_root = Path(sys.argv[1])
13
13
  task_manifest_path = project_root / sys.argv[2]
14
14
  omitted_worker_id = sys.argv[3]
15
+ WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
16
+ if WORKSPACE_ROOT:
17
+ sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
15
18
 
16
19
 
17
20
  def load_json(path: Path) -> dict:
@@ -177,36 +180,27 @@ team_state["teamCreate"] = {
177
180
  "status": "implicit",
178
181
  }
179
182
 
180
- # Phase 7 token-usage collection is normally produced by okstra-token-usage.py.
181
- # The validator (`team-state.usageSummary is empty`) treats absence as a contract
182
- # violation, so the fixture must mirror that step with a synthetic-but-valid object.
183
- team_state["usageSummary"] = {
184
- "leadTotalTokens": 0,
185
- "workerTotalTokens": 0,
186
- "grandTotalTokens": 0,
187
- "leadBillableEquivalentTokens": 0,
188
- "workerBillableEquivalentTokens": 0,
189
- "grandBillableEquivalentTokens": 0,
190
- "estimatedCostUsd": {
191
- "lead": 0.0,
192
- "claudeWorkers": 0.0,
193
- "cliWorkers": 0.0,
194
- "grandTotal": 0.0,
195
- },
196
- "collectedAt": "1970-01-01T00:00:00Z",
197
- "teamName": team_state.get("teamName", "validation-fixture"),
198
- "sessionsFound": 0,
199
- "definitions": {
200
- "totalTokens": "Validation fixture placeholder.",
201
- "billableEquivalentTokens": "Validation fixture placeholder.",
202
- "estimatedCostUsd": "Validation fixture placeholder.",
203
- },
204
- "intake": {
205
- "totalTokens": 0,
206
- "billableEquivalentTokens": 0,
207
- "estimatedCostUsd": 0,
208
- },
209
- }
183
+ # This hermetic fixture contains no provider usage records. Record that
184
+ # observation for each participant, then use the collector's summary builder.
185
+ # A timestamped summary alone cannot establish source attribution or absence.
186
+ from okstra_token_usage.blocks import na_block
187
+ from okstra_token_usage.collect import _populate_usage_summary
188
+
189
+ team_state["leadUsage"] = na_block(
190
+ "The validation fixture contains no provider usage records for the lead."
191
+ )
192
+ for worker in team_state.get("workers", []):
193
+ if isinstance(worker, dict):
194
+ worker["usage"] = na_block(
195
+ "The validation fixture contains no provider usage records for "
196
+ f"{worker.get('role') or worker.get('workerId') or 'this worker'}."
197
+ )
198
+ _populate_usage_summary(
199
+ team_state,
200
+ team_name=team_state.get("teamName", "validation-fixture"),
201
+ sessions_found=0,
202
+ needle_source="validation-fixture",
203
+ )
210
204
 
211
205
  required_status_entries = run_manifest.get("teamContract", {}).get(
212
206
  "requiredAgentStatusEntries", []
@@ -284,8 +278,6 @@ md_path.write_text("\n".join(report_lines) + "\n")
284
278
  # The workflow validator's fixture predates that step; we materialise
285
279
  # the html file in-place using the same single-reference-point helper
286
280
  # the CLI uses.
287
- import os
288
- WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
289
281
  if WORKSPACE_ROOT:
290
282
  # Write final-report .data.json SSOT next to the markdown. The validator's
291
283
  # validate_final_report_data() reads this via _data_path_for(report_path)