okstra 0.232.0 → 0.234.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 +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/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 +55 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +320 -3
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +34 -43
- 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/business_flow/cli.py +60 -6
- package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
- package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
- package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
- package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
- package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
- package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
- 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/cli.py +9 -9
- package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/fixed_text.py +10 -0
- 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/project_group.py +175 -0
- package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
- 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/business-flow-v1.schema.json +3 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
- 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 +33 -4
- 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/doyouknow/group-view.css +103 -0
- package/runtime/templates/doyouknow/group-view.js +317 -0
- package/runtime/templates/doyouknow/group-view.template.html +72 -0
- 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
|
@@ -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,7 +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 |
|
|
182
|
-
| `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 |
|
|
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. `sources/business.py`는 프로젝트 그룹에 등록된 프로젝트의 업무 흐름 실행 기록을 흐름·용어·프로젝트 관계로 수집한다. `group_view.py`는 `okstra doyouknow view`로 그룹 하나의 관계·흐름·조사 범위·연결 기록을 `templates/doyouknow/`의 틀·스타일·스크립트와 합쳐 HTML 한 파일로 쓴다 |
|
|
183
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 |
|
|
184
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`) |
|
|
185
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`) |
|
|
@@ -213,6 +223,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
|
|
|
213
223
|
| `container` | `scripts/okstra_ctl/container.py` | Container lifecycle shim; `--text` is the command-specific model projection and machine mode remains JSON |
|
|
214
224
|
| `code-review` | `scripts/okstra_ctl/code_review_target.py` | `okstra code-review target` thin shim into `scripts/okstra_ctl/code_review_target.py` — resolves what one implementation stage's or one branch's review reads (worktree, branch, base/head commits) and where its result file goes, for the okstra-code-review skill. Read-only; creates no directory or file |
|
|
215
225
|
| `manager` | `scripts/okstra_ctl/manager_cli.py` | Cross-project manager; fixed text is the default and `--json` selects machine output |
|
|
226
|
+
| `project-group` | `scripts/okstra_ctl/project_group_cli.py`, `project_group.py` | 이름 붙은 프로젝트 그룹에 속한 프로젝트 루트를 등록·해제·조회한다. 기본 출력은 JSON이고 `--text`가 고정 텍스트를 고른다 |
|
|
216
227
|
| `mcp` | `scripts/okstra_ctl/mcp_cli.py` | `okstra mcp <add\|list\|remove\|check>` — validates and writes project MCP server declarations in `.okstra/project.json` `mcpServers` (name, description, tools, aliases), and reports per provider whether each declared server is `reachable`, `disabled`, `missing`, or `unknown`; `check` and prepare list each provider CLI's servers through `ProviderSpec.mcp_inventory` with no inference call |
|
|
217
228
|
|
|
218
229
|
`src/lib/python-helper.mts` centralizes Node → Python execution so nothing duplicates subprocess wiring.
|
|
@@ -265,7 +276,7 @@ Important modules:
|
|
|
265
276
|
| `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`) |
|
|
266
277
|
| `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` |
|
|
267
278
|
| `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
|
|
268
|
-
| `path_hints.py` |
|
|
279
|
+
| `path_hints.py` | `run-context`·`active-run-context`의 schemaVersion `2.0` `identity` + `pathHints` 저장과 기존 평면 경로 키 복원을 담당한다. 작성자 형식과 사용량 정책도 보존해 재개 시 입력 경로와 정책을 설치본 기본값으로 바꾸지 않는다 |
|
|
269
280
|
| `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
|
|
270
281
|
| `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 |
|
|
271
282
|
| `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
|
|
@@ -303,9 +314,9 @@ Important modules:
|
|
|
303
314
|
| `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 |
|
|
304
315
|
| `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` |
|
|
305
316
|
| `report_projections.py` | Pure projections turning role-owned execution inputs (agent activity, execution status, convergence, design, token usage) into canonical final-report fragments |
|
|
306
|
-
| `report_narrative.py` |
|
|
307
|
-
| `report_corrections.py` |
|
|
308
|
-
| `report_synthesis_packet.py` |
|
|
317
|
+
| `report_narrative.py` | 계약 3.0의 작성자 소유 입력을 manifest의 `reportAuthoringFormat`에 따라 읽고 쓴다. 새 `json-v1`은 표준 JSON 객체와 Markdown 설명 문자열을 사용하며, 기존 `markdown-v1` 줄 문법도 유지한다. 중첩된 기계 소유 필드까지 소유권을 검사한다 |
|
|
318
|
+
| `report_corrections.py` | 리더의 교정 원장(`report-writer-corrections-<task-type>-<seq>-a<N>.json`)을 작성자 소유 스키마·태스크 계약으로 검사하고 선언된 입력 형식으로 교정한다. `replace`·`remove`만 있는 원장은 기계적으로 적용하며, JSON 입력의 필드 이름과 경로는 JSON 키로 안내한다. 호출자는 `agent/prompt_cli/corrections.py`다 |
|
|
319
|
+
| `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`이다 |
|
|
309
320
|
| `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`) |
|
|
310
321
|
| `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`) |
|
|
311
322
|
| `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 |
|
|
@@ -339,6 +350,8 @@ Important modules:
|
|
|
339
350
|
| `resolve_task_key.py` | shared skill helper resolving a bare task-id → `task-catalog.json` candidate entries (`okstra resolve-task-key`) |
|
|
340
351
|
| `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 |
|
|
341
352
|
| `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 |
|
|
353
|
+
| `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 |
|
|
354
|
+
| `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 |
|
|
342
355
|
| `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 |
|
|
343
356
|
| `session.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
|
|
344
357
|
| `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 |
|
|
@@ -406,7 +419,7 @@ Important modules:
|
|
|
406
419
|
| `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
|
|
407
420
|
| `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 |
|
|
408
421
|
| `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` |
|
|
409
|
-
| `phases/catalog.py` |
|
|
422
|
+
| `phases/catalog.py` | 13개 태스크의 패키지·프로필·보고서 자산과 호스트 지침 필요 여부를 한 자산 루트에서 해석한다. `implementation`·`implementation-planning`만 호스트 지침을 선언하며, 선언한 파일이 없으면 오류를 반환한다. phase 모듈을 import하지 않고 `{{INCLUDE:...}}`도 해석한다 |
|
|
410
423
|
| `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 |
|
|
411
424
|
| `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` |
|
|
412
425
|
| `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` |
|
|
@@ -438,7 +451,7 @@ Important modules:
|
|
|
438
451
|
| `worker_artifacts.py` | the roster worker-id vocabulary and the artifact paths derived from it |
|
|
439
452
|
| `worker_state.py` | `okstra worker-state transition` — the authoritative status transitions of one persisted team-state |
|
|
440
453
|
| `usage_cells.py` | how a token, cost, or duration figure reads in a report cell; shared by the Markdown and HTML report renderers |
|
|
441
|
-
| `report_contract.py` |
|
|
454
|
+
| `report_contract.py` | 공개 final-report 태스크 계약과 작성자 형식의 정본이다. 보고서 스키마는 `3.0`을 유지하며, `json-v1`·`markdown-v1`과 확장자를 해석한다. 형식 필드가 없는 기존 실행은 `markdown-v1`이고, 알 수 없는 형식이나 3.0 이전 계약의 `json-v1`은 거부한다 |
|
|
442
455
|
|
|
443
456
|
> `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.
|
|
444
457
|
|
|
@@ -477,10 +490,10 @@ Project resolver and read-only state helpers:
|
|
|
477
490
|
Token/cost accounting:
|
|
478
491
|
|
|
479
492
|
- 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`)
|
|
480
|
-
-
|
|
493
|
+
- 집계: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`. `policy.py`가 manifest의 `usageAccountingPolicy`와 진단을 공유한다. 새 실행의 `advisory`는 확인된 사용량 부재와 불완전 합계를 `null`·진단으로 남기며, 필드가 없는 기존 실행은 `strict`를 유지한다. 잘못된 값·귀속 모호성·예상하지 못한 수집 오류는 실패로 남는다.
|
|
481
494
|
- incremental scan cache: `cursor.py` (`$OKSTRA_HOME/cache/token-usage/` byte cursor + usage event extracts; bypass with `--no-cache`)
|
|
482
495
|
- pricing: `pricing.py`
|
|
483
|
-
-
|
|
496
|
+
- 보고서 반영: `report.py`. `advisory` 실행의 게시 후 재수집은 team-state에만 저장하며, 게시된 `data.json`·HTML을 덮어쓰지 않는다.
|
|
484
497
|
- CLI: `cli.py` via `scripts/okstra-token-usage.py` and `okstra token-usage`
|
|
485
498
|
|
|
486
499
|
### 4.6 `prompts/`
|
|
@@ -514,7 +527,7 @@ Token/cost accounting:
|
|
|
514
527
|
|
|
515
528
|
### 4.8 `schemas/`
|
|
516
529
|
|
|
517
|
-
`schemas/final-report-v3.0.schema.json
|
|
530
|
+
현재 final-report 데이터 계약은 `schemas/final-report-v3.0.schema.json`이다. 작성자는 새 `json-v1`이나 기존 `markdown-v1`의 허용 필드만 작성하고, 조립기가 역할별 기계 소유 입력을 결합해 `final-report-<task-type>-<seq>.data.json`을 원자적으로 게시한다. 두 렌더러가 읽기용 Markdown과 태스크별 HTML을 독립적으로 생성한다. 형식 변경으로 최종 스키마 버전을 올리지 않으며, 기존 v1·v2 판독도 유지한다.
|
|
518
531
|
|
|
519
532
|
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.
|
|
520
533
|
|
|
@@ -541,7 +554,7 @@ Optional (v1.0 backward-compatible) top-level keys:
|
|
|
541
554
|
|
|
542
555
|
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.
|
|
543
556
|
|
|
544
|
-
|
|
557
|
+
여러 스킬이 공유하는 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`를 사용한다. 설치된 스킬도 이 절차에는 설치 런타임의 지침 경로를 사용한다.
|
|
545
558
|
|
|
546
559
|
| Skill | User-invocable | Role |
|
|
547
560
|
|---|---:|---|
|
|
@@ -578,28 +591,6 @@ These are provider-neutral contracts rendered into every dispatch prompt, not ho
|
|
|
578
591
|
- Tests replace operating-system resources and wall-clock waits with controlled doubles.
|
|
579
592
|
- A higher-layer test keeps only the minimum positive flow needed to detect wiring failures.
|
|
580
593
|
|
|
581
|
-
### 4.13 `tools/korean-sources/`
|
|
582
|
-
|
|
583
|
-
The maintainer-only Korean review mirrors. The tool reports which mirrors have
|
|
584
|
-
drifted and checks a translation's structure; a maintainer session does the
|
|
585
|
-
translating and the writing. Nothing here observes edits or runs on its own.
|
|
586
|
-
|
|
587
|
-
| File | Role |
|
|
588
|
-
|---|---|
|
|
589
|
-
| `cli.mjs` | The three commands: `status`, `validate --source`, `mark --source` |
|
|
590
|
-
| `baseline.mjs` | Drift report and the source/mirror hash pair recorded at the last sync |
|
|
591
|
-
| `config.mjs` | `config/korean-sources.json` validation and source↔mirror path mapping |
|
|
592
|
-
| `markdown.mjs` | Protected-Markdown structure comparison behind `validate` |
|
|
593
|
-
| `path-safety.mjs` | Symlink-refusing repository reads and atomic writes |
|
|
594
|
-
|
|
595
|
-
Source and mirror hold the same document in two languages, so they never hash
|
|
596
|
-
alike and drift cannot be read from the two files alone. `mark` records the pair
|
|
597
|
-
of hashes in `.project-docs/ko-sources/.sync-baseline.json`, which is the only
|
|
598
|
-
state the tool keeps. Maintainers follow `tools/korean-sources/workflow.md`; the
|
|
599
|
-
paired local skills only delegate to it and are not published user skills.
|
|
600
|
-
|
|
601
|
-
---
|
|
602
|
-
|
|
603
594
|
## 5. Key runtime modules
|
|
604
595
|
|
|
605
596
|
### 5.1 Prepare flow
|
|
@@ -648,9 +639,9 @@ Current report pipeline:
|
|
|
648
639
|
|
|
649
640
|
1. Analysis workers write worker result files and the separate audit sidecars named by `Audit sidecar path`.
|
|
650
641
|
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`.
|
|
651
|
-
3.
|
|
652
|
-
4.
|
|
653
|
-
5.
|
|
642
|
+
3. 작성자는 manifest의 `reportNarrativePath`에 허용된 값을 쓴다. 새 `json-v1`의 경로는 `worker-results/report-writer-narrative-<task-type>-<seq>.json`이며, 기존 `markdown-v1`은 `.md` 경로를 유지한다. Phase 7이 최종 schema v3 보고서를 조립한다.
|
|
643
|
+
4. 구현 계획에서는 `okstra plan-items extract`가 `P-*` 큐를 추출하고 `validate`가 작성자 입력 또는 기존 `data.json`과 대조한다. 새 JSON 입력에는 `--run-manifest`를 함께 전달한다. 분석자별 계획 본문 검증 라운드는 별도로 유지한다.
|
|
644
|
+
5. 게시 시 사용량·비용을 보고서에 투영하며, 새 `advisory` 실행의 미수집 값과 불완전 합계는 `null`·진단으로 남긴다. 게시 후 재수집은 team-state만 갱신한다. 읽기용 Markdown은 `okstra render-final-report`가 `templates/reports/final-report-v2.template.md`에서 필요할 때 생성한다.
|
|
654
645
|
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.
|
|
655
646
|
|
|
656
647
|
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.
|
|
@@ -661,7 +652,7 @@ Both Markdown and HTML are derived, not authoring sources. The schema is the con
|
|
|
661
652
|
|
|
662
653
|
- `scripts/okstra_ctl/domain/role.py` — canonical roles and duty mapping.
|
|
663
654
|
- `scripts/okstra_ctl/model_pool.py` — unified catalog lookup.
|
|
664
|
-
- `scripts/okstra_ctl/model_cli.py` — `okstra model list` and atomic `modelDefaults` writes. No inference call.
|
|
655
|
+
- `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`.
|
|
665
656
|
- `scripts/okstra_ctl/doctor.py` — `model_pool_diagnostics()` for `okstra doctor --json`.
|
|
666
657
|
|
|
667
658
|
---
|
|
@@ -764,7 +755,7 @@ When changing code, keep these docs in sync:
|
|
|
764
755
|
- New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
|
|
765
756
|
- 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.
|
|
766
757
|
|
|
767
|
-
Edit
|
|
758
|
+
Edit canonical Markdown sources directly. Maintainer-local notes under `.project-docs/` are neither published nor committed.
|
|
768
759
|
|
|
769
760
|
---
|
|
770
761
|
|
|
@@ -799,6 +790,6 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
|
|
|
799
790
|
|
|
800
791
|
## Business flow runtime
|
|
801
792
|
|
|
802
|
-
`scripts/okstra_ctl/business_flow/` implements standalone explanations and optional task integration. `contracts.py` owns requests and artifact-schema access; `source.py` captures candidate source versions and verifies excerpts; `store.py` owns knowledge merging, selection, freshness and conflicts; `invocation.py` prepares and executes the investigator; `engine.py` accepts audited results and coordinates comparison/reconciliation; `report.py` renders the shared accepted result; `hooks.py` connects common preparation and validated completion; `cli.py` exposes `okstra explain-flow`.
|
|
793
|
+
`scripts/okstra_ctl/business_flow/` implements standalone explanations and optional task integration. `contracts.py` owns requests and artifact-schema access; `source.py` captures candidate source versions and verifies excerpts; `store.py` owns knowledge merging, selection, freshness and conflicts; `invocation.py` prepares and executes the investigator; `engine.py` accepts audited results and coordinates comparison/reconciliation; `report.py` renders the shared accepted result; `history.py`는 질문별로 가장 최근에 수락된 설명을 고르고(doyouknow의 `business` 수집원과 전수 조사가 함께 쓴다) `sweep.py`는 프로젝트 그룹의 질문 목록을 계획·실행하는 `okstra explain-flow sweep`을 구현한다; `hooks.py` connects common preparation and validated completion; `cli.py` exposes `okstra explain-flow`.
|
|
803
794
|
|
|
804
795
|
`scripts/okstra_ctl/agent/standalone.py` is shared by standalone prompt materialization and business investigation. It composes existing assignment resolution, duty snapshots and invocation preparation without importing the command-line parser. The public skill is `skills/okstra-explain-flow/SKILL.md`, its behaviour spec is `docs/skills/okstra-explain-flow.md`, and both report templates and `schemas/business-flow-v1.schema.json` ship through the existing runtime build.
|
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -6,7 +6,7 @@ These execution procedures apply only to the worker authorized to change project
|
|
|
6
6
|
|
|
7
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
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 and
|
|
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
10
|
- [ ] Apply the detailed checks in `clean-code.md`, including mutation/state, security, testing, third-party wrappers and failure paths where applicable.
|
|
11
11
|
- [ ] If the hexagonal overlay is selected, apply its H1–H6 criteria and stated exceptions under the policy precedence in `overview.md`.
|
|
12
12
|
|
|
@@ -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
|