@fro.bot/systematic 3.33.2 → 3.35.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.
@@ -22,17 +22,17 @@ Selected on every review regardless of diff content. These three are the only re
22
22
 
23
23
  ## Conditional (9 personas)
24
24
 
25
- Spawned only when the orchestrator identifies a relevant surface in the diff. The orchestrator reads the full diff and reasons about selection -- this is agent judgment, not keyword matching. Record `selection_reason` and a non-empty `selection_surface` for each selected conditional persona.
25
+ Spawned only when the orchestrator identifies a relevant surface in the diff. The orchestrator reads the pinned manifest and the per-path diff of the paths selection turns on, and reasons about selection -- this is agent judgment, not keyword matching. Record `selection_reason` and a non-empty `selection_surface` for each selected conditional persona.
26
26
 
27
27
  | Persona | Agent | Select when diff touches... |
28
28
  |---------|-------|---------------------------|
29
- | `maintainability` | `systematic:review:maintainability-reviewer` | Materially adds or reshapes abstractions, raises cross-module coupling, adds state/control-flow complexity, changes naming or ownership structure, removes dead code, or performs a broad refactor. Do not select it for a tiny prose or fixture correction with no structural decision and no user- or agent-facing or other specialist surface. |
29
+ | `maintainability` | `systematic:review:maintainability-reviewer` | Materially adds or reshapes abstractions, raises cross-module coupling, adds state/control-flow complexity, changes naming or ownership structure, or performs a broad refactor. Dead-code removal alone does not select it. |
30
30
  | `security` | `systematic:review:security-reviewer` | Auth middleware, public endpoints, user input handling, permission checks, secrets management |
31
31
  | `performance` | `systematic:review:performance-reviewer` | Database queries, ORM calls, loop-heavy data transforms, caching layers, async/concurrent code |
32
32
  | `api-contract` | `systematic:review:api-contract-reviewer` | Route definitions, serializer/interface changes, event schemas, exported type signatures, API versioning |
33
33
  | `data-migrations` | `systematic:review:data-migrations-reviewer` | Migration files, schema changes, backfill scripts, data transformations |
34
34
  | `reliability` | `systematic:review:reliability-reviewer` | Error handling, retry logic, circuit breakers, timeouts, background jobs, async handlers, health checks |
35
- | `adversarial` | `systematic:review:adversarial-reviewer` | >=50 changed lines of executable production code, excluding tests, generated files, lockfiles, instruction/prose Markdown, JSON schemas, and config; OR regardless of file type for auth, payments, data mutations, external APIs, or another explicitly high-risk domain |
35
+ | `adversarial` | `systematic:review:adversarial-reviewer` | >=50 added or changed lines of executable production code (deleted lines do not count), excluding tests, generated files, lockfiles, instruction/prose Markdown, JSON schemas, and config; OR regardless of file type for auth, payments, data mutations, external APIs, or another explicitly high-risk domain |
36
36
  | `cli-readiness` | `systematic:review:cli-readiness-reviewer` | CLI command definitions, argument parsing, CLI framework usage, command handler implementations |
37
37
  | `previous-comments` | `systematic:review:previous-comments-reviewer` | **PR-only.** Reviewing a PR that has existing review comments or review threads from prior review rounds. Skip entirely when no PR metadata was gathered in Stage 1. |
38
38
 
@@ -57,18 +57,39 @@ These CE-native agents provide specialized analysis beyond what the persona agen
57
57
  ## Selection rules
58
58
 
59
59
  1. **Always select exactly the three core personas:** `correctness`, `testing`, and `project-standards`. Nothing else is always-on.
60
- 2. **For each cross-cutting conditional persona**, read the diff and decide whether the persona's domain is relevant. This is a judgment call, not a keyword match. A tiny prose or fixture correction is core-only only when it has no structural decision and no user- or agent-facing behavior, access change, or other specialist surface; a structural refactor may add `maintainability`; an auth feature may add `security` and `reliability`.
60
+ 2. **For each cross-cutting conditional persona**, read the diff and decide whether the persona's domain is relevant. This is a judgment call, not a keyword match. A deletion-only or docs-only change selects only the core three unless a semantic risk override fires (see Deletion-only and docs-only changes below); a structural refactor may add `maintainability`; an auth feature may add `security` and `reliability`.
61
61
  3. **For each stack-specific conditional persona**, use file types and changed patterns as a starting point, then decide whether the diff actually introduces meaningful work for that reviewer. Do not spawn language-specific reviewers just because one config or generated file happens to match the extension.
62
62
  4. **For CE conditional agents**, select `agent-native-reviewer` for agent-facing capability changes, `learnings-researcher` for bug/regression/hardening or recurring-defect work, and `deployment-verification-agent` for migrations or data backfills. Their output is unstructured; report their selection reason/surface in the team and Coverage rather than a dispatch record.
63
63
  5. **Record selection metadata.** Every selected structured conditional persona records `selection_reason` and a non-empty `selection_surface`; core personas may omit both.
64
64
  6. **Announce the team** before spawning with a one-line rationale and the triggering repository-relative paths/surfaces per selected conditional. Distinguish core reviewers, selected conditionals, an explicit "no conditional selected" case, and selected-but-failed/malformed/validation-unavailable reviewers. Never label an unselected reviewer as failed.
