okstra 0.226.0 → 0.227.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.
Files changed (44) hide show
  1. package/README.md +1 -0
  2. package/dist/commands/execute/wizard.mjs +12 -15
  3. package/dist/commands/execute/wizard.mjs.map +1 -1
  4. package/docs/cli.md +29 -5
  5. package/docs/project-structure-overview.md +1 -1
  6. package/package.json +1 -1
  7. package/runtime/BUILD.json +2 -2
  8. package/runtime/agents/operations/code-review.json +1 -1
  9. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  10. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  11. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  12. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  13. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  14. package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
  15. package/runtime/python/okstra_ctl/code_review_target.py +77 -53
  16. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  17. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  18. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  19. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  20. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  21. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  22. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  23. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
  24. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  25. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  26. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  27. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  28. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  29. package/runtime/python/okstra_ctl/run.py +15 -1
  30. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  31. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  32. package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
  33. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  34. package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
  35. package/runtime/python/okstra_ctl/wizard/render.py +2 -2
  36. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  37. package/runtime/python/okstra_ctl/wizard/state.py +55 -14
  38. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  39. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  40. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  41. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  42. package/runtime/skills/okstra-code-review/SKILL.md +25 -23
  43. package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
  44. package/runtime/skills/okstra-run/SKILL.md +21 -1
package/README.md CHANGED
@@ -279,6 +279,7 @@ Major workflow changes added to `main` after 0.8.0:
279
279
  <a id="further-reading"></a>
280
280
  ## 4. Further reading
281
281
 
282
+ - [`docs/implementation-process.md`](docs/implementation-process.md) — maintainer workflow for changing okstra: isolated work, validation, reviewed PRs, correction rounds, user-approved merge, and human acceptance.
282
283
  - [`docs/architecture.md`](docs/architecture.md) — detailed manual covering prompt and team contracts, storage, task-type phase rules, lifecycle, and workflow.
283
284
  - [`docs/cli.md`](docs/cli.md) — complete reference for `okstra.sh` arguments, options, and interactive input flow.
284
285
  - [`RELEASING.md`](RELEASING.md) — version cutting and publication through release-please or the manual fallback.
@@ -18,6 +18,7 @@ Subcommands:
18
18
 
19
19
  Usage:
20
20
  okstra wizard new-state-file
21
+ okstra wizard init --worker-settings --state-file <path> --host-runtime <runtime> [--project-root <p> --project-id <id>]
21
22
  okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime> \\
22
23
  --entry-mode current-session --available-function <semantic-name>
23
24
  okstra wizard step --state-file <path> (--answer <value> | --no-submit)
@@ -41,7 +42,7 @@ All subcommands emit a single JSON object on stdout. On validation failure
41
42
  // make legitimate directive/base-ref answers unsubmittable. The inline
42
43
  // "--key=value" form lets callers pass any value (including empty)
43
44
  // unambiguously.
