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
|
@@ -65,16 +65,12 @@ Search the identifier across the file. If occurrences carry different types or r
|
|
|
65
65
|
|
|
66
66
|
Judge cohesion, complexity and abstraction levels. Split mixed responsibilities or levels when extraction improves the flow. A name containing "and" or a scrolling body prompts inspection, not automatic splitting. An orchestrator may call several named steps at one abstraction level; name their overall purpose.
|
|
67
67
|
|
|
68
|
-
### Plain-English summary test
|
|
69
|
-
|
|
70
|
-
For each added or meaningfully modified function, check whether short English sentences describing each line form readable prose. If that requires grouping lines under an invented name, represent the group as a named helper or intermediate value. A local readability helper may have one caller; the second-caller requirement concerns reuse-driven layers.
|
|
71
|
-
|
|
72
68
|
### Inspect for readability problems
|
|
73
69
|
|
|
74
|
-
-
|
|
75
|
-
- Name
|
|
76
|
-
-
|
|
77
|
-
- Extract a named builder when dense conditional fields
|
|
70
|
+
- Inspect mixed responsibilities or abstraction levels, anonymous temporaries, unnamed non-obvious transformation stages and boolean expressions with buried intent. Trace what a reader or caller must understand and identify the concrete ambiguity or maintenance consequence.
|
|
71
|
+
- Name inline phases when that exposes a cohesive step or separates unrelated responsibilities; a count of phases or temporaries alone does not require extraction.
|
|
72
|
+
- For branches over one enum, inspect whether cases and exhaustiveness are clear; use a `switch` when it improves them.
|
|
73
|
+
- Extract a named builder when dense conditional fields obscure a distinct construction responsibility. Apply "Limit nesting depth" below as an inspection signal.
|
|
78
74
|
|
|
79
75
|
### Function size review signal
|
|
80
76
|
|
|
@@ -82,7 +78,7 @@ Review newly added or substantially edited functions beyond 50 effective body li
|
|
|
82
78
|
|
|
83
79
|
### What's fine
|
|
84
80
|
|
|
85
|
-
Straight sequences of named steps, clear idiomatic framework patterns and guard clauses are acceptable. Short functions still
|
|
81
|
+
Straight sequences of named steps, clear idiomatic framework patterns and guard clauses are acceptable. Short functions still require inspection when they obscure a decision or mix responsibilities.
|
|
86
82
|
|
|
87
83
|
## Mutation and state boundaries
|
|
88
84
|
|
|
@@ -126,7 +122,7 @@ When replacing an error, retain the original as its cause, including its diagnos
|
|
|
126
122
|
|
|
127
123
|
## Testing discipline
|
|
128
124
|
|
|
129
|
-
Apply these rules to every test file; language-specific detection patterns are in `languages/*.md`.
|
|
125
|
+
Apply these rules to every test file; language-specific detection patterns are in `languages/*.md`. Changed core behavior and meaningful failure outcomes require tests unless the user explicitly waives them for this change and project rules permit it. Record the exact waived behavior or check as unverified, including any explicit project-required mutation check or resource-bound requirement. A waiver neither weakens existing tests nor establishes coverage; all other checks and quality rules for written or edited tests still apply.
|
|
130
126
|
|
|
131
127
|
### Reuse tests before adding coverage
|
|
132
128
|
|
|
@@ -134,7 +130,7 @@ Before function edits or new test plans, search names, behavior, callers and ass
|
|
|
134
130
|
|
|
135
131
|
Record the changed function, search terms, existing test locations and grounds for retaining, extending, adding or retiring coverage. Use `extend <path:line>`, `new (nothing covers <behavior>)` or `retire <path:line> (behavior moved to <where>)`. New tests without survey evidence are unfinished. Retire a test in the same commit only when its behavior is gone or a replacement asserts it more strongly through the same seam; otherwise retain it.
|
|
136
132
|
|
|
137
|
-
Keep distinct outcomes and meaningful failures, not parallel cases or cases per helper, branch, model, provider or task-type combination. Each behavior has one primary test owner; integration cases need separate wiring risks.
|
|
133
|
+
Keep distinct outcomes and meaningful failures, not parallel cases or cases per helper, branch, model, provider or task-type combination. Each behavior has one primary test owner; integration cases need separate wiring risks. Selective mutation checks reuse this coverage. Completion self-check and code review assess the mapping.
|
|
138
134
|
|
|
139
135
|
### No self-mocking
|
|
140
136
|
|
|
@@ -154,9 +150,11 @@ List all writes to the asserted field in the flow. Assert the last write as well
|
|
|
154
150
|
|
|
155
151
|
Claim an effect's coverage only where its real producing path runs. Reaching a mock that replaces that path does not verify the effect behind it.
|
|
156
152
|
|
|
157
|
-
###
|
|
153
|
+
### Focus regression tests on changed outcomes
|
|
154
|
+
|
|
155
|
+
Use retained or strengthened tests to distinguish changed core behavior and meaningful failure outcomes from an incorrect implementation. Merely reaching the method is insufficient, especially when recovery is the behavior added beyond a library's happy path.
|
|
158
156
|
|
|
159
|
-
|
|
157
|
+
Use a targeted mutation check when uncertainty remains about whether a test detects a regression, particularly for security, concurrency or recovery paths. Change the suspected behavior, confirm the focused test fails for that reason, then restore the source and rerun it. A manual mutation check for every syntactic branch is not required by this common pack; explicit project requirements retain their precedence.
|
|
160
158
|
|
|
161
159
|
### Shared fixtures keep the ordinary default
|
|
162
160
|
|
|
@@ -164,11 +162,11 @@ Keep shared fixture defaults on the ordinary path. Pass exceptional conditions e
|
|
|
164
162
|
|
|
165
163
|
### Test data must actually separate the paths
|
|
166
164
|
|
|
167
|
-
Use distinguishing inputs for source/destination, existing/incoming and success/conflict paths; identical setup and outcome do not justify separate cases. State each test's distinguishing input
|
|
165
|
+
Use distinguishing inputs for source/destination, existing/incoming and success/conflict paths; identical setup and outcome do not justify separate cases. State each test's distinguishing input and inspect whether its assertions depend on that difference; defaults must not let an incorrect implementation pass.
|
|
168
166
|
|
|
169
167
|
### A test title names the unit and the one condition it isolates
|
|
170
168
|
|
|
171
|
-
The failure line identifies the unit and isolated condition, using a grouping name where appropriate. If a parameterized case trips two guards, separate them before naming one.
|
|
169
|
+
The failure line identifies the unit and isolated condition, using a grouping name where appropriate. If a parameterized case trips two guards, separate them before naming one. Match the setup and title to the behavior the assertions actually verify.
|
|
172
170
|
|
|
173
171
|
### Test tooling you add is used in the same change
|
|
174
172
|
|
|
@@ -196,12 +194,12 @@ Use "Finding evidence and grading" below. Unreachable-state guards and extra tes
|
|
|
196
194
|
Implementation, independent verification and review use `review-rules.json` for rule IDs and blocking severity/timing. Referenced rules define applicability; `overview.md` defines precedence.
|
|
197
195
|
|
|
198
196
|
- An `execution-error` establishes a reachable input/state, expected behavior and actual wrong result.
|
|
199
|
-
- A `design-violation` establishes the
|
|
200
|
-
- `must-fix` means a defect or a violation with substantial consequences; `should-fix`
|
|
197
|
+
- A `design-violation` establishes the violating source and either an explicit applicable project requirement or a concrete maintenance or design consequence under the applicable rule; no runtime failure is required. A preferred implementation, name or style alone is insufficient.
|
|
198
|
+
- `must-fix` means a defect or a violation with substantial consequences; `should-fix` requires an explicit applicable project rule breach or an evidenced maintenance or design impact without immediate breakage; `nit` is a small, demonstrable improvement. Grade the established impact rather than generic style preference or confidence; missing inspection is incomplete coverage.
|
|
201
199
|
- `now` is introduced or changed by this change. `park` needs a cited scope or accepted-risk basis, not cost, passing tests or a restrictive plan. Reclassifying explicitly accepted product behavior requires new evidence.
|
|
202
200
|
- Unresolved blocking `now` findings prevent acceptance: executors fix them, verifiers return `FAIL`, and reviewers preserve them for settlement. Record `nit` and justified `park` findings without blocking. Semantic grading remains worker judgment.
|
|
203
201
|
|
|
204
|
-
M1 covers truthful, specific, standalone names; M2 covers cohesion, complexity, abstraction levels
|
|
202
|
+
M1 covers truthful, specific, standalone names; M2 covers cohesion, complexity, abstraction levels and comprehensible control flow. Size, nesting depth and counts of inline stages prompt inspection; they do not establish a finding by themselves. Correct execution does not waive an explicit project requirement or an evidenced design or maintenance impact. Cite the construct and the governing project rule or concrete consequence; do not demand unrelated legacy cleanup.
|
|
205
203
|
|
|
206
204
|
`file_size_cap.py` measures physical size; reviewers judge responsibility. An oversized legacy file need not be cleaned wholesale, but adding unrelated responsibility still violates S3 or M2. Small wiring edits may remain with a cited rationale. Restrictive plan placement does not waive these rules: return a plan conflict with a conforming location and preserved acceptance behavior, and obtain plan repair before writing outside authorized scope.
|
|
207
205
|
|
|
@@ -231,11 +229,11 @@ No `eval`, `Function(...)`, dynamic `import()` of an input-chosen path, or deser
|
|
|
231
229
|
|
|
232
230
|
## No magic numbers
|
|
233
231
|
|
|
234
|
-
|
|
232
|
+
Name values when their units, governing policy or repeated use carry meaning that callers or maintainers need. Keep clear idiomatic literals, such as zero for an empty count or one for an increment, inline. A numeric literal alone does not establish a finding; identify the obscured meaning, policy drift risk or explicit project rule that requires a name.
|
|
235
233
|
|
|
236
234
|
## Limit nesting depth
|
|
237
235
|
|
|
238
|
-
|
|
236
|
+
Deeply nested control flow, including four or more nested control-flow blocks, prompts inspection of the decisions, state and exit paths a reader must track. The function, class and module bodies do not count. Flatten with early returns or extract a named step when that resolves a concrete comprehension or maintenance problem; depth alone does not require a rewrite. Explicit project limits retain their precedence. Enforcement is the preflight self-check and code review.
|
|
239
237
|
|
|
240
238
|
## Comments explain *why*, not *what*
|
|
241
239
|
|
|
@@ -60,4 +60,4 @@ Workers authorized to change source also read [authoring-checks.md](authoring-ch
|
|
|
60
60
|
|
|
61
61
|
## Verification commands
|
|
62
62
|
|
|
63
|
-
Select repository-configured formatting, lint, type and test commands appropriate to the changed behavior and contracts. Execution authority and full-check timing follow the assignment and repository procedure. Do not add tools, configuration or dependencies solely for this pack. Record unavailable or unconfigured checks as unverified with reasons. Command selection does not waive
|
|
63
|
+
Select repository-configured formatting, lint, type and test commands appropriate to the changed behavior and contracts. Execution authority and full-check timing follow the assignment and repository procedure. Do not add tools, configuration or dependencies solely for this pack. Record unavailable or unconfigured checks as unverified with reasons. Command selection does not waive focused behavior and failure tests, cause verification or explicit project-required mutation checks; use the selective mutation criteria in [Testing discipline](clean-code.md#testing-discipline).
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"A clean verdict explains inspected evidence. For checked G2/G3/G5, preserve the calibration's source-cited observations after ::. Missing inspection or required execution stays unaccounted; unavailable performance bounds stay unverified."
|
|
23
23
|
],
|
|
24
24
|
"collaborationContract": [
|
|
25
|
-
"Only the assigned review function belongs to this invocation.
|
|
25
|
+
"Only the assigned review function belongs to this invocation. Return your own verdicts without spawning reviewers; the lead owns dispatch, audits and team consolidation.",
|
|
26
26
|
"Return out-of-assignment evidence and aggregation conflicts to their owner without changing cell identities or borrowing another team's verdicts."
|
|
27
27
|
],
|
|
28
28
|
"completionCriteria": [
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": "1.0",
|
|
3
|
+
"id": "interface-reviewer",
|
|
4
|
+
"roleId": "verifier",
|
|
5
|
+
"responsibilities": [
|
|
6
|
+
"Independently judge whether a proposed interface design serves every approved use case and requirement through sound domain boundaries and public signatures, before any interface code is written."
|
|
7
|
+
],
|
|
8
|
+
"requiredConduct": [
|
|
9
|
+
"Map every approved requirement to at least one use case and every use case to the boundaries and signatures that serve it. Read the existing modules, callers and conventions the design touches, and check each signature's inputs, outputs, failure results and ownership against that use case and the surrounding code."
|
|
10
|
+
],
|
|
11
|
+
"decisionPrinciples": [
|
|
12
|
+
"Prefer the smallest interface that serves the approved use cases and fits existing project boundaries. Distinguish a missing or unserved use case, a boundary that leaks another layer's concern and a signature that cannot express a required outcome from a stylistic preference, and leave scope decisions to the approved specification."
|
|
13
|
+
],
|
|
14
|
+
"authorityAndBoundaries": [
|
|
15
|
+
"Review the assigned design against the approved specification and existing code without rewriting either. Do not add requirements, redesign unrelated modules or write interface code."
|
|
16
|
+
],
|
|
17
|
+
"evidenceStandards": [
|
|
18
|
+
"Each finding names the requirement or use case affected, the boundary or signature at fault, the existing code it conflicts with as path:line where one exists, and the consequence for implementation or callers. A clean verdict states what was mapped and checked."
|
|
19
|
+
],
|
|
20
|
+
"collaborationContract": [
|
|
21
|
+
"Return findings and the verdict to the lead with their evidence. Do not negotiate the design with its author or decide whether the specification itself should change."
|
|
22
|
+
],
|
|
23
|
+
"completionCriteria": [
|
|
24
|
+
"Every requirement and use case has been traced to the design, every public signature has been checked against the use cases it serves, and unmapped items, defects and clean checks are all recorded."
|
|
25
|
+
],
|
|
26
|
+
"prohibitions": [
|
|
27
|
+
"Do not pass a design with an unserved use case or unmapped requirement, turn naming or style preferences into defects, or propose implementation details beyond the interface."
|
|
28
|
+
],
|
|
29
|
+
"blockedStateReporting": [
|
|
30
|
+
"Identify the missing specification, use-case table or source context, the mapping that cannot be completed, the attempts made and the requirements or use cases left unverified."
|
|
31
|
+
]
|
|
32
|
+
}
|
|
@@ -1,17 +1,26 @@
|
|
|
1
1
|
# Host orchestration rules
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
`
|
|
3
|
+
The phase catalog explicitly declares which task types require host rules:
|
|
4
|
+
`implementation` and `implementation-planning`. Their canonical files live in
|
|
5
|
+
the owning phase packages as `host-rules.md`; an asset root without a Python
|
|
6
|
+
package uses this directory's `<task-type>.md` path. A missing declared file is
|
|
7
|
+
an installation error. Undeclared task types get an empty host-rules path,
|
|
8
|
+
regardless of whether a file exists.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
The wizard exposes the selected canonical file's absolute path as
|
|
11
|
+
`outcome.orchestration.hostRulesPath`. The `okstra-run` skill reads a non-empty
|
|
12
|
+
path after confirmation and before the first `render-bundle`, so waiver and
|
|
13
|
+
recovery instructions are available even when preparation fails. It does not
|
|
14
|
+
embed the implementation or planning rules in its body.
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
16
|
+
`scripts/okstra_ctl/run.py` copies declared rules into the prepared instruction
|
|
17
|
+
set as `host-orchestration-rules.md`. This frozen copy governs resumed work and
|
|
18
|
+
stage chaining. The launch prompt still requires the lead to read it within the
|
|
19
|
+
run; a pre-prepare read of the canonical file does not satisfy the implementation
|
|
20
|
+
session read gate. Legacy prepared runs with no frozen file retain the existing
|
|
21
|
+
session-conformance compatibility behavior.
|
|
13
22
|
|
|
14
|
-
The
|
|
23
|
+
The frozen copy exists because a rule that lives only in the conversation is
|
|
15
24
|
one compaction away from gone: a DEV-10400 run operated for five turns on a
|
|
16
25
|
skill body truncated mid-Step-5 and nothing signalled the loss. On disk, the
|
|
17
26
|
rules survive compaction and `validators/validate_session_conformance.py` can
|
|
@@ -191,11 +191,12 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
|
|
|
191
191
|
4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
|
|
192
192
|
5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `scripts/okstra_ctl/phases/implementation_planning/profile.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
|
|
193
193
|
6. **`mode == "unresolved"`** → ask the user for stage numbers; re-enter step 3 with those numbers in `--impacted`. Do not fall back to full. Do not record `unresolved` as `incrementalDecision`. Then continue from the new `mode`.
|
|
194
|
-
7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --narrative
|
|
194
|
+
7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} --narrative <this run's reportNarrativePath> --state ...`, the lead runs:
|
|
195
195
|
```
|
|
196
196
|
okstra incremental-carry \
|
|
197
|
+
--run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} \
|
|
197
198
|
--prev-data {{RUN_REPORTS_RELATIVE_PATH}}/final-report-implementation-planning-<prev-seq>.data.json \
|
|
198
|
-
--cur-narrative <this run's
|
|
199
|
+
--cur-narrative <this run's reportNarrativePath> \
|
|
199
200
|
--state <this run's plan-body-verification state> \
|
|
200
201
|
--prev-seq <prev-seq> \
|
|
201
202
|
--decision {{INCREMENTAL_DECISION_STATE_RELATIVE_PATH}} \
|
|
@@ -45,6 +45,8 @@ Run Input is the only Phase 1 source for task identity, work category, workflow
|
|
|
45
45
|
|
|
46
46
|
Use the `Worker Roster` section for dispatch and model assignment. Use `Artifact Paths` for prompt, result, report, status, validator, and resume locations. Use `Configuration References` for the task-level Markdown resources. Do not derive sibling paths from file names or sequence counters.
|
|
47
47
|
|
|
48
|
+
Use `Report authoring format` as the current run's declared writer syntax and `Report writer input` as its exact stored authoring path, including when the lead writes that input directly.
|
|
49
|
+
|
|
48
50
|
Use the `Current phase` labels as the workflow view. Rules for `nextRecommendedPhase` are maintained by [report-writer](./report-writer.md); do not re-derive phase routing here.
|
|
49
51
|
|
|
50
52
|
## Output
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
|
-
The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the report
|
|
5
|
+
The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the report input in the run manifest's declared `reportAuthoringFormat`; report assembly publishes the final record from role-owned inputs. The lead never substitutes its own reasoning for a worker result and never bypasses a rostered report writer.
|
|
6
6
|
|
|
7
7
|
The lead owns the approval decision ledger and writes it only through `okstra approval-decision`. The activity recorder owns the activity ledger. Runtime adapters own team state and usage. The convergence engine owns convergence state and the completed plan-body result. The design-surface detector owns the design-preparation snapshot. Report assembly validates these inputs and publishes `final-report-*.data.json` once; a failure is returned to the owner named in its diagnostic.
|
|
8
8
|
|
|
@@ -57,7 +57,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
|
|
|
57
57
|
| `okstra model-io run-input --run-manifest <path>` | Read run identity, worker roster, model assignments, and artifact paths instead of opening the run manifest | `context-loader` "Step 3" |
|
|
58
58
|
| `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Read the prior executor base ref for an incremental re-run | launch prompt "Incremental re-verification" |
|
|
59
59
|
| `okstra incremental-scope --prev-data <path>` | Decide re-verify vs carry-forward stages on a clarification re-run | launch prompt "Incremental re-verification" |
|
|
60
|
-
| `okstra incremental-carry --prev-data <path> --prev-seq <seq> --cur-narrative <
|
|
60
|
+
| `okstra incremental-carry --run-manifest <current-run-manifest> --prev-data <path> --prev-seq <seq> --cur-narrative <reportNarrativePath>` | Merge carried-forward plan-item verdicts after `plan-items seed`; then repeat `plan-items prepare --state`, `prompt` and `validate-prepared --state` using that same manifest | launch prompt "Incremental re-verification" |
|
|
61
61
|
| `okstra stage-map <task-key>` | Read the prior Stage Map and done stages before re-planning | host orchestration rules (implementation-planning) |
|
|
62
62
|
| `okstra stage-close <task-key> --stage <N> --from-commit <sha> [--supersede-failed <reason>]` | Close a stage whose work already landed outside okstra, or a `failed` stage whose failure no longer applies |
|
|
63
63
|
| `okstra stage-reopen <task-key> --stage <N> --reason <why> [--evidence <report>]` | Reopen a `done` stage for a fix run, e.g. after a `blocked` final-verification of that stage | host orchestration rules (implementation-planning) |
|
|
@@ -160,19 +160,19 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
|
|
|
160
160
|
|---|---|---|
|
|
161
161
|
| `okstra agent-prompt check-corrections --project-root <dir> --run-manifest <path> --corrections <path>` | Check a report-writer corrections ledger before a corrective dispatch | `report-writer` "Corrective report-writer dispatch" |
|
|
162
162
|
| `okstra agent-prompt apply-corrections --project-root <dir> --run-manifest <path> --corrections <path>` | Apply a ledger that `check-corrections` reported `mechanical: true`, without a writer round | `report-writer` "Corrective report-writer dispatch" |
|
|
163
|
-
| `okstra design-snapshot --narrative <path> --output <path>` | Complete the design-surface detector snapshot; both paths come from
|
|
163
|
+
| `okstra design-snapshot --run-manifest <path> --narrative <path> --output <path>` | Complete the design-surface detector snapshot; both paths and the authoring format come from that run manifest | `report-writer` "Implementation-planning sequence" |
|
|
164
164
|
| `okstra plan-items prepare --run-manifest <path> --narrative <path>` | Extract this round's plan items (add `--state <path>` after a self-fix or `incremental-carry`, `--tie-vote` for a critic tie round) | `plan-body-verification` "Round protocol" |
|
|
165
165
|
| `okstra plan-items prompt --run-manifest <path>` | Print the plan-items block placed verbatim in every verifier prompt | `plan-body-verification` "Round protocol" |
|
|
166
166
|
| `okstra plan-items validate-prepared --run-manifest <path> --narrative <path>` | Validate the prepared envelope before dispatch; pass the same `--state` the last `prepare` used | `plan-body-verification` "Round protocol" |
|
|
167
|
-
| `okstra plan-items seed --narrative <path>` | Create the `planItems[]` rows a round lands in | `plan-body-verification` "Round protocol" |
|
|
168
|
-
| `okstra plan-items extract --narrative <path> --output <path>` | Re-extract plan items after a round and re-verify any item whose subject shifted | `plan-body-verification` "Round protocol" |
|
|
167
|
+
| `okstra plan-items seed --run-manifest <path> --narrative <path>` | Create the `planItems[]` rows a round lands in | `plan-body-verification` "Round protocol" |
|
|
168
|
+
| `okstra plan-items extract --run-manifest <path> --narrative <path> --output <path>` | Re-extract plan items after a round and re-verify any item whose subject shifted; use the input path declared by that run manifest | `plan-body-verification` "Round protocol" |
|
|
169
169
|
| `okstra plan-items correction-prompt --run-manifest <path> --state <path> --worker <id>` | Put its output first in a `worker-correction` re-dispatch prompt | `plan-body-verification` "Round protocol" |
|
|
170
170
|
| `okstra plan-items collect-verdicts --items <path> --result <worker>=<path> --output <path>` | Read a round's responses into a verdicts envelope; never parse them by hand | `plan-body-verification` "Round protocol" |
|
|
171
171
|
| `okstra plan-items apply-verdicts --state <path> --round <N> --result <worker>=<path>` | Record the round's verdicts | `plan-body-verification` "Round protocol" |
|
|
172
172
|
| `okstra plan-items complete-round --state <path> --run-manifest <path> --round <N>` | Record the completed round | `plan-body-verification` "Round protocol" |
|
|
173
173
|
| `okstra plan-items next-dispatch --state <path>` | Decide whether the round opens another worker batch | `plan-body-verification` "Round protocol" |
|
|
174
174
|
| `okstra plan-items resolve-dissent --state <path> --item <P-id> --decision-file <path>` | Record an evidence-based lead decision after the single self-fix | `plan-body-verification` "Round protocol" |
|
|
175
|
-
| `okstra plan-verify --
|
|
175
|
+
| `okstra plan-verify --run-manifest <path> --narrative <reportNarrativePath> --state <path>` | Score the plan-body gate before report assembly, using that run's declared input format; never tally votes in a script | `plan-body-verification` "Round protocol" |
|
|
176
176
|
| `okstra worktree-lock --worktree <dir> --command <text>` | Lead minor fix (implementation only, never in a run marked `verificationEvidenceVersion`): re-run each Tier 1 command and failing verifier check that covers a fixed finding, in the stage worktree, under its lock | `_implementation-deliverable.md` "Lead minor fix" |
|
|
177
177
|
|
|
178
178
|
### Phase 7 — persist
|
|
@@ -590,7 +590,7 @@ If convergence is disabled, `seed`/`finalize` produce the auto-disabled final st
|
|
|
590
590
|
|
|
591
591
|
### Authoring ownership (BLOCKING)
|
|
592
592
|
|
|
593
|
-
If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.workerRoles`), Lead dispatches it to author only `
|
|
593
|
+
If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.workerRoles`), Lead dispatches it to author only the input at the run manifest's `reportNarrativePath`, its worker-result pointer, and its audit sidecar. `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and the existing narrative line grammar. Use the declared path and format, including its `.json` or `.md` extension. The worker may read the complete run context but cannot write `final-report-*.data.json` or another role's ledger. After every required input exists, Phase 7 runs report assembly, which validates the role-owned inputs and atomically publishes the report record once. Phase 7 then renders the human HTML from that record. Contract v2 artifacts remain readable but no new run writes them. **Enforced:** report-writer dispatch completion paths in `scripts/okstra_ctl/dispatch_state.py`, granted artifacts in `scripts/okstra_ctl/dispatch_core.py`, and `scripts/okstra_ctl/report_assembly.py` `assemble_report`.
|
|
594
594
|
|
|
595
595
|
Before constructing the dispatch prompt, the lead MUST:
|
|
596
596
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Phase 6 gives the report writer all settled analysis, convergence, task, and planning context required for synthesis. Read access supplies context; it does not grant write authority over another owner's file.
|
|
6
6
|
|
|
7
|
-
The report writer writes only the report
|
|
7
|
+
The report writer writes only the report authoring input, its pointer record, and its audit sidecar. The run manifest's `reportAuthoringFormat` selects standard JSON for `json-v1`; an absent field selects the existing `markdown-v1` line grammar. `reportNarrativePath` retains its name and identifies that exact input path. Never infer the format from its suffix or change an existing run's format. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
|
|
8
8
|
|
|
9
9
|
The narrative owns judgments, plan body, summaries, user explanation, recommended steps, and follow-up descriptions. It never owns `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, or `planBodyVerification`. It must not pre-fill a future round, future gate result, activity identifier, usage value, or resolution.
|
|
10
10
|
|
|
@@ -14,7 +14,7 @@ Report assembly reads the role-owned inputs, validates them, derives links and s
|
|
|
14
14
|
|
|
15
15
|
| Input | Owner | Write boundary |
|
|
16
16
|
|---|---|---|
|
|
17
|
-
| report
|
|
17
|
+
| report authoring input in the declared format | report-writer | `reportNarrativePath` |
|
|
18
18
|
| approval decision ledger | lead | `approvalDecisionsPath` through `okstra approval-decision` |
|
|
19
19
|
| activity ledger | activity recorder | `leadEventsPath` through `okstra agent-activity append` |
|
|
20
20
|
| team state and usage | runtime/accounting adapter | `teamStatePath` |
|
|
@@ -48,7 +48,7 @@ project-relative path and value. The report writer receives the
|
|
|
48
48
|
packet's Markdown reading projection as the only task input instead of an
|
|
49
49
|
independently assembled list of raw paths.
|
|
50
50
|
|
|
51
|
-
The packet's authoring contract names the result path,
|
|
51
|
+
The packet's authoring contract names the result path, selected authoring format, writing
|
|
52
52
|
instructions, runtime-owned content, and validation rules. Missing configured
|
|
53
53
|
paths and missing files are collected across the full source set before dispatch
|
|
54
54
|
and reported together with their owners. Report assembly checks source availability
|
|
@@ -89,13 +89,13 @@ For `rewrite`, the materialized correction-only prompt supplies target values, c
|
|
|
89
89
|
|
|
90
90
|
This section adds report-specific checks to [okstra-lead-contract](./okstra-lead-contract.md) "Worker instruction quality gate"; it does not limit that common gate to report-writer calls. A follow-up dispatch that revises a narrative which already exists and whose structure parses is a corrective dispatch, and its instruction is a corrections ledger, not prose:
|
|
91
91
|
|
|
92
|
-
1. Preserve the attempt: copy the current
|
|
92
|
+
1. Preserve the attempt: copy the current input to a distinct attempt file in the same `worker-results/` directory, inserting `-a<N>` into its filename and retaining its actual `.json` or `.md` extension. Take the source path from `reportNarrativePath`. The ledger's `baseNarrativePath` names that copy, never the live `reportNarrativePath` — the correction overwrites the live file, and the copy is what the writer (or `apply-corrections`) reads. The preserved copy uses the run's declared format too.
|
|
93
93
|
2. The ledger lives at `runs/<task-type>/state/report-writer-corrections-<task-type>-<seq>-a<N>.json` (schema `schemas/report-writer-corrections-v1.0.schema.json`) and holds one entry per defect: `replace` with the exact replacement value (add `current` when you want it checked), `remove` for an item or optional field, `rewrite` with a `rule` when the writer has to re-author prose. Paths use the validator's grammar (`implementationOptionSelection.rankedOptions[1].coverageSummary.coveragePercent`), so a report-assembly refusal can be copied into the ledger verbatim. Never write an indirect instruction such as `use the schema value`, `use the valid status`, or `fix the enum`: a `replacement` is the literal, and a `rule` names the required outcome. You do not copy allowed enum literals by hand — okstra attaches each `rewrite`'s schema constraint from the frozen schema.
|
|
94
94
|
3. Run `okstra agent-prompt check-corrections --project-root <root> --run-manifest <path> --corrections <ledger>` until it reports no defect. It applies the ledger to a scratch copy of the base narrative and validates the complete proposed narrative against the writer-owned value schema and the task's semantic validator, listing every defect at once. Validating only the edited field is insufficient because one replacement can select a different schema branch, which is why the check covers the whole narrative.
|
|
95
95
|
4. When the check reports `mechanical: true` and has corrections, run `okstra agent-prompt apply-corrections` with the same arguments: okstra writes the corrected narrative to `reportNarrativePath` and records a `lead-correction-applied` activity row naming the ledger and its correction ids. This includes validated `replace`, `remove`, `add`, `move`, and derived step counts. No writer dispatch, `record-dispatch`, or `link-result` follows; the roster row's result already exists.
|
|
96
96
|
5. Otherwise materialize the writer prompt with the same `--corrections <ledger>` under a new invocation id and prompt path (when the first attempt's result is linked, retire that link with `reject-result` as `plan-body-verification` (the absolute path in **Okstra Runtime Resources**) describes; a dispatch that ended in `error` has no link, so skip that step). okstra renders the correction-only field values, evidence, schema constraints, replacement-file contract, application command, and output paths. Put context in the ledger; the initial instruction body is not sent to the correction writer.
|
|
97
97
|
|
|
98
|
-
A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs
|
|
98
|
+
A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs. Only an input whose structure does not parse under the run's declared format is re-authored: that dispatch needs no ledger, and its body quotes the parser's message. Before overwriting the live input, okstra preserves a `worker-results/<narrative-stem>.pre-<invocation-id><original-extension>` copy and renders a `## Previous Attempt` section naming it. Retain the actual `.json` or `.md` extension and the run's declared format (**Enforced:** `_preserve_reauthored_narrative` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`). An input that breaks its declared syntax is not a produced artifact: the dispatcher settles that attempt as `required worker artifact is unusable: narrative does not parse: …` and retries it inside the same batch, so the parser's message appears at collection (**Enforced:** `okstra_ctl.dispatch_state.unusable_result_defect`, read by `missing_completion_paths` and the `team await` record path). The synthesis packet carries `JSON_NARRATIVE_INSTRUCTIONS` for `json-v1` or `NARRATIVE_GRAMMAR_INSTRUCTIONS` for `markdown-v1`. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are handled by the correction ledger.
|
|
99
99
|
|
|
100
100
|
**Enforced:** `_with_report_writer_sections` / `_refuse_free_form_correction` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`, `report_corrections.check_corrections`, `agent/prompt_cli/corrections.run_corrections_apply`; the retired Python suite and the retired Python suite keep this procedure in the lead contract.
|
|
101
101
|
|
|
@@ -107,7 +107,7 @@ A report-writer materialization without `--corrections` whose narrative already
|
|
|
107
107
|
4. Apply at most one automatic planner self-fix to the narrative. Skip this step when `gating` is `false`.
|
|
108
108
|
5. Run targeted re-verification as round 2 when needed. Skip this step when `gating` is `false`.
|
|
109
109
|
6. Persist the completed `planBodyVerification` value in convergence state. Run `okstra plan-items next-dispatch`: after the single automatic self-fix, settle eligible judgements with `resolve-dissent`; ask the user immediately for decisions outside lead authority. Preserve dissent and do not restart the automatic loop. The exact procedure and enforced authority checks are in `scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` step 8.
|
|
110
|
-
7. Complete the design-surface detector snapshot: `okstra design-snapshot --narrative <reportNarrativePath> --output <designPreparationPath>`, taking both paths
|
|
110
|
+
7. Complete the design-surface detector snapshot: `okstra design-snapshot --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --output <designPreparationPath>`, taking both paths and the declared authoring format from that same run manifest. Nothing else writes that snapshot, and step 8 fails without it — `report_inputs._PLANNING_INPUT_FIELDS` lists `designPreparationPath` as a required planning input.
|
|
111
111
|
8. Run Phase 7 report assembly.
|
|
112
112
|
|
|
113
113
|
The writer never predicts steps 3–7 in its draft. The plan-body verifier reads the plan body, and report assembly adds its completed result afterward.
|
|
@@ -55,6 +55,6 @@ Load the applicable coding conventions for every language the diff will touch, t
|
|
|
55
55
|
- **Resource selection:** use the selected frozen policy above when present. Only legacy inputs without a frozen policy use the `**Coding preflight pack:**` installed path. Read `overview.md` and `clean-code.md`, then select every matching language, framework and architecture resource for the changed files and relevant manifests. Server-side Node includes both JavaScript/TypeScript and Node-server rules. A frozen resource's absence is a blocked input, not permission to substitute live content.
|
|
56
56
|
- **Project policy projection:** a `**Verification inputs:**` declaration supplies the policy and QA baseline through its named projection. Only an unfrozen legacy baseline uses `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` and its `Architecture style`, `Project Review Rule Packs` and `Project QA Commands` sections. Consume fixed text projections; do not open Okstra-owned JSON storage.
|
|
57
57
|
- **Declared architecture style — an authoritative Stage 3 input.** A projected `hexagonal` selects `architectures/hexagonal.md` even without layout signals. Apply H1–H6 and the policy precedence above; declaration also makes H5's otherwise-advisory concrete-adapter item binding. A projected `layered` selects no pack resource: dependencies run from upper to lower layers, never in reverse, and variation points sit on layer boundaries; ports are not required. An explicit `none` selects no architecture overlay. Only an absent or `undeclared` style uses layout detection; an inferred hexagonal overlay retains each rule's criteria and severity, including H5's undeclared-style advisory exception. The verifier applies the same policy; an established current blocking placement violation returns `FAIL`.
|
|
58
|
-
- **Project review rule packs:** union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, read their captured bodies and directly named captured `references/*.md` bodies through the verification-input projection, not live originals. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or substitute live content. Only unfrozen legacy inputs obtain standing standards from project-context and read those declared files and their directly named references; record an unreadable declaration as `project-review-rules: declared <path> unreadable`. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs,
|
|
59
|
-
- **Language-agnostic principles (apply under the policy precedence above):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names that disclose caller-visible mutations and define business terms; domain-oriented query names alone are not defects when their port contract identifies the domain-owned policy; (4) cohesive responsibility, manageable complexity, consistent abstraction levels and
|
|
58
|
+
- **Project review rule packs:** union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, read their captured bodies and directly named captured `references/*.md` bodies through the verification-input projection, not live originals. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or substitute live content. Only unfrozen legacy inputs obtain standing standards from project-context and read those declared files and their directly named references; record an unreadable declaration as `project-review-rules: declared <path> unreadable`. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, inspect newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, misleading public names and mixed responsibilities under their applicable criteria. Establish the explicit project rule breach or concrete maintenance or design impact before treating a preferred alternative as a finding.
|
|
59
|
+
- **Language-agnostic principles (apply under the policy precedence above):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names that disclose caller-visible mutations and define business terms; domain-oriented query names alone are not defects when their port contract identifies the domain-owned policy; (4) cohesive responsibility, manageable complexity, consistent abstraction levels and comprehensible control flow. More than 50 effective lines, deep nesting or inline phases prompt inspection, not an automatic split or failure; record the concrete impact or the reason for retaining a cohesive longer function. Use focused regression and failure tests, with selective mutation checks under `clean-code.md` "Testing discipline" and explicit project requirements. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
|
|
60
60
|
- **Legacy graceful degradation:** if no frozen policy exists and installed resources are unreadable, apply the agnostic principles above and the project's local rules, record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`, and keep unavailable verification explicit. Do not degrade a readable captured policy merely because its original installation is absent. Never claim an unperformed read.
|
|
@@ -14,7 +14,7 @@ profile document.
|
|
|
14
14
|
- For a new `implementation-planning` run, the plan-body sequence is initial verification → one planner self-fix → targeted re-verification → user gate. The initial verification is round 1, the targeted re-verification is round 2, and a second automatic self-fix is a contract violation. A user-directed correction does not consume the automatic self-fix limit, and a verification failure after that correction does not restart the automatic loop.
|
|
15
15
|
- **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected because a teammate pane could not be created — this is the harness running out of room for its own teammate panes, not okstra placing a worker. The wording is the host's, so match the condition rather than a fixed string. (2) **Sandbox CLI-start failure:** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted`. In either case the lead spends the one shared retry budget through the assignment's recorded runner. If the provider is still unavailable, record that terminal status and continue only under the convergence quorum rules; never replace it silently with a fixed provider or count a substitute as the original provider's vote. Completed external-CLI workers hold no pane of their own. A pane the harness opened for its own teammate carries no id okstra recorded, so no okstra command closes it — the host and the user own that surface. (This is a prompt instruction, not a code-enforced gate.)
|
|
16
16
|
- Dual-audience final-report contract (shared):
|
|
17
|
-
- The report writer authors the
|
|
17
|
+
- The report writer authors the input at the run manifest's `reportNarrativePath` using its declared `reportAuthoringFormat`: standard JSON for `json-v1`, or the existing narrative line grammar for `markdown-v1` when the field is absent. Description strings in JSON may contain ordinary Markdown. Report assembly combines it with role-owned machine inputs and publishes data.json once; the reading copy and human HTML are derived from that record.
|
|
18
18
|
- User-facing information belongs in `humanSummary` and the selected task block's `userNarrative`; it must not exist only in Markdown. The HTML human main body explains the result with those fields plus task facts.
|
|
19
19
|
- Agent coordination and audit details belong in `crossVerification`, `executionStatus`, and `tokenUsage`. HTML may expose them only inside collapsed audit details, never as the primary result.
|
|
20
20
|
- Clarification and approval controls are rendered from the lead-owned approval decision ledger after report assembly. A question that could have been resolved before dispatch through the profile or Reporter Confirmations is an intake failure, not a final-report question.
|
|
@@ -7,8 +7,11 @@ TypeScript 포워더가 들고 있던 USAGE 문자열이 여기로 왔다.
|
|
|
7
7
|
from __future__ import annotations
|
|
8
8
|
|
|
9
9
|
import argparse
|
|
10
|
+
import json
|
|
11
|
+
from collections.abc import Sequence
|
|
10
12
|
from pathlib import Path
|
|
11
13
|
import sys
|
|
14
|
+
from typing import TYPE_CHECKING
|
|
12
15
|
|
|
13
16
|
from ..invocation import AgentInvocationError
|
|
14
17
|
from ...worker_prompt_headers import WorkerPromptHeaderError
|
|
@@ -32,6 +35,9 @@ from .results import (
|
|
|
32
35
|
_verify_completion,
|
|
33
36
|
)
|
|
34
37
|
|
|
38
|
+
if TYPE_CHECKING:
|
|
39
|
+
from ...operation_invocation import OperationSlot
|
|
40
|
+
|
|
35
41
|
|
|
36
42
|
_CLI_EPILOG = r"""Usage:
|
|
37
43
|
okstra agent-prompt materialize [options] [--jobs-out <path>]
|
|
@@ -39,6 +45,7 @@ _CLI_EPILOG = r"""Usage:
|
|
|
39
45
|
okstra agent-prompt jobs --project-root <dir> --run-manifest <path> --dispatch-kind <kind> --metadata <path> [--metadata <path>] --out <path>
|
|
40
46
|
okstra agent-prompt check-corrections --project-root <dir> --run-manifest <path> --corrections <file>
|
|
41
47
|
okstra agent-prompt apply-corrections --project-root <dir> --run-manifest <path> --corrections <file>
|
|
48
|
+
okstra agent-prompt resolve-operation --operation <id> [--count <n>] [--model <provider/model> ...] [--host-runtime <host>] [--out <path>] [--json]
|
|
42
49
|
okstra agent-prompt verify [options]
|
|
43
50
|
okstra agent-prompt materialize-result [options]
|
|
44
51
|
okstra agent-prompt complete [options]
|
|
@@ -71,6 +78,18 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
71
78
|
"--count", type=int, default=None,
|
|
72
79
|
help="slots to open, from 1 to the operation contract's count (default: the contract's count)",
|
|
73
80
|
)
|
|
81
|
+
operation.add_argument(
|
|
82
|
+
"--model", action="append", default=[],
|
|
83
|
+
help="provider/model for one team, in team order; repeat per team (overrides operationModels)",
|
|
84
|
+
)
|
|
85
|
+
operation.add_argument(
|
|
86
|
+
"--host-runtime", default="",
|
|
87
|
+
help="also check that every slot resolves a cli-wrapper binding on this host",
|
|
88
|
+
)
|
|
89
|
+
operation.add_argument(
|
|
90
|
+
"--out", default="",
|
|
91
|
+
help="also write the JSON result to this file (the --slots input of code-review prepare)",
|
|
92
|
+
)
|
|
74
93
|
operation.add_argument("--json", action="store_true")
|
|
75
94
|
jobs = commands.add_parser("jobs", help="generate a verified jobs file without dispatching")
|
|
76
95
|
_common_paths(jobs)
|
|
@@ -307,48 +326,66 @@ def _refreeze_contracts(args: argparse.Namespace) -> dict[str, object]:
|
|
|
307
326
|
}
|
|
308
327
|
|
|
309
328
|
|
|
310
|
-
def _resolve_operation(
|
|
311
|
-
|
|
329
|
+
def _resolve_operation(
|
|
330
|
+
operation_id: str, count: int | None, models: Sequence[str] = (), host_runtime: str = "",
|
|
331
|
+
cwd: Path | None = None,
|
|
332
|
+
) -> dict[str, object]:
|
|
333
|
+
"""The slots an operation opens and each slot's model; a skill passes only the operation name.
|
|
334
|
+
|
|
335
|
+
Model selection belongs to `resolve_operation_team()`; this function adds the
|
|
336
|
+
optional host binding check and the output shape.
|
|
337
|
+
"""
|
|
312
338
|
from ...model_pool import ModelPool
|
|
313
339
|
from ...operation_invocation import (
|
|
314
340
|
OperationPreparationError,
|
|
315
|
-
|
|
341
|
+
operation_contract_root,
|
|
342
|
+
resolve_operation_team,
|
|
343
|
+
slot_payload,
|
|
316
344
|
)
|
|
317
|
-
from ...paths import find_asset_root
|
|
318
345
|
from ...registry.provider_registry import default_provider_registry
|
|
319
346
|
|
|
320
|
-
root = find_asset_root(("agents", "operations"), is_present=Path.is_dir)
|
|
321
|
-
if root is None:
|
|
322
|
-
raise AgentPromptCliError(
|
|
323
|
-
"operation contracts not found: no agents/operations under "
|
|
324
|
-
"OKSTRA_HOME or this checkout"
|
|
325
|
-
)
|
|
326
347
|
try:
|
|
327
|
-
slots =
|
|
328
|
-
operation_id,
|
|
329
|
-
|
|
330
|
-
pool=ModelPool.from_registry(default_provider_registry()),
|
|
331
|
-
count=count,
|
|
348
|
+
slots, source = resolve_operation_team(
|
|
349
|
+
operation_id, models, count, contract_root=operation_contract_root(),
|
|
350
|
+
pool=ModelPool.from_registry(default_provider_registry()), cwd=cwd or Path.cwd(),
|
|
332
351
|
)
|
|
333
352
|
except OperationPreparationError as exc:
|
|
334
353
|
raise AgentPromptCliError(str(exc)) from exc
|
|
354
|
+
if host_runtime:
|
|
355
|
+
_check_runnable(slots, host_runtime)
|
|
335
356
|
return {
|
|
336
357
|
"operation": operation_id,
|
|
337
358
|
"dutyId": slots[0].duty_id,
|
|
338
359
|
"roleId": slots[0].role_id,
|
|
339
360
|
"count": len(slots),
|
|
340
|
-
"slots": [
|
|
341
|
-
{
|
|
342
|
-
"ordinal": slot.ordinal,
|
|
343
|
-
"provider": slot.provider_id,
|
|
344
|
-
"modelRef": slot.model_ref,
|
|
345
|
-
"model": slot.display_name,
|
|
346
|
-
}
|
|
347
|
-
for slot in slots
|
|
348
|
-
],
|
|
361
|
+
"slots": [{**slot_payload(slot), "source": source} for slot in slots],
|
|
349
362
|
}
|
|
350
363
|
|
|
351
364
|
|
|
365
|
+
def _check_runnable(slots: Sequence[OperationSlot], host_runtime: str) -> None:
|
|
366
|
+
"""Resolve each slot's cli-wrapper binding on the host, as `code-review prepare` will."""
|
|
367
|
+
from ...assignment_environment import load_assignment_context
|
|
368
|
+
from ...assignment_resolver import AssignmentResolutionError
|
|
369
|
+
from ...dispatch_state import detect_terminal_backend
|
|
370
|
+
from ..invocation import AgentInvocationError
|
|
371
|
+
from ..standalone import standalone_assignment
|
|
372
|
+
|
|
373
|
+
try:
|
|
374
|
+
context = load_assignment_context(
|
|
375
|
+
host_runtime=host_runtime, terminal_backend=detect_terminal_backend(),
|
|
376
|
+
execution_provider_ids=tuple(slot.provider_id for slot in slots),
|
|
377
|
+
include_native_provider=False,
|
|
378
|
+
)
|
|
379
|
+
except ValueError as exc:
|
|
380
|
+
raise AgentPromptCliError(f"cannot check bindings on {host_runtime}: {exc}") from exc
|
|
381
|
+
for slot in slots:
|
|
382
|
+
try:
|
|
383
|
+
standalone_assignment(context=context, provider=slot.provider_id, model_role=slot.role_id,
|
|
384
|
+
model=slot.model_ref, requested_runner="cli-wrapper")
|
|
385
|
+
except (AgentInvocationError, AssignmentResolutionError, RuntimeError, ValueError) as exc:
|
|
386
|
+
raise AgentPromptCliError(f"{slot.model_ref} cannot run on {host_runtime}: {exc}") from exc
|
|
387
|
+
|
|
388
|
+
|
|
352
389
|
def _materialize_batch_command(args: argparse.Namespace) -> int:
|
|
353
390
|
payload = materialize_batch(args, _parser)
|
|
354
391
|
if args.json:
|
|
@@ -380,7 +417,10 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
380
417
|
try:
|
|
381
418
|
args = _parser().parse_args(argv)
|
|
382
419
|
if args.command == "resolve-operation":
|
|
383
|
-
payload = _resolve_operation(args.operation, args.count)
|
|
420
|
+
payload = _resolve_operation(args.operation, args.count, args.model, args.host_runtime)
|
|
421
|
+
if args.out:
|
|
422
|
+
Path(args.out).write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
|
|
423
|
+
encoding="utf-8")
|
|
384
424
|
if args.json:
|
|
385
425
|
_emit(payload, True)
|
|
386
426
|
else:
|
|
@@ -393,7 +433,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
393
433
|
for slot in payload["slots"]:
|
|
394
434
|
print(
|
|
395
435
|
f" slot {slot['ordinal']}: "
|
|
396
|
-
f"provider={slot['provider']} model={slot['modelRef']}"
|
|
436
|
+
f"provider={slot['provider']} model={slot['modelRef']} source={slot['source']}"
|
|
397
437
|
)
|
|
398
438
|
return 0
|
|
399
439
|
if args.command == "jobs":
|