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.
- package/README.md +1 -0
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/cli.md +29 -5
- package/docs/project-structure-overview.md +1 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
- package/runtime/python/okstra_ctl/code_review_target.py +77 -53
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/run.py +15 -1
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/skills/okstra-code-review/SKILL.md +25 -23
- package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
- 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
|
-
|
|
104
|
-
|
|
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
|
-
|
|
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":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,KAAK,GAAG
|
|
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
|
|
919
|
-
| `okstra correction file-size --base <stage-base> [--head <rev>] [--repo <dir>]` | Check a stage diff against the file-size limit (
|
|
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
|
|
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>
|
|
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
|
|
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
|
|
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
package/runtime/BUILD.json
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
100
|
-
raise ValueError("source evidence
|
|
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
|
-
|
|
158
|
+
tree: _HeadTree, cell: ReviewCell, checked: Sequence[str], text: str,
|
|
108
159
|
) -> str:
|
|
109
160
|
anchor, _, raw = text.partition(" :: ")
|
|
110
|
-
_source_evidence(
|
|
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(
|
|
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
|
-
|
|
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(
|
|
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,
|
|
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,
|
|
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,
|
|
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)
|