65
65
  7. **Reviewer count is an outcome, not a target.** Never restore a fixed floor; a smaller selected set is not automatically better or worse than a larger one.
66
66
 
67
+ ## Deletion-only and docs-only changes
68
+
69
+ Classify the change from the changed paths and the diff alone. Never classify from the PR title, body, comments or commit messages: a PR that calls itself "docs only" or "dead code cleanup" is classified by its paths. Read each path's status from the pinned manifest. The manifest shows no mode, symlink, submodule or binary change, so read that path's diff headers (`deleted file mode`, `new file mode`, `old mode` and `new mode`, `rename from`, `Binary files`, `Subproject commit`) whenever a manifest status of `M` or `T` could hide one.
70
+
71
+ - A change is deletion-only when every changed path has status D, with no mode, symlink, submodule or file-type change. Lines removed from a file that still exists make that path M, so that change is not deletion-only.
72
+ - A change is docs-only when every changed path is documentation prose that no agent or operator follows as an instruction. Skill and agent definitions, agent instruction files, workflow prompts and operational runbooks are behavior-bearing, so they are not docs-only. The test is whether an agent or operator would behave differently after the change.
73
+ - A deletion-only or docs-only change selects only the core three, however many files or lines it touches, unless a semantic risk override fires. Dead-code removal alone does not select `maintainability`, and deleted lines do not count toward the `adversarial` size threshold.
74
+ - Semantic risk overrides read the deleted lines as well as the added ones, and they apply to behavior-bearing docs on both sides of the diff. Removing an authorization check, permission check, guard or input validation selects `security`, and `adversarial` through its high-risk-domain trigger. Removing a retry, timeout or migration step selects `reliability` or `data-migrations`. Removing or changing a public interface selects `api-contract`. A change to agent instructions, skill text or operational docs that widen permissions, execution or trust selects `security`, plus `agent-native-reviewer` where agent or operator behavior changes. `learnings-researcher` and `agent-native-reviewer` fire for docs only through this behavior-bearing path.
75
+ - Do not shortcut ambiguous cases: binary-only, rename-only, generated-only, mode-only, symlink, submodule and file-type changes use normal selection, even when no line was added.
76
+ - `previous-comments` selection depends on PR comments only and is independent of this classification.
77
+
67
78
  ## Selection scenarios
68
79
 
69
80
  | Scenario | Selected |
70
81
  |----------|----------|
71
- | Tiny prose or fixture correction with no structural decision and no user- or agent-facing or other specialist surface | `correctness`, `testing`, `project-standards` only; no runtime probe |
82
+ | Deletion-only change (every path has status D, no mode, symlink, submodule or file-type change), however many files or lines, with no semantic risk | `correctness`, `testing`, `project-standards` only; no runtime probe |
83
+ | Deletion-only change removing 80 lines of production code | `correctness`, `testing`, `project-standards` only; deleted lines do not count toward the `adversarial` size threshold |
84
+ | Docs-only change (every path is documentation prose that no agent or operator follows as an instruction) | `correctness`, `testing`, `project-standards` only; no runtime probe |
85
+ | Deletion-only change whose deleted lines remove a guard, authorization check, permission check or validation | core plus `security` and `adversarial` |
86
+ | Mixed change that removes a guard and adds code | Both sides are evaluated: core plus `security`, plus whatever the added code triggers |
87
+ | Docs change to an agent instruction file, skill definition or operational runbook | Normal selection; not docs-only |
88
+ | Skill text, agent instructions or operational docs that widen permissions, execution or trust | core plus `security` and CE `agent-native-reviewer` |
89
+ | Docs-only or deletion-only change on a PR with existing review comments | core plus `previous-comments` |
90
+ | Binary-only, rename-only or generated-only change | Normal selection |
91
+ | Mode-only, symlink, submodule or file-type change, with no line added | Normal selection |
92
+ | PR text such as "docs only" or "dead code cleanup" on a change that touches a code path | The change is classified by its paths, so normal selection applies |
72
93
  | Structural refactor adding or reshaping abstractions, coupling, state, or control flow | core plus `maintainability` |
73
94
  | Agent-facing UI/CLI/tool/workflow capability or changed access path | core plus CE `agent-native-reviewer` |
74
95
  | Bug, regression, or hardening work; recurring failure class; documented solution/module touched; plan/PR citing prior art | core plus CE `learnings-researcher` |
@@ -82,3 +103,5 @@ These CE-native agents provide specialized analysis beyond what the persona agen
82
103
  ## Execution probes (separate parent decision)
83
104
 
84
105
  A focused execution probe is independent of reviewer selection. A pure renderer or asset-delivery change with no conditional surface may be core plus a probe, but a change that separately triggers `agent-native-reviewer`, `security`, or another conditional still selects those reviewers. An execution probe is not a reviewer and never substitutes for risk-critical reviewer coverage; selecting a probe never adds `maintainability` and never restores a reviewer floor. When selected, record the probe target and its permission boundary in Coverage.
