okstra 0.226.0 → 0.228.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 +2 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +43 -7
- package/docs/project-structure-overview.md +13 -3
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +115 -55
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +123 -6
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +59 -63
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- package/runtime/validators/validate-brief.py +21 -5
|
@@ -14,9 +14,12 @@ DRY 위반의 비용: 이전에는 동일 path 문자열이 50+ Python·Shell·m
|
|
|
14
14
|
"""
|
|
15
15
|
from __future__ import annotations
|
|
16
16
|
|
|
17
|
+
import contextlib
|
|
18
|
+
import fcntl
|
|
17
19
|
import os
|
|
18
20
|
import sys
|
|
19
21
|
import tempfile
|
|
22
|
+
from collections.abc import Iterator
|
|
20
23
|
from pathlib import Path
|
|
21
24
|
|
|
22
25
|
OKSTRA_DIR_NAME = ".okstra"
|
|
@@ -114,3 +117,22 @@ def tasks_root(project_root: Path) -> Path:
|
|
|
114
117
|
def discovery_dir(project_root: Path) -> Path:
|
|
115
118
|
"""`<project_root>/.okstra/discovery` 절대 path."""
|
|
116
119
|
return Path(project_root) / DISCOVERY_RELATIVE
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def json_lock_path(path: Path) -> Path:
|
|
123
|
+
return path.with_suffix(path.suffix + ".lock")
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
@contextlib.contextmanager
|
|
127
|
+
def registry_lock(lock_path: Path) -> Iterator[None]:
|
|
128
|
+
"""Hold an exclusive flock on ``lock_path``."""
|
|
129
|
+
lock_path.parent.mkdir(parents=True, exist_ok=True)
|
|
130
|
+
if not lock_path.exists():
|
|
131
|
+
lock_path.touch()
|
|
132
|
+
handle = lock_path.open("r+")
|
|
133
|
+
try:
|
|
134
|
+
fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
|
|
135
|
+
yield
|
|
136
|
+
finally:
|
|
137
|
+
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
|
|
138
|
+
handle.close()
|
|
@@ -12,7 +12,9 @@ from .dirs import (
|
|
|
12
12
|
OKSTRA_DIR_NAME,
|
|
13
13
|
PROJECT_JSON_RELATIVE,
|
|
14
14
|
ensure_okstra_gitignore,
|
|
15
|
+
json_lock_path,
|
|
15
16
|
project_json_path,
|
|
17
|
+
registry_lock,
|
|
16
18
|
)
|
|
17
19
|
|
|
18
20
|
|
|
@@ -152,6 +154,14 @@ def upsert_project_json(project_root: Path, project_id: str, *,
|
|
|
152
154
|
- 파일이 없으면 디렉터리를 만들고 4-필드 JSON 을 작성한다.
|
|
153
155
|
반환값은 결과 dict.
|
|
154
156
|
"""
|
|
157
|
+
lock_path = json_lock_path(project_json_path(project_root))
|
|
158
|
+
with registry_lock(lock_path):
|
|
159
|
+
return _upsert_project_json(project_root, project_id, now=now)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _upsert_project_json(
|
|
163
|
+
project_root: Path, project_id: str, *, now: str | None = None,
|
|
164
|
+
) -> dict:
|
|
155
165
|
if not project_id:
|
|
156
166
|
raise ResolverError("project_id is required for upsert_project_json")
|
|
157
167
|
target = project_json_path(project_root)
|
|
@@ -3944,7 +3944,7 @@
|
|
|
3944
3944
|
},
|
|
3945
3945
|
"ImplementationOptionSplitAcceptance": {
|
|
3946
3946
|
"type": "object",
|
|
3947
|
-
"description": "The user's accept-risk answer that settles a split feasibility vote. Report assembly checks that clarificationRef names a blocks: approval row answered with accept-risk.",
|
|
3947
|
+
"description": "The user's accept-risk answer that settles a split feasibility vote. Report assembly checks that clarificationRef names a blocks: approval row whose candidateRef is this candidate and that the user answered with accept-risk.",
|
|
3948
3948
|
"required": ["clarificationRef"],
|
|
3949
3949
|
"additionalProperties": false,
|
|
3950
3950
|
"properties": {
|
|
@@ -10957,6 +10957,10 @@
|
|
|
10957
10957
|
"approvalContext": {
|
|
10958
10958
|
"$ref": "#/$defs/ApprovalContext"
|
|
10959
10959
|
},
|
|
10960
|
+
"candidateRef": {
|
|
10961
|
+
"description": "The implementation option this approval decides. A candidate's splitAcceptance may cite only a row whose candidateRef is that candidate's id.",
|
|
10962
|
+
"$ref": "#/$defs/ImplementationOptionId"
|
|
10963
|
+
},
|
|
10960
10964
|
"resolution": {
|
|
10961
10965
|
"$ref": "#/$defs/ApprovalResolution"
|
|
10962
10966
|
}
|
|
@@ -195,7 +195,11 @@ for every variant and every source type below.
|
|
|
195
195
|
the task worktree is a checkout without that file, and prepare copies it
|
|
196
196
|
read-only into the analysis packet's `## Cited Local Documents` on every
|
|
197
197
|
run, so later revisions of the document reach the next phase. A tracked
|
|
198
|
-
file is in the worktree; capture it as-is per rule 1.
|
|
198
|
+
file is in the worktree; capture it as-is per rule 1. Check the size
|
|
199
|
+
first: prepare does not copy a file over 200,000 bytes
|
|
200
|
+
(`MAX_CITED_DOCUMENT_BYTES` in `scripts/okstra_ctl/analysis_packet.py`)
|
|
201
|
+
and shows workers only a "not read" line for it, so capture a larger
|
|
202
|
+
untracked document as-is per rule 1 instead of by reference.
|
|
199
203
|
|
|
200
204
|
**Enforced:** `validators/validate-brief.py`
|
|
201
205
|
(`check_cited_local_documents`) refuses a brief that names a git-untracked
|
|
@@ -252,9 +256,11 @@ each source's raw content **separately** under the `Source Material
|
|
|
252
256
|
Take an absolute or project-relative path via free-text. Read the entire
|
|
253
257
|
file. Re-ask if it doesn't exist. Captured content is preserved **verbatim**
|
|
254
258
|
in Source Material.
|
|
255
|
-
When the file is under the project root
|
|
256
|
-
it by reference instead (capture contract
|
|
257
|
-
project-relative path, `format:
|
|
259
|
+
When the file is under the project root, git does not track it, and it is
|
|
260
|
+
at most 200,000 bytes, record it by reference instead (capture contract
|
|
261
|
+
rule 4): the entry's `ref` is the project-relative path, `format:
|
|
262
|
+
by-reference`, and the fence stays empty. A larger untracked file stays
|
|
263
|
+
captured verbatim, because prepare does not copy it into the packet.
|
|
258
264
|
|
|
259
265
|
### 1b. `Issue tracker ticket`
|
|
260
266
|
|
|
@@ -6,7 +6,7 @@ description: >-
|
|
|
6
6
|
unrelated to an okstra run. The tell is a review request over a diff:
|
|
7
7
|
"review this stage", "review my branch", "code review", "leave the review
|
|
8
8
|
in a file". The orchestrator censuses the diff into an explicit worklist,
|
|
9
|
-
one
|
|
9
|
+
one to three reviewers (the user picks) each return a verdict for every cell
|
|
10
10
|
against this project's coding-preflight rules, a coverage audit
|
|
11
11
|
re-dispatches any gap, and the orchestrator settles what the reviewers
|
|
12
12
|
disagree on. NOT for writing a PR body (okstra-pr-gen), starting a run
|
|
@@ -17,17 +17,17 @@ description: >-
|
|
|
17
17
|
|
|
18
18
|
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.
|
|
19
19
|
|
|
20
|
-
##
|
|
20
|
+
## Complete accounting and bounded re-review
|
|
21
21
|
|
|
22
22
|
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.
|
|
23
23
|
|
|
24
|
-
Each reviewer
|
|
24
|
+
Each reviewer accounts for every cell, so Step 3.5 can detect missing checks. Complete accounting does not prove that every defect was discovered. A follow-up keeps the full PR census but re-inspects only the correction's impact closure; unchanged verdicts require verified prior evidence and a current boundary attestation. Follow `references/census-rules.md#follow-up-review` before dispatch.
|
|
25
25
|
|
|
26
26
|
## Rules
|
|
27
27
|
|
|
28
28
|
The rules themselves are **not in this skill**. They live in this project's coding-preflight pack — `overview.md` (core principles plus the three-stage resource routing), `clean-code.md`, and the routed `languages/` / `frameworks/` / `architectures/` resources. Step 2 decides which of them apply; reviewers read them from the absolute paths in their brief. Never restate a rule in a brief or in the report — point at it.
|
|
29
29
|
|
|
30
|
-
This
|
|
30
|
+
This file owns execution, authorization, and adjudication. Read these references for the shared review contracts:
|
|
31
31
|
|
|
32
32
|
- `references/census-rules.md` — how a diff becomes cells: the four axes, pack allocation, exclusions, and the two completion criteria.
|
|
33
33
|
- `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.
|
|
@@ -75,13 +75,14 @@ Pick the mode from what the user actually gave you:
|
|
|
75
75
|
**Branch mode.**
|
|
76
76
|
|
|
77
77
|
1. If the user named no branch, list `git -C <projectRoot> branch --format='%(refname:short)'` and offer a 3-option picker with the current branch as the first recommendation.
|
|
78
|
-
2.
|
|
78
|
+
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.
|
|
79
|
+
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.
|
|
79
80
|
|
|
80
81
|
**Then call the target CLI.** One call resolves everything the rest of this skill needs; the only reason to call it again is a base the user overrides in the confirmation step below.
|
|
81
82
|
|
|
82
83
|
```bash
|
|
83
84
|
okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --text
|
|
84
|
-
okstra code-review target --branch <name>
|
|
85
|
+
okstra code-review target --branch <name> --base <ref> --project-root <projectRoot> --text
|
|
85
86
|
```
|
|
86
87
|
|
|
87
88
|
`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, `Round`, and `Report language`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
|
|
@@ -98,10 +99,9 @@ okstra model-io code-review-input --project-root <projectRoot> --base <baseCommi
|
|
|
98
99
|
Carry this fixed Markdown view into the census and reviewer prompts. Do not
|
|
99
100
|
pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
|
|
100
101
|
|
|
101
|
-
**
|
|
102
|
-
|
|
103
|
-
**Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch. With no worktree there is no checked-out tree to read whole files from, so every brief tells the reviewer to read a file at the reviewed commit with `git -C <projectRoot> show <headCommit>:<path>` — never from the project root's working tree, which holds a different commit.
|
|
102
|
+
**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
103
|
|
|
104
|
+
**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.
|
|
105
105
|
**Then show the base and confirm it — branch mode and stage mode alike.** The CLI's answer is a recommendation the user has not seen yet, and a base nobody looked at is how unrelated commits slip into a review unnoticed. Print `baseCommit` verbatim next to `git -C <workdir> log -1 --oneline <baseCommit>` so the commit it names is legible, then ask with a 3-option picker:
|
|
106
106
|
|
|
107
107
|
1. `Use <baseCommit>` — **the recommendation**, the value the CLI returned.
|
|
@@ -124,16 +124,20 @@ A large census is never truncated. Report the cell count and confirm before disp
|
|
|
124
124
|
|
|
125
125
|
## Step 3 — Materialize and dispatch the reviewers in parallel
|
|
126
126
|
|
|
127
|
-
**Ask how many reviewers** with
|
|
127
|
+
**Ask how many reviewers** with these choices:
|
|
128
|
+
|
|
129
|
+
1. `2 reviewers` — **the recommendation**: two different models each review the whole census.
|
|
130
|
+
2. `3 reviewers` — three different models each review the whole census; higher execution cost.
|
|
131
|
+
3. `1 reviewer` — cheaper; you adjudicate every finding it returns.
|
|
132
|
+
|
|
133
|
+
Accept only `1`, `2` or `3`; a host may also allow direct text input.
|
|
128
134
|
|
|
129
|
-
|
|
130
|
-
2. `1 reviewer` — cheaper; you adjudicate every finding it returns.
|
|
131
|
-
3. `Enter directly` — always last; accept only `1` or `2`.
|
|
135
|
+
Treat reviewer-count selection as authorization for the initial invocations only. Additional model calls require explicit authorization under Step 3.5; missing coverage or a formatting error does not authorize a retry. Instruction presence is checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; actual authorization remains a lead check.
|
|
132
136
|
|
|
133
137
|
Then ask the runtime what those reviewers run — do not choose the role or the providers here:
|
|
134
138
|
|
|
135
139
|
```
|
|
136
|
-
okstra agent-prompt resolve-operation --operation code-review --count <1|2>
|
|
140
|
+
okstra agent-prompt resolve-operation --operation code-review --count <1|2|3>
|
|
137
141
|
```
|
|
138
142
|
|
|
139
143
|
It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
|
|
@@ -154,14 +158,26 @@ process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <proj
|
|
|
154
158
|
with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
|
|
155
159
|
standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
|
|
156
160
|
`.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
|
|
157
|
-
it. **Every reviewer receives the same
|
|
161
|
+
it. **Every reviewer receives the same full 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:
|
|
158
162
|
|
|
159
|
-
- the diff
|
|
163
|
+
- the diff and the fixed-head read command `git -C <gitRoot> show <headCommit>:<path>`, where Step 1 resolved `<gitRoot>`
|
|
160
164
|
- the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
|
|
161
165
|
- **the whole census** — the shared rule catalog once and every grouped cell of all four axes, verbatim
|
|
162
166
|
- the absolute paths of every applied pack (from step 2's routing)
|
|
163
167
|
- 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
|
|
164
168
|
|
|
169
|
+
**Resolve each slot's inspection scope before materializing its prompt.** Run:
|
|
170
|
+
|
|
171
|
+
Use `~/.agents/skills/okstra-code-review/SKILL.md` for `<skill-path>`, the calibration path fixed in Step 2 for `<calibration-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.
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
okstra code-review scope --project-root <projectRoot> --base <baseCommit> --head <headCommit> --census <full-census-path> --policy <skill-path> --policy <calibration-path> --policy <duty-contract-path>
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For a follow-up, add `--previous-head <priorHead> --previous-census <prior-census-path>` and repeat `--completion <prior-completion-path>` for that slot's retained verified completions. Include every applied project instruction as another `--policy`. Use the same selected provider/model; a missing or changed slot starts with a full review. Never substitute another reviewer's evidence. Prior records remain immutable. An identical head, rules and completed adjudication need no new model call; reuse the existing report.
|
|
178
|
+
|
|
179
|
+
Carry the fixed scope text into the brief. `Recheck` names mandatory inspections; `Carry candidates` are proposals, not automatic coverage. Each reviewer inspects the delta, searches changed symbols' callers and tests, checks the dependency inventory and expands Recheck for newly discovered effects before accepting any candidate. Unknown or unbounded effects require a full review. The full census remains unchanged; no candidate silently disappears. Return current coverage rows for both inspected and inherited cells, plus the baseline and dependencies in the calibration format. Only this current invocation's verified completion and gap-fills enter the current coverage audit; old completions are scope inputs, never current verdicts.
|
|
180
|
+
|
|
165
181
|
Each axis is **one rule group**, so a cell is `target × <axis>` — never `target × <individual rule>`. The reviewer names the specific rule it found violated inside the verdict's `rule` field, and one cell may carry findings from several rules of its group.
|
|
166
182
|
|
|
167
183
|
Axis scope — each reviewer works all four axes; the `Reads` column names each group's rules, and a brief never restates them; the bodies are in the packs:
|
|
@@ -183,21 +199,23 @@ review result and cannot contribute a verdict.
|
|
|
183
199
|
|
|
184
200
|
## Step 3.5 — Audit the coverage
|
|
185
201
|
|
|
186
|
-
|
|
202
|
+
Audit responses against the [coverage format](references/review-calibration.md#compact-rule-coverage).
|
|
187
203
|
|
|
188
204
|
For each reviewer separately, audit its grouped rows and explicit rule-ID accounting using its verified completion marker:
|
|
189
205
|
|
|
190
206
|
```bash
|
|
191
|
-
okstra code-review check-coverage --project-root <projectRoot> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
|
|
207
|
+
okstra code-review check-coverage --project-root <projectRoot> --head <headCommit> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
|
|
192
208
|
```
|
|
193
209
|
|
|
194
|
-
The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
|
|
210
|
+
Pass the `headCommit` that `okstra code-review target` returned. The command reads each evidence file as `<headCommit>` holds it (`git show <headCommit>:<path>`), never the project root's working tree, so a review run from a checkout on another commit audits the reviewed lines. The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
|
|
211
|
+
|
|
212
|
+
Do not automatically invoke a model for a format error, unknown ID, or missing coverage. Preserve the verified raw response and report the affected cells as incomplete; never fabricate a passing row or edit immutable evidence. The lead may inspect the cited source and record a separate manual assessment, but that assessment does not satisfy reviewer coverage or create a new verified completion. Request explicit authorization before any additional model call. If authorized for genuinely missing inspection, dispatch one gap-fill invocation per reviewer on that reviewer's original slot, carrying only its incomplete grouped cells, their shared catalog entries, the same range and rule paths. Ask for one complete row for each such cell, not separate replies per missing rule. Use a new invocation ID and repeat the full materialize → verify → dispatch → materialize-result → complete → verify-completion boundary. Re-run the audit with that reviewer's initial and gap-fill markers. Earlier usable verdicts remain unchanged. An invocation with unknown IDs is invalid; record its rejection and incomplete coverage without automatically requesting another invocation. Do not silently relabel IDs.
|
|
195
213
|
|
|
196
|
-
|
|
214
|
+
An isolated format error or 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. 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.
|
|
197
215
|
|
|
198
|
-
Before accepting a clean general cell, open its G2/G3/G5 observations and verify the result-meaning trace, the downstream workload and pre-work bound, and the applicable documented convention checks. If opened code contradicts
|
|
216
|
+
Before accepting a clean general cell, open its G2/G3/G5 observations and verify the result-meaning trace, the downstream workload and pre-work bound, and the applicable documented convention checks. If opened code contradicts an observation, record the affected cells and dependent conclusions as semantically rejected without automatically calling the reviewer again. Any explicitly authorized correction uses the same reviewer slot and the preceding paragraph's completion ordering. Exclude the entire completion only when the error's extent cannot be bounded; report the blocker instead of automatically requesting a full correction. Keep original artifacts immutable for the audit trail. The parser enforces presence and source locations; the lead checks truth. Keep these observations inside the existing Evidence column, without adding verdict rows.
|
|
199
217
|
|
|
200
|
-
|
|
218
|
+
Do not start Step 3.6 until every reviewer passes the audit. If evidence remains unavailable, report the specific blocker and incomplete coverage instead of writing a completed review.
|
|
201
219
|
|
|
202
220
|
## Step 3.6 — Check every citation
|
|
203
221
|
|
|
@@ -207,49 +225,37 @@ Reviewers miscount lines. Pass every finding's `path:line` to one call:
|
|
|
207
225
|
okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
|
|
208
226
|
```
|
|
209
227
|
|
|
210
|
-
`ok` keeps the citation. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
|
|
228
|
+
`ok` keeps the citation. A fully deleted file has no head-side citation; a deletion within a surviving file retains its anchor before the cut. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
|
|
211
229
|
|
|
212
230
|
## Step 3.7 — Settle the findings
|
|
213
231
|
|
|
214
|
-
|
|
232
|
+
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.
|
|
233
|
+
|
|
234
|
+
On follow-ups, retain the previous adjudication ledger: resolved, still open, parked and rejected. Recheck every fix and its affected paths. Reopening an unchanged verdict names the prior decision and new evidence: a reachable failure, a previously missed applicable rule with concrete impact, or a changed dependency/requirement. Classify each new finding as fix-introduced, previously missed, or newly in scope; do not count an old discovery as a new regression. A corrected rule interpretation can reopen a real defect; repeated preference or an alternative implementation cannot. Do not suppress a demonstrated failure because a prior reviewer marked it clean. Optional improvements remain parked and do not require a code change or another review round unless the user requests them. Keep existing severity/timing adjudication rules below.
|
|
235
|
+
|
|
236
|
+
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 the findings according to the reviewer count below.
|
|
215
237
|
|
|
216
|
-
**Two reviewers.**
|
|
238
|
+
**Two or three reviewers.** Group findings by the same `path:line` and defect. Inspect every reported finding, including one supported by only one of three reviewers; silence or a clean verdict is not a vote against it. Then:
|
|
217
239
|
|
|
218
|
-
- **Agreed** —
|
|
219
|
-
- **Graded differently** —
|
|
220
|
-
- **One-sided** —
|
|
240
|
+
- **Agreed** — every reviewer reports it with the same severity and timing. It keeps its severity and timing after the evidence and kind checks above; agreement does not replace those checks.
|
|
241
|
+
- **Graded differently** — at least two report it with different severity or timing. Choose one reporting reviewer's severity/timing pair for that finding after reading the code, and record all reported values and your reason. Never choose an unreported value or use majority vote in place of evidence.
|
|
242
|
+
- **One-sided** — fewer than all reviewers report it with no grading disagreement; the others returned `clean` for that cell or reported something else. Adjudicate it as below.
|
|
221
243
|
|
|
222
244
|
**One reviewer.** Adjudicate every finding it returns.
|
|
223
245
|
|
|
224
|
-
**Adjudicating** a finding: open each `evidence` location at `headCommit` and the definitions its claim depends on
|
|
246
|
+
**Adjudicating** a finding: open each `evidence` location at `headCommit` and the definitions its claim depends on, then apply the verdict criteria linked above.
|
|
225
247
|
|
|
226
|
-
- **Confirmed** — the
|
|
248
|
+
- **Confirmed** — the opened evidence satisfies the verdict criteria. The finding keeps its severity and timing.
|
|
227
249
|
- **Rejected** — the code contradicts the claim (the called function never reads `this`, the value cannot be null there, the branch is unreachable). Move it to `Rejected` with the contradicting `path:line` and one sentence on what it shows.
|
|
228
250
|
|
|
229
|
-
|
|
251
|
+
Never reject for being unconvinced. Apart from choosing among the reporting reviewers' values, never promote, demote, or re-time a finding.
|
|
230
252
|
|
|
231
253
|
## Step 4 — Merge and write
|
|
232
254
|
|
|
233
|
-
1.
|
|
234
|
-
2.
|
|
235
|
-
3.
|
|
236
|
-
4.
|
|
237
|
-
|
|
238
|
-
```yaml
|
|
239
|
-
mode: stage | branch
|
|
240
|
-
taskKey: <task-key> # stage mode
|
|
241
|
-
branch: <branch> # branch mode
|
|
242
|
-
stage: <N> # stage mode only
|
|
243
|
-
round: <round>
|
|
244
|
-
reviewers: [<provider/model>, ...] # the slots Step 3 dispatched
|
|
245
|
-
baseCommit: <exactly as the CLI returned it>
|
|
246
|
-
headCommit: <headCommit>
|
|
247
|
-
packs: [<applied coding-preflight pack paths>]
|
|
248
|
-
generatedAt: <YYYY-MM-DD HH:MM>
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
Body sections, in this order: `## Coverage`, `## Must-fix`, `## Should-fix`, `## Nits`, `## Parked`, `## Rejected`, `## Score`. Empty sections are omitted; `Coverage` and `Score` are always present, and a review with no confirmed `now` findings still emits the Score table with a total of 0. The score counts confirmed `now` findings only. Write the prose in the `Report language` from Step 1.
|
|
252
|
-
5. **In the session, print only** the `reviewPath`, the count per severity, the parked and rejected counts, and the score total. The file is the deliverable — do not replay the findings in chat.
|
|
255
|
+
1. Read the [report format](references/review-calibration.md#the-report), which owns the metadata, body sections, finding layout, scoring, and language.
|
|
256
|
+
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.
|
|
257
|
+
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.
|
|
258
|
+
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.
|
|
253
259
|
|
|
254
260
|
## Exceptions
|
|
255
261
|
|
|
@@ -258,17 +264,7 @@ generatedAt: <YYYY-MM-DD HH:MM>
|
|
|
258
264
|
| `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
|
|
259
265
|
| `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
|
|
260
266
|
| `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>` |
|
|
261
|
-
| `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count
|
|
262
|
-
| the diff is empty | dispatch no reviewers; write the
|
|
267
|
+
| `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. |
|
|
268
|
+
| the diff is empty | dispatch no reviewers; write the [empty-diff report](references/review-calibration.md#empty-diff) to `reviewPath` and stop |
|
|
263
269
|
| the census is large | never truncate — report the cell count and confirm before dispatching |
|
|
264
270
|
| detached HEAD (branch mode) | refuse and ask the user to name a branch |
|
|
265
|
-
|
|
266
|
-
## Principles
|
|
267
|
-
|
|
268
|
-
- **Stay in the diff.** Every finding cites a line this diff changed, and Step 3.6 checks it. A cell whose only wart sits on untouched lines verdicts `clean` — pre-existing issues are not this change's problem.
|
|
269
|
-
- **Don't manufacture findings.** A census fully verdicted `clean` is a valid, useful result.
|
|
270
|
-
- **No finding without a fix.** Readability findings carry a pseudocode sketch; naming findings carry a concrete alternative name.
|
|
271
|
-
- **The census is law.** A reviewer that rebuilds its own worklist reintroduces exactly the run-to-run variance this skill exists to kill.
|
|
272
|
-
- **Every cell gets a verdict.** `clean` is a result, not an omission; the audit treats a gap as unfinished work.
|
|
273
|
-
- **Only a checked claim scores.** A finding reaches the score after its citation is on a changed line and its kind-specific evidence holds against the code; everything else is `Parked` or `Rejected`, with its reason.
|
|
274
|
-
- **The report prose follows `Report language`.** Paths, identifiers, rule names, and quoted code stay verbatim.
|
|
@@ -68,7 +68,7 @@ Never ask "does this rule apply to this file?" while building the census — tha
|
|
|
68
68
|
Two consequences:
|
|
69
69
|
|
|
70
70
|
- A cell exists because a mechanical test matched (file extension, path, "the diff touched this function"), never because the orchestrator expected a violation.
|
|
71
|
-
-
|
|
71
|
+
- Read whole files at the frozen head to locate function boundaries; membership still depends only on changed lines, not on an expected violation. Use `git -C <gitRoot> show <headCommit>:<path>` from Step 1, or parse that content with an available language parser. Do not use the working tree or a hunk header as the complete function inventory.
|
|
72
72
|
|
|
73
73
|
## The four axes
|
|
74
74
|
|
|
@@ -83,7 +83,7 @@ Two consequences:
|
|
|
83
83
|
|
|
84
84
|
Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) are censused on `state-and-tests` only. They are not excluded: they are covered by a different rule group.
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
Enumerate functions from the frozen source and intersect their signature/body spans with the diff's changed lines. Include every matching enclosing or nested function, including same-line anonymous functions distinguished by column. Use base-side source spans to locate deletion-only changes and map surviving targets to their head positions. A removed function has no head target; account for its deletion in the surviving file's file-level cells. Changes outside functions (imports, module wiring, top-level declarations, class-level constants) also belong to file-level cells. If boundaries cannot be established, report the incomplete census and stop before dispatch instead of claiming the hunk criterion holds. Instruction presence is checked by `tests/contract/test_standalone_agent_invocation_surfaces.py::test_code_review_dispatches_use_verified_standalone_invocations`; boundary accuracy remains a lead check.
|
|
87
87
|
|
|
88
88
|
## Exclusions
|
|
89
89
|
|
|
@@ -135,6 +135,18 @@ Both must hold exactly, and both are shown in the response before dispatch:
|
|
|
135
135
|
One `git diff --name-status` row is one file, whatever its status letter. A rename row carries two paths (`R100 <old> <new>`) and still counts **once**: census the `<new>` path and never count `<old>` on either side of the equation. A delete row (`D <path>`) counts once too, and it is always an exclusion, with the reason `deleted — no remaining line to anchor a finding on`.
|
|
136
136
|
2. **Hunks:** every hunk in a censused file maps either to a censused function or to file-level code (imports, module wiring, declarations).
|
|
137
137
|
|
|
138
|
+
## Follow-up review
|
|
139
|
+
|
|
140
|
+
Keep the original PR base and rebuild its full net-diff census at the new head. Preserve IDs for identical targets/groups; never renumber unrelated cells to fill gaps. New or moved targets get new IDs and a fresh inspection. A delta is the previous reviewed head to the current head, not a replacement PR base.
|
|
141
|
+
|
|
142
|
+
The `code-review scope` command proposes carry candidates per reviewer. It verifies prior completion integrity, role/model consistency within the prior results, complete prior coverage, ancestor history, exact base/head baseline, catalog references, and rule/policy content fingerprints. It reopens cells with prior findings, changed targets or changed recorded inputs. Missing dependency records reopen their cells. Any changed path outside the prior inventory, changed rules/base, rewritten history or missing baseline falls back to full review. Invalid completion integrity stops scope calculation. These checks are enforced by `code_review_scope.py::review_scope` and the standalone completion scope tests.
|
|
143
|
+
|
|
144
|
+
Record each inspected cell's repository-relative input files under `Review Dependencies`: its whole target file, definitions/callees, callers, outcome consumers, relevant tests and contracts read to justify the verdict. Include transitive dependencies. Paths describe files, not line ranges; changing any part reopens the dependent cell. An external rule or instruction belongs in the repeated `--policy` inputs instead. A gap-fill retains the same baseline and records dependencies for its inspected cells.
|
|
145
|
+
|
|
146
|
+
The inventory's completeness is a reviewer/lead judgment, not mechanically proven. Before accepting carry candidates, independently search the delta's changed symbols and wiring for effects beyond that inventory. Include changed behavior, error/result mappings, state, test assumptions, public contracts and downstream work. Newly affected cells reopen even when their own bytes did not change. Reopen all affected axes for the target file; expand to callers/tests outside the original census as supporting inspection without dropping or inventing census cells. Unknown reachability, dynamic dispatch, configuration-driven wiring or unexplained test failures require broader inspection, up to full review.
|
|
147
|
+
|
|
148
|
+
Reviewers return the complete current coverage table, identifying inherited cells separately in `Review Carry`. They attest that the current impact inspection supports each inheritance. The lead verifies that attestation and the boundary evidence. Prior `checked` labels alone never satisfy current coverage. Continue using the existing current materialize/verify/result/complete/verify-completion and check-coverage boundaries; scope output cannot mark a cell clean. This boundary audit is a review criterion, not a machine guarantee of defect absence.
|
|
149
|
+
|
|
138
150
|
A count that does not balance means a file was dropped, not that the diff was odd. Find it before dispatching.
|
|
139
151
|
|
|
140
152
|
## What to emit
|
|
@@ -27,7 +27,7 @@ Fields: `cell` (`target × axis`, exactly as the census wrote it — the axis is
|
|
|
27
27
|
|
|
28
28
|
**Open the definition before you claim its behaviour.** A claim about what a called function, method, or value does — that it reads `this`, throws, mutates its argument, returns `null` — cites that definition in `evidence`. A claim you could not check against its definition remains unevaluated: report the missing evidence and leave that rule unaccounted in the grouped row. Do not turn an inspection failure into `clean`. The orchestrator opens every `evidence` location and rejects a finding the code contradicts.
|
|
29
29
|
|
|
30
|
-
There is no length budget.
|
|
30
|
+
There is no length budget. Do not drop a real finding to stay brief. A cell with an unaccounted rule remains incomplete, never `clean`. Follow the [missing-coverage procedure](../SKILL.md#step-35--audit-the-coverage) before any re-dispatch.
|
|
31
31
|
|
|
32
32
|
## Severity and points
|
|
33
33
|
|
|
@@ -44,11 +44,15 @@ Grade the established consequence, not your confidence. An unsupported candidate
|
|
|
44
44
|
- `execution-error`: establish a reachable input or state, the expected behavior, and the actual wrong result in `failure`, supported by opened code in `evidence`.
|
|
45
45
|
- `design-violation`: identify the applicable pack rule, quote the violating code, and describe its concrete design or maintenance consequence in `impact`, supported by `evidence`. A runtime failure is not required. Examples include duplicated domain decisions, business logic in an I/O adapter, misleading names, and a function that violates the assigned readability rule.
|
|
46
46
|
|
|
47
|
-
Both kinds carry a concrete fix. Severity and timing are independent of kind: a design violation can be `should-fix` and `now` even when current outputs are correct. Neither an alternative implementation nor a preferred name alone establishes a violation. An unreachable defensive scenario does not establish an execution error. The orchestrator checks these criteria in Step 3.7; semantic correctness is a review judgment, not a machine-validated guarantee.
|
|
47
|
+
Both kinds carry a concrete fix. An axis does not determine the kind. Severity and timing are independent of kind: a design violation can be `should-fix` and `now` even when current outputs are correct. Neither an alternative implementation nor a preferred name alone establishes a violation. An unreachable defensive scenario does not establish an execution error. The orchestrator checks these criteria in Step 3.7; semantic correctness is a review judgment, not a machine-validated guarantee.
|
|
48
48
|
|
|
49
49
|
## Compact rule coverage
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
Every current response and gap-fill copies the three literal `Review base:`, `Review head:` and `Review rules:` lines emitted by `code-review scope`, exactly once outside tables. They bind the reusable record to its range and rule/policy fingerprints. Append a `## Review Dependencies` table with `Cell | Inputs` columns; list literal repository-relative file paths separated by semicolons. Include the target itself and all inspected callers, callees, tests and contracts. This inventory enables conservative future scope calculation; legacy records without it trigger re-inspection.
|
|
52
|
+
|
|
53
|
+
For inherited candidates, retain the earlier rule accounting and observations, record the inherited input paths, and append `## Review Carry` with `Cell | Previous head | Boundary evidence` columns. Name the inspected delta/caller/test boundary that makes each inheritance valid; a generic unchanged claim is insufficient. These are current attestations, not old completions passed into the current audit. Scope computation verifies baseline/dependency structure; truth and completeness of the boundary attestation remain lead review criteria. Reopen a candidate whenever new evidence contradicts it.
|
|
54
|
+
|
|
55
|
+
Return one compact Coverage Verdicts row per cell under `## Coverage Verdicts`. Keep detailed prose for findings; normal checks share one inspected source location. Rule IDs refer to the shared catalog, not to individual pack bullets.
|
|
52
56
|
|
|
53
57
|
```markdown
|
|
54
58
|
## Coverage Verdicts
|
|
@@ -76,7 +80,7 @@ The command validates structured accounting and source locations; it cannot prov
|
|
|
76
80
|
## Timing — `now` or `park`
|
|
77
81
|
|
|
78
82
|
- `now` — this change should fix it before it merges: a defect on a changed line, or a rule violation the change introduced.
|
|
79
|
-
- `park` —
|
|
83
|
+
- `park` — an optional improvement beyond this change's applicable requirements, such as a follow-up refactor. Optional extra tests for already covered behavior may be parked. Missing tests required by an applicable rule for this change are `now` findings, even when current outputs are correct; cite the changed construct and the missing required verification. A fix outside the diff does not by itself make a newly introduced defect `park`. Parked findings are listed in the report and **do not score**.
|
|
80
84
|
|
|
81
85
|
Every finding carries `timing`. For `now`, establish either an execution error or an applicable design rule violation introduced on a changed line. Correct current outputs alone do not make a design violation `park`.
|
|
82
86
|
|
|
@@ -86,7 +90,7 @@ Every finding carries `timing`. For `now`, establish either an execution error o
|
|
|
86
90
|
|
|
87
91
|
- **The defect sits only on lines this diff did not change.** Findings anchor on changed lines; pre-existing warts are not this change's problem.
|
|
88
92
|
- **The rule does not apply to this cell.** Record the rule ID and applicability reason under `N/A`; other rules in the row may still be checked.
|
|
89
|
-
- **The change is mechanical for this rule.** A signature-only or type-annotation-only edit does not reopen
|
|
93
|
+
- **The change is mechanical for this rule.** A behavior-preserving signature-only or type-annotation-only edit does not reopen unrelated body-level rules. Leave pre-existing naming issues outside the review. A behavior change can make an unchanged name misleading; review that newly introduced mismatch against the applicable naming rule and anchor the finding on the changed behavior.
|
|
90
94
|
|
|
91
95
|
**The hedge test breaks a borderline `must-fix` or `should-fix`.** At those two severities the finding is one you would defend without qualifiers. If your draft note reaches for a softener that questions whether the point is worth raising at all — "marginal", "arguably", "if you are touching it anyway" — you are looking at a `nit` or at nothing: downgrade it or verdict `clean`, but never ship a hedged `should-fix`.
|
|
92
96
|
|
|
@@ -106,7 +110,22 @@ Loose typing in test files (`any`, dynamic casts, untyped fixtures) is a **typin
|
|
|
106
110
|
|
|
107
111
|
## The report
|
|
108
112
|
|
|
109
|
-
Merged and adjudicated by the orchestrator, written to `reviewPath`.
|
|
113
|
+
Merged and adjudicated by the orchestrator, written to `reviewPath`. Use the values resolved by Step 1 and the dispatched slots for the following YAML frontmatter fields, in this order. Include `taskKey` and `stage` only in stage mode, and `branch` only in branch mode.
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
mode: stage | branch
|
|
117
|
+
taskKey: <task-key>
|
|
118
|
+
branch: <branch>
|
|
119
|
+
stage: <N>
|
|
120
|
+
round: <round>
|
|
121
|
+
reviewers: [<provider/model>, ...]
|
|
122
|
+
baseCommit: <baseCommit>
|
|
123
|
+
headCommit: <headCommit>
|
|
124
|
+
packs: [<applied coding-preflight pack paths>]
|
|
125
|
+
generatedAt: <YYYY-MM-DD HH:MM>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Sections, in this order, empty ones omitted except `Coverage` and `Score`:
|
|
110
129
|
|
|
111
130
|
```
|
|
112
131
|
## Coverage
|
|
@@ -122,9 +141,9 @@ Merged and adjudicated by the orchestrator, written to `reviewPath`. Sections, i
|
|
|
122
141
|
- **Parked** — `park` findings, with their severity, not scored.
|
|
123
142
|
- **Rejected** — findings the orchestrator's adjudication disproved or that cite no changed line: the reviewer's claim in one line, then the contradicting `path:line` and what it shows. Not scored.
|
|
124
143
|
|
|
125
|
-
- **Coverage** —
|
|
126
|
-
- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with
|
|
127
|
-
- **Score** — every confirmed `now` finding gets a row
|
|
144
|
+
- **Coverage** — the reviewers (`provider/model`, one to three); N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all accounted for by every reviewer; M files excluded with reasons; applied/unavailable packs; and how findings were settled. Also show expected/covered grouped cells, missing rule IDs and reasoned applicability exclusions. On follow-ups, distinguish freshly inspected from inherited cells per reviewer, name the prior head and scope fallback/expansion reasons, and classify new findings by origin. Never describe inherited cells as newly inspected or rule flags as independent targets.
|
|
145
|
+
- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with every reporting reviewer's values), or `confirmed by orchestrator`.
|
|
146
|
+
- **Score** — every confirmed or agreed `now` finding gets a row after passing the citation and evidence checks in Steps 3.6–3.7. Count each deduplicated finding once. The table is emitted even when there are none, with a single total row reading 0:
|
|
128
147
|
|
|
129
148
|
```
|
|
130
149
|
| # | Location | Rule | Severity | Points |
|
|
@@ -134,3 +153,7 @@ Merged and adjudicated by the orchestrator, written to `reviewPath`. Sections, i
|
|
|
134
153
|
```
|
|
135
154
|
|
|
136
155
|
The report's prose is written in the `Report language` the target CLI returned (the project's `reportLanguage`). Paths, identifiers, rule names, and quoted code stay verbatim.
|
|
156
|
+
|
|
157
|
+
### Empty diff
|
|
158
|
+
|
|
159
|
+
Use the same frontmatter with `reviewers: []`. Coverage states "0 changed files → 0 cells on every axis, 0 files excluded" and lists the applied packs. Omit every finding section and emit the Score table with its single total row reading 0.
|
|
@@ -69,11 +69,11 @@ Use this when one Linear project, or one parent issue, covers work in several re
|
|
|
69
69
|
3. For each issue, propose target projects from evidence: labels, team, repository names or paths in the body. Confirm with `prompt_user` (multi-select, recommended projects first, reason in each description).
|
|
70
70
|
4. For each (issue, project) pair, draft the scope: the part of the issue this project implements. Confirm it with `prompt_user` offering one or two drafts plus a custom-input option. A pair without scope is rejected by the CLI.
|
|
71
71
|
5. Author each pair's brief fields under the okstra-brief-gen brief contract: bodies verbatim, `EB-NNN` / `PB-NNN` / `EO-NNN` items as `<id> <observable condition> — verify: <how>`, anything without an observation method under `externalGates`, and `openQuestions` rows prefixed `general:`, `terminology:`, `intent-check:`, `conversion-block:` or `adr-candidate:`.
|
|
72
|
-
List in `localSources` every local document under that project's root you read to author the pair (a spec, a plan, a note), as a path relative to the project root. Each becomes a `### Source N — file` entry with `format: by-reference`, so every run of the child copies the current file into its analysis packet; a task worktree is a checkout and lacks an untracked `.project-docs/` file. A path outside the project root
|
|
72
|
+
List in `localSources` every local document under that project's root you read to author the pair (a spec, a plan, a note), as a path relative to the project root. Each becomes a `### Source N — file` entry with `format: by-reference`, so every run of the child copies the current file into its analysis packet; a task worktree is a checkout and lacks an untracked `.project-docs/` file. A path outside the project root, a missing file, or a file over 200,000 bytes (which prepare does not copy) rejects the plan, and a brief whose text names an untracked document that `localSources` does not list fails `validate-brief`.
|
|
73
73
|
6. Write the plan JSON below with the Write tool to a scratch path outside the project roots, then run `okstra manager task split ... --plan <path>`.
|
|
74
74
|
- `split plan rejected` or `rendered briefs failed validate-brief`: fix the named fields and run it again. Nothing was written.
|
|
75
75
|
- To add issues or projects to an earlier split, add them to the kept `split-plan.json` content and run the split again without `--overwrite`. Each brief's status is `created`, `unchanged`, `refreshed` or `overwritten`. The CLI renders each existing brief from the kept plan and from the new plan, both with the brief's original `created` date. When the two differ only in `### Out of scope`, `## Related Artifacts` and `## Related Task Graph`, it removes and appends just the changed lines in those sections (`refreshed`) and keeps every other line, hand edits included. An edit to the pair's own `outOfScope` list is applied the same way. A brief the new plan does not change stays `unchanged`, even with hand edits.
|
|
76
|
-
- `briefs already exist with content this plan would change`: the plan
|
|
76
|
+
- `briefs already exist with content this plan would change`: each listed brief carries the reason its change could not be applied. The plan may change it outside those sections, for example its own scope or Context. Otherwise no comparison was possible: there is no kept plan, the kept plan no longer validates (the reason quotes its errors, for example a removed project or a moved `localSources` file), the kept plan does not list the brief, the brief lost one of those headings, or one of those sections was moved inside another. Show the listed paths with their reasons and ask before adding `--overwrite`, which re-renders only those briefs and replaces their hand edits.
|
|
77
77
|
7. Each `Brief N task key` is `<project-id>:<task-group>:<child-task-id>`. Start one with `okstra manager task run ... --project-id <project-id> --child-task-id <child-task-id>` and follow the Child Launch Rule. The packet already carries `--task-brief`, and `--task-type` until the child task exists.
|
|
78
78
|
|
|
79
79
|
Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommendedPhase` is `requirements-discovery` (default), `error-analysis` or `improvement-discovery`; `relations[].relation` uses the brief Related Task Graph values; list fields may be omitted.
|