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
|
@@ -3,35 +3,27 @@ name: okstra-code-review
|
|
|
3
3
|
description: >-
|
|
4
4
|
Use when the user wants changed code reviewed and the result written to a
|
|
5
5
|
file — either an okstra task's implementation stage, or any branch
|
|
6
|
-
unrelated to an okstra run.
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
one to three reviewers on distinct models (default two) each delegate structure, naming,
|
|
10
|
-
readability, general defects, state and tests to six same-model subagents.
|
|
11
|
-
Model reviewers consolidate their teams before the orchestrator settles the
|
|
12
|
-
combined findings. A coverage audit repeats missing checks on their original model and specialty slots,
|
|
13
|
-
and the orchestrator verifies and settles findings. NOT for writing a PR body (okstra-pr-gen), starting a run
|
|
14
|
-
(okstra-run).
|
|
6
|
+
unrelated to an okstra run. Applies to requests such as "review this stage"
|
|
7
|
+
or "review my branch". Not for generating a PR description (okstra-pr-gen)
|
|
8
|
+
or starting a run (okstra-run).
|
|
15
9
|
---
|
|
16
10
|
|
|
17
11
|
# OKSTRA Code Review
|
|
18
12
|
|
|
19
13
|
Review what a diff changed — one okstra implementation stage, or any branch — against this project's coding-preflight rules, and leave the result as a file under the project.
|
|
20
14
|
|
|
21
|
-
##
|
|
22
|
-
|
|
23
|
-
A reviewer left to build its own worklist enumerates the diff differently every run, so every run finds different things. Here the worklist — the **census** — is built **once, by you, deterministically**, before any reviewer is dispatched. Reviewers receive their slice as input; they never rebuild, reinterpret, or extend it.
|
|
15
|
+
## Rules
|
|
24
16
|
|
|
25
|
-
|
|
17
|
+
The shared coding-preflight pack and declared project policy supply the rules. Use the pack's captured "Finding evidence and grading" section to decide whether a finding is established. Step 2 captures their bodies and selects resources for the frozen range. Reviewers read selected frozen guidance delivered with their invocation; installed paths identify provenance, not replacement content. Do not manually copy rules or the typed census into briefs.
|
|
26
18
|
|
|
27
|
-
|
|
19
|
+
Apply the captured `clean-code.md` "Five simultaneous quality outcomes" through the existing groups and evidence fields. Complete accounting alone does not establish correctness, coding-principle conformance, performance, safety or security.
|
|
28
20
|
|
|
29
|
-
|
|
21
|
+
This file owns execution, authorization and adjudication. Read the relevant contract before its step:
|
|
30
22
|
|
|
31
|
-
|
|
23
|
+
- [Census rules](references/census-rules.md) own target membership, IDs, exclusions, pack allocation and completion criteria.
|
|
24
|
+
- [Review calibration](references/review-calibration.md) owns verdict fields, grades, source citations, clean observations and report layout.
|
|
32
25
|
|
|
33
|
-
|
|
34
|
-
- `references/review-calibration.md` — the per-cell verdict format, severity definitions and points, when `clean` is the correct verdict, and the report's section order.
|
|
26
|
+
Complete accounting is not proof that every defect was discovered. Assignment accuracy, context sufficiency, authorization and semantic truth remain lead checks; parser guarantees are named at the applicable steps.
|
|
35
27
|
|
|
36
28
|
## Step 0 — Preflight
|
|
37
29
|
|
|
@@ -49,7 +41,7 @@ okstra preflight --runtime <host-runtime>
|
|
|
49
41
|
|
|
50
42
|
Branch on the fixed first line:
|
|
51
43
|
- `Okstra preflight: ready` → carry `Project root` as a literal string; every later step is anchored on it.
|
|
52
|
-
- `Okstra preflight: failed` → the check only sees the cwd of the Bash call, so a project that is not the cwd can read as missing setup. Ask whether the user pointed at a specific project directory; if they did, re-run targeting it: `okstra preflight --runtime <host-runtime> --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match).
|
|
44
|
+
- `Okstra preflight: failed` → the check only sees the cwd of the Bash call, so a project that is not the cwd can read as missing setup. Ask whether the user pointed at a specific project directory; if they did, re-run targeting it: `okstra preflight --runtime <host-runtime> --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). If this also fails, show `Reason` and `Recovery`, direct the user to `/okstra-setup`, then stop.
|
|
53
45
|
|
|
54
46
|
<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
|
|
55
47
|
If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
|
|
@@ -79,7 +71,9 @@ Pick the mode from what the user actually gave you:
|
|
|
79
71
|
2. Ask for the comparison base branch, tag or commit unless the user already named one. Do not infer a parent branch or substitute the repository default. Pass it as `--base <ref>`; branch mode rejects an omitted or invalid base and freezes the selected ref as a commit.
|
|
80
72
|
3. Detached HEAD — `git -C <projectRoot> symbolic-ref --quiet HEAD` prints nothing — is refused: ask the user to name a branch. Do not review a bare commit.
|
|
81
73
|
|
|
82
|
-
**
|
|
74
|
+
**Select the comparison range before calling the target CLI.** Honor a supplied range without asking again. The first review normally starts at the recorded PR base. A requested correction review uses the previous reviewed head as `--base` and the current branch head as target unless the user explicitly requests the full PR. Record the PR merge-target branch/base separately in Coverage; selecting another review base changes neither. If the previous head or valid review record is unavailable, recover it or clarify before model calls. Rewritten history or a changed PR base requires an explicit range covering this PR's corrections without independently re-reviewing unrelated incoming work. Keep finding dispositions under [follow-up decisions](#follow-up-decisions).
|
|
75
|
+
|
|
76
|
+
**Then call the target CLI.** Resolve the selected range once. Call it again only if the user changes that range or the target changes before it is frozen. Pass an explicit `--base` in stage mode as well when the selected comparison base differs from the recorded stage base.
|
|
83
77
|
|
|
84
78
|
```bash
|
|
85
79
|
okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --text
|
|
@@ -100,160 +94,120 @@ okstra model-io code-review-input --project-root <projectRoot> --base <baseCommi
|
|
|
100
94
|
Carry this fixed Markdown view into the census and reviewer prompts. Do not
|
|
101
95
|
pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
|
|
102
96
|
|
|
103
|
-
**The user owns the comparison base.** Both modes resolve the selected base to a fixed commit before returning `baseCommit`. Stage mode selects the recorded stage base unless the user explicitly overrides it. Carry the returned hash verbatim into every later command and the report. Do not substitute the default branch or an inferred parent.
|
|
104
|
-
|
|
105
97
|
**Read the frozen head in both modes.** Run git in `worktreePath` when it is non-empty, otherwise in `projectRoot`; call that location `<gitRoot>`. Read every whole source file, caller and test with `git -C <gitRoot> show <headCommit>:<path>`, including clean observations. A checkout on the selected branch may contain uncommitted edits or move during review. `worktreePath` identifies a Git repository, not authority to read its working files. Branch targets leave it empty; a released stage can also have an empty path. Deleted targets are read with `git -C <gitRoot> show <baseCommit>:<path>`; surviving callers and contracts are still read at the head.
|
|
106
|
-
**
|
|
107
|
-
|
|
108
|
-
1. `Use <baseCommit>` — **the recommendation**, the value the CLI returned.
|
|
109
|
-
2. `Show what this range covers` — print `git -C <workdir> log --oneline <baseCommit>..<headCommit>`, then ask the same three options again.
|
|
110
|
-
3. `Enter directly` — always last: the user types a ref, and you call the target CLI a second time with `--base <that ref>`. Every field from the second call replaces the first call's, including `reviewPath` and `round`.
|
|
98
|
+
**Show the fixed range.** Print `baseCommit` and `headCommit` next to their `git -C <gitRoot> log -1 --oneline <commit>` descriptions. A user-specified or previously authorized range needs no second confirmation. Ask only when the intended range is ambiguous or the resolved range differs from it; do not dispatch until that discrepancy is resolved. If the user supplies a replacement base, call the target CLI with `--base <that ref>` and replace every returned field, including `reviewPath` and `round`.
|
|
111
99
|
|
|
112
100
|
## Step 2 — Census the diff
|
|
113
101
|
|
|
114
|
-
1. **Read
|
|
115
|
-
2. Collect the diff from
|
|
116
|
-
3. **
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
5. Restate both completion criteria and show they hold: censused files + exclusions = files in the diff, and every hunk maps to a censused function or to file-level code.
|
|
121
|
-
|
|
122
|
-
**Membership is mechanical; judgment only ever decides a cell's verdict.** Never drop a cell because you doubt the rule applies to it — that doubt is the reviewer's answer, and its name is `clean`. Over-inclusion costs one line; a judged exclusion is the run-to-run variance this census exists to remove.
|
|
102
|
+
1. **Read [census rules](references/census-rules.md).** Resolve `<okstraHome>` with `okstra paths --field home`; use its `prompts/coding-preflight/review-rules.json` as `<rules-path>`, without retyping a parallel catalog.
|
|
103
|
+
2. Collect the diff from Step 1's Git root: `git -C <gitRoot> diff --name-status <baseCommit>..<headCommit>` for files and `git -C <gitRoot> diff <baseCommit>..<headCommit>` for hunks. First run `git -C <gitRoot> rev-list --count <headCommit>..<baseCommit>`: a nonzero count is the divergence case in Exceptions. An empty diff dispatches no reviewers.
|
|
104
|
+
3. **Capture and select one policy.** Set `<census-path>` to `<projectRoot>/.okstra/agent-invocations/code-review/<review-id>.census.md`, where `<review-id>` names this review and round (for example `pr<N>-r<round>`). `code-review census` refuses a census whose `.policy.json` would fall outside the project's `.okstra/`, and reuses the immutable policy already published beside an existing `<census-path>`, so give every new review round its own `<review-id>`. Step 3's `code-review prepare` writes the specialists' assigned censuses, slots, brief and batch in the same directory. Run `okstra code-review census --project-root <projectRoot> --base <baseCommit> --head <headCommit> --rules <rules-path> --out <census-path>`. The command captures canonical coding rules, declared project policy and protocol/calibration, then selects resources from the fixed range; declared architecture precedes layout signals. When resolved stage inputs explicitly name a run manifest, add `--run-manifest <run-manifest>` to reuse its author's captured policy. Never infer a latest run or claim policy equality without that source. Additional applied project policy uses repeated `--policy <path>` inputs in the same capture.
|
|
105
|
+
4. Inspect the actual diff for embedded SQL, ORM queries and other resource needs automatic path/manifest routing misses. Add repeated `--resource <pack-relative-id>` inputs for applicable resources present in the archive; do not route again for a specialist. Review selection excludes author-only source-writing procedures. Add `--previous-census <prior-census-path>` only for [ID continuity](references/census-rules.md#follow-up-review). Exit 1 identifies unresolved non-Python function boundaries: complete their manual inventory before dispatch.
|
|
106
|
+
5. Carry the returned literal `Review policy` path as `<review-policy-path>`; the shared snapshot is `<census-path>.policy.json`. Preserve its `Review policy digest` and `Review resources` metadata lines in every full or assigned census. `-` resources means no explicit additions. Keep the same snapshot and resource values for every specialist and gap-fill, passing additions to `code-review prepare` as the same repeated `--resource` inputs. Materialization routes language and framework bodies from the assignment's own targets, so a specialist can receive fewer packs than the census selection lists; the rule catalog and architecture routing stay identical because architecture detection reads the whole frozen tree. Mutable installed skill or calibration paths are capture inputs, never replacements for delivered frozen guidance.
|
|
107
|
+
6. Verify [both completion criteria](references/census-rules.md#completion-criteria) and follow [What to emit](references/census-rules.md#what-to-emit). Preserve the complete census and policy selection. Report a large census's size without truncation; dispatch follows the [authorization boundary](#authorization-and-recovery), not another confirmation based on size alone.
|
|
123
108
|
|
|
124
|
-
|
|
109
|
+
## Step 3 — Select model teams and prepare every specialist
|
|
125
110
|
|
|
126
|
-
|
|
111
|
+
Select one to three model teams; default to 2. Honor an explicit count without asking again; otherwise offer 2 as recommended, with 1 and 3 as alternatives. When the user names models, pass each as `--model <provider/model>` in team order instead of `--count`; otherwise the project's or global `operationModels.code-review`, then the adapter defaults, supply them. Write the result beside the census:
|
|
127
112
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
```
|
|
131
|
-
okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount>
|
|
113
|
+
```bash
|
|
114
|
+
okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount> --host-runtime <host-runtime> --out <projectRoot>/.okstra/agent-invocations/code-review/<review-id>.slots.json
|
|
132
115
|
```
|
|
133
116
|
|
|
134
|
-
|
|
135
|
-
provider and model. The operation contract (`agents/operations/code-review.json`) owns the duty and count ceiling;
|
|
136
|
-
the duty supplies the role, and the runtime model pool supplies the provider/model assignments.
|
|
137
|
-
Always pass the selected count explicitly; the operation contract's count is the ceiling, not this skill's default.
|
|
138
|
-
A machine with too few distinct models fails here rather than quietly running fewer reviewers.
|
|
139
|
-
Dispatch exactly the returned slots; never replace them with a remembered or preferred model list.
|
|
140
|
-
Keep the resolved assignments within that review and its gap-fills. Child inheritance below refers to
|
|
141
|
-
the selected runtime assignment, never to a specific model required by this skill.
|
|
117
|
+
The printed slots and their `source` are authoritative; `--host-runtime` has already confirmed each slot's binding on this host. Every team has a different provider, and the operation contract owns the ceiling. Do not substitute remembered or preferred models; to change models at the user's request, run the command again with `--model`. Carry `<reviewerCount>` and the slots file into this review and its gap-fills.
|
|
142
118
|
|
|
143
|
-
Each
|
|
119
|
+
Each slot is one model team of four specialists, each under the slot's exact provider/model; the lead dispatches them, and no model call dispatches another.
|
|
144
120
|
|
|
145
|
-
|
|
|
121
|
+
| Specialist within every model team | Assigned axis | Assigned rule IDs |
|
|
146
122
|
|---|---|---|
|
|
147
123
|
| Structure | `structural` | `S1`–`S4`, plus routed `S5`–`S10` |
|
|
148
|
-
|
|
|
149
|
-
| Readability | `semantic` | `M2`, `M3` |
|
|
124
|
+
| Semantic | `semantic` | `M1`–`M3` |
|
|
150
125
|
| General defects | `general` | `G1`–`G5` |
|
|
151
|
-
| State | `state-and-tests` | `T1` |
|
|
152
|
-
| Tests | `state-and-tests` | `T2`–`T4` |
|
|
126
|
+
| State and tests | `state-and-tests` | `T1`–`T4` |
|
|
153
127
|
|
|
154
|
-
|
|
128
|
+
`code-review prepare` splits the census into these axes, one `<review-id>.<axis>.census.md` each, and refuses a split that changes the rule catalog or leaves a cell unowned or doubly owned. A specialist whose axis has no cells is not prepared; record that acknowledgment. Never divide specialists between models or borrow another team's verdicts. An inability to run a specialist under the exact provider/model binding is an execution blocker, not permission to substitute a model, merge specialists into one call or simulate specialists as headings.
|
|
155
129
|
|
|
156
|
-
|
|
130
|
+
### Authorization and recovery
|
|
157
131
|
|
|
158
|
-
|
|
132
|
+
The authorized review includes up to `4 × reviewerCount` specialist calls and the continuations in [Step 3.5](#step-35--audit-the-coverage). Existing authorization remains valid for investigation, safe recovery, resumed work and reinspection within the approved scope, assigned models and user-set call/cost limits. A stopped invocation, new invocation ID or automatic-retry stop does not revoke that authorization. Request approval only before expanding the approved scope, changing assigned models or exceeding a user-set call/cost limit. Pass a user-set call limit to `start` as `--max-calls`; it refuses to start calls beyond it, automatic repairs included. No command checks a cost limit; the lead tracks it. An insufficient limit blocks the affected dispatch rather than silently reducing the team. Authorization accuracy remains a lead check.
|
|
159
133
|
|
|
160
134
|
### Shared test execution evidence
|
|
161
135
|
|
|
162
|
-
|
|
136
|
+
Inspect repository test commands and requirements before dispatch. Reuse results only when source tree, dependencies, configuration and inputs match the frozen head. Otherwise the lead runs relevant tests once in an isolated checkout of that head, preserving command, head, environment, exit code and full log. Follow the repository's full-gate timing and existing external/paid/destructive-test permissions. Share results with all teams; necessary additional local tests run once through the lead. Reviewers neither edit/add tests nor launch duplicate suites.
|
|
163
137
|
|
|
164
|
-
|
|
138
|
+
Each State and tests specialist independently inspects assertions, failure/boundary discrimination and self-mocking; passing commands do not prove correctness or conformance. Corrections invalidate affected results only. Report missing, failed or blocked checks in the [test-evidence fields](references/review-calibration.md#the-report). These are lead/reviewer checks, not parser guarantees.
|
|
165
139
|
|
|
166
|
-
|
|
167
|
-
`.okstra/agent-invocations/code-review/<invocation-id>.instructions.md` from that reviewer's brief, then run
|
|
168
|
-
`okstra agent-prompt materialize --project-root <projectRoot> --invocation-id <invocation-id> --host-runtime <runtime> --provider <slot provider> --model <slot model> --model-role <role> --audience <duty> --purpose code-review --instruction <instructions-path> --prompt <prompt-path>`,
|
|
169
|
-
copying `role`, `duty`, and the slot's `provider` and `model` verbatim from `resolve-operation` (`--model`
|
|
170
|
-
takes the `provider/model` value the slot line prints). The prompt path is the canonical `.prompt.md` beside
|
|
171
|
-
the instructions file; the returned assignment is authoritative. Run `okstra agent-prompt verify` against the returned `metadataPath` before
|
|
172
|
-
invoking any model.
|
|
140
|
+
### Inspection scope and briefing
|
|
173
141
|
|
|
174
|
-
|
|
175
|
-
process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path> "" <role> --invocation-metadata <metadataPath>`
|
|
176
|
-
with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
|
|
177
|
-
standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
|
|
178
|
-
`.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
|
|
179
|
-
it. **Every reviewer receives its assigned census** and independently owns its verdicts. On follow-ups, add that slot's verified previous results and scope decision as described below. Every brief carries:
|
|
142
|
+
Write one shared brief to `<projectRoot>/.okstra/agent-invocations/code-review/<review-id>.brief.md`. It carries the diff and the frozen read command; a short project layout; shared test evidence and blockers; and the inspection requirements below. `prepare` appends each specialist's team, axis, census paths and its `code-review scope` output, and materialization delivers the canonical rules and cells, so do not copy them into the brief. A specialist's task grants no delegation. Require its [baseline, dependency and carry fields](references/review-calibration.md#compact-rule-coverage), including current coverage for inherited cells. Do not restate the materialized duty.
|
|
180
143
|
|
|
181
|
-
|
|
182
|
-
- the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
|
|
183
|
-
- **the assigned census** — its rule subset and grouped cells, verbatim, plus its model-team slot, specialty, parent coordinator ID and the full census path for context. Coordinators receive the full census and all six child assignments; children receive only their own verdict assignment
|
|
184
|
-
- the absolute paths of the packs allocated to its axes (from step 2's routing)
|
|
185
|
-
- shared test execution evidence, including missing or blocked verification
|
|
186
|
-
- the full-context inspection requirement: read whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head; follow transitive effects as needed. Read with targeted `git show` ranges and `git grep`; never print a whole generated report or graph dump (for example under `graphify-out/`) into a child's context. Specialty limits verdict ownership, not access to context. Report a suspected issue outside the assignment to the lead, who checks it and routes any required inspection to the owning specialist without duplicating or changing cells
|
|
187
|
-
- the calibration path, written out in full as Step 2 fixed it — `~/.agents/skills/okstra-code-review/references/review-calibration.md`. The verdict format, the severity points, and the rules for a legitimate `clean` are defined there, not in the brief; a reviewer that cannot open this file cannot return a usable verdict, so never hand it a relative path or a "next to the skill" hint
|
|
144
|
+
Every reviewer reads whole target files, enclosing definitions, affected callers/callees, outcome consumers, contracts and tests at the frozen head, following transitive effects. Open definitions before claiming their behavior. Use targeted `git show` ranges and `git grep`, not whole generated reports or graph dumps. A specialist's axis limits verdict ownership, not context access. Route suspected issues on another axis through the lead without changing cells. Every reviewer also reads the delivered frozen calibration and applicable rule sections completely, without clipping normative lines.
|
|
188
145
|
|
|
189
|
-
|
|
146
|
+
Every applied project instruction belongs in the shared snapshot. Snapshot content, resource selection and catalog bindings are fingerprinted, and materialization separately freezes its rendered role and duty contracts. For a new correction base, inspect the whole current census without earlier full-PR completions as reuse inputs. Full inspection means the supplied census, not an expanded PR range.
|
|
190
147
|
|
|
191
|
-
|
|
148
|
+
With an unchanged comparison base and policy, pass the previous round's batch as `--previous-batch`: `prepare` offers each item only the completions of the same team ordinal, axis, provider and model, latest attempt first, and `code_review_scope.py::review_scope` checks prior integrity, baseline, ancestry, references and policy fingerprints. Incompatible or legacy baselines fall back to full inspection, while invalid integrity stops calculation. Prior findings, changed targets/recorded inputs, unverified cells and missing dependency records reopen. Prior records remain immutable; an identical range, rules and completed adjudication need no new call.
|
|
192
149
|
|
|
193
|
-
|
|
194
|
-
okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --policy <skill-path> --policy <calibration-path> --policy <census-rules-path> --policy <duty-contract-path>
|
|
195
|
-
```
|
|
150
|
+
`Recheck` is mandatory; `Carry candidates` are proposals. Before inheriting any verdict, search the delta's changed symbols and wiring beyond recorded dependencies, including result/error mappings, state, test assumptions, contracts and downstream work. Reopen newly affected cells across applicable axes. Unknown reachability, dynamic/configuration-driven wiring or unexplained failures require broader supporting inspection, up to the full current census. Source outside that census remains context, not an independent target. Expanding the comparison range or model-call authorization requires approval. Dependency completeness and current boundary attestations remain reviewer/lead judgments; scope output cannot mark a cell clean.
|
|
196
151
|
|
|
197
|
-
|
|
152
|
+
### Authenticated invocations
|
|
198
153
|
|
|
199
|
-
|
|
154
|
+
Prepare every specialist of every team in one call:
|
|
200
155
|
|
|
201
|
-
|
|
156
|
+
```bash
|
|
157
|
+
okstra code-review prepare --project-root <projectRoot> --review-id <review-id> --census <census-path> --review-policy <review-policy-path> --base <baseCommit> --head <headCommit> --slots <slots-path> --brief <brief-path> --host-runtime <host-runtime> [--resource <pack-relative-id> ...] [--previous-batch <previous-batch-path>]
|
|
158
|
+
```
|
|
202
159
|
|
|
203
|
-
|
|
160
|
+
Pass the same `--resource` values as the census. For each team and axis, `prepare` writes the instructions, materializes the prompt under the cli-wrapper runner with the frozen policy, assigned census and fixed range, and verifies it. It prints one `Item:` row per prompt and writes `<review-id>.batch.json`. Show the selected teams and items before dispatch. An identical rerun reuses every published file; a refusal names the items already prepared. Use a new `<review-id>` when an input must change.
|
|
204
161
|
|
|
205
|
-
|
|
206
|
-
|---|---|---|
|
|
207
|
-
| `structural` | non-test source file × `structural` | core principles 1, 2, 3, 6; `clean-code.md` DRY / KISS / SOLID / YAGNI; the completion sweep's domain-literal and documented-fork items; plus the architecture pack when one was routed |
|
|
208
|
-
| `semantic` | function × `semantic` | core principles 4, 5; `clean-code.md` meaningful naming, functions-do-one-thing, the plain-English summary test, the 50-line cap, nesting depth, magic numbers, comments-explain-why |
|
|
209
|
-
| `state-and-tests` | non-test source file × `state-and-tests`, test file × `state-and-tests` | `clean-code.md` "Mutation and state boundaries" and "Testing discipline"; plus the routed language pack's self-mock signals |
|
|
210
|
-
| `general` | non-test source file × `general` | correctness bugs, swallowed errors, `clean-code.md` "Untrusted input and security" (work that grows faster than the input before a size bound rejects it, input building SQL / shell / paths / fetch targets / templates / regexes, a new entry point without auth or ownership checks, secrets or personal data in code, logs or responses, evaluating input), clear performance problems, core principle 7 (fix at the cause — nothing previously green edited to silence a failure); `clean-code.md` "Wrapping a third-party call" — a recovery branch the library already performs, a comment naming a condition the call site never establishes, a rethrow that drops the original error; plus the routed language pack's language-specific traps |
|
|
162
|
+
Every specialist call and continuation keeps its own invocation ID (`<review-id>-t<team>-<axis>-a<attempt>`) and is authenticated by the commands of Step 3.5. The single-invocation commands (`agent-prompt materialize`, `verify`, the provider wrapper, `materialize-result`, `complete`, `verify-completion`, `code-review scope` and `check-coverage`) remain for diagnosis and manual recovery only.
|
|
211
163
|
|
|
212
|
-
|
|
164
|
+
## Step 3.5 — Audit the coverage
|
|
213
165
|
|
|
214
|
-
|
|
215
|
-
`okstra agent-prompt materialize-result`, publish the immutable completion marker with
|
|
216
|
-
`okstra agent-prompt complete`, then run `okstra agent-prompt verify-completion`. Parse only the
|
|
217
|
-
`returnedBody` emitted by that last command. A model response without a verified completion is not a
|
|
218
|
-
review result and cannot contribute a verdict.
|
|
166
|
+
Start every prepared specialist, then wait for them:
|
|
219
167
|
|
|
220
|
-
|
|
168
|
+
```bash
|
|
169
|
+
okstra code-review start --project-root <projectRoot> --batch <batch-path> [--max-calls <user-set-call-limit>]
|
|
170
|
+
```
|
|
221
171
|
|
|
222
|
-
|
|
172
|
+
```bash
|
|
173
|
+
okstra code-review await --project-root <projectRoot> --batch <batch-path> --timeout-seconds 540
|
|
174
|
+
```
|
|
223
175
|
|
|
224
|
-
1.
|
|
225
|
-
2. Compare the collected results with the assigned subsets and the received full census; list missing cells and rules by responsible child.
|
|
226
|
-
3. Return only those omissions or invalid verdicts to the same responsible subagent, preserving its logical child identity and original assignment. Resume that child when supported; otherwise use a linked continuation invocation with its prior verified results. Do not assign the omission to another reviewer or restart completed investigations.
|
|
227
|
-
4. Collect the supplementary results and repeat the audit and requests until no cells or rules remain unaccounted for. A new invocation ID records each continuation without changing logical ownership.
|
|
228
|
-
5. Only then consolidate the complete results and return the model report. A stopping condition below produces an explicitly incomplete status with its blocker, never a completed review.
|
|
176
|
+
`start` launches each item in its own session and returns; the wrapper keeps running after the call ends, and a supervisor records its exit even when it fails preflight. `await` stops after the timeout with `POLL_TIMEOUT` (exit 75); call it again until it prints `ALL_DONE` (exit 0 complete, 1 incomplete). Keep the timeout below the host's command time limit. Do not run the wrappers yourself while a batch is in progress.
|
|
229
177
|
|
|
230
|
-
For each
|
|
178
|
+
For each finished item, `await` publishes the raw return from `.tmp/`, writes and verifies the completion, and audits it against its own axis census. Frozen standalone completions are bound to the source/index integrity audit; a mutation or invalid audit fails the item. It then audits each team and axis over all of that specialist's attempts, latest first, and each team over the full census. `Item:`, `Axis:` and `Team:` rows report states, missing and unknown cells. A row for another axis's cell is an unknown cell on that axis. Read each completed item's verified body with:
|
|
231
179
|
|
|
232
180
|
```bash
|
|
233
|
-
okstra
|
|
181
|
+
okstra agent-prompt verify-completion --project-root <projectRoot> --purpose code-review --completion <completion-path> --json
|
|
234
182
|
```
|
|
235
183
|
|
|
236
|
-
|
|
184
|
+
Only that command's `returnedBody` is usable. Audit current verified completions and gap-fills only; prior completions are scope inputs, never current verdicts. `code_review_coverage.py` verifies completions and refuses mixed model assignments; `review_verdicts.py` checks the supplied catalog, rule accounting and source anchors at the fixed commits. Neither proves exhaustive references or semantic truth.
|
|
237
185
|
|
|
238
|
-
|
|
186
|
+
`await` repeats two cases once per team and axis without the lead: an invocation that exits non-zero without a returned body is retried, and an attempt whose rejected cells were all rejected for how their rows are written gets a format repair of those cells carrying the parser's reasons. Format reasons cover the table columns, duplicate rows or rule verdicts, an N/A alias, the finding ID form, a finding body missing outside the Coverage Verdicts section, and the wording of clean-check evidence; a missing row counts only when the response has no verdict at all. Rejections for unchecked or unknown rules and for evidence that names a missing file or line are not format reasons and wait for `gap-fill`. Do not repeat those yourself. A repeated failure stops blind retries; diagnosed recovery after correcting its cause follows the [same authorization](#authorization-and-recovery).
|
|
239
187
|
|
|
240
|
-
|
|
188
|
+
For every other open cell, request the next attempt from the same logical specialist:
|
|
241
189
|
|
|
242
|
-
|
|
190
|
+
```bash
|
|
191
|
+
okstra code-review gap-fill --project-root <projectRoot> --batch <batch-path> [--reject <team>:<cell-id> ...]
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`gap-fill` sends only each latest attempt's missing or invalid cells, plus cells you reject, with their reasons and the previous attempt's verified body, under the same range, rules and full-context requirements; a failed or stalled attempt gets its whole assignment again. Then `start` and `await` the new items. It prints `NO_PROGRESS: <team>/<axis>` instead of a new attempt when the last gap-fill closed none of its cells; stop that pair. Each specialist's progress is judged separately; one specialist's stop does not stop another's permitted work. Do not reassign omissions or rerun completed investigations.
|
|
195
|
+
|
|
196
|
+
Stop blind gap-fills when they make no progress, evidence is unavailable, authentication, billing, execution or integrity verification fails, or a response has unknown cell IDs. Preserve the response and diagnose the cause; do not relabel unknown IDs or repeat the same failing invocation without a concrete recovery. A reached user call/cost limit stops further calls covered by that limit.
|
|
243
197
|
|
|
244
|
-
|
|
198
|
+
Continue investigation, safe recovery and re-verification within the [existing authorization](#authorization-and-recovery). Resume affected checks once evidence shows the blocker is resolved, retaining the fixed range, assigned model and frozen policy. Preserve prior results, baselines and audit records unchanged; do not weaken checks, rewrite evidence or accept a failed result to make recovery pass. Failure alone is not a reason to request renewed approval.
|
|
245
199
|
|
|
246
|
-
|
|
200
|
+
While a blocker remains unresolved, continue other permitted work and record every unevaluated pair, owner and blocker in [Coverage](references/review-calibration.md#the-report). These checks have no defect kind, severity, timing or points; the review remains incomplete even at score zero. Manual assessment cannot replace verified reviewer coverage. The lead checks recovery evidence and authorization bounds; the parser checks accounting and source anchors.
|
|
247
201
|
|
|
248
|
-
|
|
202
|
+
An isolated false observation reopens the affected cells and any dependent conclusions, not automatically every valid verdict. Reject those cells with `gap-fill --reject <team>:<cell-id>`; the next attempt's rows come first in every later audit, so the corrected row replaces the disproved one while the older attempt still covers unaffected cells. If the error's extent cannot be bounded, report the uncertainty and re-inspect the full affected assignment under the [existing authorization](#authorization-and-recovery). Never edit an immutable response to make it pass.
|
|
249
203
|
|
|
250
|
-
|
|
204
|
+
Before accepting clean general cells, open and verify their [G2/G3/G5 observations](references/review-calibration.md#compact-rule-coverage). Contradictory source evidence rejects the affected cells and dependent conclusions through the bounded procedure above. This is a truth check beyond the parser's format/source-location checks.
|
|
251
205
|
|
|
252
|
-
|
|
206
|
+
### Audit each team, then compare teams
|
|
253
207
|
|
|
254
|
-
|
|
208
|
+
The `Team:` rows of the final `ALL_DONE` are each team's full-census audit over every current completion of that team, gap-fills included. Specialists own disjoint cells, so their union is the team's full-census coverage. Build each team's model report from its verified `returnedBody` values only: namespace finding IDs by team and specialist, retain every finding with its specialist provenance, and record conflicts rather than discarding them. Never convert missing rules to clean.
|
|
255
209
|
|
|
256
|
-
|
|
210
|
+
Proceed to Step 3.6 only after each selected team passes full-census coverage or stops explicitly incomplete. Stopped teams contribute verified verdicts plus unevaluated checks; they cannot supply complete coverage.
|
|
257
211
|
|
|
258
212
|
## Step 3.6 — Check every citation
|
|
259
213
|
|
|
@@ -263,44 +217,46 @@ Reviewers miscount lines. Pass every finding's `path:line` to one call:
|
|
|
263
217
|
okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
|
|
264
218
|
```
|
|
265
219
|
|
|
266
|
-
|
|
220
|
+
Apply the [source-citation forms](references/review-calibration.md#source-citations). Keep `ok` citations. For `not-changed` or `not-in-diff`, locate the snippet on its declared side and re-anchor only to a changed location there; otherwise reject it as "cites no changed line". Repeat until every retained citation is `ok`.
|
|
267
221
|
|
|
268
222
|
## Step 3.7 — Settle the findings
|
|
269
223
|
|
|
270
|
-
A formatting-only or minor correction does not automatically require another model review. The lead verifies the exact delta, confirms that behavior, public contracts, dependencies and requirements are unchanged, and records the relevant deterministic checks. A nit label alone is insufficient. Keep the prior reviewed head and the current checked head distinct; never present an old completion as evidence for a new head. If impact is uncertain, record the uncertainty and
|
|
224
|
+
A formatting-only or minor correction does not automatically require another model review. The lead verifies the exact delta, confirms that behavior, public contracts, dependencies and requirements are unchanged, and records the relevant deterministic checks. A nit label alone is insufficient. Keep the prior reviewed head and the current checked head distinct; never present an old completion as evidence for a new head. If impact is uncertain, record the uncertainty and perform targeted inspection under the [existing authorization](#authorization-and-recovery) rather than silently declaring it clean.
|
|
225
|
+
|
|
226
|
+
### Follow-up decisions
|
|
227
|
+
|
|
228
|
+
Retain the prior ledger's resolved, still-open, parked and rejected dispositions separately from the current census. Absence from a correction range does not resolve a finding. Recheck fixes and affected paths; before merge, reconcile the initial full review and subsequent correction/reuse evidence against the final PR. A correction report alone is insufficient for that cumulative check.
|
|
229
|
+
|
|
230
|
+
To reopen an unchanged verdict, name its prior decision and new evidence: a reachable failure, missed applicable rule with concrete impact, or changed dependency/requirement. Classify discoveries as fix-introduced, previously missed or newly in scope; do not label old discoveries regressions. Corrected interpretations can reopen real defects; preference cannot. Do not suppress demonstrated failures because of prior clean results. Optional improvements stay parked without requiring changes or another round unless requested.
|
|
271
231
|
|
|
272
|
-
|
|
232
|
+
### Evidence and grades
|
|
273
233
|
|
|
274
234
|
Before pairing findings, check every finding, including agreed ones, against the [kind-specific verdict criteria](references/review-calibration.md#separate-execution-errors-from-design-violations) and [finding requirements](references/review-calibration.md#every-finding-carries-its-fix). Record the specific reason for rejecting unsupported evidence. Then settle single and overlapping reports as below.
|
|
275
235
|
|
|
276
|
-
**Selected independent model reports.** With one model, adjudicate its report directly against source evidence; do not require cross-model agreement. Group the consolidated findings by the same `path:line` and defect. Adjudicate every finding, including one reported by only one model or one of its
|
|
236
|
+
**Selected independent model reports.** With one model, adjudicate its report directly against source evidence; do not require cross-model agreement. Group the consolidated findings by the same `path:line` and defect. Adjudicate every finding, including one reported by only one model or one of its specialists. Multiple specialists within one team count as one model's report, not independent model agreement. Missing inspection is never a clean verdict or a vote. For overlapping reports:
|
|
277
237
|
|
|
278
|
-
- **Agreed** — multiple model teams report the same defect with the same severity and timing.
|
|
279
|
-
- **Graded differently** — at least two report it with different severity or timing.
|
|
238
|
+
- **Agreed** — multiple model teams report the same defect with the same severity and timing. Verify the grade against the established consequence; agreement does not replace evidence or calibration.
|
|
239
|
+
- **Graded differently** — at least two report it with different severity or timing. Set the final grade from source evidence and the calibration rubric, recording every reported value, the final value and the reason for any change. The final value may differ from every reported value; never use majority vote in place of evidence.
|
|
280
240
|
- **Single report** — only one model team reports the defect. Check the other teams' corresponding rule verdicts, then adjudicate against source evidence as below; silence does not override a demonstrated defect.
|
|
281
241
|
|
|
282
242
|
**Adjudicating** a finding: open each `evidence` location at its declared side (`baseCommit` for `base:` citations, otherwise `headCommit`) and the definitions its claim depends on, then apply the verdict criteria linked above.
|
|
283
243
|
|
|
284
|
-
- **Confirmed** — the opened evidence satisfies the verdict criteria.
|
|
285
|
-
- **Rejected** — the code contradicts the claim
|
|
244
|
+
- **Confirmed** — the opened evidence satisfies the verdict criteria. Apply the calibrated severity and timing, retaining the original reported values and source-cited reasoning for any correction.
|
|
245
|
+
- **Rejected** — the code contradicts the claim. Record the contradicting `path:line` and what it shows.
|
|
286
246
|
|
|
287
|
-
|
|
247
|
+
Do not reject or regrade merely because a finding is inconvenient, tests pass, or several reviewers disagree. A correction to severity or timing requires the applicable rubric, opened source evidence and a concrete impact or scope reason. Preserve the immutable reviewer responses and record the final adjudication separately. Unsupported inspection remains unevaluated rather than becoming a clean verdict.
|
|
288
248
|
|
|
289
249
|
## Step 4 — Merge and write
|
|
290
250
|
|
|
291
251
|
1. Read the [report format](references/review-calibration.md#the-report), which owns the metadata, body sections, finding layout, scoring, and language.
|
|
292
252
|
2. Dedupe across axes and reviewers. Keep the same defect once under the rule that explains it best, retaining the Step 3.7 adjudication and reported grades.
|
|
293
253
|
3. Write the report to `reviewPath`, creating its parent directories, with the fields returned by Step 1 and the adjudicated results. Follow the referenced format without redefining it here.
|
|
294
|
-
4. In the session, print only `reviewPath`, the count per severity, the parked and rejected counts, and the score total. Do not replay the findings in chat.
|
|
254
|
+
4. In the session, print only `reviewPath`, whether the review is complete, the unevaluated-check count, the count per severity, the parked and rejected counts, and the score total. Do not replay the findings in chat.
|
|
295
255
|
|
|
296
256
|
## Exceptions
|
|
297
257
|
|
|
298
258
|
| Situation | Handling |
|
|
299
259
|
|---|---|
|
|
300
|
-
| `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
|
|
301
260
|
| `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
|
|
302
|
-
| `worktreePath` is empty | not a hard stop and not a missing stage: run git in `projectRoot` against the stage's `branch` ref, and have reviewers read whole files with `git -C <projectRoot> show <headCommit>:<path>` |
|
|
303
261
|
| `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count | Stop and show the divergence. Ask the user to choose an ancestor commit that preserves the intended review changes, or to authorize `okstra git-reconcile` before retrying. Do not use the reviewed branch's current tip as a recovery base or infer that divergence proves a rebase. Resolve and confirm a replacement through Step 1, then repeat the ancestry and range checks. Never reconcile automatically. |
|
|
304
262
|
| the diff is empty | dispatch no reviewers; write the [empty-diff report](references/review-calibration.md#empty-diff) to `reviewPath` and stop |
|
|
305
|
-
| the census is large | never truncate — report the cell count and confirm before dispatching |
|
|
306
|
-
| detached HEAD (branch mode) | refuse and ask the user to name a branch |
|