pi-gauntlet 7.43.0 → 8.0.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/CHANGELOG.md +11 -0
- package/README.md +2 -2
- package/agents/plan-writer.md +4 -4
- package/agents/wave-reviewer.md +111 -0
- package/extensions/lib/phase-tracker-helpers.test.ts +7 -8
- package/extensions/lib/phase-tracker-helpers.ts +2 -5
- package/extensions/lib/plan-check.test.ts +45 -0
- package/extensions/lib/plan-check.ts +19 -7
- package/extensions/lib/telemetry-collect.test.ts +21 -1
- package/extensions/lib/telemetry-collect.ts +23 -1
- package/extensions/phase-tracker.test.ts +80 -73
- package/extensions/phase-tracker.ts +10 -13
- package/extensions/telemetry.test.ts +11 -5
- package/extensions/telemetry.ts +2 -2
- package/package.json +1 -1
- package/skills/brainstorming/reference/amendment-surface.md +10 -2
- package/skills/chase-bug/hotfix.md +1 -1
- package/skills/dispatching-parallel-agents/SKILL.md +2 -2
- package/skills/finishing-a-development-branch/reference/disposition-protocol.md +1 -1
- package/skills/gatekeep-pr/SKILL.md +1 -1
- package/skills/gatekeep-pr/reference/assessment.md +1 -1
- package/skills/gatekeep-pr/reference/sync.md +1 -1
- package/skills/loop-implementation/SKILL.md +1 -1
- package/skills/requesting-code-review/SKILL.md +9 -9
- package/skills/requesting-code-review/{code-reviewer.md → wave-reviewer.md} +2 -2
- package/skills/subagent-driven-development/SKILL.md +124 -121
- package/skills/subagent-driven-development/reference/dispatch-contract.md +10 -9
- package/skills/subagent-driven-development/reference/implement-amendments.md +4 -2
- package/skills/subagent-driven-development/stop-note.md +4 -4
- package/skills/subagent-driven-development/wave-reviewer-prompt.md +55 -0
- package/skills/verification-before-completion/reference/conformance-check.md +2 -2
- package/skills/writing-plans/SKILL.md +7 -1
- package/skills/writing-plans/reference/plan-contract.md +6 -0
- package/agents/code-reviewer.md +0 -115
- package/agents/spec-reviewer.md +0 -121
- package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +0 -67
- package/skills/subagent-driven-development/reference/fix-loop.md +0 -45
- package/skills/subagent-driven-development/spec-reviewer-prompt.md +0 -125
|
@@ -4,36 +4,37 @@ Read these schemas and carrier rules before the first implement dispatch. Keep t
|
|
|
4
4
|
|
|
5
5
|
## Schemas
|
|
6
6
|
|
|
7
|
-
Mirror each child's saved report, not an independent verdict calculation. Bound implementer reasoning to one sentence and 300 characters; keep concerns and evidence entries one line each, questions explicit, and delegated answers one paragraph. Preserve `parallelSafe` as the `Parallel-safe:` line verbatim and `trajectory.line` as the `TRAJECTORY:` line verbatim.
|
|
7
|
+
Mirror each child's saved report, not an independent verdict calculation. Bound implementer reasoning to one sentence and 300 characters; keep concerns and evidence entries one line each, questions explicit, and delegated answers one paragraph. Preserve `parallelSafe` as the `Parallel-safe:` line verbatim and `trajectory.line` as the `TRAJECTORY:` line verbatim. Use `measured` only for values an explicit `orchestrator` instruction consumes.
|
|
8
8
|
|
|
9
9
|
```ts
|
|
10
10
|
const IMPLEMENTER_STATUS_SCHEMA = {"type":"object","required":["status","reasoning"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["DONE","DONE_WITH_CONCERNS","NEEDS_CONTEXT","BLOCKED"]},"reasoning":{"type":"string","maxLength":300},"concerns":{"type":"array","items":{"type":"string"}},"question":{"type":"string"},"anchorUnreadable":{"type":"string"},"measured":{"type":"object"}},"allOf":[{"if":{"properties":{"status":{"const":"DONE_WITH_CONCERNS"}}},"then":{"required":["concerns"]}},{"if":{"properties":{"status":{"const":"NEEDS_CONTEXT"}}},"then":{"required":["question"]}}]};
|
|
11
|
-
const
|
|
12
|
-
const CODE_VERDICT_SCHEMA = {"type":"object","required":["verdict","reasoning","behaviourChange"],"additionalProperties":false,"properties":{"reasoning":{"type":"string"},"findingCount":{"type":"integer","minimum":0},"parallelSafe":{"type":"string"},"touchedTasks":{"type":"array","items":{"type":"integer"}},"trajectory":{"type":"object","required":["verdict","line"],"additionalProperties":false,"properties":{"verdict":{"type":"string","enum":["CONVERGING","DIVERGING","STAGNANT"]},"line":{"type":"string"}}},"anchorUnreadable":{"type":"string"},"verdict":{"type":"string","enum":["SHIP","FIX_FIRST","REJECT"]},"maxSeverity":{"type":"string","enum":["Critical","Moderate","Minor"]},"behaviourChange":{"type":"boolean"}}};
|
|
11
|
+
const WAVE_VERDICT_SCHEMA = {"type":"object","required":["verdict","reasoning","findingCount","findings"],"additionalProperties":false,"properties":{"reasoning":{"type":"string"},"findingCount":{"type":"integer","minimum":0},"parallelSafe":{"type":"string"},"touchedTasks":{"type":"array","items":{"type":"integer"}},"trajectory":{"type":"object","required":["verdict","line"],"additionalProperties":false,"properties":{"verdict":{"type":"string","enum":["CONVERGING","DIVERGING","STAGNANT"]},"line":{"type":"string"}}},"anchorUnreadable":{"type":"string"},"verdict":{"type":"string","enum":["SHIP","FIX_FIRST","REJECT"]},"maxSeverity":{"type":"string","enum":["Critical","Moderate","Minor"]},"findings":{"type":"object","required":["critical","moderate","minor"],"additionalProperties":false,"properties":{"critical":{"type":"integer","minimum":0},"moderate":{"type":"integer","minimum":0},"minor":{"type":"integer","minimum":0}}},"clauses":{"type":"array","items":{"type":"object","required":["clause","status","evidence"],"additionalProperties":false,"properties":{"clause":{"type":"string"},"status":{"type":"string","enum":["met","unmet","out-of-scope"]},"evidence":{"type":"string"}}}}}};
|
|
13
12
|
const ANSWER_SCHEMA = {"type":"object","required":["answer","evidence"],"additionalProperties":false,"properties":{"answer":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}}}};
|
|
14
13
|
const DIAGNOSIS_SCHEMA = {"type":"object","required":["tasks","decision","diagnostic"],"additionalProperties":false,"properties":{"tasks":{"type":"array","items":{"type":"object","required":["task","status","reportPath","diagnostic"],"additionalProperties":false,"properties":{"task":{"type":"integer"},"status":{"type":"string"},"reportPath":{"type":"string"},"patchPath":{"type":"string"},"diagnostic":{"type":"string"}}}},"decision":{"type":"string","enum":["retry","repair","stop"]},"diagnostic":{"type":"string"}}};
|
|
15
14
|
const PREPARE_SCHEMA = {"type":"object","required":["items","redraws"],"additionalProperties":false,"properties":{"items":{"type":"array","items":{"type":"object","required":["evidence","recommended","location","edit"],"additionalProperties":false,"properties":{"evidence":{"type":"string"},"recommended":{"type":"string","pattern":"^(accept|alt-[0-9]+)$"},"location":{"type":"string"},"edit":{"type":"string"}}}},"redraws":{"type":"array","items":{"type":"object","required":["location","reason"],"additionalProperties":false,"properties":{"location":{"type":"string"},"reason":{"type":"string","maxLength":300}}}}}};
|
|
16
15
|
const APPLY_SCHEMA = {"type":"object","required":["amendedSections","tasksAdded","tasksAnchorChanged","tasksRemoved","passed"],"additionalProperties":false,"properties":{"amendedSections":{"type":"array","items":{"type":"string"}},"tasksAdded":{"type":"array","items":{"type":"integer"}},"tasksAnchorChanged":{"type":"array","items":{"type":"integer"}},"tasksRemoved":{"type":"array","items":{"type":"integer"}},"passed":{"type":"boolean"},"failLines":{"type":"array","items":{"type":"string"}}}};
|
|
17
16
|
```
|
|
18
17
|
|
|
18
|
+
Keep `APPLY_SCHEMA` unchanged. Interpret `tasksAnchorChanged` as semantic obligation or work changes against the original anchored obligation text, task bodies and Tests, not line offsets or meaning-preserving rewording; reopen completed tasks only for those semantic changes. Preserve original inventory in the saved apply report through failures and idempotent retry.
|
|
19
|
+
|
|
19
20
|
## One-step carrier
|
|
20
21
|
|
|
21
|
-
Use this shape for initial
|
|
22
|
+
Use this shape for initial wave review, repair implementers and wave re-reviews, escalated/funded rounds, delegated answers and amendment workers. Set the persona and schema for each item; use `/status` for implementers and `/verdict` for reviewers with their non-clean enums. Put `output`, `outputMode` and `outputSchema` on every item, never on a `ParallelStep`. Keep `async: false` invocation-level. Set `context: "fresh"` for initial implementers and reviews, diagnosis, answers and amendments; omit context on repair, escalated and funded implementers. Omit `model` except a runtime-resolved setting or a user-named override. A reviewer `anchorUnreadable` is a hard stop; an implementer anchor failure is a failed attempt, not permission for the primary to inspect the file.
|
|
22
23
|
|
|
23
24
|
```ts
|
|
24
25
|
subagent({ async: false, context: "fresh", cwd: "<owning checkout>",
|
|
25
26
|
chain: [{ parallel: [
|
|
26
|
-
{ agent: "
|
|
27
|
-
outputMode: "file-only", outputSchema:
|
|
27
|
+
{ agent: "wave-reviewer", output: "<REPORT_DIR>/wave<w>-review<k>.md",
|
|
28
|
+
outputMode: "file-only", outputSchema: WAVE_VERDICT_SCHEMA,
|
|
28
29
|
task: "planPath: <absolute plan>; anchors: <wave task prefixes>; Spec: <absolute home spec>; BASE_SHA: <WAVE_BASE_SHA>; HEAD_SHA: WORKTREE; SCOPED_TEST_COMMANDS: <manifest union>" }
|
|
29
30
|
], stopOn: { path: "/verdict", in: ["FIX_FIRST", "REJECT"] } }]
|
|
30
31
|
})
|
|
31
32
|
```
|
|
32
33
|
|
|
33
|
-
For answer/evidence, preparation and apply results, retain their approved schemas without adding a status field. Use carrier-only `stopOn: { path: "/status", in: ["BLOCKED"] }`: an absent pointer does not match, but the presence of stopOn exposes successful `## Outputs` JSON. Save each report under `REPORT_DIR`. Give delegated
|
|
34
|
+
For answer/evidence, preparation and apply results, retain their approved schemas without adding a status field. Use carrier-only `stopOn: { path: "/status", in: ["BLOCKED"] }`: an absent pointer does not match, but the presence of stopOn exposes successful `## Outputs` JSON. Save each report under `REPORT_DIR`. Give delegated source lookups the question, source artifact paths, owning checkout, and documented lookup ordering; let the child read source, provenance, task contents or current grants. Consume only `answer` and `evidence`. A delegated failure stops; never recursively diagnose delegated failures.
|
|
34
35
|
|
|
35
36
|
## Anchored payload
|
|
36
37
|
|
|
37
|
-
Pass `planPath: <absolute plan path>`, `anchor: "### Task N:"` or `anchors: [<exact prefixes>]`, and `Spec: <absolute authoritative home spec path>` to every implementer
|
|
38
|
+
Pass `planPath: <absolute plan path>`, `anchor: "### Task N:"` or `anchors: [<exact prefixes>]`, and `Spec: <absolute authoritative home spec path>` to every implementer and wave-reviewer. `### Task 4:` never matches `### Task 40:`; end each selected section at `^#{2,3}\s`. Children read the union of selected sections, `Spec:`, `Files:`, `Tests:`, `Rules:` and `Leg:` themselves. Combine task Rules with that leg's Rules in home `## Legs`; absent Leg uses the first `### Leg:`. Resolve rules in the owning checkout. Pass isolated implementers only their own task's manifest `tests` as `SCOPED_TEST_COMMANDS`, or `none` when empty, including isolated repairs. Give the integrated gate, in-place repairs and wave reviews the wave union; give initial in-place implementers that union too. Preserve command strings verbatim; keep dispatch-supplied commands independent of the Tests metadata children read.
|
|
38
39
|
|
|
39
|
-
Forward dependent context as the prior status line plus report path. Put the saved prior report path under `## Previous review report (re-review trigger)`; require the child to read it and apply the existing trajectory block.
|
|
40
|
+
Forward dependent context as the prior status line plus report path. Put the saved prior report path under `## Previous review report (re-review trigger)`; require the child to read it and apply the existing trajectory block. Read report findings only under the bounded direct-read rule in SKILL.md; never dispatch a child to relay reports. Keep binary delta bytes child-owned.
|
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
Read [amendment-surface.md](../../brainstorming/reference/amendment-surface.md) for the existing gate and Standing grants. Apply this delegation only during implement; keep the planning caller unchanged. Use the one-step carrier and schemas in [dispatch-contract.md](dispatch-contract.md) for every child, with saved output, file-only, fresh context and foreground execution.
|
|
4
4
|
|
|
5
|
-
1. Dispatch `plan-writer` with `Amend-prepare:`, the five absolute paths (worktree, approved spec, plan, plan skill and plan contract) and the evidence already in context: plan_check FAIL lines, structured concerns/question or measured baseline rows. Preparation writes nothing. Require `{ items: [{ evidence, recommended: "accept" | "alt-<n>", location: "<spec section>", edit: string }], redraws: [{ location: "<spec section>", reason: string (max 300 characters) }] }`; keep each edit one paragraph. Keep the existing menu spelling `alt-n` for a named alternative; encode the selected number as `alt-<n>` in JSON. Require both items and redraws arrays, including empty arrays; put redraws only in redraws, never items. Fail malformed preparation output.
|
|
5
|
+
1. Dispatch `plan-writer` with `Amend-prepare:`, the five absolute paths (worktree, approved spec, plan, plan skill and plan contract) and the evidence already in context: plan_check FAIL lines, structured concerns/question or measured baseline rows. Include the literal sentence `Do not edit any file.` in the `Amend-prepare:` task text. Preparation writes nothing. Require `{ items: [{ evidence, recommended: "accept" | "alt-<n>", location: "<spec section>", edit: string }], redraws: [{ location: "<spec section>", reason: string (max 300 characters) }] }`; keep each edit one paragraph. Keep the existing menu spelling `alt-n` for a named alternative; encode the selected number as `alt-<n>` in JSON. Require both items and redraws arrays, including empty arrays; put redraws only in redraws, never items. Fail malformed preparation output.
|
|
6
6
|
2. Inspect structured redraws first. A nonempty array holds the whole batch at the redraw gate before grant evaluation or applying any sibling item, for redraw-only and mixed batches alike. Never open the preparation report to discover redraws. With no redraws, delegate reading the current `Amend-grant:` and Value decoding through the answer/evidence carrier. Preserve the surface's grant predicate: malformed -> stop and quote; absent, none or no permission -> the existing human menu and escalation gate. Stop on changed problem statement or a component added, removed or re-bounded.
|
|
7
|
-
3. With amend permission, apply the recommended choice without reviewer, menu or confirmation turns; pass granted items verbatim to `plan-writer` under `Amend-apply:` plus the existing `Amend:` entry and parent-supplied `In-flight:` paths from `status --porcelain`, including staged in-place repair deliverables. Preserve Baseline ownership, protected-path and dirty-baseline exits; delegate attribution reads and human wording instead of loading documents in the primary. Authorize only the named spec sections and
|
|
7
|
+
3. With amend permission, apply the recommended choice without reviewer, menu or confirmation turns; pass granted items verbatim to `plan-writer` under `Amend-apply:` plus the existing `Amend:` entry and parent-supplied `In-flight:` paths from `status --porcelain`, including staged in-place repair deliverables. Preserve Baseline ownership, protected-path and dirty-baseline exits; delegate attribution reads and human wording instead of loading documents in the primary. Authorize only the named spec sections and local patches to affected task entries, coverage and shifted anchors; preserve unaffected ids, titles, wave order, state and evidence. Use the implement-only historical Baseline policy, not wholesale regeneration. Admit declared in-flight repairs, including staged source, for maintenance requiring no execution; preserve staged repairs rather than committing, restoring or discarding them merely to plan. For necessary runs require an identified execution tree and nonzero executed-test count; stop on unidentified dirt, contamination or moved test revision. Before the first apply, require original task numbers, titles, spec anchors, and wave positions in the existing saved apply report; retain that original inventory on every return, including failures. Also capture anchored obligation text, task bodies and Tests. Add no sidecar.
|
|
8
8
|
4. Consume the unchanged apply result `{ amendedSections: string[], tasksAdded: number[], tasksAnchorChanged: number[], tasksRemoved: number[], passed: boolean, failLines?: string[] }`. On `passed: false`, retry once in a fresh child with failLines as the rule and `previousApplyReport` set to the first apply report path. Require the retry to read original inventory, apply granted edits idempotently without duplicates, and compute deltas against that original inventory rather than the already-mutated plan. Missing original inventory fails the retry. Escalate a second failure; never repeat granted edits blindly.
|
|
9
|
+
Match retained failures by failing command, assertion or path plus corresponding repair evidence, never task membership. Preserve failed revision/output and resolving evidence; route outstanding repairs to their existing task gate loop and keep unrelated regressions substantive blockers. Decode the standing grant at each batch boundary. Repeated authorized intermediate evidence is neither new consent nor a refresh trigger; keep budget-only, malformed-grant and redraw stops and the existing funding unchanged.
|
|
10
|
+
|
|
9
11
|
5. After child success, run parent `plan_check({ planPath })`. Reconcile only after parent PASS: replace the manifest; use tracker update and `add` for tasksAdded, reopen completed tasksAnchorChanged as `in_progress`, and handle tasksRemoved through the surface's existing path. Print `amended the spec: <title> - <what>` from structured item location/edit observations, and make the existing single `amend:` audit commit. Keep the parent from opening spec, plan or reports. Persist measured values from explicit orchestrator instructions through this same path.
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# Stop note (subagent-driven-development companion)
|
|
2
2
|
|
|
3
|
-
For a `NEEDS_CONTEXT`/`BLOCKED` fact ask, dispatch a delegated answer/evidence child to search the locations documented by the spec, plan, or repo: one bounded lookup per location in documented order, stopping at the first hit. Record each lookup and result, including earlier misses; consume the compact answer/evidence and re-dispatch with the found result.
|
|
3
|
+
For a `NEEDS_CONTEXT`/`BLOCKED` fact ask, dispatch a delegated answer/evidence child to search the locations documented by the spec, plan, or repo: one bounded lookup per location in documented order, stopping at the first hit. Record each lookup and result, including earlier misses; consume the compact answer/evidence and re-dispatch with the found result. Keep source reads delegated; use the bounded direct-report read rule in SKILL.md for child reports. Stop on a delegated failure.
|
|
4
4
|
|
|
5
|
-
Emit when no escalation model resolves, the escalated dispatch errors, its one escalated round
|
|
5
|
+
Emit when no escalation model resolves, the escalated dispatch errors, its one escalated round and any funded rounds fail (see `SKILL.md` "The Wave Loop"), or a `NEEDS_CONTEXT`/`BLOCKED` fact ask exhausts documented locations, needs credentials for a remaining location, or lacks its named lookup tool; an unavailable `gauntlet_setting` tool also ends in this stop note. Inline in the reply; the turn ends; phase stays `implement`, the task stays `in_progress`; no further tasks start. Emit one note per stalled task, after the current batch returns.
|
|
6
6
|
|
|
7
7
|
## Template
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Write the note from structured fields, bounded report findings and lookup observations. Never dispatch a child to relay a report. While a budget token exists, put `budget: <spent> of <N> spent` after `Problem:` and any `Searched:` lines and before findings, including zero-spent stops. On unrecoverable resume use `budget: <N> of <N> spent (not recovered on resume)`. Omit budget without a token.
|
|
10
10
|
|
|
11
11
|
Read and apply [menu-layout](../brainstorming/reference/menu-layout.md). Start the message with `gauntlet: question` alone on the first output line, followed by a newline before the stop note; this is an implementation decision, not a done or stuck outcome.
|
|
12
12
|
|
|
@@ -30,7 +30,7 @@ Recommendation: <option> - <why>
|
|
|
30
30
|
|
|
31
31
|
## Rules
|
|
32
32
|
|
|
33
|
-
- End every note with `Recommendation: <option> - <why>`, or `Recommendation: none - <why>` when no named change is recommended. Apply [
|
|
33
|
+
- End every note with `Recommendation: <option> - <why>`, or `Recommendation: none - <why>` when no named change is recommended. Apply [takeable-decision ladder](./SKILL.md#escalation-and-funding) before emitting an execution decision note.
|
|
34
34
|
- Bracketed header clause only when an escalated round actually ran; omit it when no model was resolvable or the dispatch errored.
|
|
35
35
|
- For review stalls, quote only residual issues from the final review report; do not summarize history.
|
|
36
36
|
- For fact asks, put one `Searched: <where> - <result>` line per lookup directly under `Problem:`, in lookup order. For an unavailable named tool, write `Searched: <tool> - not available`. Omit `Searched:` for decisions, including extra-round approval.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Integrated Wave Reviewer Prompt Template
|
|
2
|
+
|
|
3
|
+
Dispatch one wave-reviewer after the wave gate is green, including doc-only waves.
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
planPath: <absolute plan>
|
|
7
|
+
anchor: ### Task N:
|
|
8
|
+
anchors: <use instead of anchor for the wave union>
|
|
9
|
+
Spec: <absolute authoritative home spec>
|
|
10
|
+
Leg: <owning leg>
|
|
11
|
+
Rules: <combined task/leg Rules resolved in owning checkout>
|
|
12
|
+
Implementer reports: <saved paths>
|
|
13
|
+
BASE_SHA: <fixed WAVE_BASE_SHA>
|
|
14
|
+
HEAD_SHA: WORKTREE
|
|
15
|
+
SCOPED_TEST_COMMANDS: <wave manifest tests union; none for docs>
|
|
16
|
+
|
|
17
|
+
Read selected task sections and their Spec:, Files:, Tests: and Rules: yourself. Treat the spec as the sole authority. Review the integrated whole diff, including additions. Return clause rows met | unmet | out-of-scope with evidence before findings; any unmet or out-of-scope yields at least FIX_FIRST. Emit structured output matching WAVE_VERDICT_SCHEMA and the saved report. On unreadable anchors return REJECT with anchorUnreadable and Reasoning: anchor unreadable: <path>#<anchor>.
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
For re-reviews append the prior saved path under `## Previous review report (re-review trigger)` and `## Fix delta` with tree-before/tree-after object IDs. Run `git diff --binary <tree-before> <tree-after>` in the integrated checkout yourself to inspect only the repair delta; retain BASE_SHA for the whole-wave review. Never substitute a worker commit range or a working-tree diff for the Fix delta tree pair.
|
|
21
|
+
|
|
22
|
+
## Re-review: trajectory verdict
|
|
23
|
+
|
|
24
|
+
Include the following in the reviewer's task text on every re-review, after
|
|
25
|
+
the prior review report path under a
|
|
26
|
+
`## Previous review report (re-review trigger)` heading.
|
|
27
|
+
Read the saved report yourself; retain the supplied `## Fix delta` block:
|
|
28
|
+
|
|
29
|
+
If your task contains a "Previous review report (re-review trigger)" section
|
|
30
|
+
and you found issues, append exactly one more line after the verdict footer; make it the true final line of the report:
|
|
31
|
+
|
|
32
|
+
TRAJECTORY: CONVERGING (<n_prev> -> <n_now>, max severity <X>)
|
|
33
|
+
TRAJECTORY: DIVERGING
|
|
34
|
+
TRAJECTORY: STAGNANT (repeat of: <finding>)
|
|
35
|
+
|
|
36
|
+
Pick the first label that applies, in this order:
|
|
37
|
+
|
|
38
|
+
1. STAGNANT: a previous Critical or Moderate finding survives materially unchanged - name it.
|
|
39
|
+
(e.g. the same unchecked error path flagged last round is still unchecked)
|
|
40
|
+
2. DIVERGING: <n_now> >= <n_prev>, or the fix introduced a new Critical or Moderate finding.
|
|
41
|
+
(e.g. 3 findings fixed but the fix broke an import: DIVERGING, not CONVERGING)
|
|
42
|
+
3. CONVERGING: otherwise - the Critical/Moderate count fell, no new Critical or
|
|
43
|
+
Moderate appeared, and every surviving Critical or Moderate was materially improved.
|
|
44
|
+
|
|
45
|
+
<n_prev>/<n_now> count Critical and Moderate findings only; Minors - ride-along
|
|
46
|
+
Minors declined or unchanged, and `(outside fix delta)` downgrades alike - never
|
|
47
|
+
move the `TRAJECTORY:` line. <X> is the highest remaining severity. For this line the severity set is
|
|
48
|
+
exactly Critical/Moderate/Minor, regardless of the vocabulary used elsewhere in
|
|
49
|
+
your report.
|
|
50
|
+
|
|
51
|
+
The orchestrator dispatches one extra fix only when this line says CONVERGING
|
|
52
|
+
without "max severity Critical" - be accurate, not generous.
|
|
53
|
+
|
|
54
|
+
If you found no issues, report success as usual and omit this line.
|
|
55
|
+
First reviews (no previous-report section) omit this line.
|
|
@@ -193,8 +193,8 @@ Per round:
|
|
|
193
193
|
**Convergence** — runs after R0 `CONFORMS` and after every `CONFORMS` re-audit. `r0-head` is HEAD when the loop was entered (the R0 dispatch, or the finish-time `fix-now` entry) - the parent of the oldest `conformance fix` commit; `audited-base` stays the last audit's HEAD SHA.
|
|
194
194
|
|
|
195
195
|
a. Run the full plan-header `Verification` set once as `(cd "<conformance-worktree>" && <command>)` (ad-hoc: the project's canonical test command). After R0 `CONFORMS` with no round run, the pre-R0 full run counts.
|
|
196
|
-
b. Dispatch `
|
|
197
|
-
c. Repair items = every failing command from a + every Critical/Moderate finding from b (
|
|
196
|
+
b. Dispatch `wave-reviewer` directly (foreground, `async: false`, `cwd` = the conformance worktree, `SCOPED_TEST_COMMANDS: none`) over `git diff <r0-head>..HEAD`; never via `/skill:requesting-code-review`. An empty diff is nothing to review - no dispatch.
|
|
197
|
+
c. Repair items = every failing command from a + every Critical/Moderate finding from b (the re-audit is their origin check). None → write the closure block; done. Any at the cap → escalate per step 6 with the test/CR trail (an explicit human approval re-enters via `grant_fix_rounds`, as step 6 describes). Any under the cap → re-enter step 2 as a one-task `tasks` wave: one `implementer` whose task is every repair item verbatim (ownership boundary = the files in `git diff <r0-head>..HEAD`, the CR findings' `touched-files`, and the files each failing command's output names, `SCOPED_TEST_COMMANDS: none`, no `Gn` tracker task, no gap selection), integrate as one `conformance fix CR`, re-audit, then Convergence again. That wave counts against `maxFixRounds`. Later Convergence CRs keep the same `<r0-head>..HEAD` range.
|
|
198
198
|
|
|
199
199
|
`conformance fix CR` is not a gap fix: it is absent from the `auto-applied fix commits` index and has no `revert conformance fix Gn` action at the finish gate.
|
|
200
200
|
|
|
@@ -200,7 +200,7 @@ Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track
|
|
|
200
200
|
| `merge: unresolved` | Merge the named base and resolve the listed files; preserve the original commits. |
|
|
201
201
|
| `sync: unresolved - <files>` | Run `git rebase --no-rebase-merges origin/<base>` and resolve `<files>`. |
|
|
202
202
|
| `Member replay: #<N> unresolved - <files>` | Replay #<N> onto home and resolve `<files>`. |
|
|
203
|
-
Place a rebase-form Task 1 alone in Wave 1 marked `in-place`; keep the merge-form Task 1 as an ordinary wave task.
|
|
203
|
+
Place a rebase-form Task 1 alone in Wave 1 marked `in-place`; keep the merge-form Task 1 as an ordinary wave task. In both forms, keep Task 1 alone in Wave 1 and place every thread fix task in Wave 2 or later, behind Task 1.
|
|
204
204
|
For both rebase forms, consume every `pending` member in listed order, run `git update-ref refs/gauntlet/rework-base/pr-<home> HEAD`, and persist `Rework base: <sha>` plus final `Member replay:` outcomes through the existing [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) before finishing. Use [pr-head's sync and helper contract](../using-git-worktrees/reference/pr-head.md), including replay commands, conflict checks, continuation and abort assertions; do not duplicate it. Make each `fix` thread exactly one task whose title carries that thread id. Name the thread's request in its `Tests:` block through the scoped command and `via:` seam that exercises it. Keep `keep open` and `decline: <reason>` as recorded dispositions, not repair tasks. Apply the existing file-disjoint wave, spec-anchor, baseline and checker rules to these tasks without changing executor or spec-commit mechanics.
|
|
205
205
|
|
|
206
206
|
```markdown
|
|
@@ -294,6 +294,11 @@ If a decision is genuinely open, put it in an explicit **Open Questions** sectio
|
|
|
294
294
|
|
|
295
295
|
The plan-writer runs Baseline, the deterministic checker, then the judgment checks before replying.
|
|
296
296
|
|
|
297
|
+
- **Implement-local Baseline (`Amend-apply:` only).** Use this branch instead of ordinary Baseline steps 1-4 during implement; keep initial planning and ordinary Findings/Amend below unchanged. Write `**Baseline policy:** implement-local` only in this mode. Preserve original per-leg declarations and valid unchanged command bullets at their measured revisions, including derived-pass, skipped and artifact suffixes; perform no endpoint-tree equivalence or rerun-all sweep. Capture original evidence in the saved apply report before editing. For retained skipped evidence whose anchors now exist, copy its exact leg, command and bullet value into the existing provenance note as `Baseline provenance: retained <leg or home> | <exact command> | <exact baseline value>`; require matching original inventory, never invent a skip or execution.
|
|
298
|
+
1. Inventory status using ordinary step 1 before maintenance and before/after each run. Admit only explicit parent `In-flight:` paths, spec/plan and eligible recorded artifacts. Unknown dirty paths block. With no test execution needed, preserve declared staged repairs without committing, restoring or discarding them.
|
|
299
|
+
2. Run only changed/added commands or missing/invalid evidence, exact or documented derived scoped commands by the ordinary selector procedure. Count already-created anchors as existing; create new skipped evidence only when all anchors are truly absent at the execution revision. Retained historical skips describe their recorded revision, not current existence.
|
|
300
|
+
3. Require an identified execution tree: current or retained implementation with revision and admitted changes identified, or an existing parent-owned committed snapshot. Never label a dirty run as clean HEAD. Stop on unidentified trees; create no snapshot, source edit or restoration yourself. Record leg, checkout, revision, admitted changes, exact/derived command, exit and nonzero executed-test count in the existing provenance and saved report. Exit 0 with zero tests fails. Apply ordinary contamination/artifact rules, stop on unknown dirty paths or moved test revision, and retain failed revision/output plus subsequent resolving evidence.
|
|
301
|
+
4. Match retained failures by failing command, assertion or path plus corresponding repair evidence, never task membership. Return outstanding repairs to the existing task gate loop; keep unrelated regressions substantive blockers. Preserve failure history in the report while removing only resolved Open Questions rows. Keep parent stamp, integrated gate, review and final verification mandatory. Explicit `Findings: rerun baseline` overrides this branch: execute all commands, remove the implement-local header and restore ordinary uniform evidence; preserve the historical inventory in the report.
|
|
297
302
|
- **Baseline.** Execute the numbered procedure below for task `Tests:` commands only; leave header `**Verification:**` to verify. Never author baseline evidence without execution or a recorded tree-equivalence.
|
|
298
303
|
1. Read provenance: `BASE=$(git -C "<abs worktree path>" rev-parse --short HEAD)` and `git -C "<abs worktree path>" status --porcelain --untracked-files=all`. Match every `XY <path>` entry (including `??`) against the worktree-relative plan and spec paths, plus only the parent-supplied `In-flight:` paths on an `Amend:` re-dispatch; never infer that set. Also allow untracked paths already recorded in existing baseline bullets' ` - artifacts:` suffixes in the plan at the plan path, excluding every plan `Create:` or `Test:` path. Keep those suffixes on retained bullets. Any other entry blocks all commands: collect `- Baseline: worktree dirty on <BASE>: <paths>`. Allowed in-flight paths outside the spec and plan directories are source edits: collect `- Baseline: in-flight source edits on <BASE>: <paths>` and run nothing. Allow doc-only workflow edits. For plain jj (no `.git`, VCS kind `jj`), use `BASE=$(jj -R "<abs worktree path>" log -r @- --no-graph -T 'commit_id.short()')` and `jj -R "<abs worktree path>" diff --summary`; classify one-letter status and relative paths identically (`A` includes new files). Never revert or clean anything. Record a short baseline provenance note with the initial per-file inventory, BASE, and which exact paths were admitted before running commands; retain it even when a later run is contaminated or blocked.
|
|
299
304
|
2. On Findings/Amend, before any command runs, use step 1's BASE and prove endpoint-tree equivalence once per distinct recorded SHA in the plan. Derive `<spec dir>` and `<plan dir>` as the worktree-relative directories of the dispatched spec and plan paths. Run `git -C "<abs worktree path>" diff --quiet <recorded> <BASE> -- . ':!<spec dir>/' ':!<plan dir>/'`; only exit 0 proves equivalence. Keep the trailing `/` directory boundaries. For plain jj, run `jj -R "<abs worktree path>" diff --from <recorded> --to <BASE> --summary`: require exit 0 and empty stdout after dropping entries whose paths all lie under `<spec dir>/` or `<plan dir>/`. Reject entries that do not parse as `<status> <path>`; exclude stderr from filtered evidence. Prove every recorded SHA before rewriting any bullet; retention is all-or-nothing.
|
|
@@ -322,6 +327,7 @@ The plan-writer runs Baseline, the deterministic checker, then the judgment chec
|
|
|
322
327
|
- Under each contamination/global row indent `blocked: Task M `<command>`` for every command it blocked. Keep failure output verbatim, including `TODO` or `etc.` inside valid continuation fences; only those evidence fences are exempt from placeholder scanning.
|
|
323
328
|
|
|
324
329
|
With substantive rows remaining reply `OPEN QUESTIONS <abs plan path>` immediately; do not spend repair rounds on them.
|
|
330
|
+
- **Implement-local patch (`Amend-apply:` only).** Capture original task numbers, titles, anchors, anchored obligation text, task bodies, Tests and wave positions in the existing saved apply report before editing; retain it on failure and read it from `previousApplyReport` on retry. Patch affected entries, coverage and shifted anchors only, preserving unaffected text, state and evidence. Compare semantic obligations/work, ignoring line shifts and meaning-preserving rewording; return no completed task in `tasksAnchorChanged` for a pure offset move. Keep full-file write mechanics, idempotent retry, missing-original-inventory failure and parent stamping.
|
|
325
331
|
- **Deterministic checker.** Run `plan_check({ planPath: "<abs plan path>" })` on the saved plan. Repair every `baseline-line` finding (missing, malformed, misplaced, invalid skipped/pass via or differing SHAs) and substantive baseline `open-questions` finding only through Baseline, never by authoring `pass`/`skipped` evidence or deleting/rewording a row. Normalize `## Open Questions malformed` into `- ` rows without changing substantive text. Fix every other finding yourself and rerun. With substantive rows remaining, reply `OPEN QUESTIONS <abs plan path>` without a passing check. Apply the 3-round budget only to ordinary findings: convert a finding surviving 3 rounds to an Open Questions row and stop. A child pass validates; the parent's call writes the execution stamp. Omit an empty questions section and reply `PLAN WRITTEN <abs plan path>` after all checks pass. Findings are defined in [reference/plan-contract.md](reference/plan-contract.md).
|
|
326
332
|
- **Contract decisions.** For every task crossing a boundary the spec leaves unsettled (a host-forwarded value, a caller's error type), derive the decision from code, the harness contract, or a sibling task. State `Decision: <what> - <caller/contract/sibling task cited>` in the task text. Ask only when the spec is silent or wrong and no source settles it; put that unresolved contract in Open Questions. Add no per-task `Decisions:` field.
|
|
327
333
|
- **Code-vs-anchor sanity.** For each task-owned requirement row, re-read the anchored spec lines and confirm the owner tasks' bodies do what they say - mechanism present, not just the quoted literal. For each `Verification` row, confirm the header command exercises the anchored requirement. Fix the task, don't annotate.
|
|
@@ -40,6 +40,12 @@ Baseline forms (`baseline-line`): `- baseline: <sha> pass`, `- baseline: <sha> p
|
|
|
40
40
|
|
|
41
41
|
Commands are written repo-relative and run in the worktree via `(cd "<abs worktree path>" && <command>)` - the checker never runs them; Baseline and the executor do. Each command is split into segments on `&&`, `||`, `;`, `|`; every segment must contain, as a whitespace-delimited token, a `Test:` path of the same task (the path alone, or followed by `::`, `#`, or `:` and a filter). A `Test:` value containing `*`, `?`, `[` or ending in `/` never anchors; any other argument token with those shapes is a broadening selector and fails. `cd `, `sh -c`, `bash -c`, `eval `, `$(` are unsupported. Each `Test:` path must exist or be a `Create:` path of some task. A segment equal to a header `**Verification:**` or `**Happy path:**` segment is a full-suite command and fails. Runners with no file-addressable form are out of scope (`go test ./pkg -run X`, `mvn -Dtest=`).
|
|
42
42
|
|
|
43
|
+
### Implement-only historical evidence
|
|
44
|
+
|
|
45
|
+
Write the optional header `**Baseline policy:** implement-local` only from implement-phase `Amend-apply:`. Reject duplicate, misplaced, empty or unknown policy values. Absence preserves ordinary uniform-SHA checks. In local mode retain one valid original `Baseline <repo>: <sha>` declaration per admitted leg; allow genuinely evidenced mixed per-command revisions within that leg without implying freshness at current HEAD. Keep syntax, adjacency, leg ownership and anchor checks unchanged.
|
|
46
|
+
|
|
47
|
+
Count an existing Test path still declared Create as existing for new derived evidence; create new skipped evidence only for truly absent all-created anchors. Retain historical skipped evidence even when its anchors now exist only with matching original evidence in the saved apply inventory and existing provenance note: `Baseline provenance: retained <leg or home> | <exact command> | <exact baseline value>`. The value is the whole text after `- baseline: `, including suffixes. The checker matches this note by leg, exact command and value; the writer owns validating the historical observation against the original inventory. Preserve pass-via and artifact suffixes byte-identically on retention. Explicit full refresh executes all commands and restores ordinary uniform evidence; never infer mode from mixed SHAs.
|
|
48
|
+
|
|
43
49
|
## Open Questions (`open-questions`)
|
|
44
50
|
|
|
45
51
|
Bound the section from `## Open Questions` to the next `## ` heading or EOF. Use `- ` rows with indented continuations (`ran:`, `blocked:`, fenced output). The empty sentinel is exactly one line `- none`; an absent section also passes. Every substantive row produces one finding quoting its first line. Prose and tables are malformed: normalize them to rows without changing substantive content.
|
package/agents/code-reviewer.md
DELETED
|
@@ -1,115 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: code-reviewer
|
|
3
|
-
description: Production-readiness code review with prioritized findings (Critical and Moderate block merge, Minor is a nit). Read-only — does not edit.
|
|
4
|
-
tools: read, grep, find, ls, bash
|
|
5
|
-
defaultContext: fresh
|
|
6
|
-
inheritProjectContext: true
|
|
7
|
-
inheritSkills: false
|
|
8
|
-
systemPromptMode: replace
|
|
9
|
-
completionGuard: false
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
You are a code reviewer. You find issues before they ship. You **do not edit code**. You may run the verification commands your dispatch supplies (`SCOPED_TEST_COMMANDS`, read-only) and quote their actual output. Run ONLY those. Never run a repo-wide suite, linter, or type-checker on your own initiative. Dispatch carries no commands: say so in your report; run nothing.
|
|
13
|
-
|
|
14
|
-
A dispatch that carries `Rules:` lines or a `Leg:` value: Read the combined spec/task `Rules:` files before acting, resolve repo-relative rules in that leg's checkout, read the home spec at its supplied absolute path, review the caller's mapped original AC and leg, and keep git operations and supplied scoped commands in that checkout. Report a rules file you cannot read instead of inventing its contents. A dispatch without them: review as usual and write nothing about rules.
|
|
15
|
-
|
|
16
|
-
## Anchored tasks
|
|
17
|
-
|
|
18
|
-
When the task carries `planPath` and `anchor`/`anchors`, read the task section there first and treat it as the task text; otherwise the task text is inline as before. Match the exact heading-line prefix with number plus colon: `### Task 4:` never matches `### Task 40:`. End each section at the next line matching `^#{2,3}\s`; for an anchor list use the union of those sections.
|
|
19
|
-
|
|
20
|
-
Read each selected task's `Spec:` anchors, `Files:` and `Tests:` yourself. Derive the combined `Rules:` from the task plus its leg's entry in the home spec's `## Legs`: use the task's explicit `Leg:`, otherwise the first `### Leg:` entry. Resolve Rules in the supplied worker checkout. Read the authoritative spec at the supplied absolute path and any implementer or previous review report by path. Keep dispatch-supplied `SCOPED_TEST_COMMANDS` independent of task Tests metadata.
|
|
21
|
-
|
|
22
|
-
On an unreadable plan or anchor, stop with `REJECT` in both report and structured output, set `anchorUnreadable: "<path>#<anchor>"`, and include `Reasoning: anchor unreadable: <path>#<anchor>` in the report. Do not ask the parent to read it or review the section as successful. Retain the required `Behaviour-change:` footer.
|
|
23
|
-
|
|
24
|
-
## Structured output
|
|
25
|
-
|
|
26
|
-
Keep the existing report layout. When structured output is requested, emit the following contract; its verdict mirrors the report, not a separate assessment:
|
|
27
|
-
|
|
28
|
-
`{ verdict: SHIP|FIX_FIRST|REJECT, reasoning: string (one sentence), maxSeverity?: Critical|Moderate|Minor, findingCount?: number, behaviourChange: boolean (every report, mirrors `Behaviour-change:`), parallelSafe?: string, touchedTasks?: number[], trajectory?: { verdict, line }, anchorUnreadable?: string }`.
|
|
29
|
-
|
|
30
|
-
Map `Behaviour-change: yes` to true and `no` to false on every report. Populate applicable severity, finding count and touched task numbers from the report; copy `Parallel-safe:` and `TRAJECTORY:` lines verbatim, with trajectory.verdict set to CONVERGING, DIVERGING or STAGNANT.
|
|
31
|
-
|
|
32
|
-
## Review priorities, in order
|
|
33
|
-
|
|
34
|
-
1. **Correctness** — Does the change do what it claims? Are edge cases handled? Off-by-one, null/undefined, empty input, concurrency.
|
|
35
|
-
2. **Tests** — Is the new behavior covered? Are tests meaningful, or do they only assert type shape? Name any missing behavior worth a test concretely; never a reflexive "add edge cases". Then check added **and changed** tests for economy - each of these is a `[Minor]` finding the implementer may decline with a reason, except the last:
|
|
36
|
-
- Read the supplied spec's `## Acceptance criteria` and `## Design` sections first, from the requirements block or its named spec path. Report a test proving no observable those sections name as `[Moderate]` `delete:`, overriding the Minor default, and cite the spec section searched. Exempt a test only on a justification citing the approved acceptance row or Design clause it proves, including a `Keep:` preservation obligation or edge rule; treat summary-only behavior as uncommitted and route genuinely new behavior through the existing scope decision. Preserve the single smoke test or `assert`-based self-check exemption. With no spec supplied, report `unverified: no spec supplied`, keep the existing economy checks, and never treat the missing spec as an empty observable set.
|
|
37
|
-
- several new tests repeat one setup and operation with the assertions split across them -> `shrink:` to one test with the assertions together.
|
|
38
|
-
- a new test repeats an existing test's assertions -> `delete:`.
|
|
39
|
-
- equivalent cases written as separate tests -> `shrink:` to one table with named rows.
|
|
40
|
-
- input or setup larger than the tested behavior and its contract need -> `shrink:` naming the fields or records the path reads. A mock of an external API response keeps that response's shape; a field the contract requires is never oversized.
|
|
41
|
-
- an expensive artifact (parsed file, built document, loaded corpus) rebuilt per test -> `shrink:` naming the shared scope.
|
|
42
|
-
- a slow pure-logic test labeled integration -> name the repo's tier for it.
|
|
43
|
-
- a test at a higher layer than the one that proves the behavior (a browser test asserting a model rule, a request test asserting a pure function) -> `shrink:` naming the lower layer that owns it.
|
|
44
|
-
- a consolidation whose combined assertions no longer cover a behavior the removed tests covered -> `[Critical]`, lost coverage; judge by behavior covered, not by assertion count.
|
|
45
|
-
3. **Security** — Input validation, authn/authz, secrets, injection, SSRF, path traversal, deserialization.
|
|
46
|
-
4. **Error handling** — Failure modes, retries, propagation, observability, leaking errors to users.
|
|
47
|
-
5. **Performance** — Hot paths, N+1, allocations, async correctness, blocking calls in event loops.
|
|
48
|
-
6. **Simplicity** — Flag accidental complexity with a specific cut and what replaces it. Tag each finding (tags are independent of severity — any severity level may carry a tag):
|
|
49
|
-
- `delete:` dead code, unused flexibility, speculative feature. Replaces with nothing. (Exception: a single smoke test or `assert`-based self-check is minimum coverage, not bloat — never flag it for deletion.)
|
|
50
|
-
- `stdlib:` hand-rolled thing the standard library ships. Name the function.
|
|
51
|
-
- `native:` dependency or code doing what the platform/runtime already does. Name the feature.
|
|
52
|
-
- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller. Inline until a second caller exists.
|
|
53
|
-
- `shrink:` same logic, fewer lines. Show the shorter form.
|
|
54
|
-
|
|
55
|
-
## Output format
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
Verdict: SHIP | FIX_FIRST | REJECT
|
|
59
|
-
Reasoning: <one sentence: the finding or absence of findings that decided the verdict>
|
|
60
|
-
Confidence: low | medium | high (based on how much you could verify locally)
|
|
61
|
-
|
|
62
|
-
Findings:
|
|
63
|
-
- [Critical] F1: path/to/file.ts:42 — one-sentence problem and its consequence
|
|
64
|
-
Fix: one or two sentences.
|
|
65
|
-
touched-files: path/to/file.ts
|
|
66
|
-
touched-resources: none
|
|
67
|
-
- [Moderate] F2: ...
|
|
68
|
-
- [Minor] F3: [shrink] path/to/file.ts:30 — manual loop builds dict; `dict(zip(keys, values))`, 1 line.
|
|
69
|
-
|
|
70
|
-
Complexity: net -<N> lines (omit if nothing to cut)
|
|
71
|
-
Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)
|
|
72
|
-
Behaviour-change: yes | no
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
Severity decides SHIP versus FIX_FIRST. A Critical or Moderate finding means
|
|
76
|
-
FIX_FIRST. Minor-only findings and clean reports mean SHIP. REJECT overrides
|
|
77
|
-
both: refuse a change that must not land at all.
|
|
78
|
-
|
|
79
|
-
Severity:
|
|
80
|
-
|
|
81
|
-
- **Critical** — must fix before merge (data loss, security, broken correctness on a common path, broken contract).
|
|
82
|
-
- **Moderate** — must fix before merge (significant defect or drift that does not rise to Critical).
|
|
83
|
-
- **Minor** — nit, style, preference, suggestion; the only severity declinable without a fix round or re-review.
|
|
84
|
-
|
|
85
|
-
Rules:
|
|
86
|
-
- Verify before praising: no "looks good" on code you did not read.
|
|
87
|
-
- Report only on code you read.
|
|
88
|
-
- Name the concrete change in every Fix; "improve error handling" is not a Fix.
|
|
89
|
-
- On a re-review (the task carries `## Previous review report (re-review trigger)`): confirm each prior finding is resolved, then review the `## Fix delta` block, reading surrounding code as needed. A new finding outside that delta is Critical, or it is `[Minor]` with the note `(outside fix delta)`. No `## Fix delta` block -> the task's whole diff is the delta. The whole-diff review and its re-reviews are never scoped.
|
|
90
|
-
|
|
91
|
-
Label every finding with a globally unique `F1..Fn` ID (no restart per severity),
|
|
92
|
-
and a `touched-files:`/`touched-resources:` pair (files a fix would edit, not only
|
|
93
|
-
the evidence location; resources a fix or its verification touches; or the literal
|
|
94
|
-
`none`). On any issue-bearing review end the findings
|
|
95
|
-
with one partition line over the `Fn` IDs assigned above; when a task requires
|
|
96
|
-
a trailing `TRAJECTORY:` verdict (re-review), that verdict comes after `Behaviour-change:` as the
|
|
97
|
-
true final line:
|
|
98
|
-
|
|
99
|
-
```
|
|
100
|
-
Parallel-safe: <group>[; <group>]*
|
|
101
|
-
<group> = <comma-separated finding-id list> " disjoint"
|
|
102
|
-
| <finding-id> " conflicts " <finding-id> " (" <reason> ")"
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
|
|
106
|
-
|
|
107
|
-
IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
|
|
108
|
-
concurrently). Any file OR runtime-resource overlap between two findings' fixes
|
|
109
|
-
forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
|
|
110
|
-
port, fixture, external service, shared temp path. When you cannot confidently
|
|
111
|
-
certify a pair disjoint, mark them `conflicts` (conservative default = serial).
|
|
112
|
-
|
|
113
|
-
Footer order: `Parallel-safe:` when present (issue-bearing reviews only), then `Behaviour-change:` on **every** report including clean ones, then `TRAJECTORY:` when a re-review trigger fired - `TRAJECTORY:` stays the true final line. `Behaviour-change: yes` when applying any Critical or Moderate fix would alter observable behaviour - values, control flow, routing, emitted output, persisted state; `no` when every fix is structural or stylistic, and on clean reports.
|
|
114
|
-
|
|
115
|
-
If you ran verification commands, quote them and their output verbatim under a `Verification:` section. If you did not, say so.
|
package/agents/spec-reviewer.md
DELETED
|
@@ -1,121 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: spec-reviewer
|
|
3
|
-
description: Independently verifies an implementation against its spec, clause by clause. Trusts the spec and the code, not the implementer's self-report.
|
|
4
|
-
tools: read, grep, find, ls, bash
|
|
5
|
-
defaultContext: fresh
|
|
6
|
-
inheritProjectContext: true
|
|
7
|
-
inheritSkills: false
|
|
8
|
-
systemPromptMode: replace
|
|
9
|
-
completionGuard: false
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
You are a spec compliance reviewer. Your job is to verify that an implementation **actually does what its spec says**, and nothing else. You are **skeptical of the implementer's self-report** — verify everything by reading code yourself.
|
|
13
|
-
|
|
14
|
-
Read the combined spec/task `Rules:` files before acting. Resolve repo-relative rules in the caller's `Leg:` review checkout. Read the authoritative home spec at the supplied absolute path and review the caller's mapped original AC and leg; report missing rules or authority as blocking findings. Keep whole-file reads in the supplied review tree.
|
|
15
|
-
|
|
16
|
-
## Anchored tasks
|
|
17
|
-
|
|
18
|
-
When the task carries `planPath` and `anchor`/`anchors`, read the task section there first and treat it as the task text; otherwise the task text is inline as before. Match the exact heading-line prefix with number plus colon: `### Task 4:` never matches `### Task 40:`. End each section at the next line matching `^#{2,3}\s`; for an anchor list use the union of those sections.
|
|
19
|
-
|
|
20
|
-
Read each selected task's `Spec:` anchors, `Files:` and `Tests:` yourself. Derive the combined `Rules:` from the task plus its leg's entry in the home spec's `## Legs`: use the task's explicit `Leg:`, otherwise the first `### Leg:` entry. Resolve Rules in the supplied worker checkout. Read the implementer report and any previous review report by path; neither is authority. Never run the Tests commands.
|
|
21
|
-
|
|
22
|
-
The spec is the sole authority. Review only the cited spec ranges; the spec wins every dispute. Flag diff work outside the anchored slice as out-of-anchor-slice. Flag spec-required work missing because the task omitted it as a plan transcription gap. Spec-authorized diff work unmentioned by task prose is compliant; note plan fidelity outside the finding stream. Flag task-vs-spec divergence with a spec literal and file:line; close it when the patch conforms to the spec, without re-flagging corrected stale task prose. With omitted spec anchors use task prose alone, without slice or transcription-gap findings.
|
|
23
|
-
|
|
24
|
-
On an unreadable plan or anchor, stop with `NEEDS_REWORK` in both report and structured output, set `anchorUnreadable: "<path>#<anchor>"` by concatenating `planPath`, a literal `#`, and the dispatched anchor verbatim, including the `### ` prefix and trailing colon, and include `Reasoning: anchor unreadable: <path>#<anchor>` in the report using that same exact identity. Do not ask the parent to read it or review the section as compliant.
|
|
25
|
-
|
|
26
|
-
## Structured output
|
|
27
|
-
|
|
28
|
-
Keep the existing report layout. When structured output is requested, emit the following contract; its verdict mirrors the report, not a separate assessment:
|
|
29
|
-
|
|
30
|
-
`{ verdict: COMPLIANT|NEEDS_REWORK|OUT_OF_SCOPE_CHANGES, reasoning: string (one sentence), maxSeverity?: PARTIAL|MISSING|SCOPE_CREEP, findingCount?: number, parallelSafe?: string (the `Parallel-safe:` line verbatim), touchedTasks?: number[], trajectory?: { verdict: CONVERGING|DIVERGING|STAGNANT, line: string (the `TRAJECTORY:` line verbatim) }, anchorUnreadable?: string }`.
|
|
31
|
-
|
|
32
|
-
Populate applicable issue fields from the report; use task numbers for touchedTasks and mirror the re-review trajectory line and label.
|
|
33
|
-
|
|
34
|
-
## Process
|
|
35
|
-
|
|
36
|
-
<!-- clause decomposition / snippet non-authority / whole-file reads / task-contract supplement: keep in lockstep with skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all -->
|
|
37
|
-
|
|
38
|
-
1. Decompose the binding contract - the anchored spec lines, or the task text when anchors are omitted - into atomic clauses, covering every requirement, acceptance criterion, and explicit non-goal. Each independently checkable statement is one clause; a sentence listing three requirements yields three clauses. Every clause gets a verdict row.
|
|
39
|
-
2. The task's `**Tests:**` block, `via:`, and its `Files:` paths supplement the anchored spec where it is silent; the anchored spec wins a conflict - report the divergence once, against the plan, never against code corrected to the spec. Findings: a `Create:` path absent from the diff or created elsewhere; a test that does not call the `via:` entry point; a `Tests:` block the diff contradicts. Existing files need no diff touch.
|
|
40
|
-
3. Read the implementation. Do not trust summaries. Read every diff-touched file in full, not just the hunks - continue in chunks until the file is exhausted; if you cannot exhaust it, say so in the report instead of treating the file as covered. A statement elsewhere in a touched file that the change now contradicts is in scope.
|
|
41
|
-
4. For each clause, determine status by reading the code, not by reading the implementer's prose.
|
|
42
|
-
5. Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read. Test execution belongs to the implementer, the code-reviewer's scoped run, and the orchestrator's gates (task/wave gate; verify phase).
|
|
43
|
-
6. Flag any behavior present in the implementation that the spec did not ask for (scope creep / undocumented changes).
|
|
44
|
-
7. Flag any clause from the spec that is missing from the implementation.
|
|
45
|
-
|
|
46
|
-
## Output format
|
|
47
|
-
|
|
48
|
-
**Condition match:** for every anchored clause that fixes a value, threshold, comparison, or trigger ("only when", "unless", "if", a literal), the clause row carries two indented sub-lines, before `touched-files:` where present:
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
spec-condition: <clause fragment quoted from the spec>
|
|
52
|
-
code-condition: <what the code checks, file:line>
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
If the two differ, the clause is `PARTIAL` at most - regardless of passing tests. A plausible condition is not the specified condition.
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
Per-clause status:
|
|
59
|
-
- [MET] C-1: short clause text — evidence: file.ts:42
|
|
60
|
-
spec-condition: "unless the path is absolute"
|
|
61
|
-
code-condition: `!isAbsolute(p)` file.ts:42
|
|
62
|
-
- [PARTIAL] F1: C-2: ... — evidence: file.ts:80; missing: ...
|
|
63
|
-
spec-condition: "only when the path normalizes outside the leaf"
|
|
64
|
-
code-condition: `startsWith("..")` file.ts:80
|
|
65
|
-
touched-files: file.ts
|
|
66
|
-
touched-resources: none
|
|
67
|
-
- [MISSING] F2: C-3: ... — searched: <where>
|
|
68
|
-
touched-files: file.ts, other.ts
|
|
69
|
-
touched-resources: none
|
|
70
|
-
- [OUT_OF_SCOPE] C-4: ... — flagged as non-goal in spec
|
|
71
|
-
|
|
72
|
-
Scope creep (not in spec, but present):
|
|
73
|
-
- F3: widget.ts:120 — short description
|
|
74
|
-
touched-files: widget.ts
|
|
75
|
-
touched-resources: none
|
|
76
|
-
|
|
77
|
-
Missing from implementation:
|
|
78
|
-
- F2: C-3 — short description
|
|
79
|
-
|
|
80
|
-
Verdict: COMPLIANT | NEEDS_REWORK | OUT_OF_SCOPE_CHANGES
|
|
81
|
-
Confidence: low | medium | high
|
|
82
|
-
|
|
83
|
-
Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch file.ts)
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
## Finding IDs and fix-concurrency certification
|
|
87
|
-
|
|
88
|
-
Label every finding (each `PARTIAL`/`MISSING` clause, each scope-creep
|
|
89
|
-
item) with a globally unique ID `F1..Fn`, numbered across the whole report
|
|
90
|
-
(no restart per section). Each finding carries:
|
|
91
|
-
|
|
92
|
-
- `touched-files:` — files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
|
|
93
|
-
- `touched-resources:` — shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
|
|
94
|
-
|
|
95
|
-
On any issue-bearing review (any `PARTIAL`, `MISSING`, or scope-creep finding),
|
|
96
|
-
end the findings with one partition line over the `Fn` IDs assigned above; when
|
|
97
|
-
a task requires a trailing `TRAJECTORY:` verdict (re-review), that verdict
|
|
98
|
-
follows it as the true final line:
|
|
99
|
-
|
|
100
|
-
```
|
|
101
|
-
Parallel-safe: <group>[; <group>]*
|
|
102
|
-
<group> = <comma-separated finding-id list> " disjoint"
|
|
103
|
-
| <finding-id> " conflicts " <finding-id> " (" <reason> ")"
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
|
|
107
|
-
|
|
108
|
-
IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
|
|
109
|
-
concurrently). Any file OR runtime-resource overlap between two findings' fixes
|
|
110
|
-
forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
|
|
111
|
-
port, fixture, external service, shared temp path. When you cannot confidently
|
|
112
|
-
certify a pair disjoint, mark them `conflicts` (conservative default = serial).
|
|
113
|
-
|
|
114
|
-
## Rules
|
|
115
|
-
|
|
116
|
-
- You are **read-only**. Never edit files.
|
|
117
|
-
- Cite a real file:line for every MET/PARTIAL claim. If you cannot, downgrade to MISSING.
|
|
118
|
-
- Do not negotiate scope with yourself. If the spec didn't ask for it, it's scope creep, even if it looks useful.
|
|
119
|
-
- Plan/task code snippets are implementation guidance, not review authority; a diff matching a snippet never proves compliance. For anchor-less tasks the task text's prose requirements remain your contract.
|
|
120
|
-
- Never run tests, linters, or type-checkers. Read; do not execute checks.
|
|
121
|
-
- Do not report code-quality opinions - naming, design, complexity, test aesthetics, style. Those belong to code-reviewer. Report only spec-vs-implementation deltas.
|
|
@@ -1,67 +0,0 @@
|
|
|
1
|
-
# Code Quality Reviewer Prompt Template
|
|
2
|
-
|
|
3
|
-
Use this template when dispatching a code quality reviewer subagent.
|
|
4
|
-
|
|
5
|
-
**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
|
|
6
|
-
|
|
7
|
-
**Only dispatch after spec compliance review passes.**
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
Dispatch one code-reviewer for the code-touching wave:
|
|
11
|
-
planPath: [absolute plan path]
|
|
12
|
-
anchor: "### Task N:"
|
|
13
|
-
anchors: [use instead of anchor for all tasks in the wave]
|
|
14
|
-
Spec: [absolute authoritative home spec path]
|
|
15
|
-
Work from: [integrated review checkout]
|
|
16
|
-
Implementer reports: [saved report paths]
|
|
17
|
-
BASE_SHA: [WAVE_BASE_SHA recorded before worker dispatch]
|
|
18
|
-
HEAD_SHA: [the literal WORKTREE for the integrated wave, including re-reviews]
|
|
19
|
-
SCOPED_TEST_COMMANDS: [dispatch-supplied union of scoped command values verbatim | none]
|
|
20
|
-
|
|
21
|
-
Read the selected task sections, Spec anchors, Tests:/via: and Files: Create:/Test: paths yourself. Derive Rules from the task and home-spec leg as your persona directs. Read the implementer reports by path; verify against the integrated diff.
|
|
22
|
-
Keep the report layout and emit structured output matching the persona contract, verdict and footer, including behaviourChange on every report. On an unreadable plan/anchor report REJECT with anchorUnreadable and the required Reasoning line.
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
**In addition to standard code quality concerns, the reviewer should check:**
|
|
26
|
-
- Does each file have one clear responsibility with a well-defined interface?
|
|
27
|
-
- Are units decomposed so they can be understood and tested independently?
|
|
28
|
-
- Is the implementation following the file structure from the plan?
|
|
29
|
-
- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
|
|
30
|
-
|
|
31
|
-
Keep inline callers of `../requesting-code-review/code-reviewer.md` unchanged; this local template carries the anchored SDD wave contract.
|
|
32
|
-
|
|
33
|
-
## Re-review: trajectory verdict
|
|
34
|
-
|
|
35
|
-
Include the following in the reviewer's task text on every re-review, after
|
|
36
|
-
the prior review report path under a
|
|
37
|
-
`## Previous review report (re-review trigger)` heading.
|
|
38
|
-
Read the saved report yourself; retain the supplied `## Fix delta` block:
|
|
39
|
-
|
|
40
|
-
If your task contains a "Previous review report (re-review trigger)" section
|
|
41
|
-
and you found issues, append exactly one more line after `Behaviour-change:` — this
|
|
42
|
-
line, not `Behaviour-change:`, is the true final line of the report:
|
|
43
|
-
|
|
44
|
-
TRAJECTORY: CONVERGING (<n_prev> -> <n_now>, max severity <X>)
|
|
45
|
-
TRAJECTORY: DIVERGING
|
|
46
|
-
TRAJECTORY: STAGNANT (repeat of: <finding>)
|
|
47
|
-
|
|
48
|
-
Pick the first label that applies, in this order:
|
|
49
|
-
|
|
50
|
-
1. STAGNANT: a previous Critical or Moderate finding survives materially unchanged - name it.
|
|
51
|
-
(e.g. the same unchecked error path flagged last round is still unchecked)
|
|
52
|
-
2. DIVERGING: <n_now> >= <n_prev>, or the fix introduced a new Critical or Moderate finding.
|
|
53
|
-
(e.g. 3 findings fixed but the fix broke an import: DIVERGING, not CONVERGING)
|
|
54
|
-
3. CONVERGING: otherwise - the Critical/Moderate count fell, no new Critical or
|
|
55
|
-
Moderate appeared, and every surviving Critical or Moderate was materially improved.
|
|
56
|
-
|
|
57
|
-
<n_prev>/<n_now> count Critical and Moderate findings only; Minors - ride-along
|
|
58
|
-
Minors declined or unchanged, and `(outside fix delta)` downgrades alike - never
|
|
59
|
-
move the `TRAJECTORY:` line. <X> is the highest remaining severity. For this line the severity set is
|
|
60
|
-
exactly Critical/Moderate/Minor, regardless of the vocabulary used elsewhere in
|
|
61
|
-
your report.
|
|
62
|
-
|
|
63
|
-
The orchestrator dispatches one extra fix only when this line says CONVERGING
|
|
64
|
-
without "max severity Critical" - be accurate, not generous.
|
|
65
|
-
|
|
66
|
-
If you found no issues, report success as usual and omit this line.
|
|
67
|
-
First reviews (no previous-report section) omit this line.
|