okstra 0.227.0 → 0.228.1
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 +1 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +15 -3
- package/docs/project-structure-overview.md +12 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/coding-preflight/clean-code.md +24 -18
- package/runtime/prompts/coding-preflight/overview.md +6 -6
- 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 +1 -1
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
- 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 +11 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +46 -10
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- 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-executor.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
- 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/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/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/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +108 -5
- 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/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_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 +39 -45
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- 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
|
@@ -2,9 +2,13 @@
|
|
|
2
2
|
from __future__ import annotations
|
|
3
3
|
|
|
4
4
|
from pathlib import Path
|
|
5
|
+
import shlex
|
|
5
6
|
from typing import Any, Mapping
|
|
6
7
|
|
|
8
|
+
from .analysis_packet import PACKET_PAGE_LINES
|
|
9
|
+
from .fixed_text import block
|
|
7
10
|
from .paths import okstra_home
|
|
11
|
+
from .verification_input_ref import VerificationInputReference
|
|
8
12
|
from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
|
|
9
13
|
from .worker_prompt_policy import (
|
|
10
14
|
GRILLING_LOG_HEADER,
|
|
@@ -42,12 +46,22 @@ READ_SCOPE_HEADER = (
|
|
|
42
46
|
"`SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an "
|
|
43
47
|
"un-enumerated file seems essential, record it under *Missing Information "
|
|
44
48
|
"or Assumptions* instead of reading it. Read the primary analysis packet "
|
|
45
|
-
"in pages of at most
|
|
49
|
+
f"in pages of at most {PACKET_PAGE_LINES} lines "
|
|
50
|
+
f"(`sed -n '1,{PACKET_PAGE_LINES}p'`, "
|
|
51
|
+
f"then `'{PACKET_PAGE_LINES + 1},{2 * PACKET_PAGE_LINES}p'`, …), "
|
|
46
52
|
"never with one whole-file `cat` or view: worker CLIs cut long output "
|
|
47
53
|
"without saying so, and the packet's `## Section Index` gives each "
|
|
48
54
|
"section's line range."
|
|
49
55
|
)
|
|
50
56
|
EVIDENCE_LEDGER_HEADER = "**Evidence ledger:** required-v1"
|
|
57
|
+
VERIFICATION_INPUT_PATH_HEADER = "**Verification inputs:**"
|
|
58
|
+
VERIFICATION_INPUT_DIGEST_HEADER = "**Verification inputs digest:**"
|
|
59
|
+
VERIFICATION_INPUT_SOURCE_HEADER = "**Verification input source:**"
|
|
60
|
+
VERIFICATION_INPUT_HEADER_PREFIXES = (
|
|
61
|
+
VERIFICATION_INPUT_PATH_HEADER,
|
|
62
|
+
VERIFICATION_INPUT_DIGEST_HEADER,
|
|
63
|
+
VERIFICATION_INPUT_SOURCE_HEADER,
|
|
64
|
+
)
|
|
51
65
|
|
|
52
66
|
# `required-v1` is a mode name; what it demands lives in the Worker Preamble's
|
|
53
67
|
# "Evidence read ledger". But the preamble reaches the worker as a *path* —
|
|
@@ -167,9 +181,44 @@ def worker_prompt_headers(
|
|
|
167
181
|
headers.extend(_final_verification_target_headers(active_context))
|
|
168
182
|
else:
|
|
169
183
|
headers.extend(source_worktree_headers(active_context))
|
|
184
|
+
headers.extend(verification_input_headers(project_root, manifest))
|
|
170
185
|
return headers
|
|
171
186
|
|
|
172
187
|
|
|
188
|
+
def verification_input_headers(
|
|
189
|
+
project_root: Path, manifest: Mapping[str, Any],
|
|
190
|
+
) -> list[str]:
|
|
191
|
+
try:
|
|
192
|
+
reference = VerificationInputReference.from_artifact_fields(manifest)
|
|
193
|
+
except ValueError as exc:
|
|
194
|
+
raise WorkerPromptHeaderError(str(exc)) from exc
|
|
195
|
+
if reference is None:
|
|
196
|
+
return []
|
|
197
|
+
manifest_ref = _string_value(manifest.get("runManifestPath"))
|
|
198
|
+
if not manifest_ref:
|
|
199
|
+
raise WorkerPromptHeaderError(
|
|
200
|
+
"verification input reference requires runManifestPath for projection"
|
|
201
|
+
)
|
|
202
|
+
command = shlex.join([
|
|
203
|
+
"okstra", "model-io", "verification-input", "--run-manifest",
|
|
204
|
+
str(project_root / manifest_ref),
|
|
205
|
+
])
|
|
206
|
+
return [
|
|
207
|
+
f"{VERIFICATION_INPUT_PATH_HEADER} "
|
|
208
|
+
f"{block(str(project_root / reference.relative_path))}",
|
|
209
|
+
f"{VERIFICATION_INPUT_DIGEST_HEADER} {block(reference.digest)}",
|
|
210
|
+
f"{VERIFICATION_INPUT_SOURCE_HEADER} "
|
|
211
|
+
f"Read frozen declarations with `{block(command)}`. "
|
|
212
|
+
"Read Tier 2 qaCommands from Verification inputs, including an empty "
|
|
213
|
+
"collection. Read Tier 1 from approvedPlan.validationChecklist when "
|
|
214
|
+
"approvedPlan is present; otherwise retain this phase's approved-plan "
|
|
215
|
+
"or brief source. Preserve existing phase, stage and QA ownership rules. "
|
|
216
|
+
"Use frozen declarations; do not replace them with current project QA "
|
|
217
|
+
"settings. Do not open the snapshot JSON directly. "
|
|
218
|
+
"The snapshot is not command-execution evidence.",
|
|
219
|
+
]
|
|
220
|
+
|
|
221
|
+
|
|
173
222
|
def source_worktree_headers(active_context: Mapping[str, Any]) -> list[str]:
|
|
174
223
|
worktree = active_context.get("executorWorktree")
|
|
175
224
|
path = _string_value(worktree.get("path")) if isinstance(worktree, Mapping) else ""
|
|
@@ -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
|
|
|
@@ -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.
|
|
@@ -99,7 +99,7 @@ okstra model-io code-review-input --project-root <projectRoot> --base <baseCommi
|
|
|
99
99
|
Carry this fixed Markdown view into the census and reviewer prompts. Do not
|
|
100
100
|
pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
|
|
101
101
|
|
|
102
|
-
**The user owns the comparison base.**
|
|
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.
|
|
103
103
|
|
|
104
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:
|
|
@@ -132,6 +132,8 @@ A large census is never truncated. Report the cell count and confirm before disp
|
|
|
132
132
|
|
|
133
133
|
Accept only `1`, `2` or `3`; a host may also allow direct text input.
|
|
134
134
|
|
|
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.
|
|
136
|
+
|
|
135
137
|
Then ask the runtime what those reviewers run — do not choose the role or the providers here:
|
|
136
138
|
|
|
137
139
|
```
|
|
@@ -156,7 +158,7 @@ process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <proj
|
|
|
156
158
|
with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
|
|
157
159
|
standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
|
|
158
160
|
`.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
|
|
159
|
-
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:
|
|
160
162
|
|
|
161
163
|
- the diff and the fixed-head read command `git -C <gitRoot> show <headCommit>:<path>`, where Step 1 resolved `<gitRoot>`
|
|
162
164
|
- the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
|
|
@@ -164,6 +166,18 @@ it. **Every reviewer receives the same brief** and reviews every cell independen
|
|
|
164
166
|
- the absolute paths of every applied pack (from step 2's routing)
|
|
165
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
|
|
166
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
|
+
|
|
167
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.
|
|
168
182
|
|
|
169
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:
|
|
@@ -185,7 +199,7 @@ review result and cannot contribute a verdict.
|
|
|
185
199
|
|
|
186
200
|
## Step 3.5 — Audit the coverage
|
|
187
201
|
|
|
188
|
-
|
|
202
|
+
Audit responses against the [coverage format](references/review-calibration.md#compact-rule-coverage).
|
|
189
203
|
|
|
190
204
|
For each reviewer separately, audit its grouped rows and explicit rule-ID accounting using its verified completion marker:
|
|
191
205
|
|
|
@@ -195,11 +209,13 @@ okstra code-review check-coverage --project-root <projectRoot> --head <headCommi
|
|
|
195
209
|
|
|
196
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.
|
|
197
211
|
|
|
198
|
-
|
|
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.
|
|
199
213
|
|
|
200
|
-
|
|
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.
|
|
201
215
|
|
|
202
|
-
|
|
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.
|
|
217
|
+
|
|
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.
|
|
203
219
|
|
|
204
220
|
## Step 3.6 — Check every citation
|
|
205
221
|
|
|
@@ -213,7 +229,11 @@ okstra code-review check-lines --project-root <projectRoot> --base <baseCommit>
|
|
|
213
229
|
|
|
214
230
|
## Step 3.7 — Settle the findings
|
|
215
231
|
|
|
216
|
-
|
|
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.
|
|
217
237
|
|
|
218
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:
|
|
219
239
|
|
|
@@ -223,35 +243,19 @@ Reviewers are wrong in a way a census cannot catch: a claim about code they did
|
|
|
223
243
|
|
|
224
244
|
**One reviewer.** Adjudicate every finding it returns.
|
|
225
245
|
|
|
226
|
-
**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.
|
|
227
247
|
|
|
228
|
-
- **Confirmed** — the
|
|
248
|
+
- **Confirmed** — the opened evidence satisfies the verdict criteria. The finding keeps its severity and timing.
|
|
229
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.
|
|
230
250
|
|
|
231
|
-
|
|
251
|
+
Never reject for being unconvinced. Apart from choosing among the reporting reviewers' values, never promote, demote, or re-time a finding.
|
|
232
252
|
|
|
233
253
|
## Step 4 — Merge and write
|
|
234
254
|
|
|
235
|
-
1.
|
|
236
|
-
2.
|
|
237
|
-
3.
|
|
238
|
-
4.
|
|
239
|
-
|
|
240
|
-
```yaml
|
|
241
|
-
mode: stage | branch
|
|
242
|
-
taskKey: <task-key> # stage mode
|
|
243
|
-
branch: <branch> # branch mode
|
|
244
|
-
stage: <N> # stage mode only
|
|
245
|
-
round: <round>
|
|
246
|
-
reviewers: [<provider/model>, ...] # the slots Step 3 dispatched
|
|
247
|
-
baseCommit: <exactly as the CLI returned it>
|
|
248
|
-
headCommit: <headCommit>
|
|
249
|
-
packs: [<applied coding-preflight pack paths>]
|
|
250
|
-
generatedAt: <YYYY-MM-DD HH:MM>
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
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.
|
|
254
|
-
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.
|
|
255
259
|
|
|
256
260
|
## Exceptions
|
|
257
261
|
|
|
@@ -260,17 +264,7 @@ generatedAt: <YYYY-MM-DD HH:MM>
|
|
|
260
264
|
| `preflight` reports `Okstra preflight: failed` | retry with `--cwd <dir>`; if that also fails, tell the user to run `/okstra-setup` first and stop |
|
|
261
265
|
| `unknown command: code-review` | the `okstra` binary predates this skill — tell the user to update it (`npm i -g okstra@latest`) and stop |
|
|
262
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>` |
|
|
263
|
-
| `baseCommit` is not an ancestor of `headCommit` — `git -C <workdir> rev-list --count <headCommit>..<baseCommit>` returns a **non-zero** count
|
|
264
|
-
| 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 |
|
|
265
269
|
| the census is large | never truncate — report the cell count and confirm before dispatching |
|
|
266
270
|
| detached HEAD (branch mode) | refuse and ask the user to name a branch |
|
|
267
|
-
|
|
268
|
-
## Principles
|
|
269
|
-
|
|
270
|
-
- **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.
|
|
271
|
-
- **Don't manufacture findings.** A census fully verdicted `clean` is a valid, useful result.
|
|
272
|
-
- **No finding without a fix.** Readability findings carry a pseudocode sketch; naming findings carry a concrete alternative name.
|
|
273
|
-
- **The census is law.** A reviewer that rebuilds its own worklist reintroduces exactly the run-to-run variance this skill exists to kill.
|
|
274
|
-
- **Every cell gets a verdict.** `clean` is a result, not an omission; the audit treats a gap as unfinished work.
|
|
275
|
-
- **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.
|
|
276
|
-
- **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** —
|
|
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.
|
|
126
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`.
|
|
127
|
-
- **Score** — every confirmed `now` finding gets a row
|
|
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.
|
|
@@ -166,6 +166,8 @@ matching section:
|
|
|
166
166
|
into task worktrees.
|
|
167
167
|
- **B. project QA commands** (`qaCommands`, recommended) + **B.1 `qaEnv`** —
|
|
168
168
|
check-only lint/format/typecheck/test baselines and the Tier 3 environment.
|
|
169
|
+
The reference also describes `okstra qa register/show/check` for reusable
|
|
170
|
+
feature procedures; registration and structural checks do not execute the feature.
|
|
169
171
|
Local `io` conformance is blocking; DB/HTTP/external QA is advisory and
|
|
170
172
|
remains user-owned when automatic execution cannot PASS.
|
|
171
173
|
- **C. `.claude/settings.local.json` symlink** — automatic; read only to
|
|
@@ -90,6 +90,8 @@ The field is preserved across the runtime's auto-upserts of `project.json`, so
|
|
|
90
90
|
manual edits to `qaCommands` survive every subsequent `okstra setup` /
|
|
91
91
|
`okstra run` invocation.
|
|
92
92
|
|
|
93
|
+
For reusable feature procedures, use `okstra qa register --project-root <absolute-root> --id <id> --category test --label <label> --cmd <command> --procedure-input <file> --source-path <relative-source>`. The procedure has five level-two headings: `Execution`, `Environment`, `User actions`, `Success observations`, and `Cleanup`. Read existing project checks before authoring it. Use `okstra qa show --project-root <absolute-root>` to inspect registration and `okstra qa check --project-root <absolute-root>` to check structure and related-source freshness. These commands do not execute the feature. See the CLI manual's reusable verification procedures section for update digests, source worktrees, and resource keys.
|
|
94
|
+
|
|
93
95
|
### B.1 `qaEnv` — Tier 3 conformance environment
|
|
94
96
|
|
|
95
97
|
`implementation` / `final-verification` verifiers run **stage conformance
|