okstra 0.231.0 → 0.232.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 +15 -3
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +113 -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/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +129 -2
- package/docs/architecture.md +11 -2
- package/docs/cli.md +234 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- 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 +85 -281
- 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/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
- package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/code_review_census.py +71 -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_scope.py +36 -9
- package/runtime/python/okstra_ctl/code_review_target.py +85 -11
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- 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/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- 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 +261 -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/json_boundary.py +21 -2
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +26 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_sync.py +3 -22
- package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/report_assembly.py +15 -0
- package/runtime/python/okstra_ctl/report_narrative.py +3 -0
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
- 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 +24 -1
- 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/team.py +3 -1
- 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/worker_dispatch.py +3 -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/wrapper_status.py +16 -0
- 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 +25 -20
- 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/skills/okstra-code-review/SKILL.md +71 -123
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
- package/runtime/skills/okstra-manager/SKILL.md +7 -0
- package/runtime/skills/okstra-memory/SKILL.md +7 -0
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/validate-run.py +17 -8
|
@@ -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. 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,45 +94,27 @@ 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.
|
|
123
|
-
|
|
124
|
-
A large census is never truncated. Report the cell count and confirm before dispatching — a silent cut is a false "I looked at everything" signal.
|
|
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.** 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 in a coordinator or child. 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 coordinator, child and gap-fill, passing additions as repeated `--review-resource` materialization inputs. 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. For a large census, report its size and confirm dispatch; never truncate it.
|
|
125
108
|
|
|
126
109
|
## Step 3 — Select one to three model teams with six specialists each
|
|
127
110
|
|
|
128
|
-
|
|
111
|
+
Select one to three distinct-model reviewers; default to 2. Honor an explicit count without asking again; otherwise offer 2 as recommended, with 1 and 3 as alternatives. Carry `<reviewerCount>` into this review and its gap-fills. Resolve each new roster from the registered pool, without hard-coded providers, models, versions or preferred ordering:
|
|
129
112
|
|
|
130
113
|
```
|
|
131
114
|
okstra agent-prompt resolve-operation --operation code-review --count <reviewerCount>
|
|
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 returned duty, role and `slot` provider/model values are authoritative. The operation contract owns the ceiling; `resolve_operation_slots` enforces the count range and refuses too few distinct models. Pass the count explicitly because the contract ceiling is not the default. Keep the returned assignments for coordinators, children and gap-fills; do not substitute remembered or preferred models. Default selection and assignment fidelity remain lead checks.
|
|
142
118
|
|
|
143
119
|
Each returned slot is a model-team coordinator, not a specialty. Every coordinator receives the full census and delegates to six actual subagents using its exact provider/model assignment:
|
|
144
120
|
|
|
@@ -151,109 +127,79 @@ Each returned slot is a model-team coordinator, not a specialty. Every coordinat
|
|
|
151
127
|
| State | `state-and-tests` | `T1` |
|
|
152
128
|
| Tests | `state-and-tests` | `T2`–`T4` |
|
|
153
129
|
|
|
154
|
-
|
|
130
|
+
Give each coordinator the same complete census. The coordinator divides it by the table, retaining each specialty's rules and all cells of that axis with IDs, targets, references and order unchanged. Naming/readability share semantic IDs, and state/tests share state-and-tests IDs, with disjoint rule subsets. Each team's `(cell ID, rule ID)` union must equal the full census; every model repeats that assignment independently. Never divide specialties between models or borrow another team's verdicts. A coordinator acknowledges an empty specialty without spawning it or passing an empty census to `scope` or `check-coverage`.
|
|
155
131
|
|
|
156
|
-
Show
|
|
132
|
+
Show the selected teams and division before dispatch; each coordinator records its concrete child assignments before spawning. It owns actual separate child invocations, collection, gap-fills and [consolidation](#consolidate-within-each-model-then-across-models). The orchestrator launches coordinators and does not perform those duties for them. Children do not delegate further. An inability to spawn and collect children under the exact provider/model binding is an execution blocker, not permission to substitute a model, serialize the whole review into one call or simulate specialties as headings. Keep team verdicts private until independent model reports are complete.
|
|
157
133
|
|
|
158
|
-
|
|
134
|
+
The authorized review includes `<reviewerCount>` coordinator calls, up to `6 × reviewerCount` specialty calls and the bounded continuations in [Step 3.5](#step-35--audit-the-coverage). Honor user call/cost limits; an insufficient limit blocks dispatch rather than reducing the team. New scope, another model, a new implementation round or retries beyond those limits require their own authorization. Delegation and authorization accuracy remain lead checks.
|
|
159
135
|
|
|
160
136
|
### Shared test execution evidence
|
|
161
137
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
Share the evidence with all model teams and subagents. Every model's Tests subagent independently checks whether tests discriminate the changed behavior, cover applicable failure and boundary cases, and avoid self-mocking; test success is not proof of correctness or rule conformance. A missing, failed or blocked required test stays explicit in the report. If review identifies a necessary additional local test, the lead runs it once and shares the result. Reviewers do not edit code, add tests or launch duplicate suites. Follow-up changes invalidate affected results; unchanged, matching evidence is reused. These are lead/reviewer checks, not enforced by the coverage parser.
|
|
138
|
+
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.
|
|
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
|
+
Each 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.
|
|
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
|
+
### Inspection scope and briefing
|
|
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
|
|
188
|
-
|
|
189
|
-
**Resolve each slot's inspection scope before materializing its prompt.** Run:
|
|
190
|
-
|
|
191
|
-
Use `~/.agents/skills/okstra-code-review/SKILL.md` for `<skill-path>`, the calibration path fixed in Step 2 for `<calibration-path>`, `~/.agents/skills/okstra-code-review/references/census-rules.md` for `<census-rules-path>`, and `<okstraHome>/prompts/duties/code-reviewer.json` for `<duty-contract-path>` using Step 2's resolved home. This installed duty source exists before materialization; invocation materialization still freezes its own duty snapshot. Keep the same ordered list of policy documents and applied project instructions across rounds. Policy content is matched by position; catalog references retain the rule-to-resource binding.
|
|
144
|
+
Resolve each slot's scope before materializing its prompt, using Step 2's shared snapshot:
|
|
192
145
|
|
|
193
146
|
```bash
|
|
194
|
-
okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --
|
|
147
|
+
okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --review-policy <review-policy-path>
|
|
195
148
|
```
|
|
196
149
|
|
|
197
|
-
|
|
150
|
+
Every applied project instruction belongs in the shared snapshot. Additional scope `--policy` paths must already identify captured sources; keep their order across rounds. Snapshot content, resource selection and catalog bindings are fingerprinted. 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.
|
|
198
151
|
|
|
199
|
-
|
|
152
|
+
With an unchanged comparison base and policy, add `--previous-head <priorHead> --previous-census <prior-assigned-census-path>` and repeated `--completion <prior-completion-path>` from this team's same specialty and provider/model only. A missing or changed assignment needs full inspection of that specialty. `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. Input paths are whole files. Prior records remain immutable; an identical range, rules and completed adjudication need no new call.
|
|
200
153
|
|
|
201
|
-
|
|
154
|
+
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 specialty limits verdict ownership, not context access. Route suspected issues in another specialty through the lead without changing cells.
|
|
202
155
|
|
|
203
|
-
|
|
156
|
+
`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.
|
|
204
157
|
|
|
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 |
|
|
158
|
+
Each brief carries the fixed scope text, diff and frozen read command; a short project layout; team/specialty/parent IDs and the full-census path for context; the shared policy identity; shared test evidence and blockers; and the inspection requirements above. Pass the assignment through `--review-census` with unchanged digest/resource metadata; materialization delivers its canonical rules and cells, so do not copy them into the brief. A coordinator's task explicitly owns child dispatch, checks, gap-fills and consolidation; a specialist's task grants no delegation and carries no coordinator procedures. Read the delivered frozen calibration and applicable rule sections completely, without clipping normative lines. 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.
|
|
211
159
|
|
|
212
|
-
|
|
160
|
+
### Authenticated invocations
|
|
213
161
|
|
|
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.
|
|
162
|
+
Every coordinator, child and continuation uses a unique invocation ID. Write its brief to `.okstra/agent-invocations/code-review/<invocation-id>.instructions.md`, with the canonical `.prompt.md` beside it, then run:
|
|
219
163
|
|
|
220
|
-
|
|
164
|
+
```bash
|
|
165
|
+
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> --review-policy <review-policy-path> --review-census <assigned-census-path> --review-base <baseCommit> --review-head <headCommit> [--review-resource <pack-relative-id> ...]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Copy duty, role, provider and `provider/model` from the resolved slot. Run `okstra agent-prompt verify` against the returned `metadataPath` before any model call. Native calls receive the verified prompt body and `hostModelValue`; provider processes use:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
~/.okstra/bin/okstra-<provider>-exec.sh <projectRoot> <modelExecutionValue> <prompt-path> "" <role> --invocation-metadata <metadataPath>
|
|
172
|
+
```
|
|
221
173
|
|
|
222
|
-
|
|
174
|
+
Use the verified prompt path and never interchange model values. `worker-dispatch` handles run-manifest assignments, not standalone prompts. The wrapper writes the prompt's `.log`; dispatch verified calls in parallel where supported. Capture raw returns under `.okstra/agent-invocations/code-review/.tmp/`, publish with `okstra agent-prompt materialize-result`, then `complete` and `verify-completion`. Only that last command's `returnedBody` is usable. Frozen standalone completions are also bound to the source/index integrity audit; a mutation or invalid audit prevents usable completion evidence. Audit current verified completions and gap-fills only; prior completions are scope inputs, never current verdicts.
|
|
223
175
|
|
|
224
|
-
|
|
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
|
+
## Step 3.5 — Audit the coverage
|
|
229
177
|
|
|
230
|
-
|
|
178
|
+
Each spawning coordinator collects its children's evidence, findings and [coverage rows](references/review-calibration.md#compact-rule-coverage). Audit each child separately against its assigned subset using verified completion markers:
|
|
231
179
|
|
|
232
180
|
```bash
|
|
233
181
|
okstra code-review check-coverage --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <assigned-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
|
|
234
182
|
```
|
|
235
183
|
|
|
236
|
-
|
|
184
|
+
Use Step 1's frozen commits. `code_review_coverage.py` verifies completions and refuses mixed model assignments; `review_verdicts.py` checks the supplied catalog, rule accounting and source anchors at those commits. Exit 0 means complete valid accounting with no unknown cell; exit 1 lists missing/invalid cells or rules; exit 2 reports invalid input or completion evidence. Neither command proves exhaustive references, delegation or semantic truth.
|
|
237
185
|
|
|
238
|
-
|
|
186
|
+
For an incomplete child, send only its missing or invalid grouped cells, assigned rule subset, same range, rule paths and full-context requirements back to that same logical child. Resume it where supported; otherwise create a linked continuation carrying its verified prior results. Use a new invocation ID and the [authenticated lifecycle](#authenticated-invocations), asking for a complete row per affected cell. Preserve raw results and earlier usable verdicts; audit initial plus gap-fill completions against the child's whole assignment. Repeat only while the incomplete count decreases. Do not reassign omissions or rerun completed investigations.
|
|
239
187
|
|
|
240
188
|
Two cases get one bounded repeat before the no-progress rule applies. A row rejected only for its syntax (cell or rule separators, escaping, a column count, an observation form the calibration does not allow there) gets one format repair: a continuation on the same child that carries the parser's rejection text and asks for the same verdicts in the calibration row format. That repair does not count toward the no-progress stop. An invocation that exits non-zero without a returned body is retried once on the same slot and specialty under a new invocation ID; a second failure is a provider-execution stop. Each specialist's gap-fills, repair and retry are judged separately: one specialist's stop never stops another specialist that has not had its own gap-fill.
|
|
241
189
|
|
|
242
|
-
Stop
|
|
190
|
+
Stop the affected coverage loop when a gap-fill makes no progress, a user call/cost limit is reached, source evidence is unavailable, or authentication, billing, provider execution or integrity verification fails. Unknown cell IDs also stop the loop: preserve the response rather than relabeling or automatically retrying. Dispatch no further gap-fills for that stopped assignment; a global user limit stops further dispatch altogether. Continue with verified results and record every unevaluated pair, owner and blocker in [Coverage](references/review-calibration.md#the-report). These are not code findings and receive no kind, severity, timing or points; the review remains incomplete even at score zero. Manual assessment cannot replace verified reviewer coverage. A later review needs its own authorization. The lead checks stopping conditions.
|
|
243
191
|
|
|
244
192
|
An isolated false observation reopens the affected cells and any dependent conclusions, not automatically every valid verdict. Record the excluded completion/cells and retain only independently valid evidence. Semantically rejected rows enter the same affected-cell gap-fill procedure; count them as incomplete when checking progress. If an older row is syntactically valid but disproved, pass the corrected completion first so the existing first-usable rule selects it; retain the older completion only for unaffected rows. If the error's extent cannot be bounded, report the unresolved extent; a full correction requires explicit authorization. Never edit an immutable response to make it pass.
|
|
245
193
|
|
|
246
|
-
Before accepting
|
|
194
|
+
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.
|
|
247
195
|
|
|
248
196
|
### Consolidate within each model, then across models
|
|
249
197
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
The coordinator returns the full-census coverage, findings, and a child manifest listing each specialty, invocation/completion paths, assignment path and audit result, including empty-specialty acknowledgments. Publish and verify this coordinator completion through the same standalone boundary. The lead checks that every full-census `(cell ID, rule ID)` status is supported by the corresponding child's verified row and that all child findings survive consolidation. A coordinator's summary is not proof that its children ran. This provenance reconciliation is a lead check; the coverage parser does not enforce delegation or parent-child relationships.
|
|
198
|
+
Once each child has passed its audit or stopped explicitly incomplete, their coordinator consolidates the audited results into the model report. Namespace finding IDs by team/specialty, retain every finding and child provenance, and record conflicts rather than discarding them. Combine complementary rule statuses for shared semantic and state/test cells into complete rows; union observations and dependency files while retaining inspected/inherited distinctions and the frozen baseline. Never convert missing rules to clean.
|
|
253
199
|
|
|
254
|
-
|
|
200
|
+
Return full-census coverage, findings and a child manifest naming specialties, assignment paths, invocation/completion paths, audit results and empty-specialty acknowledgments. Publish and verify the coordinator completion through the same lifecycle. The lead reconciles every full-census pair and finding against verified child rows; a coordinator summary alone does not prove delegation. Audit the coordinator against the full census with `check-coverage`, never mixing model assignments. The parser selects whole usable rows and cannot merge split child rows, so children are not direct full-census audit inputs.
|
|
255
201
|
|
|
256
|
-
|
|
202
|
+
Return aggregation discrepancies to their coordinator for correction from saved child results, without rerunning completed children or having the orchestrator reconstruct the report. Authenticate the replacement; the same gap-fill progress/cost limits apply. Proceed to Step 3.6 only after each selected model passes full-census coverage and child provenance checks or stops explicitly incomplete. Stopped teams contribute verified verdicts plus unevaluated checks; they cannot supply complete coverage.
|
|
257
203
|
|
|
258
204
|
## Step 3.6 — Check every citation
|
|
259
205
|
|
|
@@ -263,44 +209,46 @@ Reviewers miscount lines. Pass every finding's `path:line` to one call:
|
|
|
263
209
|
okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
|
|
264
210
|
```
|
|
265
211
|
|
|
266
|
-
|
|
212
|
+
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
213
|
|
|
268
214
|
## Step 3.7 — Settle the findings
|
|
269
215
|
|
|
270
216
|
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 request authorization for targeted inspection rather than silently declaring it clean.
|
|
271
217
|
|
|
272
|
-
|
|
218
|
+
### Follow-up decisions
|
|
219
|
+
|
|
220
|
+
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.
|
|
221
|
+
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
### Evidence and grades
|
|
273
225
|
|
|
274
226
|
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
227
|
|
|
276
228
|
**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 children. Multiple children 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
229
|
|
|
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.
|
|
230
|
+
- **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.
|
|
231
|
+
- **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
232
|
- **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
233
|
|
|
282
234
|
**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
235
|
|
|
284
|
-
- **Confirmed** — the opened evidence satisfies the verdict criteria.
|
|
285
|
-
- **Rejected** — the code contradicts the claim
|
|
236
|
+
- **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.
|
|
237
|
+
- **Rejected** — the code contradicts the claim. Record the contradicting `path:line` and what it shows.
|
|
286
238
|
|
|
287
|
-
|
|
239
|
+
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
240
|
|
|
289
241
|
## Step 4 — Merge and write
|
|
290
242
|
|
|
291
243
|
1. Read the [report format](references/review-calibration.md#the-report), which owns the metadata, body sections, finding layout, scoring, and language.
|
|
292
244
|
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
245
|
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.
|
|
246
|
+
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
247
|
|
|
296
248
|
## Exceptions
|
|
297
249
|
|
|
298
250
|
| Situation | Handling |
|
|
299
251
|
|---|---|
|
|
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
252
|
| `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
253
|
| `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
254
|
| 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 |
|