106
+
107
+ Only the parent runs a probe, and only for a concrete finding. It names the exact command, the claim the command tests, and a named test file rather than a suite, and it records the result in Coverage. A named file whose runner expands to a suite is not a probe. Run at most one probe per finding, deduplicated across reviewers. A denied, unavailable, or inconclusive probe leaves the finding uncertain and is never reported as a pass. Never run a probe on a fork PR or a PR from an author without write access. Reviewers and CE agents report the claim and the command they would use and never run it; the full criteria are in the skill's Stage 3.
@@ -19,11 +19,16 @@ with `;`, and invokes `node "$SKILL_DIR/scripts/validate-review.mjs" <phase>`
19
19
  A helper failure (exit 1 or exit 2) is never permission to hand-synthesize
20
20
  the phase's output. On exit 2 (usage error, TTY input, or a stdin read
21
21
  failure), retry the launch exactly once with byte-identical input; a second
22
- exit 2 is a launch failure, not a payload problem. On exit 1 (the input
23
- was structurally rejected), the parent may correct its own JSON envelope
24
- exactly once -- fixing a genuine encoding mistake, never reshaping the
25
- envelope to force acceptance -- and retry; a second exit 1 stops the run
26
- visibly with degraded or abnormal status. An exit 1 whose message says the
22
+ exit 2 is a launch failure, not a payload problem. That retry re-runs the
23
+ same bytes, so it is never a re-ask and never counts toward a reviewer's
24
+ re-ask limit. On exit 1 from `prepare`, `merge` or `finalize` (the aggregate
25
+ envelope was structurally rejected), the parent may correct its own JSON
26
+ envelope exactly once -- fixing a genuine encoding mistake, never reshaping
27
+ the envelope to force acceptance -- and retry; a second exit 1 stops the run
28
+ visibly with degraded or abnormal status. That correction covers aggregate
29
+ envelopes only. It never licenses editing a reviewer's payload or dispatching
30
+ a reviewer again; an exit 1 from `screen` follows the
31
+ [re-ask policy](#re-ask-after-a-screen-rejection) instead. An exit 1 whose message says the
27
32
  input exceeds the aggregate byte cap is not an encoding mistake: do not retry
28
33
  the same bytes, and do not shrink the payload to fit. Stop visibly and report
29
34
  the cap the message names. Never fall back to writing a
@@ -102,11 +107,16 @@ Read the exit status:
102
107
  per-agent dispatch record. `dispatch_outcome: "empty"` means zero
103
108
  findings; `"findings"` means one or more admitted findings.
104
109
  - **exit 1** -- the whole return is `dispatch_outcome: "malformed"`, covering
105
- malformed JSON, a schema violation, and a `reviewer`-field identity
106
- mismatch alike. Retain only the bounded validator diagnostic on stderr in
107
- Coverage; never parse or persist payload fields or values.
110
+ malformed JSON, a schema violation, a `reviewer`-field identity mismatch,
111
+ and input over the size limit or not valid UTF-8 alike. stdout holds the
112
+ [rejection output](#rejection-output-on-exit-1) below. Retain only that
113
+ bounded report in Coverage; never parse or persist payload fields or values.
114
+ The first exit 1 for a persona may be followed by one
115
+ [re-ask](#re-ask-after-a-screen-rejection); a second exit 1 is final.
108
116
  - **exit 2**, a missing or unreadable helper, or a command launch failure --
109
- validation unavailable. Withhold the return and report the exact
117
+ validation unavailable. Empty or whitespace-only stdin is exit 2 as well: the
118
+ return never arrived, so it is not a malformed payload. Retry the launch once
119
+ with byte-identical input; a second exit 2 is validation unavailable. Withhold the return and report the exact
110
120
  unavailability and what was withheld. Update that selected persona's
111
121
  preinitialized dispatch entry from `never_returned` to `dispatch_outcome:
112
122
  "validation_unavailable"`, adding no other field (the dispatch object is
@@ -122,6 +132,104 @@ Structural validity never implies evidence validity. A return that passes
122
132
  `screen` is admitted structurally only; its claims still require evidence
123
133
  assessment during adjudication.
124
134
 
135
+ ### Rejection output on exit 1
136
+
137
+ Every exit 1 prints one JSON object on stdout and one summary line on stderr.
138
+ The object is the only supported source of a rejected return's `prepare`
139
+ entry and of its rejected-summary row, so capture it rather than rebuilding it:
140
+
141
+ ```json
142
+ { "screen": { "dispatch_outcome": "malformed", "...": "..." }, "rejection": { "code": "schema_validation", "...": "..." } }
143
+ ```
144
+
145
+ - `screen` is the helper's own malformed screen result, in the shape `prepare`
146
+ reads. It carries a `rejected_summary` row only when the helper produced
147
+ one. Never add a row by hand.
148
+ - `rejection` is a bounded report for the parent to quote back to the
149
+ reviewer. It holds no payload value, no unrecognized key name and no issue
150
+ message.
151
+
152
+ The report's `code` is one of five fixed values:
153
+
154
+ | `code` | When | Report fields |
155
+ |--------|------|---------------|
156
+ | `schema_validation` | The JSON parsed but breaks the reviewer return schema. This also covers a `findings` array that is absent, not an array, empty beside another fault, or over 32 entries. | `code`, `issue_count`, `issues`, `omitted` |
157
+ | `malformed_json` | stdin is not exactly one JSON document: a code fence, prose before or after it, a `<task_result>` wrapper, a trailing comma, or truncation. | `code` |
158
+ | `identity_mismatch` | The return is schema-valid but its `reviewer` is not the dispatched persona. | `code` |
159
+ | `input_oversized` | stdin is over 1 MiB. | `code` |
160
+ | `input_invalid_utf8` | stdin is not valid UTF-8. | `code` |
161
+
162
+ A `schema_validation` report lists every fault in one pass. `issue_count` is
163
+ the full count. `issues` holds at most 8 entries, each `{ path, code }`, and
164
+ `omitted` is the number left out (`issue_count` minus the entries listed).
165
+ `path` is a dotted JSON path (`findings.0.owner`, or `$` for the whole payload) and `code` is a
166
+ schema issue code such as `invalid_type`, `too_big` or `unrecognized_keys`. An
167
+ issue on a closed set (`severity`, `owner`, `autofix_class`) adds `allowed`, the
168
+ values the schema accepts. `unrecognized_keys` at a path means an unlisted key
169
+ sits at that object; the report does not name it. Remove keys the return
170
+ schema does not list.
171
+
172
+ stderr is one line: the rejected-summary row's `reason` when there is a row,
173
+ `screen rejected the reviewer return` for a schema or JSON rejection with no
174
+ row, and the size or encoding message for the other two codes.
175
+
176
+ The persisted `reason` is unchanged and path-only, for example `Rejected
177
+ persona correctness return: field findings.0.severity failed schema
178
+ validation.` An identity mismatch keeps the `reviewer` schema-validation
179
+ reason; `identity_mismatch` appears only in `rejection.code`.
180
+
181
+ How each case enters `prepare` and `finalize`. In every case the envelope's
182
+ `screen` member goes into `prepare`'s `screen_results` unchanged, with the
183
+ persona's dispatch outcome `malformed`:
184
+
185
+ | Case | `rejected_summary` row | `finalize` |
186
+ |------|------------------------|------------|
187
+ | Schema failure with 1 to 32 `findings` entries | Present | The dispatch entry carries `rejection_reason` from the row |
188
+ | Identity mismatch with 1 or more findings | Present, reason names `reviewer` | The dispatch entry carries `rejection_reason` from the row |
189
+ | Schema failure with `findings` absent, not an array, empty, or over 32 | Absent | `malformed`, no `rejection_reason` |
190
+ | Identity mismatch with empty `findings` | Absent | `malformed`, no `rejection_reason` |
191
+ | Payload is not a JSON object | Absent | `malformed`, no `rejection_reason` |
192
+ | `malformed_json`, `input_oversized`, `input_invalid_utf8` | Absent | `malformed`, no `rejection_reason` |
193
+
194
+ A row appears only when the helper could count the rejected findings, so a
195
+ missing row is not an error and is never a reason to build one.
196
+
197
+ ### Re-ask after a screen rejection
198
+
199
+ A persona gets at most 2 returns and 2 screens. After the first exit 1, the
200
+ parent may resume the same reviewer session once. It sends the `rejection`
201
+ report exactly as printed, the existing return contract, and a request for a
202
+ complete corrected payload under the same reviewer name, then screens the new
203
+ return with a fresh heredoc and a fresh delimiter. A second exit 1 is final.
204
+
205
+ - The parent never edits, trims or re-serializes a rejected payload, never
206
+ dispatches a correction, repair or replacement agent, and never reads the
207
+ helper source or bundle.
208
+ - If the harness cannot continue that session, the persona is `malformed` from
209
+ its first `screen` result, Coverage says "continuation unavailable", and no
210
+ new session is opened.
211
+ - The byte-identical retry of an exit 2 launch failure re-runs the same bytes.
212
+ It is not a re-ask and does not count toward the cap.
213
+ - One persona has one terminal result. A corrected return supersedes the
214
+ earlier one, so only the terminal `screen` result goes into `prepare` and the
215
+ superseded result is dropped. `prepare` still rejects two entries for one
216
+ persona as a duplicate; that guard backstops the rule and does not replace it.
217
+ - A re-ask never counts as coverage. A risk-critical persona whose terminal
218
+ result is `malformed` blocks a clean verdict as it does without a re-ask.
219
+
220
+ | Sequence for one persona | Terminal result | Coverage records |
221
+ |---|---|---|
222
+ | Accepted first time | The accepted result | Nothing extra |
223
+ | Rejected, then accepted | The second, accepted result | One re-ask |
224
+ | Rejected, then rejected | The second `malformed` result and its `rejection` report | One re-ask, final `malformed` |
225
+ | Rejected, continuation unavailable | The first `malformed` result | Continuation unavailable |
226
+ | Launch failure (exit 2) | `validation_unavailable` | The exit status and what was withheld |
227
+ | Never returned | `never_returned` | The task-lifecycle fact, with no `screen` call |
228
+
229
+ `malformed`, `never_returned` and `validation_unavailable` stay three distinct
230
+ dispatch outcomes through `prepare` and `finalize`. The parent invents no
231
+ finding, payload or rejected-summary row for any of them.
232
+
125
233
  ## prepare
126
234
 
127
235
  Applies the confidence gate, forms dedup candidate groups, and unions
@@ -129,10 +237,22 @@ selection-surface coverage across every screened return -- deterministic
129
237
  parent-owned bookkeeping that no longer needs model recomputation.
130
238
 
131
239
  **Input:** `{ screen_results[{reviewer, result:<screen output>}], selected_dispatches[{persona, dispatch_outcome, selection_surface?}] }`.
132
- Assemble `screen_results` from every `screen` call made in this run, and
133
- `selected_dispatches` from the Stage 3 selection record (including any
134
- persona whose dispatch never produced a screen result, so `never_returned`
135
- and `validation_unavailable` personas are represented too).
240
+ Assemble `screen_results` from each persona's terminal `screen` result, never
241
+ from every `screen` call made in this run: a persona that was re-asked
242
+ contributes its last result only, so a superseded rejection is not passed
243
+ alongside the corrected return. `prepare` rejects a second entry for one
244
+ persona as a duplicate; that guard stays. Assemble `selected_dispatches` from
245
+ the Stage 3 selection record (including any persona whose dispatch never
246
+ produced a screen result, so `never_returned` and `validation_unavailable`
247
+ personas are represented too).
248
+
249
+ `prepare` needs one `screen_results` entry for every selected dispatch. A
250
+ persona with no helper `screen` output (`never_returned`, or
251
+ `validation_unavailable` after an exit 2) gets a lifecycle entry the parent
252
+ writes from the lifecycle fact, not from a payload: `{ reviewer, result: {
253
+ dispatch_outcome, admitted_findings: [], residual_risks: [], testing_gaps: [],
254
+ harness } }`, with `dispatch_outcome` set to that outcome. It carries no
255
+ finding and no `rejected_summary`.
136
256
 
137
257
  **Output:** `{ confidence_dispositions, coverage_union, singletons, candidate_groups[{file, members[{input_id,line}]}], surviving_findings }`.
138
258
  `candidate_groups` are the file-grouped, line-sorted sets of two or more
@@ -327,7 +447,10 @@ carried state. `validator_lifecycle_results` carries one entry per
327
447
  is the model's Stage 2b requirements check: each result's `kind` routes it --
328
448
  `explicit_unmet_requirement` becomes residual actionable work and blocks a
329
449
  clean verdict; `inferred_gap` becomes advisory-only output and never blocks
330
- the verdict by itself. Neither kind becomes a finding. `parent_run_metadata`
450
+ the verdict by itself. Neither kind becomes a finding. `plan_assessment.verdict`
451
+ is exactly one of `Ready to merge`, `Ready with fixes`, or `Not ready`: it is
452
+ the report's verdict text when the run is clean, and finalize replaces it with
453
+ a fixed non-clean phrase otherwise. `parent_run_metadata`
331
454
  carries the run's own identity and mode; `validation` is the artifact
332
455
  self-validation envelope, but finalize is called before that
333
456
  [artifact validation](./synthesis-artifact-contract.md#artifact-validation)
@@ -0,0 +1,198 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "Code Review Reviewer Return",
4
+ "description": "The payload a code review sub-agent returns to the parent: exactly the subAgentReturn shape. Parent-owned fields are not part of it.",
5
+ "$ref": "#/definitions/subAgentReturn",
6
+ "definitions": {
7
+ "subAgentFinding": {
8
+ "type": "object",
9
+ "properties": {
10
+ "title": {
11
+ "type": "string",
12
+ "minLength": 1,
13
+ "maxLength": 256,
14
+ "pattern": "\\S",
15
+ "description": "Short, specific issue title. 10 words or fewer."
16
+ },
17
+ "severity": {
18
+ "type": "string",
19
+ "enum": ["P0", "P1", "P2", "P3"],
20
+ "description": "Issue severity level"
21
+ },
22
+ "file": {
23
+ "type": "string",
24
+ "minLength": 1,
25
+ "maxLength": 256,
26
+ "allOf": [
27
+ {
28
+ "type": "string",
29
+ "pattern": "\\S"
30
+ },
31
+ {
32
+ "type": "string",
33
+ "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
34
+ }
35
+ ],
36
+ "description": "Relative file path from repository root; absolute POSIX, drive-letter, and UNC paths are rejected"
37
+ },
38
+ "line": {
39
+ "type": "integer",
40
+ "exclusiveMinimum": 0,
41
+ "maximum": 9007199254740991,
42
+ "description": "Primary line number of the issue"
43
+ },
44
+ "why_it_matters": {
45
+ "type": "string",
46
+ "minLength": 1,
47
+ "maxLength": 2048,
48
+ "pattern": "\\S",
49
+ "description": "Non-empty impact and failure mode -- not 'what is wrong' but 'what breaks'"
50
+ },
51
+ "autofix_class": {
52
+ "type": "string",
53
+ "enum": ["safe_auto", "gated_auto", "manual", "advisory"],
54
+ "description": "Reviewer's conservative recommendation for how this issue should be handled after synthesis"
55
+ },
56
+ "owner": {
57
+ "type": "string",
58
+ "enum": ["review-fixer", "downstream-resolver", "human", "release"],
59
+ "description": "Who should own the next action for this finding after synthesis"
60
+ },
61
+ "requires_verification": {
62
+ "type": "boolean",
63
+ "description": "Whether any fix for this finding must be re-verified with targeted tests or a follow-up review pass"
64
+ },
65
+ "suggested_fix": {
66
+ "description": "Concrete minimal fix. Omit or null if no good fix is obvious -- a bad suggestion is worse than none.",
67
+ "anyOf": [
68
+ {
69
+ "type": "string",
70
+ "maxLength": 2048
71
+ },
72
+ {
73
+ "type": "null"
74
+ }
75
+ ]
76
+ },
77
+ "confidence": {
78
+ "type": "number",
79
+ "minimum": 0,
80
+ "maximum": 1,
81
+ "description": "Reviewer confidence in this finding, calibrated per persona"
82
+ },
83
+ "evidence": {
84
+ "minItems": 1,
85
+ "maxItems": 5,
86
+ "type": "array",
87
+ "items": {
88
+ "anyOf": [
89
+ {
90
+ "type": "string",
91
+ "minLength": 1,
92
+ "maxLength": 500,
93
+ "allOf": [
94
+ {
95
+ "type": "string",
96
+ "pattern": "\\S"
97
+ },
98
+ {
99
+ "type": "string",
100
+ "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
101
+ }
102
+ ],
103
+ "description": "Bounded code-grounded evidence; absolute POSIX, drive-letter, and UNC paths are rejected"
104
+ },
105
+ {
106
+ "type": "object",
107
+ "properties": {
108
+ "overflow": {
109
+ "type": "boolean",
110
+ "const": true,
111
+ "description": "Explicit marker that the complete evidence did not fit in one bounded entry"
112
+ },
113
+ "excerpt": {
114
+ "type": "string",
115
+ "minLength": 1,
116
+ "maxLength": 500,
117
+ "allOf": [
118
+ {
119
+ "type": "string",
120
+ "pattern": "\\S"
121
+ },
122
+ {
123
+ "type": "string",
124
+ "pattern": "^(?!\\/)(?![A-Za-z]:[\\\\/])(?!\\\\).+"
125
+ }
126
+ ],
127
+ "description": "Bounded excerpt retained when evidence must be shortened"
128
+ }
129
+ },
130
+ "required": ["overflow", "excerpt"],
131
+ "additionalProperties": false
132
+ }
133
+ ]
134
+ },
135
+ "description": "Code-grounded evidence. At least 1 and at most 5 bounded entries; split evidence across entries or use an explicit overflow marker rather than silently truncating it."
136
+ },
137
+ "pre_existing": {
138
+ "type": "boolean",
139
+ "description": "True if this issue exists in unchanged code unrelated to the current diff"
140
+ }
141
+ },
142
+ "required": [
143
+ "title",
144
+ "severity",
145
+ "file",
146
+ "line",
147
+ "why_it_matters",
148
+ "autofix_class",
149
+ "owner",
150
+ "requires_verification",
151
+ "confidence",
152
+ "evidence",
153
+ "pre_existing"
154
+ ],
155
+ "additionalProperties": false
156
+ },
157
+ "subAgentReturn": {
158
+ "type": "object",
159
+ "properties": {
160
+ "reviewer": {
161
+ "type": "string",
162
+ "minLength": 1,
163
+ "maxLength": 64,
164
+ "pattern": "\\S",
165
+ "description": "Persona name that produced this output (e.g., 'correctness', 'security')"
166
+ },
167
+ "findings": {
168
+ "maxItems": 32,
169
+ "type": "array",
170
+ "items": {
171
+ "$ref": "#/definitions/subAgentFinding"
172
+ },
173
+ "description": "List of code review findings. Empty array if no issues found."
174
+ },
175
+ "residual_risks": {
176
+ "maxItems": 64,
177
+ "type": "array",
178
+ "items": {
179
+ "type": "string",
180
+ "maxLength": 1024
181
+ },
182
+ "description": "Risks the reviewer noticed but could not confirm as findings"
183
+ },
184
+ "testing_gaps": {
185
+ "maxItems": 64,
186
+ "type": "array",
187
+ "items": {
188
+ "type": "string",
189
+ "maxLength": 1024
190
+ },
191
+ "description": "Missing test coverage the reviewer identified"
192
+ }
193
+ },
194
+ "required": ["reviewer", "findings", "residual_risks", "testing_gaps"],
195
+ "additionalProperties": false
196
+ }
197
+ }
198
+ }
@@ -18,7 +18,7 @@ You are a specialist code reviewer.
18
18
  </scope-rules>
19
19
 
20
20
  <bounded-investigation>
21
- The supplied diff is the primary source of truth. Use the supplied paths and line numbers, and read each unresolved surrounding range or symbol once. Re-read only when a concrete ambiguity remains or the file changed since the prior read. Stop and return a finding or verdict once the evidence is sufficient. If evidence cannot be obtained within this bounded pass, return an explicit blocker or residual risk instead of broadening the investigation indefinitely.
21
+ The per-path diff of the pinned scope is the primary source of truth. Read one path's diff at a time from the pinned checkout, base SHA, and head given in the review context. Do not recompute the supplied review scope: never run a diff or log across the whole range to rebuild or widen it. Use the supplied paths and line numbers, and read each unresolved surrounding range or symbol once. Re-read only when a concrete ambiguity remains or the file changed since the prior read. Stop and return a finding or verdict once the evidence is sufficient. If evidence cannot be obtained within this bounded pass, return an explicit blocker or residual risk instead of broadening the investigation indefinitely.
22
22
  </bounded-investigation>
23
23
 
24
24
  <output-contract>
@@ -26,10 +26,42 @@ Return exactly one JSON payload to the parent. The payload contains the complete
26
26
 
27
27
  Do not write any file. Do not use a Run ID or an artifact path. Persistence is owned by the parent orchestrator: it structurally validates this returned payload with the packaged validator before it parses any field, adds parent-owned provenance, and writes only conforming data. Return exactly one JSON payload; never wrap it in prose, markdown, or a parent-owned annotation. This rule is the same in every supported harness.
28
28
 
29
- The schema below defines the payload's fields and bounds. Its transport is inline for this contract; any schema metadata describing a compact return or a separate detail artifact is superseded by this output contract.
29
+ The schema below defines the payload's fields and bounds. Its transport is inline for this contract; any schema metadata describing a compact return or a separate detail artifact is superseded by this output contract. Your payload is exactly the `subAgentReturn` shape below, and `harness`, `dispatch_outcome`, and `disposition` are parent-owned, so a payload that carries any of them is rejected.
30
30
 
31
31
  {schema}
32
32
 
33
+ A populated example of a conforming payload. The `reviewer` value is the `Reviewer name` below:
34
+
35
+ <example-return>
36
+ {
37
+ "reviewer": "{reviewer_name}",
38
+ "findings": [
39
+ {
40
+ "title": "Unchecked null return from account lookup",
41
+ "severity": "P1",
42
+ "file": "src/accounts/lookup.ts",
43
+ "line": 42,
44
+ "why_it_matters": "A missing account returns null and the caller dereferences it, so the request fails with a 500 instead of a 404.",
45
+ "autofix_class": "safe_auto",
46
+ "owner": "review-fixer",
47
+ "requires_verification": false,
48
+ "confidence": 0.85,
49
+ "evidence": [
50
+ "src/accounts/lookup.ts:42 returns null when no row matches.",
51
+ "src/accounts/handler.ts:17 reads account.id without a null check."
52
+ ],
53
+ "pre_existing": false
54
+ }
55
+ ],
56
+ "residual_risks": [
57
+ "The caller in src/accounts/batch.ts may rely on the null return."
58
+ ],
59
+ "testing_gaps": [
60
+ "No test covers a lookup for an account that does not exist."
61
+ ]
62
+ }
63
+ </example-return>
64
+
33
65
  Confidence rubric (0.0-1.0 scale):
34
66
  - 0.00-0.29: Not confident / likely false positive. Do not report.
35
67
  - 0.30-0.49: Somewhat confident. Do not report -- too speculative for actionable review.
@@ -52,15 +84,18 @@ Rules:
52
84
  - You are a leaf reviewer inside an already-running systematic review workflow. Do not invoke systematic skills or agents unless this template explicitly instructs you to. Perform your analysis directly and return findings in the required output format only.
53
85
  - Every returned finding MUST include at least one evidence item grounded in the actual code. Detail fields are part of the returned payload, not a second output.
54
86
  - Evidence is bounded to at most 5 entries of at most 500 characters each. Split a longer trail across entries when it fits; otherwise retain a bounded `excerpt` with `{ "overflow": true, "excerpt": "..." }`. Never silently truncate evidence.
55
- - Finding paths MUST be repository-relative. The schema rejects absolute paths. Do not reproduce credential literals (API keys, tokens, passwords) in a finding's title, evidence, or fix; a source-level environment-variable reference (`process.env.API_KEY`, `${SECRET_TOKEN}`, and similar) is valid evidence and should be cited as such.
87
+ - Finding paths MUST be repository-relative, with the checkout prefix stripped (`src/a.ts`, never `/work/repo/src/a.ts`). The schema rejects absolute paths, and an evidence entry that begins with an absolute path is rejected too. Do not reproduce credential literals (API keys, tokens, passwords) in a finding's title, evidence, or fix; a source-level environment-variable reference (`process.env.API_KEY`, `${SECRET_TOKEN}`, and similar) is valid evidence and should be cited as such.
88
+ - `line` is one positive integer: no range, no string, not 0. `confidence` is a number from 0 to 1, not a percentage. `severity` is one of P0, P1, P2, P3. `reviewer` is the `Reviewer name` value from the review context, copied exactly.
89
+ - For a deleted file, cite the base-side path and line (the line in the file as it was at the base) and say so in the first evidence entry, for example `Deleted file: base-side path and line, src/a.ts:12.` Do not invent a head-side line.
56
90
  - The parent adds `harness`, `dispatch_outcome`, and `disposition` after validating the return. Do not invent those parent-owned fields. The parent uses only the canonical values defined by the schema (`findings`, `empty`, `malformed`, `never_returned`, `validation_unavailable` and `surviving`, `merged`, `suppressed`, `filtered`, `rejected`).
57
91
  - Set pre_existing to true ONLY for issues in unchanged code that are unrelated to this diff. If the diff makes the issue newly relevant, it is NOT pre-existing.
58
- - You are operationally read-only. You may use non-mutating inspection commands, including read-oriented `git` / `gh` commands, to gather evidence. Do not write files, edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.
92
+ - You are operationally read-only. You may use non-mutating inspection commands, including read-oriented `git` / `gh` commands, to gather evidence. Do not write files, edit project files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state. Never run a build, typecheck, or lint at any scope, and never run a test or a probe, including `bun test`, `bun run typecheck`, `bunx tsc`, any alias or wrapper of them, or a named test file whose runner expands to a suite. CI owns those gates. When a claim needs execution to confirm, report the claim and the exact command you would use in the finding's evidence or in `testing_gaps`, and the parent decides whether to run it.
59
93
  - Set `autofix_class` accurately -- not every finding is `advisory`. Use this decision guide:
60
94
  - `safe_auto`: The fix is local and deterministic — the fixer can apply it mechanically without design judgment. Examples: extracting a duplicated helper, adding a missing nil/null check, fixing an off-by-one, adding a missing test for an untested code path, removing dead code.
61
95
  - `gated_auto`: A concrete fix exists but it changes contracts, permissions, or crosses a module boundary in a way that deserves explicit approval. Examples: adding authentication to an unprotected endpoint, changing a public API response shape, switching from soft-delete to hard-delete.
62
96
  - `manual`: Actionable work that requires design decisions or cross-cutting changes. Examples: redesigning a data model, choosing between two valid architectural approaches, adding pagination to an unbounded query.
63
97
  - `advisory`: Report-only items that should not become code-fix work. Examples: noting a design asymmetry the PR improves but doesn't fully resolve, flagging a residual risk, deployment notes.
98
+ Pair `autofix_class` with `owner` the way the parent routes them: `safe_auto` with `review-fixer`; `gated_auto` or `manual` with `downstream-resolver` or `human`; `advisory` with `human` or `release`.
64
99
  Do not default to `advisory` when uncertain -- if a concrete fix is obvious, classify it as `safe_auto` or `gated_auto`.
65
100
  - Set `owner` to the default next actor for this finding: `review-fixer`, `downstream-resolver`, `human`, or `release`.
66
101
  - Set `requires_verification` to true whenever the likely fix needs targeted tests, a focused re-review, or operational validation before it should be trusted.
@@ -82,10 +117,16 @@ Selection reason: {selection_reason}
82
117
 
83
118
  Selection surface: {selection_surface}
84
119
 
85
- Changed files: {file_list}
120
+ Pinned review scope. Do not recompute the supplied review scope, and do not widen it. No diff is inlined here: read one path's diff from git as the scope rules describe.
121
+
122
+ Checkout: {checkout_path}
123
+
124
+ Base SHA: {base_sha}
125
+
126
+ Head: {head}
86
127
 
87
- Diff:
88
- {diff}
128
+ Manifest (path, status, rename source, added lines, deleted lines):
129
+ {manifest}
89
130
  </review-context>
90
131
  ```
91
132
 
@@ -95,11 +136,13 @@ Diff:
95
136
  |----------|--------|-------------|
96
137
  | `{persona_file}` | Agent markdown file content | The full persona definition (identity, failure modes, calibration, suppress conditions) |
97
138
  | `{diff_scope_rules}` | `references/diff-scope.md` content | Primary/secondary/pre-existing tier rules |
98
- | `{schema}` | `references/findings-schema.json` content | The JSON schema reviewers must conform to |
139
+ | `{schema}` | `references/reviewer-return-schema.json` content | The reviewer-rooted JSON schema view reviewers must conform to. It is generated from the full findings schema and omits the parent-owned records |
99
140
  | `{intent_summary}` | Stage 2 output | 2-3 line description of what the change is trying to accomplish |
100
141
  | `{pr_metadata}` | Stage 1 output | PR title, body, and URL when reviewing a PR. Empty string when reviewing a branch or standalone checkout |
101
- | `{file_list}` | Stage 1 output | List of changed files from the scope step |
102
- | `{diff}` | Stage 1 output | The actual diff content to review |
142
+ | `{checkout_path}` | Stage 1 pinned scope | The absolute path of the authoritative checkout. Every git command targets it |
143
+ | `{base_sha}` | Stage 1 pinned scope | The full base SHA. Old source comes from this commit |
144
+ | `{head}` | Stage 1 pinned scope | The checked-out commit SHA, or `working tree` when the checkout was dirty. It selects how a path's diff is read |
145
+ | `{manifest}` | Stage 1 pinned scope | One entry per changed path: path, status (`A`, `M`, `D`, `R`, or `T`), rename source, and added and deleted line counts |
103
146
  | `{reviewer_name}` | Stage 3 output | Persona name used in the returned `reviewer` field |
104
147
  | `{selection_reason}` | Stage 3 output | One-line reason this conditional persona was selected. Empty for core personas, which have no selection condition |
105
148
  | `{selection_surface}` | Stage 3 output | Non-empty repository-relative paths/surfaces that triggered selection. Empty for core personas. These are bounded domain hints for the reviewer, not fields of the returned payload |