okstra 0.231.1 → 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 -271
- package/dist/cli-registry.mjs +14 -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/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.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.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +98 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- 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/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +163 -5
- package/docs/architecture.md +17 -4
- package/docs/cli.md +511 -0
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +33 -42
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +88 -286
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- 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 +41 -6
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +162 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- 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 +49 -9
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +212 -13
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- 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/doctor.py +8 -25
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- 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 +51 -5
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +148 -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_registration.py +29 -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 +45 -25
- 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 +16 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- 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/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- 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 +16 -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 +6 -6
- 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 +53 -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 +182 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +67 -36
- 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/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- 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/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -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_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +45 -20
- 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/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -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 +92 -136
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
- 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 +31 -0
- package/runtime/skills/okstra-memory/SKILL.md +8 -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/implementation-worker-preamble.md +4 -9
- 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/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +107 -38
|
@@ -20,6 +20,20 @@
|
|
|
20
20
|
|
|
21
21
|
## 1. Project identity
|
|
22
22
|
|
|
23
|
+
`skills/okstra-tdd/SKILL.md` adds a single-session implementation flow independent
|
|
24
|
+
of the cross-verification lifecycle. Its TypeScript state authority is
|
|
25
|
+
`src/commands/trace/trace.mts`, registered as `okstra trace` in
|
|
26
|
+
`src/cli-registry.mts`. It uses `src/lib/report-language.mts` and the built-in
|
|
27
|
+
`templates/trace/trace.template.md`, retaining attempts under `.okstra/traces/`.
|
|
28
|
+
`src/commands/trace/task-link.mts` connects saved traces to the Python task
|
|
29
|
+
projection in `scripts/okstra_ctl/trace_tasks.py`. Registration and completion
|
|
30
|
+
reuse `direct_work.py`; bounded read-only task discovery lives in `task_query.py`
|
|
31
|
+
and is exposed by `task_list_cli.py`. Task manifests retain latest trace metadata
|
|
32
|
+
and compact attempt history without a verification run. Regression owners are
|
|
33
|
+
`tests/run/test_trace_tasks.py`, `tests/run/test_task_query.py` and
|
|
34
|
+
`tests-js/trace.test.mjs`; run `npm run test:js`
|
|
35
|
+
separately from `npm run check`.
|
|
36
|
+
|
|
23
37
|
`okstra` is a host-aware, multi-provider cross-verification runtime distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs one neutral lifecycle core through Claude Code, Codex, or an explicit external adapter around a stable task key.
|
|
24
38
|
|
|
25
39
|
Current baseline:
|
|
@@ -55,8 +69,6 @@ okstra/
|
|
|
55
69
|
│ ├── okstra_vendor/ vendored Jinja2 / MarkupSafe (final-report rendering)
|
|
56
70
|
│ └── lib/okstra/ Bash helpers for okstra.sh
|
|
57
71
|
├── skills/ User-invocable skills (15); `_fragments/` holds shared marker blocks
|
|
58
|
-
├── .agents/skills/ Codex repo-local maintainer skills
|
|
59
|
-
├── .claude/skills/ Claude Code project-only mirror-sync surface
|
|
60
72
|
├── .codex/hooks.json Codex project lifecycle hooks
|
|
61
73
|
├── agents/ native Claude execution-adapter definitions
|
|
62
74
|
├── prompts/ launch/profile contracts, duty catalog, wizard prompt JSON
|
|
@@ -65,8 +77,6 @@ okstra/
|
|
|
65
77
|
├── validators/ run / brief / schedule / view validators
|
|
66
78
|
├── tools/build.mjs source → runtime sync
|
|
67
79
|
├── tools/sync-skill-fragments.mjs expand shared fragment blocks into skills/*/SKILL.md
|
|
68
|
-
├── tools/korean-sources/ maintainer-only Korean mirror drift report
|
|
69
|
-
├── config/korean-sources.json configured English Markdown source roots
|
|
70
80
|
├── runtime/ generated install payload; do not edit directly
|
|
71
81
|
├── tests/ pytest unit suite
|
|
72
82
|
├── tests-e2e/ Bash end-to-end scenarios
|
|
@@ -179,6 +189,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
|
|
|
179
189
|
| `task-list`, `task-show` | `scripts/okstra_ctl/task_list_cli.py`, `scripts/okstra_ctl/task_show_cli.py` | Task/run introspection for skills; `task-show` consumes the Python task read-side snapshot |
|
|
180
190
|
| `resolve-task-key` | `scripts/okstra_ctl/resolve_task_key.py` | Resolve a bare task-id to candidate task-keys from the project catalog |
|
|
181
191
|
| `set-work-status` | `scripts/okstra_ctl/set_work_status.py`, `scripts/okstra_ctl/direct_work.py` | Set user-managed `workStatus`, register an existing brief without a run, and share direct completion records through group memory and task queries |
|
|
192
|
+
| `doyouknow` | `scripts/okstra_ctl/doyouknow/cli.py`, `source_store.py`, `sources/` | Store manual records; configure, collect and list memory, manager and project-task source projections |
|
|
182
193
|
| `time-report`, `log-report`, `error-report`, `error-zip` | `scripts/okstra_ctl/time_report.py`, `scripts/okstra_ctl/log_report.py`, `scripts/okstra_ctl/error_report.py`, `scripts/okstra_ctl/error_zip.py` | Read-side task runtime, wrapper log, and error aggregation helpers |
|
|
183
194
|
| `run-audit` | `scripts/okstra_ctl/run_audit.py` | Anomaly detection — checks run artifacts against progress invariants and reports invariant violations, read-only (Python: `okstra_ctl.run_audit`) |
|
|
184
195
|
| `worker-liveness` | `scripts/okstra_ctl/worker_liveness.py` | Report whether pending workers are still alive, so the lead's poll ends a stalled wait early instead of paying the deadline (Python: `okstra_ctl.worker_liveness`) |
|
|
@@ -204,7 +215,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
|
|
|
204
215
|
| `wizard` | `src/commands/execute/wizard.mts` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
|
|
205
216
|
| `token-usage` | `scripts/okstra-token-usage.py` | Wrap installed Python token usage CLI |
|
|
206
217
|
| `spawn-followups`, `error-log` | `scripts/okstra-spawn-followups.py`, `scripts/okstra-error-log.py` | Follow-up task bundle creation and run error-log append helpers |
|
|
207
|
-
| `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
|
|
218
|
+
| `memory` | `src/commands/memory/memory.mts`, `src/lib/memory-entry-contract.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; share entry validation with Python through `schemas/memory-entry-contract-v1.json`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
|
|
208
219
|
| `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (default `templates/pr/pr-body.template.md`, shared with release-handoff), base-branch recommendation, and a fixed-text generation bundle — template, `<base>..<head>` commits, `<base>...<head>` diffstat and the `templates/pr/drafting-rules.md` drafting rules — used by the okstra-pr-gen skill and the release-handoff lead; `check` lists okstra identifiers left in a drafted body. `--json` preserves the same fields as a machine contract. Git-only; no project registration required |
|
|
209
220
|
| `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper for task and group recaps — `assemble` is a read-only phase-transition summary for a task or, with `--task-group`, the group's start order plus each task's latest conclusion; `record` appends one line to `recap/recap-log.jsonl` (task) or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (`--task-group`); `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
|
|
210
221
|
| `stage-map` | `scripts/okstra_ctl/stage_map_cli.py` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
|
|
@@ -264,7 +275,7 @@ Important modules:
|
|
|
264
275
|
| `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and the waiver-matching mechanics both gates share — `selfmock_path_key` (the one path-normalization), `waiver_entry_key` (the `(file, line, <discriminator>)` triple, with the hand-typed line coerced to `int`) and `partition_waived_entries` (the split into still-failing vs waived). Gate A passes the discriminator `signal`, gate B `mutant`; one definition means the two cannot disagree about whether a waiver matches a finding. The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). The static detector `validators/detect_self_mock.py`, the drift guard and `mutation_probe.py` MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate (`mutation_probe.py`) |
|
|
265
276
|
| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `python` → Cosmic Ray, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). The Python adapter activates only when the worktree has both an installed `cosmic-ray` executable and `cosmic-ray.toml`; Okstra never installs it. It verifies that `module-path` covers every changed Python target and that no target is excluded, snapshots the configured Python source bytes and modes, restores them after every run, and filters the JSONL dump to diff-added lines. A completed session with no applicable operator on a changed line is `nothing-to-verify`; malformed configuration, command/report failures, incomplete trials, and failed source restoration are blocking `integrity-inspection` results. `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
|
|
266
277
|
| `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
|
|
267
|
-
| `path_hints.py` |
|
|
278
|
+
| `path_hints.py` | `run-context`·`active-run-context`의 schemaVersion `2.0` `identity` + `pathHints` 저장과 기존 평면 경로 키 복원을 담당한다. 작성자 형식과 사용량 정책도 보존해 재개 시 입력 경로와 정책을 설치본 기본값으로 바꾸지 않는다 |
|
|
268
279
|
| `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
|
|
269
280
|
| `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it raises `workflow.nextRecommendedPhase.status` to `ready` (keeping the `contract-violated` audit information). It never picks the phase — `phase` is left as the last stage's report routing settled it, and the status is raised only while `phase` is non-empty |
|
|
270
281
|
| `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
|
|
@@ -302,9 +313,9 @@ Important modules:
|
|
|
302
313
|
| `report_execution_evidence.py` | Derives each verifier's execution evidence references and final-verification command rows from the verification execution records, and compares a report's references with them for the phase validators |
|
|
303
314
|
| `report_assembly.py` | Validates the role-owned report inputs and publishes the contract 3.0 record once (assembled in a temp file, then atomically promoted); a bad input aborts with owner / artifact path / field path / reason and preserves the existing `data.json` |
|
|
304
315
|
| `report_projections.py` | Pure projections turning role-owned execution inputs (agent activity, execution status, convergence, design, token usage) into canonical final-report fragments |
|
|
305
|
-
| `report_narrative.py` |
|
|
306
|
-
| `report_corrections.py` |
|
|
307
|
-
| `report_synthesis_packet.py` |
|
|
316
|
+
| `report_narrative.py` | 계약 3.0의 작성자 소유 입력을 manifest의 `reportAuthoringFormat`에 따라 읽고 쓴다. 새 `json-v1`은 표준 JSON 객체와 Markdown 설명 문자열을 사용하며, 기존 `markdown-v1` 줄 문법도 유지한다. 중첩된 기계 소유 필드까지 소유권을 검사한다 |
|
|
317
|
+
| `report_corrections.py` | 리더의 교정 원장(`report-writer-corrections-<task-type>-<seq>-a<N>.json`)을 작성자 소유 스키마·태스크 계약으로 검사하고 선언된 입력 형식으로 교정한다. `replace`·`remove`만 있는 원장은 기계적으로 적용하며, JSON 입력의 필드 이름과 경로는 JSON 키로 안내한다. 호출자는 `agent/prompt_cli/corrections.py`다 |
|
|
318
|
+
| `report_synthesis_packet.py` | 작성자에게 전달할 자료의 소유자·경로·digest와 저작 계약을 `report-writer-synthesis-packet-<task-type>-<seq>.{json,md}`로 동결한다. `initial_prompt_materialization.py`가 디스패치 시 생성하며, 선언된 작성 형식과 해당 확장자를 사용한다. 게시 시 `report_assembly.py`가 원본 digest를 대조한다. 스키마는 `schemas/report-synthesis-packet-v1.0.schema.json`이다 |
|
|
308
319
|
| `approval_decisions.py` | Lead-owned approval-decision input ledger — `disposition` (`select`/`accept-risk`/`request-revision`/`reject`), reach, scope effect, and classification invariants (`correctness-critical`/`noncritical-dissent`/`user-decision`) |
|
|
309
320
|
| `design_snapshot.py` | Builds the design-surface-detector-owned snapshot from the report narrative — reproducible design surfaces plus conservative `PREP-NNN` preparation items (delegates surface detection to `design_surfaces.py`) |
|
|
310
321
|
| `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the full reading copy — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
|
|
@@ -338,6 +349,8 @@ Important modules:
|
|
|
338
349
|
| `resolve_task_key.py` | shared skill helper resolving a bare task-id → `task-catalog.json` candidate entries (`okstra resolve-task-key`) |
|
|
339
350
|
| `code_review_paths.py` | filesystem-layout SSOT for code-review result files — `stage_review_dir` / `branch_review_dir` plus `next_stage_review` / `next_branch_review`, which read the existing files to derive the next round's name (`stage-<NN>.md`, then `-r2`, `-r3`, …) or the next same-day sequence (`<YYYY-MM-DD>-<NN>.md`), so skill markdown never re-derives a literal review path |
|
|
340
351
|
| `code_review_target.py` | `okstra code-review` argument and output boundary. Stage mode reads recorded stage targets; branch mode requires an explicit frozen base. Routes citation checks, verified coverage and conservative follow-up scope proposals. Read-only: it never creates the review directory |
|
|
352
|
+
| `code_review_invocation.py` | binds a standalone code review to its assigned census, selected frozen review policy and fixed comparison range, so the prompt carries applicable rules and calibration |
|
|
353
|
+
| `code_review_integrity.py` | records immutable source/Git integrity evidence (baseline before, audit after execution) for standalone review completions; source, protected-input or semantic Git index changes fail the run. Detects changes after execution; not an OS write sandbox |
|
|
341
354
|
| `code_review_scope.py` | Proposes per-reviewer carry candidates using verified prior coverage, frozen range and rule/policy fingerprints, and recorded source dependencies. Current reviewers still attest the impact boundary and publish current verdicts |
|
|
342
355
|
| `session.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
|
|
343
356
|
| `pane_reclaim.py` | resolves which runs of the current project still hold a non-terminal dispatch, so the `SessionStart(compact)` hook can re-inject the pane-cleanup obligation for them. The signal is the newest `team-state` per run directory, not the central run index — an in-session run never appears there (ADR-0011). Imports the status split from the `dispatch_state.NON_TERMINAL_WORKER_STATUSES` SSOT |
|
|
@@ -405,7 +418,7 @@ Important modules:
|
|
|
405
418
|
| `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
|
|
406
419
|
| `contract_refreeze.py` | re-freezes a running run's frozen contracts in the installed format. A run freezes its duty/role/common contracts at start and pins their digest, so installing a release that changed the contract format leaves that run unable to produce another prompt (`run duty snapshot catalog digest does not match`). Backs `okstra agent-prompt refreeze-contracts`, rewrites the frozen copies and the manifest digest only, and never touches a prompt, result or ledger |
|
|
407
420
|
| `operation_invocation.py` | prepares an Okstra-owned LLM operation that runs outside `okstra-run` — the operation contract (`agents/operations/<id>.json`) owns the duty and the worker count, and the role is derived from that duty's `roleId`, so a skill passes the operation name instead of assembling role/provider/model itself (ADR-0017). Backs `okstra agent-prompt resolve-operation` |
|
|
408
|
-
| `phases/catalog.py` |
|
|
421
|
+
| `phases/catalog.py` | 13개 태스크의 패키지·프로필·보고서 자산과 호스트 지침 필요 여부를 한 자산 루트에서 해석한다. `implementation`·`implementation-planning`만 호스트 지침을 선언하며, 선언한 파일이 없으면 오류를 반환한다. phase 모듈을 import하지 않고 `{{INCLUDE:...}}`도 해석한다 |
|
|
409
422
|
| `phases/final_verification/` | Final-verification policy and assets: `profile.md`/`profile.json` (recorded under the logical paths `prompts/profiles/final-verification.*`), `spec.md` (process note and guarantees), `entry.py` (verification-target request, snapshot writer, prepare-flag checks), `validation.py` (added-surface, verdict, and scope checks that `validate-run` calls before its routing check), `wizard.py` (whole-task pick condition), `target.py` (`acquire_final_verification_target()`: chooses single-stage, containing-stage, or integrated whole-task target behind one task-key mutex), `report.py` (HTML view builder and `verificationScope` reader), and `report_assets/` (report body templates). Its `tests/` directory is collected by pytest and left out of the runtime copy |
|
|
410
423
|
| `report_template_loader.py` | Jinja loader for report templates: a logical name owned by a migrated phase opens from that phase's `report_assets/`, and every other name opens from `templates/reports` |
|
|
411
424
|
| `contract_graph.py`, `contract_graph_cli.py` | runtime-contract graph loader + cross-reference/dependency-closure validator and its `okstra contract-check --root <dir> (--profile\|--operation)` CLI boundary. Loads the agent contract schemas (`common`/`role`/`duty`/`profile`/`operation`), validates known role capabilities, and reports the dependency closure with per-file `path`/`schemaVersion`/`sha256`; an invalid contract raises `ContractGraphError` |
|
|
@@ -437,7 +450,7 @@ Important modules:
|
|
|
437
450
|
| `worker_artifacts.py` | the roster worker-id vocabulary and the artifact paths derived from it |
|
|
438
451
|
| `worker_state.py` | `okstra worker-state transition` — the authoritative status transitions of one persisted team-state |
|
|
439
452
|
| `usage_cells.py` | how a token, cost, or duration figure reads in a report cell; shared by the Markdown and HTML report renderers |
|
|
440
|
-
| `report_contract.py` |
|
|
453
|
+
| `report_contract.py` | 공개 final-report 태스크 계약과 작성자 형식의 정본이다. 보고서 스키마는 `3.0`을 유지하며, `json-v1`·`markdown-v1`과 확장자를 해석한다. 형식 필드가 없는 기존 실행은 `markdown-v1`이고, 알 수 없는 형식이나 3.0 이전 계약의 `json-v1`은 거부한다 |
|
|
441
454
|
|
|
442
455
|
> `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.
|
|
443
456
|
|
|
@@ -476,10 +489,10 @@ Project resolver and read-only state helpers:
|
|
|
476
489
|
Token/cost accounting:
|
|
477
490
|
|
|
478
491
|
- provider adapters: `claude.py`, `codex.py`, `antigravity.py`, `grok.py`, `kimi.py`, `zai/adapter.py` (`grok.py` reads the Grok Build session docs under `~/.grok/sessions/<percent-encoded-cwd>/`, taking cumulative tokens from the last `params.update.usage.modelUsage` snapshot in `updates.jsonl`; `zai/adapter.py` wraps the Claude Code executor for GLM workers — reads `ZAI_API_KEY` from the process env or the current user's `~/.env`, runs each child against `https://api.z.ai/api/anthropic` with `--setting-sources ""`, attests the served model only from response `message.model`, and prices usage at Z.ai's public API rates for `glm-5.3` / `glm-5.3-flash`)
|
|
479
|
-
-
|
|
492
|
+
- 집계: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`. `policy.py`가 manifest의 `usageAccountingPolicy`와 진단을 공유한다. 새 실행의 `advisory`는 확인된 사용량 부재와 불완전 합계를 `null`·진단으로 남기며, 필드가 없는 기존 실행은 `strict`를 유지한다. 잘못된 값·귀속 모호성·예상하지 못한 수집 오류는 실패로 남는다.
|
|
480
493
|
- incremental scan cache: `cursor.py` (`$OKSTRA_HOME/cache/token-usage/` byte cursor + usage event extracts; bypass with `--no-cache`)
|
|
481
494
|
- pricing: `pricing.py`
|
|
482
|
-
-
|
|
495
|
+
- 보고서 반영: `report.py`. `advisory` 실행의 게시 후 재수집은 team-state에만 저장하며, 게시된 `data.json`·HTML을 덮어쓰지 않는다.
|
|
483
496
|
- CLI: `cli.py` via `scripts/okstra-token-usage.py` and `okstra token-usage`
|
|
484
497
|
|
|
485
498
|
### 4.6 `prompts/`
|
|
@@ -513,7 +526,7 @@ Token/cost accounting:
|
|
|
513
526
|
|
|
514
527
|
### 4.8 `schemas/`
|
|
515
528
|
|
|
516
|
-
`schemas/final-report-v3.0.schema.json
|
|
529
|
+
현재 final-report 데이터 계약은 `schemas/final-report-v3.0.schema.json`이다. 작성자는 새 `json-v1`이나 기존 `markdown-v1`의 허용 필드만 작성하고, 조립기가 역할별 기계 소유 입력을 결합해 `final-report-<task-type>-<seq>.data.json`을 원자적으로 게시한다. 두 렌더러가 읽기용 Markdown과 태스크별 HTML을 독립적으로 생성한다. 형식 변경으로 최종 스키마 버전을 올리지 않으며, 기존 v1·v2 판독도 유지한다.
|
|
517
530
|
|
|
518
531
|
The deterministic convergence inputs are `schemas/convergence-groups-v1.0.schema.json`, `schemas/convergence-round-results-v1.0.schema.json`, and `schemas/convergence-critic-results-v1.0.schema.json`. `tools/build.mjs` syncs the entire source `schemas/` directory to `runtime/schemas/`; these JSON Schema files are runtime contracts, not Markdown publication-inventory entries.
|
|
519
532
|
|
|
@@ -540,7 +553,7 @@ Optional (v1.0 backward-compatible) top-level keys:
|
|
|
540
553
|
|
|
541
554
|
14 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mts`; the Claude plugin manifest and the installer both derive from it.
|
|
542
555
|
|
|
543
|
-
|
|
556
|
+
여러 스킬이 공유하는 bash 호출·CLI 버전 확인·Python 준비 문구는 `skills/_fragments/*.md`를 정본으로 두고 `tools/sync-skill-fragments.mjs`가 각 `SKILL.md`의 fragment 마커 사이에 전개한다. `node tools/sync-skill-fragments.mjs --check`로 불일치를 확인한다. 구현·계획의 호스트 절차는 스킬 본문에 미리 전개하지 않는다. wizard가 선택한 태스크의 `orchestration.hostRulesPath`를 반환하면 첫 준비 전에 읽고, 준비 후에는 동결된 `instruction-set/host-orchestration-rules.md`를 사용한다. 설치된 스킬도 이 절차에는 설치 런타임의 지침 경로를 사용한다.
|
|
544
557
|
|
|
545
558
|
| Skill | User-invocable | Role |
|
|
546
559
|
|---|---:|---|
|
|
@@ -577,28 +590,6 @@ These are provider-neutral contracts rendered into every dispatch prompt, not ho
|
|
|
577
590
|
- Tests replace operating-system resources and wall-clock waits with controlled doubles.
|
|
578
591
|
- A higher-layer test keeps only the minimum positive flow needed to detect wiring failures.
|
|
579
592
|
|
|
580
|
-
### 4.13 `tools/korean-sources/`
|
|
581
|
-
|
|
582
|
-
The maintainer-only Korean review mirrors. The tool reports which mirrors have
|
|
583
|
-
drifted and checks a translation's structure; a maintainer session does the
|
|
584
|
-
translating and the writing. Nothing here observes edits or runs on its own.
|
|
585
|
-
|
|
586
|
-
| File | Role |
|
|
587
|
-
|---|---|
|
|
588
|
-
| `cli.mjs` | The three commands: `status`, `validate --source`, `mark --source` |
|
|
589
|
-
| `baseline.mjs` | Drift report and the source/mirror hash pair recorded at the last sync |
|
|
590
|
-
| `config.mjs` | `config/korean-sources.json` validation and source↔mirror path mapping |
|
|
591
|
-
| `markdown.mjs` | Protected-Markdown structure comparison behind `validate` |
|
|
592
|
-
| `path-safety.mjs` | Symlink-refusing repository reads and atomic writes |
|
|
593
|
-
|
|
594
|
-
Source and mirror hold the same document in two languages, so they never hash
|
|
595
|
-
alike and drift cannot be read from the two files alone. `mark` records the pair
|
|
596
|
-
of hashes in `.project-docs/ko-sources/.sync-baseline.json`, which is the only
|
|
597
|
-
state the tool keeps. Maintainers follow `tools/korean-sources/workflow.md`; the
|
|
598
|
-
paired local skills only delegate to it and are not published user skills.
|
|
599
|
-
|
|
600
|
-
---
|
|
601
|
-
|
|
602
593
|
## 5. Key runtime modules
|
|
603
594
|
|
|
604
595
|
### 5.1 Prepare flow
|
|
@@ -647,9 +638,9 @@ Current report pipeline:
|
|
|
647
638
|
|
|
648
639
|
1. Analysis workers write worker result files and the separate audit sidecars named by `Audit sidecar path`.
|
|
649
640
|
2. The lead writes semantic groups; the convergence engine persists working state, per-round plans/results, an optional critic transition, and then a validated `state/convergence-<task-type>-<seq>.json` terminal state: schema v1.4 when newly finalized, or an unchanged historical final schema v1.0, v1.1, v1.2, or v1.3 returned by `reuse-final`.
|
|
650
|
-
3.
|
|
651
|
-
4.
|
|
652
|
-
5.
|
|
641
|
+
3. 작성자는 manifest의 `reportNarrativePath`에 허용된 값을 쓴다. 새 `json-v1`의 경로는 `worker-results/report-writer-narrative-<task-type>-<seq>.json`이며, 기존 `markdown-v1`은 `.md` 경로를 유지한다. Phase 7이 최종 schema v3 보고서를 조립한다.
|
|
642
|
+
4. 구현 계획에서는 `okstra plan-items extract`가 `P-*` 큐를 추출하고 `validate`가 작성자 입력 또는 기존 `data.json`과 대조한다. 새 JSON 입력에는 `--run-manifest`를 함께 전달한다. 분석자별 계획 본문 검증 라운드는 별도로 유지한다.
|
|
643
|
+
5. 게시 시 사용량·비용을 보고서에 투영하며, 새 `advisory` 실행의 미수집 값과 불완전 합계는 `null`·진단으로 남긴다. 게시 후 재수집은 team-state만 갱신한다. 읽기용 Markdown은 `okstra render-final-report`가 `templates/reports/final-report-v2.template.md`에서 필요할 때 생성한다.
|
|
653
644
|
6. `scripts/okstra-render-report-views.py` independently selects one of twelve dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks the record and the human HTML. A quick Markdown input retains its legacy conditional path.
|
|
654
645
|
|
|
655
646
|
For the three analysis sidetracks, the HTML view also exports an immutable-source `## ANALYSIS REVIEW` sidecar. A revision rerun carries that sidecar, reanalyzes the whole confirmed scope, and records one `analysisReviewResolution` row for every affected ID before `validate_analysis_report.py` accepts the result.
|
|
@@ -660,7 +651,7 @@ Both Markdown and HTML are derived, not authoring sources. The schema is the con
|
|
|
660
651
|
|
|
661
652
|
- `scripts/okstra_ctl/domain/role.py` — canonical roles and duty mapping.
|
|
662
653
|
- `scripts/okstra_ctl/model_pool.py` — unified catalog lookup.
|
|
663
|
-
- `scripts/okstra_ctl/model_cli.py` — `okstra model list` and atomic `modelDefaults` writes. No inference call.
|
|
654
|
+
- `scripts/okstra_ctl/model_cli.py` — `okstra model list` and locked, atomic `modelDefaults` and `operationModels` writes. No inference call. `operation_invocation.py` reads `operationModels` and selects an operation's models for `resolve-operation`.
|
|
664
655
|
- `scripts/okstra_ctl/doctor.py` — `model_pool_diagnostics()` for `okstra doctor --json`.
|
|
665
656
|
|
|
666
657
|
---
|
|
@@ -763,7 +754,7 @@ When changing code, keep these docs in sync:
|
|
|
763
754
|
- New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
|
|
764
755
|
- New phase/profile behavior: update the phase directory under `scripts/okstra_ctl/phases/` and its `spec.md`, plus `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
|
|
765
756
|
|
|
766
|
-
Edit
|
|
757
|
+
Edit canonical Markdown sources directly. Maintainer-local notes under `.project-docs/` are neither published nor committed.
|
|
767
758
|
|
|
768
759
|
---
|
|
769
760
|
|
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -2,27 +2,27 @@
|
|
|
2
2
|
"schemaVersion": "1.0",
|
|
3
3
|
"id": "common",
|
|
4
4
|
"assignmentFidelity": [
|
|
5
|
-
"
|
|
5
|
+
"Follow the assigned scope, priorities and acceptance conditions. Preserve project architecture, terminology and ownership; choose the smallest conforming change without unrelated cleanup."
|
|
6
6
|
],
|
|
7
7
|
"requiredInputs": [
|
|
8
|
-
"Read
|
|
8
|
+
"Read required inputs completely. Report missing, unreadable, stale or contradictory inputs instead of inventing their contents."
|
|
9
9
|
],
|
|
10
10
|
"evidenceFirst": [
|
|
11
|
-
"
|
|
11
|
+
"Ground claims in inspected sources and observed results. Distinguish verified facts, inferences and unknowns; evidence outweighs repetition or votes. Recheck settled facts only for a stated cause."
|
|
12
12
|
],
|
|
13
13
|
"authorityAndScope": [
|
|
14
|
-
"Use only
|
|
14
|
+
"Use only granted permissions, tools and project scope. Outward-facing actions require explicit authorization."
|
|
15
15
|
],
|
|
16
16
|
"collaborationAndIndependence": [
|
|
17
|
-
"Respect
|
|
17
|
+
"Respect duty ownership and required independence. Preserve evidence-backed dissent; do not seed another agent's verdict or transfer your required decision to another role."
|
|
18
18
|
],
|
|
19
19
|
"instructionPrecedence": [
|
|
20
|
-
"
|
|
20
|
+
"Task instructions specialize this contract's procedures. They cannot expand authority or override independence and honesty; report such conflicts."
|
|
21
21
|
],
|
|
22
22
|
"conflictHandling": [
|
|
23
|
-
"
|
|
23
|
+
"Preserve the reserved boundaries, continue separable safe work and return the exact unresolved conflict to the responsible lead."
|
|
24
24
|
],
|
|
25
25
|
"completionHonesty": [
|
|
26
|
-
"
|
|
26
|
+
"Finish the assigned checks and deliverables, recovering from safe local failures. Report remaining work, failed or skipped checks and uncertainty; never present unperformed or partial work as complete."
|
|
27
27
|
]
|
|
28
28
|
}
|
|
@@ -2,17 +2,15 @@
|
|
|
2
2
|
"schemaVersion": "1.0",
|
|
3
3
|
"id": "verifier",
|
|
4
4
|
"legacyAliases": [],
|
|
5
|
-
"identity": "
|
|
5
|
+
"identity": "Independently judges assigned artifacts against their acceptance criteria.",
|
|
6
6
|
"responsibilities": [
|
|
7
|
-
"
|
|
8
|
-
"Report a failure with the specific condition that failed and what would satisfy it."
|
|
7
|
+
"Own the verdict and identify each unmet criterion and the evidence or correction that would satisfy it."
|
|
9
8
|
],
|
|
10
9
|
"requiredCapabilities": [
|
|
11
10
|
"source-readonly",
|
|
12
11
|
"worker-artifact-io"
|
|
13
12
|
],
|
|
14
13
|
"prohibitions": [
|
|
15
|
-
"Do not accept a claim on the strength of who made it, how many agreed, or how much effort it represents.",
|
|
16
14
|
"Do not repair the artifact you are verifying."
|
|
17
15
|
]
|
|
18
16
|
}
|
|
@@ -41,6 +41,7 @@ from okstra_ctl.dispatch_core import verify_served_model, verify_served_model_re
|
|
|
41
41
|
from okstra_ctl.dispatch_state import DispatchError # noqa: E402
|
|
42
42
|
from okstra_ctl.execution_manifest import read_execution_manifest_view # noqa: E402
|
|
43
43
|
from okstra_ctl.write_policy import ( # noqa: E402
|
|
44
|
+
build_standalone_review_write_contract,
|
|
44
45
|
WriteEnforcement,
|
|
45
46
|
WritePolicy,
|
|
46
47
|
write_enforcement_from_payload,
|
|
@@ -366,10 +367,15 @@ def _standalone_context(
|
|
|
366
367
|
return str(exc)
|
|
367
368
|
return ""
|
|
368
369
|
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
370
|
+
status = {"standaloneInvocationId": metadata["invocationId"], "role": actual_role}
|
|
371
|
+
policy, enforcement = None, None
|
|
372
|
+
if metadata["audience"] == "code-reviewer":
|
|
373
|
+
policy, enforcement = build_standalone_review_write_contract(
|
|
374
|
+
project_root, prompt_path, metadata_path, metadata,
|
|
375
|
+
)
|
|
376
|
+
status.update(standalonePurpose="code-review", writePolicyDigest=policy.digest,
|
|
377
|
+
writeEnforcement=enforcement.to_payload())
|
|
378
|
+
return _V2InvocationContext(status, verify_attestation, policy, enforcement, "")
|
|
373
379
|
|
|
374
380
|
|
|
375
381
|
def _execution_authority(
|
|
@@ -11,13 +11,15 @@ If unsure, ask the user once: *"Does this project use ports-and-adapters? What f
|
|
|
11
11
|
|
|
12
12
|
These rules are language-agnostic. The examples use TypeScript/Java-ish syntax; translate to Rust traits, Kotlin interfaces, etc., as needed.
|
|
13
13
|
|
|
14
|
+
Apply the policy precedence in `../overview.md`: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Once this overlay is selected, apply each rule's stated criteria and severity whether selection came from a declaration or layout signals. H5 alone keeps its undeclared-style advisory exception. Existing concrete dependencies or misplaced rules do not create an exception to an applicable architecture rule.
|
|
15
|
+
|
|
14
16
|
---
|
|
15
17
|
|
|
16
18
|
## Rule H1 — Ports stay thin
|
|
17
19
|
|
|
18
|
-
A port is the interface (or abstract class) at the domain/application boundary.
|
|
20
|
+
A port is the interface (or abstract class) at the domain/application boundary. It declares an operation's inputs, outputs, errors and domain-owned query specifications without implementing business decisions. Describing those behavioral contracts is part of the port's interface.
|
|
19
21
|
|
|
20
|
-
A port file's method body
|
|
22
|
+
A port file's executable method body does not implement:
|
|
21
23
|
|
|
22
24
|
- `if` statements that branch on domain state.
|
|
23
25
|
- Validation that throws or returns errors based on input shape.
|
|
@@ -53,36 +55,29 @@ Not a violation:
|
|
|
53
55
|
|
|
54
56
|
---
|
|
55
57
|
|
|
56
|
-
## Rule H2 — Adapters
|
|
57
|
-
|
|
58
|
-
Same principle as H1, on the adapter side. The adapter's job is to implement **just** the I/O — a SQL query, an HTTP call, a filesystem read. It is **not** the place to filter by domain state, branch on domain values, or compute business answers.
|
|
58
|
+
## Rule H2 — Adapters execute I/O; the domain owns business policy
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
An adapter translates a port operation into a SQL query, HTTP call, filesystem operation or other I/O. The domain owns the policy that determines eligibility, validity or a business outcome; the adapter may execute that policy's query specification efficiently without redefining its meaning.
|
|
61
61
|
|
|
62
|
-
|
|
63
|
-
- An `if` that rejects results based on a domain rule (*"skip if expired"*, *"exclude shared items"*).
|
|
64
|
-
- A method whose name encodes a business rule — `findValid*` / `findActive* `/ `findEligible*`. The adapter should fetch *things*; the caller (or the query itself) should apply the rule.
|
|
65
|
-
- Multiple joins and conditions assembled specifically to satisfy a compound domain rule — the adapter is answering a business question rather than offering a primitive fetch.
|
|
62
|
+
Inspect policy ownership and preservation of the port contract:
|
|
66
63
|
|
|
67
|
-
|
|
64
|
+
- A predicate or business calculation invented inside an adapter, with no domain-owned policy or defined port contract, hides the decision in infrastructure.
|
|
65
|
+
- An adapter that changes, omits or duplicates the policy's conditions can return a different business answer. Cite the governing policy and the differing condition.
|
|
66
|
+
- Post-fetch filtering merits inspection of its owner and cost. Technical row mapping or execution of a domain-owned specification is not inherently a policy violation.
|
|
68
67
|
|
|
69
|
-
-
|
|
70
|
-
- The method name itself encodes a domain rule that a reader cannot tell from the name alone.
|
|
68
|
+
SQL predicates, joins, aggregation, ordering and pagination may implement a domain-owned query specification at the storage boundary. Complexity or the number of conditions alone does not establish a misplaced rule. Check where the policy is defined and whether the query preserves its semantics.
|
|
71
69
|
|
|
72
|
-
A
|
|
70
|
+
A name such as `findValid*`, `findActive*` or `findEligible*` is valid when the port contract defines that term and identifies its governing policy or specification. An undefined or misleading term is a contract or naming problem, not proof that every business-oriented query belongs outside the adapter.
|
|
73
71
|
|
|
74
|
-
|
|
75
|
-
- Moving the predicate out would force an N+1 (the caller would have to fetch all rows and round-trip per row to decide which are valid).
|
|
72
|
+
Keep efficient execution near the data. Do not replace a policy-driven query with `findAll` plus in-memory filtering merely to move the predicate's syntax. Express the policy at the domain/application boundary and let the adapter translate it while preserving bounded work and avoiding N+1 calls.
|
|
76
73
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
Not a smell:
|
|
74
|
+
Examples of adapter responsibilities:
|
|
80
75
|
|
|
81
76
|
- Simple `WHERE` clauses for *data-shape* reasons (`WHERE user_id = ?`) — that's scoping the fetch, not a business rule.
|
|
82
77
|
- Pagination, ordering, basic projection.
|
|
83
78
|
- Mapping raw rows to domain objects — that's the adapter's translation job.
|
|
84
79
|
|
|
85
|
-
|
|
80
|
+
The review distinguishes changing business policy from translating it for a storage or transport system. A finding names the policy hidden or changed by the adapter and the concrete consequence; a complex query or a domain-oriented name alone is not evidence.
|
|
86
81
|
|
|
87
82
|
---
|
|
88
83
|
|
|
@@ -109,7 +104,7 @@ The test: **is this type/class a thing the business talks about, or is it plumbi
|
|
|
109
104
|
|
|
110
105
|
## Rule H4 — Dependency direction: the domain imports nothing outward
|
|
111
106
|
|
|
112
|
-
|
|
107
|
+
Dependencies point inward. A file under the domain folder imports only from the domain itself and from pure utility code. Read each changed domain file's imports and resolve their targets against the declared boundaries; apply the explicit repository instructions before judging an outward dependency.
|
|
113
108
|
|
|
114
109
|
Violations — any import of:
|
|
115
110
|
|
|
@@ -131,9 +126,9 @@ When the domain needs something the outside owns, invert it: declare the shape a
|
|
|
131
126
|
|
|
132
127
|
When a change adds or modifies a service's dependency on a concrete adapter — constructor injection of a repository class, or direct model / DB access from a service — that boundary should be a port the adapter implements, so the caller depends on shape rather than on infrastructure.
|
|
133
128
|
|
|
134
|
-
|
|
129
|
+
Inspect dependencies this change adds or modifies against the declared boundary and explicit repository instructions. An injection entirely outside the changed scope is not a new finding merely because it already uses a concrete class.
|
|
135
130
|
|
|
136
|
-
|
|
131
|
+
Existing concrete `*Repository` injections do not waive a declared hexagonal boundary. Apply the precedence in `../overview.md` and cite any explicit repository exception. Under a declared hexagonal style, fix a current violating dependency through a port before completion. Without that declaration, record the advisory and a proposed port with the method signatures it needs; do not require unrelated legacy cleanup.
|
|
137
132
|
|
|
138
133
|
---
|
|
139
134
|
|
|
@@ -145,7 +140,7 @@ Violations:
|
|
|
145
140
|
|
|
146
141
|
- An `if` / `else` chain over domain fields that decides an outcome — eligibility, validity, which branch of a business process runs.
|
|
147
142
|
- Arithmetic expressing a business formula: money, ranking, quota, date-based entitlement.
|
|
148
|
-
- A private service method
|
|
143
|
+
- A private service method that implements a business decision such as eligibility, a downgrade formula or status transition. Inspect its body and governing rule; a domain-oriented name alone is not a violation.
|
|
149
144
|
|
|
150
145
|
Not a violation:
|
|
151
146
|
|
|
@@ -155,21 +150,19 @@ Not a violation:
|
|
|
155
150
|
|
|
156
151
|
The test: **if this decision changed, would the change be described as a business rule change or as a plumbing change?** A business rule change that lands in a service is the violation — the rule is now invisible to the domain's own tests, and the next caller that needs it writes its own copy.
|
|
157
152
|
|
|
158
|
-
|
|
153
|
+
Grade an established H6 violation by `clean-code.md` "Finding evidence and grading". A substantial embedded rule, such as money, permissions or a state machine, is a current blocking finding even when layout signals selected this overlay. Current blocking findings are fixed before completion, subject to the explicit repository instructions.
|
|
159
154
|
|
|
160
155
|
---
|
|
161
156
|
|
|
162
|
-
**
|
|
163
|
-
|
|
164
|
-
Severity: advisory in a project that has not declared `architecture.style = hexagonal` — a direction-of-travel rule there, not a correctness gate, so it never blocks on its own. Under that declaration it is blocking: the injection is fixed before the write.
|
|
157
|
+
**Conflict resolution.** The precedence in `../overview.md` applies to every rule in this overlay, including H4 and H5. A surrounding code pattern alone cannot clear an explicit architecture violation. Cite an explicit repository instruction when it overrides a common-pack rule; record an unresolved conflict instead of treating it as a clean result. Boundary interpretation and grading are self-check and review judgments, not a guarantee from import scanning alone.
|
|
165
158
|
|
|
166
159
|
---
|
|
167
160
|
|
|
168
161
|
## Quick checklist before declaring a port/adapter change complete
|
|
169
162
|
|
|
170
163
|
- [ ] No `if` / `.filter` / validation / business math inside any port body.
|
|
171
|
-
- [ ]
|
|
172
|
-
- [ ]
|
|
164
|
+
- [ ] The domain owns business policy; adapter queries and any post-fetch processing preserve that policy and the port contract without redefining it.
|
|
165
|
+
- [ ] Domain-oriented adapter names identify a policy defined by the port contract; query complexity or the name alone is not a violation.
|
|
173
166
|
- [ ] Every entity, value object, domain enum, and domain error is declared under `domain/`.
|
|
174
167
|
- [ ] Port files only declare shape and `import` domain types — they don't *define* them.
|
|
175
168
|
- [ ] No changed domain file imports an ORM, a framework, or anything under adapters / infrastructure / services.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Authoring checks
|
|
2
|
+
|
|
3
|
+
These execution procedures apply only to the worker authorized to change project source. Read-only reviewers evaluate the shared criteria and report findings; this resource grants no write authority. Enforcement is author self-check and code review unless a referenced rule names an automated gate.
|
|
4
|
+
|
|
5
|
+
## Mandatory pre-write checks (every language)
|
|
6
|
+
|
|
7
|
+
- [ ] Read project instructions, configured conventions and every selected resource for this turn. Apply the shared [quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) before editing.
|
|
8
|
+
- [ ] Before adding a unit, search identifiers, behavior, callers, domain literals, error strings and returned-data shapes; read the candidates. Record search terms, nearest implementation and `extend <path:line>` or `new (nothing covers <behavior>)`. Name-only uniqueness does not establish absence; missing survey evidence leaves the addition unfinished.
|
|
9
|
+
- [ ] **Tests planned:** identify retained or extended tests for changed core behavior and meaningful failure outcomes under [Testing discipline](clean-code.md#testing-discipline) and [test reuse](clean-code.md#reuse-tests-before-adding-coverage). Select mutation checks only where needed under those criteria or an explicit project requirement. Record uncovered outcomes, any permitted waiver and its unverified scope there.
|
|
10
|
+
- [ ] Apply the detailed checks in `clean-code.md`, including mutation/state, security, testing, third-party wrappers and failure paths where applicable.
|
|
11
|
+
- [ ] If the hexagonal overlay is selected, apply its H1–H6 criteria and stated exceptions under the policy precedence in `overview.md`.
|
|
12
|
+
|
|
13
|
+
## Completion sweep (before declaring a multi-file change done)
|
|
14
|
+
|
|
15
|
+
- [ ] Review the combined change for shared decisions and exported-name distinctions using `clean-code.md`'s DRY and naming checks, not only per-file checks.
|
|
16
|
+
- [ ] Manually inspect changed tests using the selected language's self-mock signals and `clean-code.md`'s testing criteria. Distinguish the tested unit from injected collaborators. In implementation runs, `validators/detect_self_mock.py` execution and its result files belong to the verifier designated by "Self-mock detection"; authors perform this manual sweep only. `validate-run.py` checks the result.
|
|
17
|
+
- [ ] Run the authorized repository commands selected under [Verification commands](overview.md#verification-commands). Report results, unresolved findings, waivers and unavailable checks without claiming unverified coverage.
|