44
- const BOOLEAN_FLAGS = new Set(["no-submit"]);
45
+ const BOOLEAN_FLAGS = new Set(["no-submit", "worker-settings"]);
45
46
  function stringFlag(flags, key) {
46
47
  const value = flags[key];
47
48
  return typeof value === "string" ? value : undefined;
@@ -97,11 +98,15 @@ export function buildPythonArgs(sub, flags, workspaceRoot = "") {
97
98
  pyArgs.push("--workspace-root", workspaceRoot);
98
99
  const projectRoot = stringFlag(flags, "project-root");
99
100
  const projectId = stringFlag(flags, "project-id");
100
- if (!projectRoot || !projectId) {
101
+ if (!flags["worker-settings"] && (!projectRoot || !projectId)) {
101
102
  throw new Error("init requires --project-root and --project-id");
102
103
  }
103
- pyArgs.push("--project-root", projectRoot);
104
- pyArgs.push("--project-id", projectId);
104
+ if (flags["worker-settings"])
105
+ pyArgs.push("--worker-settings");
106
+ if (projectRoot)
107
+ pyArgs.push("--project-root", projectRoot);
108
+ if (projectId)
109
+ pyArgs.push("--project-id", projectId);
105
110
  const hostRuntime = stringFlag(flags, "host-runtime");
106
111
  if (hostRuntime) {
107
112
  pyArgs.push("--host-runtime", hostRuntime);
@@ -166,28 +171,20 @@ export async function run(args) {
166
171
  return 0;
167
172
  }
168
173
  let flags;
174
+ let pyArgs;
169
175
  try {
170
176
  flags = parseFlags(rest);
177
+ pyArgs = buildPythonArgs(sub, flags);
171
178
  }
172
179
  catch (err) {
173
180
  const message = err instanceof Error ? err.message : String(err);
174
181
  process.stderr.write(`error: ${message}\n\n${USAGE}`);
175
182
  return 2;
176
183
  }
177
- if (!flags["state-file"]) {
178
- process.stderr.write("error: --state-file is required\n");
179
- return 2;
180
- }
181
- let workspaceRoot = "";
182
184
  if (sub === "init") {
183
- if (!flags["project-root"] || !flags["project-id"]) {
184
- process.stderr.write("error: init requires --project-root and --project-id\n");
185
- return 2;
186
- }
187
185
  const paths = await resolvePaths();
188
- workspaceRoot = paths.workspace;
186
+ pyArgs = buildPythonArgs(sub, flags, paths.workspace);
189
187
  }
190
- const pyArgs = buildPythonArgs(sub, flags, workspaceRoot);
191
188
  const result = await runPythonModule({
192
189
  module: "okstra_ctl.wizard",
193
190
  args: pyArgs,
@@ -1 +1 @@
1
- {"version":3,"file":"wizard.mjs","sourceRoot":"","sources":["../../../src/commands/execute/wizard.mts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"wizard.mjs","sourceRoot":"","sources":["../../../src/commands/execute/wizard.mts"],"names":[],"mappings":"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"}
package/docs/cli.md CHANGED
@@ -546,6 +546,30 @@ Legacy `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`,
546
546
 
547
547
  `okstra model list [--role <role>] [--host <host>] [--json]` prints the catalog without an inference call. `okstra model default set|unset <role> ... --scope project|global` writes `modelDefaults` to `.okstra/project.json` or `~/.okstra/config.json`.
548
548
 
549
+ ### Saved worker rosters
550
+
551
+ Ask `/okstra-run` to configure worker settings, or say `okstra-run worker settings`. This opens a separate settings flow rather than starting a task. Select global defaults or project overrides, edit the roles you need, then review and save the changes together. Cancel leaves configuration unchanged. Global settings also work outside a registered project.
552
+
553
+ The settings flow writes `workerDefaults` into the existing configuration files: `~/.okstra/config.json` for global settings (respecting `OKSTRA_HOME`), or `<PROJECT_ROOT>/.okstra/project.json` for project overrides.
554
+
555
+ ```json
556
+ {
557
+ "workerDefaults": {
558
+ "analyser": ["claude/opus", "codex/gpt-6.1-sol"],
559
+ "critic": [],
560
+ "report-writer": ["claude/sonnet"]
561
+ }
562
+ }
563
+ ```
564
+
565
+ Each model is one worker. An empty array means zero workers for an optional role. A missing project role inherits the global role; a project array replaces the entire global array. Removing a project override restores inheritance. The editor validates the shared count range across phases where the role is static; for example, verifier defaults allow 1–3 workers, while a particular final-verification run may select up to 5.
566
+
567
+ A valid saved roster skips that role's launch picker. Unconfigured or unavailable roles alone need a selection. The final confirmation shows models, count, and source, and Edit changes only the current run. Explicit role flags and explicitly reused previous-run selections take precedence over saved settings. If either count or model is explicit for a role, saved roster values are not mixed into that role. Existing `modelDefaults` remain candidate preferences.
568
+
569
+ These settings apply to static worker roles. The leader remains host-controlled, and dynamic verifiers keep their source participant's assignment. The runtime uses the same default resolver for the wizard and direct preparation.
570
+
571
+ For host integrations, initialize the settings state with `okstra wizard init --worker-settings --state-file <path> --host-runtime <host>`. Project flags are optional in this mode. Relay the returned prompts using the normal `step` command. Settings initialization returns the host's `relayContract` path; `done` ends settings and never authorizes task launch.
572
+
549
573
  ### `--lead-provider`
550
574
 
551
575
  Compatibility assertion for previously recorded invocations. The value must match the host-native provider: `claude` on Claude Code, `codex` on Codex, and `antigravity` on Antigravity. It is not an independent lead selector. Other providers belong in the worker roster and run through CLI wrappers; preparation rejects a cross-provider lead rather than recording one model and silently running another.
@@ -915,9 +939,9 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
915
939
  | `okstra stage-map <task-key> [--cwd <dir>\|--project <dir>]` | Dump the task's implementation-planning Stage Map as JSON: `{ ok, taskKey, taskRoot, state, sourcePlanPath, stages:[{stage_number,title,depends_on,step_count,cancelled}], doneStages:[int] }`. Each stage row carries `cancelled: true` when the plan marks that Stage Map row `status: cancelled`; such a stage is never selected, cannot be closed, and is left out of whole-task final verification and release handoff. `sourcePlanPath` is the task's latest implementation-planning report — the authority on which stages exist, so a plan amendment's added stages are selectable as soon as the amended plan lands. `state` is `ready` for a resolved source and `missing` when no Stage Map exists; a corrupt source returns a structured non-zero error instead of silently selecting another report. `doneStages` is read from the implementation-planning stage consumer state (with carry recovery). This is the read-side source `/okstra-schedule-gen [task-group]` uses to derive selectable unfinished stages and their completed dependency closure |
916
940
  | `okstra stage-close <task-key> --stage <N> --from-commit <sha> [--supersede-failed <reason>] [--cwd <dir>\|--project <dir>]` | Record the `done` stage-consumer row an implementation run would have written, for a stage whose work is already committed but which never registered as done — the run ended before writing its carry sidecar, and `backfill_done_from_carry` recovers only from that file. Without it `stage-map` reports `doneStages: []` while the branch carries the commit, the next plan re-describes the stage, and every RED expectation it produces is unreachable. Refuses unless the Stage Map has that stage and does not mark it cancelled, no `done`/`failed` row exists for it, `--from-commit` resolves to a commit in the project repo, and the stage's conformance gate permits progress — the same `decide_conformance_gate` the run validator uses, so a stage closed here is not one the validator would have blocked. `--supersede-failed <reason>` closes a stage whose last row is `failed` under the same checks, for a failure that no longer applies (the checks ran in the wrong environment and the commit needs no product edit); the `done` row records `superseded_status`, the reason, the latest plan path and the conformance verdict. Closing also moves the `stage-<N>-exit` tag and releases the stage reservation, exactly as a normal stage completion does. Emits `{ ok, taskKey, taskRoot, stage, headCommit, conformance, consumersPath, supersededFailed, sourcePlanPath }` |
917
941
  | `okstra stage-reopen <task-key> --stage <N> --reason <why> [--evidence <path>] [--cwd <dir>\|--project <dir>]` | Append a `failed` stage-consumer row after a stage's `done` row, so `/okstra-run` offers that stage again for a fix run and its dependents stop branching from the withdrawn head. Use it when a later verification found a defect in a done stage — a single-stage final-verification that ended `blocked` and points at `implementation` is the case the wizard otherwise refuses. The row records the reason, `reopened_by: stage-reopen`, the head it withdraws and, with `--evidence`, the project-relative report path. Refuses a stage that is not in the latest Stage Map, is cancelled, or whose last row is not `done`. Emits `{ ok, taskKey, stage, headCommit, reason, evidencePath, consumersPath }` |
918
- | `okstra correction prompt --run-manifest <path> --round <N> --role <executor\|verifier> --base <sha> [--stage-base <sha>] [--finding <F-id> ...]` | Print the instruction body for one correction-round prompt of an implementation run, built from the convergence record that preceded the round (the run's initial one for round 1, round N-1's `convergence-correction-r<N-1>-…` re-convergence for round N): the findings to fix, the stage HEAD before the round, and the executor's or verifiers' rules. `--stage-base` adds one `FILE-SIZE:<path>` finding per file that `<stage-base>..<base>` leaves over the 400-line limit (advisory 300-line lines are not added); a round needs at least one finding from either source. Pass it to `okstra agent-prompt materialize --dispatch-kind correction-r<N>`. At most 2 rounds; exit 1 on an unknown finding or round. |
919
- | `okstra correction file-size --base <stage-base> [--head <rev>] [--repo <dir>]` | Check a stage diff against the file-size limit (400 lines, blocking) and target (300 lines, advisory). A threshold is broken by a file the diff adds over it, takes past it, or grows while already over it. Prints `FILE-SIZE:<path>:401 <before>-><after> lines (<kind>; limit 400)` per limit breach and `FILE-SIZE-ADVISORY:<path>:301 … (<kind>; target 300)` per file that breaks only the target, then `QA-RESULT: PASS\|FAIL`; only a limit breach fails. Lines are physical lines. Only `.py`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.kt`, `.kts`, `.rs` and `.java` files are checked; `.okstra`, `node_modules`, `vendor`, `fixtures`, `__fixtures__`, `__snapshots__`, `generated` and `__generated__` directories, `*.min.*` files, and files whose first 5 lines say `@generated` or `do not edit` are exempt. Writes nothing. Exit 1 on FAIL, 2 when git cannot read the range. |
920
- | `okstra stage-done <task-key> --stage <N> --carry <carry.json> --report <path> [--cwd <dir>\|--project <dir>]` | Settle an implementation stage whose verdict is not FAIL: write the executor's Stage Carry Evidence JSON to the flat `runs/implementation/carry/stage-<N>.json`, then append the `done` row with that carry path, the report path relative to its run directory, the carry head and the completion time. A reopened stage's previous sidecar moves to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json`. Refuses a carry for another stage, a failed carry, a stage already done at another head, and a carry whose `stageCommitRange` diff breaks the 400-line file-size limit (`okstra correction file-size`; the refusal names the `--stage-base` for a correction round); a repeat with the same carry writes nothing new. Prints JSON with `fileSizeCap` (`pass: <range>` or `not checked: <reason>`); exit 1 on a refusal. |
942
+ | `okstra correction prompt --run-manifest <path> --round <N> --role <executor\|verifier> --base <sha> [--stage-base <sha>] [--finding <F-id> ...]` | Print the instruction body for one correction-round prompt of an implementation run, built from the convergence record that preceded the round (the run's initial one for round 1, round N-1's `convergence-correction-r<N-1>-…` re-convergence for round N): the findings to fix, the stage HEAD before the round, and the executor's or verifiers' rules. `--stage-base` adds one `FILE-SIZE:<path>` finding per file that `<stage-base>..<base>` leaves over the 500-line limit (advisory 300-line lines are not added); a round needs at least one finding from either source. Pass it to `okstra agent-prompt materialize --dispatch-kind correction-r<N>`. At most 2 rounds; exit 1 on an unknown finding or round. |
943
+ | `okstra correction file-size --base <stage-base> [--head <rev>] [--repo <dir>]` | Check a stage diff against the file-size limit (500 lines, blocking) and target (300 lines, advisory). A threshold is broken by a file the diff adds over it or takes past it; the target is also broken by a file the diff grows while already over it, including a file already over the limit at the stage base, which the limit does not block. Prints `FILE-SIZE:<path>:501 <before>-><after> lines (<kind>; limit 500)` per limit breach and `FILE-SIZE-ADVISORY:<path>:301 … (<kind>; target 300)` per file that breaks only the target, then `QA-RESULT: PASS\|FAIL`; only a limit breach fails. Lines are physical lines. Only `.py`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.kt`, `.kts`, `.rs` and `.java` files are checked; `.okstra`, `node_modules`, `vendor`, `fixtures`, `__fixtures__`, `__snapshots__`, `generated` and `__generated__` directories, `*.min.*` files, and files whose first 5 lines say `@generated` or `do not edit` are exempt. Writes nothing. Exit 1 on FAIL, 2 when git cannot read the range. |
944
+ | `okstra stage-done <task-key> --stage <N> --carry <carry.json> --report <path> [--cwd <dir>\|--project <dir>]` | Settle an implementation stage whose verdict is not FAIL: write the executor's Stage Carry Evidence JSON to the flat `runs/implementation/carry/stage-<N>.json`, then append the `done` row with that carry path, the report path relative to its run directory, the carry head and the completion time. A reopened stage's previous sidecar moves to `carry/superseded/stage-<N>-from-<task-type>-<seq>.json`. Refuses a carry for another stage, a failed carry, a stage already done at another head, and a carry whose `stageCommitRange` diff breaks the 500-line file-size limit (`okstra correction file-size`; the refusal names the `--stage-base` for a correction round); a repeat with the same carry writes nothing new. Prints JSON with `fileSizeCap` (`pass: <range>` or `not checked: <reason>`); exit 1 on a refusal. |
921
945
  | `okstra stage-fail <task-key> --stage <N> --head-commit <sha> --report <path> --reason <why> [--cwd <dir>\|--project <dir>]` | Append the `failed` stage-consumer row an implementation run writes when its verdict is FAIL or no verifier returned a result. Dependents stay blocked and the stage becomes selectable for a fix run. Refuses a stage missing from or cancelled in the latest Stage Map, or already `done` (use `stage-reopen`). Prints JSON; exit 1 on a refusal. |
922
946
  | `okstra discussion <confirm-subject\|ask\|address\|answer\|decide> <task-key> … --run-manifest <path>` / `okstra discussion draft <task-key>` | The facilitator's only way to write a discussion task's record under `<task-root>/discussion/`: the confirmed subject and question, questions for the user (`ask`), the user's question to one worker (`address`), answers and user decisions. `--run-manifest` must be a discussion run manifest of the same task; authors are `leader` or a worker of that run, and only a question's addressee answers it. A resent record returns the stored one (`created: false`). Every write rebuilds `draft.json`; `draft` prints it as the fixed text every participant reads. Write commands emit `{ ok, created, record, pendingForUser, pendingForParticipants }`. `add-material --kind <evidence|alternative>` records new evidence or a new alternative, and `status` prints the phase, the next question for the user, unrecovered failures and remaining disagreements |
923
947
  | `okstra discussion <cycle-open\|settle\|cycle-close> <task-key> --run-manifest <path>` / `okstra discussion recover <task-key> --failure <X-NNNN> --choice <retry\|replace\|reduce> --run-manifest <path>` / `okstra discussion <question-prompt\|collect-answer> <task-key> --question <Q-NNNN> --run-manifest <path>` | The research, refutation and question cycle of a discussion, one research cycle per run. `cycle-open` writes the research instruction from the record and records its input references (start inputs, subject, answers, materials), or returns why nothing is dispatched: `await-user`, `await-participant`, `await-recovery`, `present-options` (the references equal the last closed cycle's) or `prepare-run` (the next cycle needs a run prepared with `--discussion-start <task-key>`). `settle` records each analyser's `initial` result and each failure the dispatcher left after its retry loop (`start` when the batch could not launch, `after-retries` otherwise); `recover` records the user's choice for one failure. `cycle-close` validates the run's convergence final state and imports its findings as claims with their origin worker and verdicts. `question-prompt` writes one direct question's instruction and `agent-prompt materialize --batch` file (dispatch kind `discussion-question`), and `collect-answer` records the addressee's whole result as the answer |
@@ -925,8 +949,8 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
925
949
  | `okstra discussion follow-up-brief <task-key> --revision <id> --follow-up <label> --target-task <task-key> [--target-project-root <dir>] [--end-state <N-NNNN>=<EB\|PB\|EO>[:<how>]]… [--replace]` / `okstra discussion links <task-key>` / `okstra discussion impact <task-key> --from <id> --to <id> [--follow-up <label>]` / `okstra discussion apply <task-key> --revision <latest id> --target-task <task-key> --choice <adopt\|keep> [--end-state …]… [--replace]` | Follow-up tasks of a published revision, run outside a discussion run at the user's request. `follow-up-brief` writes `<target-project-root>/.okstra/briefs/<task-group>/<task-id>-<label>.md` from the revision's common requirements and those of `--follow-up`, through `validators/validate-brief.py`; it recommends `requirements-discovery` and pins the discussion, revision id, content digest and requirement ids in the frontmatter, which prepare copies into the run inputs as `discussionRevisionRef`. `--end-state` maps a requirement to an `EB`/`PB`/`EO` item; an observation method the revision does not carry leaves the brief `reporter-confirmations: pending` with an `intent-check:` row for the user. The brief is written before the link in `<task-root>/discussion/links.jsonl`, so a resend after an interruption records the link once; a brief this command did not write last needs `--replace`. `links` re-reads every target (`current`, `needs-impact-review`, `kept`, `amendment-pending`, or `unknown` when the target cannot be read), `impact` prints the changes between two revisions, and `apply` records the user's choice for one target and the latest revision: `keep`, or `adopt`, which rewrites the brief of a target without an implementation-planning plan and routes a target with a plan to the plan amendment path without touching its plan, brief or source. A resent choice returns the stored record. `okstra discussion complete-amendment <task-key> --revision <id> --target-task <task-key> [--end-state …]… [--replace]` finishes a routed adoption once the target has an implementation-planning report newer than the one it had at routing whose `frontmatter.approved` is `true`: it rewrites the brief to pin the revision and records the plan report it relied on, and `links` then shows the target `current`. Without such a report it is refused and names what is missing, and `links` shows the same in the target's `next`; it never edits or approves a plan |
926
950
  | `okstra incremental-scope <args…>` | Decide re-verify vs carry-forward scope for an `implementation-planning` clarification re-run. Thin shim into `scripts/okstra_ctl/incremental_scope.py` (deterministic): it reads the dependency graph from the prior run `data.json`'s `implementationPlanning.stageMap` and returns `mode:"incremental"` only when the base-ref SHA is unchanged and the affected stages' `downstream_stage_closure` covers at most half of all stages; `--full-reason` (selected option / Stage Map / approach) still forces `mode:"full"`. An answered `C-NNN` that traces to no stage returns `mode:"unresolved"` rather than full — pass `--impacted` with the stage numbers or `--full-reason`. `--run-manifest <path>` is required for a decision (not for `--preview`): the same decision is written to the record that manifest names in `incrementalDecisionPath`, so the report writer's authoring contract and `okstra incremental-carry` read it instead of CSVs the lead re-typed. `mode: "unresolved"` is a question back to the lead and is deliberately not recorded. `--preview --prev-data <path> --answered-clarifications <csv>` runs the link half alone — no base SHA, no side effects — and prints `{wouldForceFull, unlinkedIds, reason}`; unlinked ids set `wouldForceFull: false` and fill `unlinkedIds` |
927
951
  | `okstra incremental-carry <args…>` | Merge carried-forward plan-item verdicts into an incremental re-run. Contract v3 takes `--prev-data`, `--cur-narrative`, and the convergence-owned `--state`; it verifies carried stage rows and writes only `--out-state`, tagging copied verdicts with `carriedForwardFromSeq`. Pass `--decision <incrementalDecisionPath>` for the two stage sets — the same record the report writer's authoring contract was built from — instead of `--carry-stages` / `--reverify-stages`, which the lead re-typed off stdout; the two forms cannot be combined, and a record whose `mode` is not `incremental` is refused. Unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract hash still matches are carried the same way, and the sibling `plan-items-*.json` `dispatchQueue` is rewritten to match. The historical v2 `--cur-data --out` form remains readable. Ownership, scope, item, or schema drift raises `CarryError` and forces a full fallback. |
928
- | `okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] [--json]` / `okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] [--cwd <dir>] [--json]` | Resolve what a code review reads and where its result file goes. Output is always JSON, so `--json` only makes that explicit. `--project-root` and `--cwd` are shared pre-dispatch arguments and apply to both modes; `--cwd` is only consulted when `--project-root` is absent. Both modes return `{ ok, projectRoot, mode, worktreePath, branch, baseCommit, headCommit, reviewPath, round }`; stage mode additionally returns `taskKey`, `taskRoot`, and `stage`. Stage mode takes the diff base from the `base_ref` recorded on that stage's worktree-registry row when it was provisioned — not from a rule re-applied at review time — and names the result `.okstra/tasks/<task-group>/<task-id>/code-reviews/stage-<NN>.md`, where a re-review of the same stage becomes `-r2`, `-r3`, … (the `round` field). Only a legacy row provisioned before `base_ref` was recorded falls back to re-deriving the base through `stage_targets`, and a failure there is reported as `stage_base_unresolved`. `worktreePath` comes back empty whenever the stage worktree is not usable as a live checkout — the registry row is no longer `active` (whole-task final-verification released it), the row never carried a path, or the recorded directory is gone — and the review then reads the `branch` ref instead. Branch mode uses `--base` when given, otherwise the merge-base with the default branch (`refs/remotes/origin/HEAD`, else `main`/`master`), and names the result `.project-docs/code-reviews/<branch>/<YYYY-MM-DD>-<NN>.md`, where `<NN>` (the `round` field) is the next sequence number for that date — the highest already on disk plus one. Read-only: it resolves paths and creates no directory and no file, so the review directory does not exist until the caller writes the report. Backend for the okstra-code-review skill |
929
- | `okstra code-review check-coverage --project-root <dir> --census <table-path> --completion <completion-path> [--completion <gap-fill-path> ...]` | Audits compact grouped-cell verdicts from one reviewer's verified standalone completions. Rejects changed model assignments or invalid evidence (exit 2); lists missing/unknown IDs (exit 1); complete usable coverage exits 0. The census has `## Rules` (Rule, Group, Reference) and `## Cells` (Cell, Target, Group) tables. Each result row explicitly accounts for the group's rules through Checked, N/A and Findings, with one existing target-source path:line. Checked general G2/G3/G5 criteria also require source-cited observations after ` :: ` in Evidence. Missing rules or observations are reported without expanding a target-by-bullet table; the lead audits selected references and semantic truth. |
952
+ | `okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] [--json]` / `okstra code-review target --branch <name> --base <ref> [--date <YYYY-MM-DD>] [--project-root <dir>] [--cwd <dir>] [--json]` | Resolve what a code review reads and where its result file goes. Output is always JSON, so `--json` only makes that explicit. `--project-root` and `--cwd` are shared pre-dispatch arguments and apply to both modes; `--cwd` is only consulted when `--project-root` is absent. Both modes return `{ ok, projectRoot, mode, worktreePath, branch, baseCommit, headCommit, reviewPath, round }`; stage mode additionally returns `taskKey`, `taskRoot`, and `stage`. Stage mode takes the diff base from the `base_ref` recorded on that stage's worktree-registry row when it was provisioned — not from a rule re-applied at review time — and names the result `.okstra/tasks/<task-group>/<task-id>/code-reviews/stage-<NN>.md`, where a re-review of the same stage becomes `-r2`, `-r3`, … (the `round` field). Only a legacy row provisioned before `base_ref` was recorded falls back to re-deriving the base through `stage_targets`, and a failure there is reported as `stage_base_unresolved`. `worktreePath` comes back empty whenever the stage worktree is not usable as a live checkout — the registry row is no longer `active` (whole-task final-verification released it), the row never carried a path, or the recorded directory is gone — and the review then reads the `branch` ref instead. Branch mode requires an explicit `--base` branch or commit, rejects invalid refs, freezes it as a commit, leaves `worktreePath` empty for fixed-head reads, and names the result `.project-docs/code-reviews/<branch>/<YYYY-MM-DD>-<NN>.md`, where `<NN>` (the `round` field) is the next sequence number for that date — the highest already on disk plus one. Read-only: it resolves paths and creates no directory and no file, so the review directory does not exist until the caller writes the report. Backend for the okstra-code-review skill |
953
+ | `okstra code-review check-coverage --project-root <dir> --head <headCommit> --census <table-path> --completion <completion-path> [--completion <gap-fill-path> ...]` | Audits compact grouped-cell verdicts from one reviewer's verified standalone completions. Rejects changed model assignments or invalid evidence (exit 2); lists missing/unknown IDs (exit 1); complete usable coverage exits 0. The census has `## Rules` (Rule, Group, Reference) and `## Cells` (Cell, Target, Group) tables. Each result row explicitly accounts for the group's rules through Checked, N/A and Findings, with one target-source path:line that exists at `--head`; evidence files are read from that commit, not the working tree. Checked general G2/G3/G5 criteria also require source-cited observations after ` :: ` in Evidence. Missing rules or observations are reported without expanding a target-by-bullet table; the lead audits selected references and semantic truth. |
930
954
  | `okstra set-work-status <token> <todo\|in-progress\|blocked\|done> [--note <text> \| --note-file <path>] [--task-group <g>] [--project-root <dir>]` | Update user-managed `workStatus`. Existing briefs can be registered without a run. Direct completion requires a work and verification summary; use a UTF-8 note file for longer results. Records are shared through group context, inspect, and subsequent runs without claiming cross-verification. Ambiguous IDs return `matches[]`. A `share` failure with `statusRecorded:true` can be retried with the same command. |
931
955
  | `okstra worktree-lookup <project-id> <task-group> <task-id>` | Return the `worktree_registry.lookup` result: reserved path, branch, base ref, and current status |
932
956
  | `okstra worktree-status [--path <dir>] [--check-clean]` | Answer "is this worktree clean?" over source paths only, excluding what okstra provisioned there — `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and any nested stage worktree. A bare `git status --porcelain` in a task worktree is never empty for that reason, so a plan step asserting a clean tree with one fails on okstra's scaffolding instead of on the stage's own work; this is the same gate `handoff` and stage integration use. Output is JSON `{ ok, path, clean, entries, excluded }` where `entries` holds the `git status --short` rows that made it dirty. Exit code is 0 regardless unless `--check-clean` is given, which exits 1 on a dirty tree so it can stand as a shell assertion (`okstra worktree-status --check-clean`). okstra writes `stage-<N>-exit` itself when it settles the stage, so a plan step must not tag. A path outside a git work tree exits 2 rather than reporting a clean tree |
@@ -324,7 +324,7 @@ Important modules:
324
324
  | `usage_report.py` | Read-only okstra-usage backend — scans the whole current project's recent run timelines, defaults to 30 days, and returns task-type coverage, raw/billable tokens, known USD cost, CPU-sum and wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
325
325
  | `json_registry.py` | shared flock + atomic JSON persistence for small okstra registries (`registry_lock`/`load_registry_json`/`save_registry_json`) — used by `worktree_registry` |
326
326
  | `stage_integrate.py` | whole-task stage integration (merge) + worktree teardown core (`integrate_stages`) — shared by whole-task final-verification entry, `okstra integrate-stages`, and container up |
327
- | `file_size_cap.py` | Stage-diff file-size thresholds for the correction round and `stage-done` (`okstra correction file-size` backend) — a 300-line target (advisory) and a 400-line limit (blocking), measured on the stage diff in physical lines for the source/test extensions okstra's coding preflight covers; vendored, fixture, snapshot, generated and `.okstra` paths, and files whose head declares itself generated, are exempt |
327
+ | `file_size_cap.py` | Stage-diff file-size thresholds for the correction round and `stage-done` (`okstra correction file-size` backend) — a 300-line target (advisory) and a 500-line limit (blocking), measured on the stage diff in physical lines for the source/test extensions okstra's coding preflight covers; vendored, fixture, snapshot, generated and `.okstra` paths, and files whose head declares itself generated, are exempt |
328
328
  | `resolve_task_key.py` | shared skill helper resolving a bare task-id → `task-catalog.json` candidate entries (`okstra resolve-task-key`) |
329
329
  | `code_review_paths.py` | filesystem-layout SSOT for code-review result files — `stage_review_dir` / `branch_review_dir` plus `next_stage_review` / `next_branch_review`, which read the existing files to derive the next round's name (`stage-<NN>.md`, then `-r2`, `-r3`, …) or the next same-day sequence (`<YYYY-MM-DD>-<NN>.md`), so skill markdown never re-derives a literal review path |
330
330
  | `code_review_target.py` | `okstra code-review target` backend — argument validation and JSON shaping only. Stage mode delegates whole to `okstra_project.state.code_review_target_snapshot`; branch mode is resolved here, defaulting the diff base to the merge-base with the default branch (`refs/remotes/origin/HEAD`, else `main`/`master`). Read-only: it never creates the review directory |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.226.0",
3
+ "version": "0.227.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.226.0",
3
- "builtAt": "2026-10-30T16:11:21.288Z",
2
+ "package": "0.227.0",
3
+ "builtAt": "2026-10-31T13:06:36.074Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -2,5 +2,5 @@
2
2
  "schemaVersion": "1.0",
3
3
  "id": "code-review",
4
4
  "dutyId": "code-reviewer",
5
- "count": 2
5
+ "count": 3
6
6
  }
@@ -180,7 +180,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
180
180
  |---|---|---|
181
181
  | `okstra report-finalize --project-root <dir> --run-manifest <path> [--report <path>]` | Run the whole Phase 7 sequence; do not run its steps separately. `--report` defaults to the manifest's `expectedReportRecordPath`. Without `--only` it records `phase-7-persist` first; emit its `progressLines` | `report-writer` "Phase 6 → Phase 7 execution sequence" |
182
182
  | `okstra handoff record-verified --plan-run-root <dir> --stage <N> --report-path <path> --data-json <path>` | Record an accepted final-verification against its stage. `report-finalize` runs it in its `record-verified` step; run it by hand only to repair a registry after that step failed | `report-writer` "Phase 6 → Phase 7 execution sequence" |
183
- | `okstra correction prompt --run-manifest <path> --round <N> --role <executor\|verifier> --base <sha> --stage-base <sha> --finding <F-id>` | Write a correction-round instruction body; materialize it with dispatch kind `correction-r<N>`. `--stage-base` adds the stage's 400-line file-size findings | `_implementation-deliverable.md` "Correction round" |
183
+ | `okstra correction prompt --run-manifest <path> --round <N> --role <executor\|verifier> --base <sha> --stage-base <sha> --finding <F-id>` | Write a correction-round instruction body; materialize it with dispatch kind `correction-r<N>`. `--stage-base` adds the stage's 500-line file-size limit findings | `_implementation-deliverable.md` "Correction round" |
184
184
  | `okstra stage-done <task-key> --stage <N> --carry <carry.json> --report <path>` | Settle an implementation stage whose synthesised verdict is not FAIL: writes the flat `runs/implementation/carry/stage-<N>.json` sidecar and appends the `done` row — never write either by hand | `_implementation-deliverable.md` "Lead post-stage persistence" |
185
185
  | `okstra stage-fail <task-key> --stage <N> --head-commit <sha> --report <path> --reason <why>` | Record an implementation stage whose synthesised verdict is FAIL, or that ended with no verifier result, as `failed` — never call `append_consumer` from python | `_implementation-deliverable.md` "Lead post-stage persistence" |
186
186
  | `okstra team teardown --project-root <dir> --run-manifest <path>` | Close every recorded pane at the end of the run | cmux adapter "Semantic operation mapping" |
@@ -617,5 +617,49 @@
617
617
  "reverify_scope_user_stages": " reverify-scope: stage {stages} 재검증 지정 (사용자 지정 — 하위 stage 포함, 나머지는 직전 판정 이월)",
618
618
  "stage_whole_task": "전체 task",
619
619
  "handoff_scope_stages": "stage {stages} (stage 당 PR 1건)"
620
+ },
621
+ "worker_settings": {
622
+ "source_global": "전역",
623
+ "source_project": "프로젝트",
624
+ "source_once": "이번 실행",
625
+ "source_previous": "직전 실행",
626
+ "role_analyser": "분석자",
627
+ "role_designer": "설계자",
628
+ "role_planner": "계획자",
629
+ "role_implementer": "구현자",
630
+ "role_verifier": "검증자",
631
+ "role_critic": "판정자",
632
+ "role_report-writer": "보고서 작성자",
633
+ "unset": "미설정 · 실행 시 질문",
634
+ "invalid_models": "{source} · 잘못된 모델 목록: {models}",
635
+ "configured": "{count}명 · {models} · {source}",
636
+ "disabled": "사용 안 함",
637
+ "summary_header": "워커 설정 · {scope} · {path}",
638
+ "role_summary": "- {label} ({role}): {value}",
639
+ "changes": "변경 내용:",
640
+ "before": "- {role} 이전: {value}",
641
+ "after": "- {role} 저장 후: {value}",
642
+ "inherit": "전역 설정 상속",
643
+ "clear": "설정 해제",
644
+ "cancel": "취소",
645
+ "scope_label": "워커 설정 범위",
646
+ "scope_global": "전역 기본값",
647
+ "scope_project": "이 프로젝트 덮어쓰기",
648
+ "save": "저장",
649
+ "edit": "계속 수정",
650
+ "review": "변경 검토",
651
+ "models_label": "{role} · 허용 {minimum}..{maximum}명\n선택한 모델 하나당 1명입니다. 상속·해제·사용 안 함은 단독으로 선택하세요.\n검증자 기본값은 시작 역할에만 적용하며 동적 검증자는 원본 배정을 따릅니다.",
652
+ "exclusive": "상속·해제·사용 안 함은 다른 모델과 함께 선택할 수 없습니다.",
653
+ "conflict": "{path}: {role} 설정이 이 편집을 시작한 뒤 바뀌었습니다. 설정을 다시 여세요.",
654
+ "choose_scope": "설정 범위를 선택하세요.",
655
+ "choose_role": "변경할 역할을 선택하세요.",
656
+ "choose_save": "저장 또는 계속 수정을 선택하세요.",
657
+ "cancelled": "워커 설정 취소",
658
+ "saved": "워커 설정 저장 완료",
659
+ "editing": "워커 설정 편집 중",
660
+ "run_invalid": "{error}\n이번 실행의 구성을 다시 선택하세요.\n{label}",
661
+ "run_source": " {role}: {count}명 · 설정 출처: {source}",
662
+ "run_disabled": " {role}: 0명 · 사용 안 함 · 설정 출처: {source}",
663
+ "issue": "{value} · 오류: {error}"
620
664
  }
621
665
  }
@@ -0,0 +1,63 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Mapping
4
+ from pathlib import Path
5
+
6
+ from okstra_project import project_json_path
7
+ from okstra_project.dirs import okstra_home
8
+
9
+ from ..domain.worker_defaults import (
10
+ WorkerDefaultError,
11
+ WorkerDefaultScopes,
12
+ WorkerDefaultUpdates,
13
+ WorkerScope,
14
+ merge_worker_default_updates,
15
+ )
16
+ from ..json_boundary import load_owned_object, write_owned_object_atomic
17
+ from ..json_registry import registry_lock
18
+
19
+
20
+ def _read_worker_config(path: Path) -> tuple[dict[str, object], dict[str, object]]:
21
+ config = (
22
+ load_owned_object(path, artifact="worker settings") if path.exists() else {}
23
+ )
24
+ values = config.get("workerDefaults", {})
25
+ if not isinstance(values, dict):
26
+ raise WorkerDefaultError(f"{path}: workerDefaults must be an object")
27
+ return config, values
28
+
29
+
30
+ class JsonWorkerDefaultsStore:
31
+ def scope_path(self, scope: WorkerScope, project_root: Path | None) -> Path:
32
+ if scope == "global":
33
+ return okstra_home() / "config.json"
34
+ if scope != "project" or project_root is None:
35
+ raise WorkerDefaultError(
36
+ "project worker settings require an okstra project"
37
+ )
38
+ return project_json_path(project_root)
39
+
40
+ def load_scopes(self, project_root: Path | None) -> WorkerDefaultScopes:
41
+ scopes: WorkerDefaultScopes = {
42
+ "global": _read_worker_config(self.scope_path("global", project_root))[1],
43
+ }
44
+ if project_root is not None:
45
+ scopes["project"] = _read_worker_config(
46
+ self.scope_path("project", project_root)
47
+ )[1]
48
+ return scopes
49
+
50
+ def save_scope(
51
+ self,
52
+ scope: WorkerScope,
53
+ project_root: Path | None,
54
+ updates: WorkerDefaultUpdates,
55
+ before: Mapping[str, object],
56
+ ) -> dict[str, object]:
57
+ path = self.scope_path(scope, project_root)
58
+ with registry_lock(path.with_suffix(path.suffix + ".lock")):
59
+ config, current = _read_worker_config(path)
60
+ values = merge_worker_default_updates(current, before, updates)
61
+ config["workerDefaults"] = values
62
+ write_owned_object_atomic(path, config, artifact="worker settings")
63
+ return values
@@ -13,6 +13,7 @@ import sys
13
13
  from ..invocation import AgentInvocationError
14
14
  from ...worker_prompt_headers import WorkerPromptHeaderError
15
15
  from ...error_log_write import record_runtime_failure
16
+ from ...file_size_cap import headroom_text
16
17
  from ...dispatch_state import BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE, DispatchError
17
18
  from .emit import _emit, _prepared_payload
18
19
  from .inputs import AgentPromptCliError
@@ -407,6 +408,8 @@ def main(argv: list[str] | None = None) -> int:
407
408
  else:
408
409
  for defect in payload["defects"]:
409
410
  print(defect, file=sys.stderr)
411
+ for row in payload["fileSizeHeadroom"]:
412
+ print(f"File-size headroom: {headroom_text(row)}")
410
413
  print("ok" if payload["ok"] else "defects: " + str(len(payload["defects"])))
411
414
  return 0 if payload["ok"] else 1
412
415
  if args.command == "apply-corrections":
@@ -23,6 +23,7 @@ from ..activity import (
23
23
  agent_activity_rows,
24
24
  record_activity,
25
25
  )
26
+ from ...file_size_cap import planned_file_headroom
26
27
  from ...final_report_schema import load_schema_version
27
28
  from ...json_boundary import load_owned_object
28
29
  from ...phases.implementation_option_selection.validation import validate_implementation_option_selection
@@ -156,6 +157,7 @@ def corrections_payload(
156
157
  check: CorrectionsCheck, *, project_root: Path, corrections_path: Path,
157
158
  ) -> dict[str, Any]:
158
159
  """`check-corrections --json` 의 출력."""
160
+ planning = (check.scratch or {}).get("implementationPlanning")
159
161
  return {
160
162
  "ok": check.ok,
161
163
  "correctionsPath": _relative(project_root, corrections_path),
@@ -169,6 +171,9 @@ def corrections_payload(
169
171
  for item in check.corrections
170
172
  ],
171
173
  "defects": list(check.defects),
174
+ "fileSizeHeadroom": (
175
+ planned_file_headroom(planning, project_root) if isinstance(planning, Mapping) else []
176
+ ),
172
177
  }
173
178
 
174
179
 
@@ -1,8 +1,9 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import re
4
+ import subprocess
4
5
  from collections.abc import Sequence
5
- from dataclasses import dataclass
6
+ from dataclasses import dataclass, field
6
7
  from pathlib import Path, PurePosixPath
7
8
 
8
9
  from .agent.invocation import AgentInvocationError, verify_standalone_completion
@@ -86,28 +87,78 @@ def _keyed_values(text: str) -> dict[str, str]:
86
87
  return values
87
88
 
88
89
 
89
- def _source_evidence(project_root: Path, cell: ReviewCell, evidence: str) -> str:
90
+ @dataclass
91
+ class _HeadTree:
92
+ """리뷰 대상 커밋이 담은 파일.
93
+
94
+ 프로젝트 루트에는 다른 커밋이 체크아웃돼 있을 수 있다.
95
+ """
96
+
97
+ root: Path
98
+ commit: str
99
+ line_counts: dict[str, int] = field(default_factory=dict)
100
+
101
+ def line_count(self, path: str) -> int:
102
+ if path not in self.line_counts:
103
+ self.line_counts[path] = self._read_line_count(path)
104
+ return self.line_counts[path]
105
+
106
+ def _git(self, *args: str) -> subprocess.CompletedProcess[bytes]:
107
+ return subprocess.run(
108
+ ["git", "--literal-pathspecs", "-C", str(self.root), *args],
109
+ capture_output=True, check=False,
110
+ )
111
+
112
+ def _read_line_count(self, path: str) -> int:
113
+ listing = self._git("ls-tree", "-z", self.commit, "--", path)
114
+ if listing.returncode != 0:
115
+ raise ValueError("cannot list the head commit")
116
+ entries = [entry for entry in listing.stdout.split(b"\0") if entry]
117
+ named = (entry.partition(b"\t") for entry in entries)
118
+ matched = [
119
+ meta.split() for meta, _, name in named
120
+ if name.decode("utf-8", "surrogateescape") == path
121
+ ]
122
+ if not matched:
123
+ raise ValueError("source evidence file does not exist at head")
124
+ mode, kind, blob = matched[0]
125
+ if kind != b"blob" or mode == b"120000":
126
+ raise ValueError("source evidence is not a regular file at head")
127
+ content = self._git("cat-file", "blob", blob.decode())
128
+ if content.returncode != 0:
129
+ raise ValueError("cannot read source evidence at head")
130
+ return len(content.stdout.decode("utf-8").splitlines())
131
+
132
+
133
+ def _head_tree(project_root: Path, head: str) -> _HeadTree:
134
+ resolved = subprocess.run(
135
+ ["git", "-C", str(project_root), "rev-parse", "--verify", "--quiet",
136
+ "--end-of-options", f"{head}^{{commit}}"],
137
+ capture_output=True, text=True, check=False,
138
+ )
139
+ if resolved.returncode != 0:
140
+ raise ValueError(f"--head {head!r} is not a commit in {project_root}")
141
+ return _HeadTree(project_root, resolved.stdout.strip())
142
+
143
+
144
+ def _source_evidence(tree: _HeadTree, cell: ReviewCell, evidence: str) -> str:
90
145
  match = re.fullmatch(r"(.+?):([1-9][0-9]*)`?(?: — .+)?", evidence.strip("`"))
91
146
  target = cell.target.partition(":")[0]
92
147
  if match is None or match[1] != target:
93
148
  raise ValueError("evidence must cite the target source path:line")
94
149
  relative = PurePosixPath(target)
95
- source = (project_root / target).resolve()
96
- if (relative.is_absolute() or ".." in relative.parts
97
- or not source.is_relative_to(project_root.resolve())):
150
+ if relative.is_absolute() or ".." in relative.parts:
98
151
  raise ValueError("source evidence escapes project")
99
- if not source.is_file():
100
- raise ValueError("source evidence file does not exist")
101
- if int(match[2]) > len(source.read_text(encoding="utf-8").splitlines()):
102
- raise ValueError("source evidence line does not exist")
152
+ if int(match[2]) > tree.line_count(target):
153
+ raise ValueError("source evidence line does not exist at head")
103
154
  return evidence
104
155
 
105
156
 
106
157
  def _checked_rule_evidence(
107
- project_root: Path, cell: ReviewCell, checked: Sequence[str], text: str,
158
+ tree: _HeadTree, cell: ReviewCell, checked: Sequence[str], text: str,
108
159
  ) -> str:
109
160
  anchor, _, raw = text.partition(" :: ")
110
- _source_evidence(project_root, cell, anchor)
161
+ _source_evidence(tree, cell, anchor)
111
162
  observations = _keyed_values(raw.strip() or "-")
112
163
  required = set(checked) & {"G2", "G3", "G5"} if cell.group == "general" else set()
113
164
  missing = required - observations.keys()
@@ -123,13 +174,13 @@ def _checked_rule_evidence(
123
174
  raise ValueError("clean check evidence needs an observation, not a verdict label")
124
175
  citation = match[1].strip("`")
125
176
  source_cell = ReviewCell(citation.partition(":")[0], cell.group)
126
- _source_evidence(project_root, source_cell, citation)
177
+ _source_evidence(tree, source_cell, citation)
127
178
  return text
128
179
 
129
180
 
130
181
  def _group_verdict(
131
182
  fields: Sequence[str], expected: Sequence[str], cell: ReviewCell,
132
- project_root: Path, references: Sequence[str],
183
+ tree: _HeadTree, references: Sequence[str],
133
184
  ) -> tuple[str, str]:
134
185
  if len(fields) != 5:
135
186
  raise ValueError("expected Cell, Checked, N/A, Findings, Evidence columns")
@@ -155,7 +206,7 @@ def _group_verdict(
155
206
  raise ValueError("invalid finding ID")
156
207
  if not any(id_occurs_wordbounded(body, item) for body in references):
157
208
  raise ValueError(f"finding {item} has no finding body")
158
- evidence = _checked_rule_evidence(project_root, cell, checked, fields[4])
209
+ evidence = _checked_rule_evidence(tree, cell, checked, fields[4])
159
210
  if findings:
160
211
  return "finding", "; ".join(findings.values())
161
212
  if checked:
@@ -164,7 +215,7 @@ def _group_verdict(
164
215
 
165
216
 
166
217
  def _group_results(
167
- body: str, census: ReviewCensus, project_root: Path, references: Sequence[str],
218
+ body: str, census: ReviewCensus, tree: _HeadTree, references: Sequence[str],
168
219
  ) -> CellVerdicts:
169
220
  section, _ = split_coverage_verdict_section(body)
170
221
  verdicts: dict[str, tuple[str, str]] = {}
@@ -188,7 +239,7 @@ def _group_results(
188
239
  cell = census.cells[identity]
189
240
  try:
190
241
  verdicts[identity] = _group_verdict(
191
- fields, census.rules[cell.group], cell, project_root, references,
242
+ fields, census.rules[cell.group], cell, tree, references,
192
243
  )
193
244
  except (OSError, ValueError) as exc:
194
245
  reasons[identity] = str(exc)
@@ -200,9 +251,10 @@ def _group_results(
200
251
 
201
252
 
202
253
  def check_review_coverage(
203
- project_root: Path, census_path: Path, completions: Sequence[Path],
254
+ project_root: Path, census_path: Path, completions: Sequence[Path], head: str,
204
255
  ) -> CellVerdicts:
205
256
  census = read_review_census(census_path)
257
+ tree = _head_tree(project_root, head)
206
258
  if not completions or len(set(completions)) != len(completions):
207
259
  raise ValueError("pass distinct completion paths for one reviewer")
208
260
  bodies: list[str] = []
@@ -226,7 +278,7 @@ def check_review_coverage(
226
278
  unknown: list[str] = []
227
279
  references = [split_coverage_verdict_section(body)[1] for body in bodies]
228
280
  for body in bodies:
229
- parsed = _group_results(body, census, project_root, references)
281
+ parsed = _group_results(body, census, tree, references)
230
282
  unknown.extend(key for key in parsed.unknown if key not in unknown)
231
283
  for key, verdict in parsed.verdicts.items():
232
284
  verdicts.setdefault(key, verdict)