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.
- package/README.md +19 -283
- package/dist/cli-registry.mjs +8 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.mjs +2 -17
- package/dist/lib/memory-auto-register.mjs.map +1 -1
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +36 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +279 -2
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +31 -41
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
- package/runtime/prompts/coding-preflight/clean-code.md +18 -20
- package/runtime/prompts/coding-preflight/overview.md +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -1
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
- package/runtime/python/okstra_ctl/code_review_census.py +93 -2
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +140 -15
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +33 -6
- package/runtime/python/okstra_ctl/manager_cli.py +122 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +42 -3
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +38 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +179 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
- package/runtime/python/okstra_ctl/run.py +43 -35
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_project/state.py +20 -0
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +58 -50
- package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
- package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +24 -0
- package/runtime/skills/okstra-memory/SKILL.md +1 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/validators/checks/fixtures-02.py +25 -33
- 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
|
|
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
|
|
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
|
|
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
|
-
|
|
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):
|
|
@@ -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
|
|
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
|
|
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
|
-
###
|
|
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
|
-
#
|
|
181
|
-
#
|
|
182
|
-
#
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
"
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
"
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
"
|
|
200
|
-
|
|
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)
|