pi-gauntlet 5.18.2 → 5.18.4
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 +14 -0
- package/README.md +9 -2
- package/agents/code-reviewer.md +11 -4
- package/agents/conformance-reviewer.md +2 -2
- package/agents/spec-reviewer.md +0 -2
- package/package.json +1 -1
- package/skills/brainstorming/SKILL.md +1 -1
- package/skills/chase-bug/SKILL.md +1 -1
- package/skills/check-delivery/SKILL.md +7 -3
- package/skills/dispatching-parallel-agents/SKILL.md +2 -2
- package/skills/finishing-a-development-branch/SKILL.md +1 -1
- package/skills/gatekeep-pr/SKILL.md +1 -1
- package/skills/gatekeep-pr/reference/decision-menu.md +23 -2
- package/skills/gatekeep-pr/reference/post-selection-loop.md +6 -5
- package/skills/gatekeep-pr/verification-brief.md +6 -5
- package/skills/gauntlet-handoff/SKILL.md +7 -3
- package/skills/gauntlet-performance/SKILL.md +7 -3
- package/skills/gauntlet-resume/SKILL.md +7 -3
- package/skills/linear/SKILL.md +1 -1
- package/skills/receiving-code-review/SKILL.md +10 -30
- package/skills/requesting-code-review/SKILL.md +2 -40
- package/skills/requesting-code-review/code-reviewer.md +2 -124
- package/skills/roasting-the-spec/SKILL.md +1 -1
- package/skills/shape-ticket/SKILL.md +2 -2
- package/skills/subagent-driven-development/SKILL.md +45 -13
- package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +1 -5
- package/skills/subagent-driven-development/implementer-prompt.md +1 -1
- package/skills/subagent-driven-development/spec-reviewer-prompt.md +1 -30
- package/skills/test-driven-development/SKILL.md +1 -1
- package/skills/using-git-worktrees/SKILL.md +1 -1
- package/skills/verification-before-completion/SKILL.md +1 -1
- package/skills/writing-plans/SKILL.md +1 -1
- package/skills/writing-skills/SKILL.md +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v5.18.4 - 2026-09-23
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Every skill reads and applies `## conventions` from the selected overrides file whenever present, without relevance filtering; this skill's named section wins on conflict while non-conflicting conventions still apply. (#48)
|
|
8
|
+
|
|
9
|
+
## v5.18.3 - 2026-09-23
|
|
10
|
+
|
|
11
|
+
- Happy-path verification runs command setup, execution, status capture, and summary generation in one self-contained shell call, preventing an unset command in a later call from reporting a false pass. Executable regression tests cover real local producer-consumer delivery, broken-delivery timeouts, exit classification, and worktree residue.
|
|
12
|
+
- `gatekeep-pr` reviews new or changed comment bodies against source before updating merge readiness after a push, after waiting, and immediately before merge. Source-confirmed defects enter the existing blocking findings; a new body delta invalidates prior merge consent, including `anyway`. Timestamp-only edits avoid repeat source review, and polling preserves the unreviewed comment baseline. (#46)
|
|
13
|
+
- Reviewer personas (`code-reviewer`, `spec-reviewer`, `conformance-reviewer`) are the sole owners of their report contracts; the request template and SDD reviewer prompts carry scope payload plus one pointer sentence, and the `Ready to merge?` variant is gone (#47).
|
|
14
|
+
- `code-reviewer` reports gain a `Reasoning:` line after `Verdict:`, three review rules, and a wider `touched-files:` qualifier.
|
|
15
|
+
- Recipient guidance lives in `receiving-code-review` only; the worktree `cwd` dispatch rule lives in `dispatching-parallel-agents` only; `scripts/ci.mjs` drops the two template `Behaviour-change:` pins.
|
|
16
|
+
|
|
3
17
|
## v5.18.2 - 2026-09-23
|
|
4
18
|
|
|
5
19
|
- `gatekeep-pr` refetches PR comments after every head move and diffs them against a `C#` ledger by comment `id` and `updated_at` (unchanged rows keep their `C#`; edited rows mint a new one and render the old as `superseded by C<new>`; vanished rows render `withdrawn`). claude-code-action's sticky in-progress placeholder (first line `Claude Code is working`) renders as `pending`, withholds pre-composed `merge-*` courses (`merge-squash anyway` overrides), and a new `wait` course polls the reviewer run for up to `timeout minutes` before re-rendering; a failed reviewer run renders `reviewer failed (<conclusion>)` and its check is inert - it never blocks merge. (#46)
|
package/README.md
CHANGED
|
@@ -255,7 +255,14 @@ exact repo folder* in interactive Claude Code. Trusting a parent folder,
|
|
|
255
255
|
|
|
256
256
|
## Project-specific overrides
|
|
257
257
|
|
|
258
|
-
The skills shipped here are generic on purpose - they describe *how* to TDD, brainstorm, debug, request review, etc., without naming your services, your CI command, or your worktree wrapper. When you need that level of detail, drop a file at `.pi/gauntlet-overrides.md` in your repo.
|
|
258
|
+
The skills shipped here are generic on purpose - they describe *how* to TDD, brainstorm, debug, request review, etc., without naming your services, your CI command, or your worktree wrapper. When you need that level of detail, drop a file at `.pi/gauntlet-overrides.md` in your repo. Every active skill reads and applies `## conventions` whenever present in the selected file, without relevance filtering. Use this heading for repo-wide rules that bind more than one skill:
|
|
259
|
+
|
|
260
|
+
```markdown
|
|
261
|
+
## conventions
|
|
262
|
+
Keep scratch files outside the repository.
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
This skill's named section means the section named for the active skill (for example, `## writing-plans`), not another heading it reads by name. This skill's named section wins over conflicting `## conventions` rules; non-conflicting conventions still apply. Other relevant sections can also override or extend skill instructions, as in this skill-specific example:
|
|
259
266
|
|
|
260
267
|
```markdown
|
|
261
268
|
## verification-before-completion
|
|
@@ -269,7 +276,7 @@ Use the project's wrapper: `script/worktree create <name>`. It provisions an iso
|
|
|
269
276
|
database and copies `.env.local`. Never call `git worktree add` directly.
|
|
270
277
|
```
|
|
271
278
|
|
|
272
|
-
|
|
279
|
+
Beyond `## conventions` and skill-named sections, headings a skill reads by name are documented in their owning skills; other headings retain topic/workflow-convention matching. The override file is read by skill instructions, not by the Pi runtime itself. Missing or empty `## conventions` adds no rules; a lower-priority file cannot supplement the selected file.
|
|
273
280
|
|
|
274
281
|
**Discovery ladder:** skills check three locations, in order, and use the first one found - never merged: `.pi/gauntlet-overrides.md`, then `<repo root>/gauntlet-overrides.md`, then `<repo root>/doc/gauntlet-overrides.md` (`<repo root>` = `git rev-parse --show-toplevel`, or the current directory outside a repo). Pick one location per repo.
|
|
275
282
|
|
package/agents/code-reviewer.md
CHANGED
|
@@ -29,10 +29,11 @@ You are a code reviewer. You find issues before they ship. You **do not edit cod
|
|
|
29
29
|
|
|
30
30
|
```
|
|
31
31
|
Verdict: SHIP | FIX_FIRST | REJECT
|
|
32
|
+
Reasoning: <one sentence: the finding or absence of findings that decided the verdict>
|
|
32
33
|
Confidence: low | medium | high (based on how much you could verify locally)
|
|
33
34
|
|
|
34
35
|
Findings:
|
|
35
|
-
- [Critical] F1: path/to/file.ts:42 — one-sentence problem
|
|
36
|
+
- [Critical] F1: path/to/file.ts:42 — one-sentence problem and its consequence
|
|
36
37
|
Fix: one or two sentences.
|
|
37
38
|
touched-files: path/to/file.ts
|
|
38
39
|
touched-resources: none
|
|
@@ -54,14 +55,20 @@ Severity:
|
|
|
54
55
|
- **Moderate** — must fix before merge (significant defect or drift that does not rise to Critical).
|
|
55
56
|
- **Minor** — nit, style, preference, suggestion; the only severity declinable without a fix round or re-review.
|
|
56
57
|
|
|
58
|
+
Rules:
|
|
59
|
+
- Verify before praising: no "looks good" on code you did not read.
|
|
60
|
+
- Report only on code you read.
|
|
61
|
+
- Name the concrete change in every Fix; "improve error handling" is not a Fix.
|
|
62
|
+
|
|
57
63
|
Label every finding with a globally unique `F1..Fn` ID (no restart per severity),
|
|
58
|
-
and a `touched-files:`/`touched-resources:` pair (files
|
|
59
|
-
|
|
64
|
+
and a `touched-files:`/`touched-resources:` pair (files a fix would edit, not only
|
|
65
|
+
the evidence location; resources a fix or its verification touches; or the literal
|
|
66
|
+
`none`). On any issue-bearing review end the findings
|
|
60
67
|
with one partition line over the `Fn` IDs assigned above; when a task requires
|
|
61
68
|
a trailing `TRAJECTORY:` verdict (re-review), that verdict comes after `Behaviour-change:` as the
|
|
62
69
|
true final line:
|
|
63
70
|
|
|
64
|
-
<!--
|
|
71
|
+
<!-- writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form; do not unify -->
|
|
65
72
|
|
|
66
73
|
```
|
|
67
74
|
Parallel-safe: <group>[; <group>]*
|
|
@@ -113,8 +113,6 @@ Empty values use the literal tokens `absent` / `none` / `unknown` — never a bl
|
|
|
113
113
|
After the gap blocks, emit one `Parallel-safe:` line so the orchestrator does not
|
|
114
114
|
re-derive fix concurrency:
|
|
115
115
|
|
|
116
|
-
<!-- grammar identical to skills/subagent-driven-development/spec-reviewer-prompt.md and skills/requesting-code-review/code-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
|
|
117
|
-
|
|
118
116
|
```
|
|
119
117
|
Parallel-safe: <group>[; <group>]*
|
|
120
118
|
<group> = <comma-separated gap-id list> " disjoint"
|
|
@@ -131,6 +129,8 @@ Any **file OR runtime-resource** overlap forces the conflicting gaps into separa
|
|
|
131
129
|
serial waves — identical to planned-execution wave grouping. Runtime-resource disjointness is not machine-checkable; estimate it over: DB/schema, port, fixture, external service, shared temp path. When you cannot confidently certify a pair disjoint, mark them
|
|
132
130
|
`conflicts` (conservative default = serial).
|
|
133
131
|
|
|
132
|
+
Footer order: `Parallel-safe:` is the final line of the report.
|
|
133
|
+
|
|
134
134
|
### `recommended` selection policy
|
|
135
135
|
|
|
136
136
|
`recommended` is a proposal; you never decide, edit, dispatch, or re-audit.
|
package/agents/spec-reviewer.md
CHANGED
|
@@ -77,8 +77,6 @@ end the findings with one partition line over the `Fn` IDs assigned above; when
|
|
|
77
77
|
a task requires a trailing `TRAJECTORY:` verdict (re-review), that verdict
|
|
78
78
|
follows it as the true final line:
|
|
79
79
|
|
|
80
|
-
<!-- grammar identical to skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
|
|
81
|
-
|
|
82
80
|
```
|
|
83
81
|
Parallel-safe: <group>[; <group>]*
|
|
84
82
|
<group> = <comma-separated finding-id list> " disjoint"
|
package/package.json
CHANGED
|
@@ -293,4 +293,4 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
|
|
|
293
293
|
|
|
294
294
|
## Project overrides
|
|
295
295
|
|
|
296
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
296
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -440,4 +440,4 @@ nested resources" (the decision that made it so).
|
|
|
440
440
|
|
|
441
441
|
## Project overrides
|
|
442
442
|
|
|
443
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
443
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands. `## Response channels` and `## Issue tracker` are the named extension points for this skill.
|
|
@@ -399,9 +399,13 @@ unset (no body edits).
|
|
|
399
399
|
|
|
400
400
|
If a gauntlet overrides file exists - checked in order:
|
|
401
401
|
`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
|
|
402
|
-
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
403
|
-
|
|
404
|
-
|
|
402
|
+
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read
|
|
403
|
+
and apply `## conventions` whenever present, without a relevance
|
|
404
|
+
judgment.
|
|
405
|
+
Give this skill's named section precedence over conflicting
|
|
406
|
+
`## conventions` rules. Use other relevant sections - by name match,
|
|
407
|
+
by topic (routing,
|
|
408
|
+
verification, worktrees, etc.), or by workflow convention - to override or
|
|
405
409
|
extend the instructions above. Project-local `AGENTS.md` is already in
|
|
406
410
|
context - check it for project-specific routing tables, service paths, and
|
|
407
411
|
verification commands.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dispatching-parallel-agents
|
|
3
|
-
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
|
|
3
|
+
description: "Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies, when fanning out review-finding fixes in parallel, or when checking a reviewer's Parallel-safe: line before doing so"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
> **Related skills:** Verify all fixes with `/skill:verification-before-completion`.
|
|
@@ -218,4 +218,4 @@ After agents return:
|
|
|
218
218
|
|
|
219
219
|
## Project overrides
|
|
220
220
|
|
|
221
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
221
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -379,4 +379,4 @@ Once the merge (and any deploy) has landed, `/skill:check-delivery <ticket-ref>`
|
|
|
379
379
|
|
|
380
380
|
## Project overrides
|
|
381
381
|
|
|
382
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
382
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -204,4 +204,4 @@ overrides file - see Project overrides.
|
|
|
204
204
|
|
|
205
205
|
## Project overrides
|
|
206
206
|
|
|
207
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
207
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands. A `## comms style` section in the overrides file extends the output done-check with project rules.
|
|
@@ -94,7 +94,7 @@ the reason: `reviewer still running` or `comments not refreshed`. This is a
|
|
|
94
94
|
menu-level gate modelled on the `flaky` disposition's custom-row path, never
|
|
95
95
|
a `## Verdict` precondition: `### Merge course` does not refuse the override.
|
|
96
96
|
Only the custom row's `merge-squash anyway` / `merge-commit anyway` executes
|
|
97
|
-
merge in that state, under the normal Merge course rules.
|
|
97
|
+
merge in that state, under the normal Merge course rules. Apply the comment-delta consent and incomplete-review rules in `post-selection-loop.md` `### Compare-and-swap` and `### Re-render`; `anyway` does not bypass an unreviewed delta or a blocking finding.
|
|
98
98
|
|
|
99
99
|
`wait` is `[recommended]` in cells whose recommended course would otherwise
|
|
100
100
|
be `merge-*` or `approve` (clean / follow-ups only, and the post-fix
|
|
@@ -187,7 +187,26 @@ Pick one:
|
|
|
187
187
|
```
|
|
188
188
|
|
|
189
189
|
(b) The run concluded `success`; the reviewer check moved from pending to
|
|
190
|
-
`success` in the refreshed rollup and the comment carries the verdict:
|
|
190
|
+
`success` in the refreshed rollup and the comment carries the verdict. Reconcile C5 against source at the assessed head. For a confirmed retry bug missed by the previous source review, mint source-backed P11 and withhold merge; C5's triage label remains verdict-neutral:
|
|
191
|
+
|
|
192
|
+
```markdown
|
|
193
|
+
## Findings (blocking)
|
|
194
|
+
Blocking findings (P#):
|
|
195
|
+
P11. **<source_ref>** - Retry attempts never increment. Fix: increment attempts on failure and throw after the retry limit. | Action: fix P11. [code]
|
|
196
|
+
## Comment-thread replies
|
|
197
|
+
C1. <thread ref> -> superseded by C3
|
|
198
|
+
C2. <thread ref> -> superseded by C4
|
|
199
|
+
C3. <thread ref> -> superseded by C5
|
|
200
|
+
C4. <thread ref> -> <drafted reply> (reasonable)
|
|
201
|
+
C5. <thread ref> -> <drafted reply> (reasonable)
|
|
202
|
+
Pick one:
|
|
203
|
+
1. fix P11 [recommended]
|
|
204
|
+
2. stop
|
|
205
|
+
3. review-comment
|
|
206
|
+
4. Custom
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
When source review instead disproves C5's concern, mint no `P#` and retain the clean menu:
|
|
191
210
|
|
|
192
211
|
```markdown
|
|
193
212
|
## Comment-thread replies
|
|
@@ -204,3 +223,5 @@ Pick one:
|
|
|
204
223
|
4. review-comment
|
|
205
224
|
5. Custom
|
|
206
225
|
```
|
|
226
|
+
|
|
227
|
+
Golden fixture 4 - last premerge refetch finds a new human comment after merge consent. Reconcile it against source at the assessed head, abort that merge even when the concern is false, and show the refreshed menu for a new selection. A same-head identical-body timestamp edit mints the next `C#` but causes no repeat source review or test run. A bot placeholder or error header keeps its existing state and does not enter source review.
|
|
@@ -6,7 +6,7 @@ Read from SKILL.md `## Act`. Treat the menu as a state machine: execute only the
|
|
|
6
6
|
|
|
7
7
|
### Compare-and-swap
|
|
8
8
|
|
|
9
|
-
Before every external write, re-fetch `headRefOid`, `state`, and `mergeable`. Any change since assessment invalidates the current state - re-sync the worktree, re-run Phase 3 per `assessment.md` `## Phase 3 - Verify, then review`, and re-render the menu. Exception: a course's own push updates the assessed head to the pushed SHA as part of that course's execution - this self-inflicted head move does not invalidate the course; the next compare-and-swap check runs against the new head on the next external write. Before a merge executes (plain or `anyway`),
|
|
9
|
+
Before every external write, re-fetch `headRefOid`, `state`, and `mergeable`. Any change since assessment invalidates the current state - re-sync the worktree, re-run Phase 3 per `assessment.md` `## Phase 3 - Verify, then review`, and re-render the menu. Exception: a course's own push updates the assessed head to the pushed SHA as part of that course's execution - this self-inflicted head move does not invalidate the course; the next compare-and-swap check runs against the new head on the next external write. Before a merge executes (plain or `anyway`), run the full comment refetch and reconciliation (`### Re-render` steps 1-5), not just placeholder detection. If the head changed, follow the re-assessment rule above instead. A new or changed-body delta since the consent render aborts the selected merge, plain or `anyway`: show the reconciled report and request a fresh selection even when no blocker resulted. A newly `pending` row, a queued/in-progress reviewer run, or a failed refetch (`comments not refreshed (<reason>)`) refuses a plain merge and re-renders; `anyway` overrides only those existing pending/refetch-failure overlays and prints what it overrode, never a new blocker or unreviewed delta.
|
|
10
10
|
|
|
11
11
|
### Fix wave
|
|
12
12
|
|
|
@@ -28,7 +28,7 @@ Merge always executes as `gh pr merge --match-head-commit <assessed-sha>`. Push
|
|
|
28
28
|
|
|
29
29
|
### Re-render
|
|
30
30
|
|
|
31
|
-
After any mutation that can change readiness (fix wave pushed, docs pushed, PR head moved), re-run the claim-check and Review on the synced worktree: claims are re-checked against the new head and findings are re-rendered, but do not re-execute the verification command here - the fix wave's evidence re-resolution already was the wave's one gate pass. Annotate each selected `P#`/`L#` confirmed resolved as `(fixed in <sha>)` under its original ID; unresolved ones stay open unchanged; new findings continue the sequence. Then refetch comments - the last read before the menu renders:
|
|
31
|
+
After every push or any mutation that can change readiness (fix wave pushed, docs pushed, PR head moved), re-run the claim-check and Review on the synced worktree: claims are re-checked against the new head and findings are re-rendered, but do not re-execute the verification command here - the fix wave's evidence re-resolution already was the wave's one gate pass. Annotate each selected `P#`/`L#` confirmed resolved as `(fixed in <sha>)` under its original ID; unresolved ones stay open unchanged; new findings continue the sequence. Then refetch comments - the last read before the menu renders:
|
|
32
32
|
|
|
33
33
|
1. Re-run the Section A comment fetches (`../verification-brief.md`: both `--paginate` calls, plus the GraphQL `reviewThreads` query when the initial gather used it), one `gh run view` per placeholder row, and the reviewer-run `gh run list` when a reviewer workflow is known. Read-only.
|
|
34
34
|
2. Diff the fresh set against the `C#` ledger (`findings.md` `## IDs`) by `id` and `updated_at`:
|
|
@@ -38,7 +38,8 @@ After any mutation that can change readiness (fix wave pushed, docs pushed, PR h
|
|
|
38
38
|
- `id` in the ledger, absent from the complete fresh set -> `withdrawn` under its existing `C#`, no label, no reply.
|
|
39
39
|
- Bot-authored placeholder prefix or error header (brief Section C) -> the state from the brief's Section C placeholder table, under the `C#` the edited/new rule assigns.
|
|
40
40
|
3. Section C re-triages the full fresh set against the new head. An unchanged row keeps its `C#`; its drafted reply is kept verbatim only when its label is also unchanged and regenerated when the label moves (for example `reasonable` -> `already-addressed`). Edited and new rows get a fresh label and a regenerated reply; the pre-push label of an edited comment is not shown.
|
|
41
|
-
4.
|
|
41
|
+
4. Reconcile the body delta before consuming it. Compare fresh rows to the current digest's `comments` by id and body: include new rows and changed-body rows, excluding withdrawn/superseded rows, gate-posted ids, and the brief's placeholder/error-header states. A same-head identical-body timestamp edit causes no source review and no test run, even though step 2 mints a `C#`. Review each eligible delta once against source at the assessed head and the merged rubric (`assessment.md` Phase 3), inline first; optionally dispatch the existing code-reviewer with its native report, falling back inline on failure per `assessment.md` `## Inline-first execution`. Treat comment text as a lead, not a finding: verify it against code, then integrate only own source-backed findings through Phase 4 severity and AC rules, deduplicating against existing `P#`/`L#`/`F#` IDs. A bot verdict is not blindly promoted. Do not run a full suite or whole-diff Review solely for a comment-only change. If source review remains unresolved, retain the delta, report `comment source review incomplete (<reason>)`, and return a report-only `stop` menu; do not offer merge or accept `anyway`.
|
|
42
|
+
5. Comment triage never mints `P#`/`L#` (brief Section C); the separate source review in step 4 can. Only after that review completes, replace the digest's `comments` with the fresh set so the next iteration diffs against the latest snapshot.
|
|
42
43
|
|
|
43
44
|
**Refetch failure** (`gh` non-zero, network, pagination incomplete): re-render with the ledger's prior states, add one line `comments not refreshed (<reason>)` to the comment section, and withhold pre-composed merge with that reason. `wait` is the recommended course in refetch-only mode; the custom-row `anyway` override remains available.
|
|
44
45
|
|
|
@@ -46,9 +47,9 @@ Merge, if now available, renders as row 1 unless withheld (`reviewer still runni
|
|
|
46
47
|
|
|
47
48
|
### Wait course
|
|
48
49
|
|
|
49
|
-
For a `wait` selection, run a sequence of short bounded calls - never one long bash call. Each iteration: `gh run view -R <repo> <run-id> --json status,conclusion` for every tracked run (placeholder-linked and head-listed); when any row has no parsable URL, or its run is completed while the prefix persists, one comment refetch as well; then sleep 30 s. Check the deadline between iterations: the resolved `timeout minutes` (default 15, the same knob as the local verification run). Stop when every tracked run is completed and no row is in the "completed `success`, prefix persists" state, or the deadline passes.
|
|
50
|
+
For a `wait` selection, run a sequence of short bounded calls - never one long bash call. Each iteration: `gh run view -R <repo> <run-id> --json status,conclusion` for every tracked run (placeholder-linked and head-listed); when any row has no parsable URL, or its run is completed while the prefix persists, one comment refetch as well; then sleep 30 s. Use each polling refetch only to observe run/placeholder state; leave the digest and `C#` ledger untouched until the completion/timeout reconciliation below. Check the deadline between iterations: the resolved `timeout minutes` (default 15, the same knob as the local verification run). Stop when every tracked run is completed and no row is in the "completed `success`, prefix persists" state, or the deadline passes.
|
|
50
51
|
|
|
51
|
-
Then re-fetch `statusCheckRollup`, `headRefOid`, `state`, `mergeable
|
|
52
|
+
Then re-fetch `statusCheckRollup`, `headRefOid`, `state`, `mergeable`. If the head advanced or state/mergeability changed, route through compare-and-swap re-assessment before reusing evidence or reviewing comments; otherwise re-resolve the brief's Evidence table on the fresh rollup; run the verification command only when the re-resolved table selects the Fallback row and no evidence exists yet for this head (the Pending row never ran it) - otherwise the existing evidence stands: the head is unchanged, so the wave's evidence stays valid and the Stale head row does not fire. On completion or timeout, run the refetch (steps 1-5 above) and re-render the comment section, evidence, findings, and menu; do not re-run claim-check or whole-diff Review solely because the head did not move. On timeout: rows in the completed-`success`/prefix-persists state become `reviewer failed (stale placeholder)` (brief Section C placeholder table); every other `pending` row stays `pending`, merge stays withheld, `wait` renders as row 1 again, then the cell's courses, then Custom.
|
|
52
53
|
|
|
53
54
|
### Teardown
|
|
54
55
|
|
|
@@ -75,15 +75,16 @@ result as not merge-ready. Bot author noted
|
|
|
75
75
|
isCrossRepository, mergeable, headRefOid, files, additions, deletions, reviewDecision }
|
|
76
76
|
- viewer: { login, is_author, permission }
|
|
77
77
|
- status_checks: [ { name, status, conclusion, required, url, workflowName } ] # evidence semantics: Section B Evidence resolution; workflowName from the CheckRun rollup entry (absent on StatusContext)
|
|
78
|
-
- comments: { inline[ { id, updated_at, user_type, ... } ], top_level[ { id, updated_at, user_type, ... } ], review_threads[]? } #
|
|
78
|
+
- comments: { inline[ { id, updated_at, user_type, body, ... } ], top_level[ { id, updated_at, user_type, body, ... } ], review_threads[]? } # retain REST body for source-review deltas; C# identity diffs on id/updated_at, Section C gates placeholder detection on user_type
|
|
79
79
|
- issue: { ref, title, body, acceptance_criteria[], comments[] } | null
|
|
80
80
|
- worktree_discovery: { expected_path, exists, branch, dirty, ahead, behind }
|
|
81
81
|
- truncation_notes: []
|
|
82
82
|
```
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
`--paginate` calls already return.
|
|
84
|
+
Retain `id`, `updated_at`, `body`, and `user_type` (REST `user.type`) in every
|
|
85
|
+
entry under `comments.inline[]` and `comments.top_level[]` from the payload
|
|
86
|
+
the `--paginate` calls already return. Keep body text for the reconciliation
|
|
87
|
+
baseline; do not substitute the drafted reply or triage label.
|
|
87
88
|
`review_threads[]` stays resolution flags only: `C#` identity comes from inline
|
|
88
89
|
and top-level comment ids, so a thread's inline comments are diffed once, as
|
|
89
90
|
inline comments.
|
|
@@ -239,7 +240,7 @@ alone when none is (never inventing ACs either way).
|
|
|
239
240
|
each labeled one of: already-addressed, reasonable, judgment-call - except
|
|
240
241
|
placeholder rows, which carry a state instead of a label. Comment triage never
|
|
241
242
|
mints `P#`/`L#`: a landed reviewer verdict is a labelled `C#`; a concern it
|
|
242
|
-
raises becomes a `P#` only through
|
|
243
|
+
raises becomes a `P#` only through source-backed review on the code (`reference/post-selection-loop.md` `### Re-render` step 4 for refetched body deltas).
|
|
243
244
|
|
|
244
245
|
**Placeholder detection.** A comment - inline or top-level - whose author is
|
|
245
246
|
a GitHub App (digest `user_type == "Bot"`, from REST `user.type`) and whose body's first line starts
|
|
@@ -105,9 +105,13 @@ loop: tracker state is extension state no subagent can read.
|
|
|
105
105
|
|
|
106
106
|
If a gauntlet overrides file exists - checked in order:
|
|
107
107
|
`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
|
|
108
|
-
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
109
|
-
|
|
110
|
-
|
|
108
|
+
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read
|
|
109
|
+
and apply `## conventions` whenever present, without a relevance
|
|
110
|
+
judgment.
|
|
111
|
+
Give this skill's named section precedence over conflicting
|
|
112
|
+
`## conventions` rules. Use other relevant sections - by name match,
|
|
113
|
+
by topic (routing,
|
|
114
|
+
verification, worktrees, etc.), or by workflow convention - to override or
|
|
111
115
|
extend the instructions above. Project-local `AGENTS.md` is already in
|
|
112
116
|
context - check it for project-specific routing tables, service paths, and
|
|
113
117
|
verification commands.
|
|
@@ -35,9 +35,13 @@ Nothing else: no preamble, no restated digest, no file written before item 1 is
|
|
|
35
35
|
|
|
36
36
|
If a gauntlet overrides file exists - checked in order:
|
|
37
37
|
`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
|
|
38
|
-
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
39
|
-
|
|
40
|
-
|
|
38
|
+
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read
|
|
39
|
+
and apply `## conventions` whenever present, without a relevance
|
|
40
|
+
judgment.
|
|
41
|
+
Give this skill's named section precedence over conflicting
|
|
42
|
+
`## conventions` rules. Use other relevant sections - by name match,
|
|
43
|
+
by topic (routing,
|
|
44
|
+
verification, worktrees, etc.), or by workflow convention - to override or
|
|
41
45
|
extend the instructions above. Project-local `AGENTS.md` is already in
|
|
42
46
|
context - check it for project-specific routing tables, service paths, and
|
|
43
47
|
verification commands.
|
|
@@ -123,9 +123,13 @@ owning skill **without** its reset-bearing entry:
|
|
|
123
123
|
## Project overrides
|
|
124
124
|
If a gauntlet overrides file exists - checked in order:
|
|
125
125
|
`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
|
|
126
|
-
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
127
|
-
|
|
128
|
-
|
|
126
|
+
`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read
|
|
127
|
+
and apply `## conventions` whenever present, without a relevance
|
|
128
|
+
judgment.
|
|
129
|
+
Give this skill's named section precedence over conflicting
|
|
130
|
+
`## conventions` rules. Use other relevant sections - by name match,
|
|
131
|
+
by topic (routing,
|
|
132
|
+
verification, worktrees, etc.), or by workflow convention - to override or
|
|
129
133
|
extend the instructions above. Project-local `AGENTS.md` is already in
|
|
130
134
|
context - check it for project-specific routing tables, service paths, and
|
|
131
135
|
verification commands.
|
package/skills/linear/SKILL.md
CHANGED
|
@@ -258,4 +258,4 @@ for product behavior the CLI doesn't expose.
|
|
|
258
258
|
|
|
259
259
|
## Project overrides
|
|
260
260
|
|
|
261
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
261
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands. `## Issue tracker` is the named extension point for this skill.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: receiving-code-review
|
|
3
|
-
description: Use when receiving code review feedback, before implementing suggestions, especially
|
|
3
|
+
description: Use when receiving code review feedback from a human or external reviewer (GitHub review, human partner), before implementing suggestions, especially when feedback is unclear or technically questionable - verify, push back with evidence, never perform agreement; the subagent-driven-development review-fix loop is out of scope
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
> **Related skills:** Verify each fix with `/skill:verification-before-completion`. Use `/skill:test-driven-development` for regression tests.
|
|
@@ -51,7 +51,7 @@ WHY: Items may be related. Partial understanding = wrong implementation.
|
|
|
51
51
|
|
|
52
52
|
**Example:**
|
|
53
53
|
```
|
|
54
|
-
your human partner: "Fix 1-6"
|
|
54
|
+
your human partner: "Fix items 1-6"
|
|
55
55
|
You understand 1,2,3,6. Unclear on 4,5.
|
|
56
56
|
|
|
57
57
|
❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
|
|
@@ -130,6 +130,13 @@ Push back when:
|
|
|
130
130
|
|
|
131
131
|
**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
|
|
132
132
|
|
|
133
|
+
**Example:**
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
Reviewer: "Remove legacy code"
|
|
137
|
+
✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
|
|
138
|
+
```
|
|
139
|
+
|
|
133
140
|
## Gracefully Correcting Your Pushback
|
|
134
141
|
|
|
135
142
|
If you pushed back and were wrong:
|
|
@@ -156,33 +163,6 @@ State the correction factually and move on.
|
|
|
156
163
|
| Partial implementation | Clarify all items first |
|
|
157
164
|
| Can't verify, proceed anyway | State limitation, ask for direction |
|
|
158
165
|
|
|
159
|
-
## Real Examples
|
|
160
|
-
|
|
161
|
-
**Performative Agreement (Bad):**
|
|
162
|
-
```
|
|
163
|
-
Reviewer: "Remove legacy code"
|
|
164
|
-
❌ "You're absolutely right! Let me remove that..."
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
**Technical Verification (Good):**
|
|
168
|
-
```
|
|
169
|
-
Reviewer: "Remove legacy code"
|
|
170
|
-
✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
**YAGNI (Good):**
|
|
174
|
-
```
|
|
175
|
-
Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
|
|
176
|
-
✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
**Unclear Item (Good):**
|
|
180
|
-
```
|
|
181
|
-
your human partner: "Fix items 1-6"
|
|
182
|
-
You understand 1,2,3,6. Unclear on 4,5.
|
|
183
|
-
✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
|
|
184
|
-
```
|
|
185
|
-
|
|
186
166
|
## GitHub Thread Replies
|
|
187
167
|
|
|
188
168
|
When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
|
|
@@ -197,4 +177,4 @@ No performative agreement. Technical rigor always.
|
|
|
197
177
|
|
|
198
178
|
## Project overrides
|
|
199
179
|
|
|
200
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
180
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -51,42 +51,9 @@ subagent({ agent: "code-reviewer", async: false, task: "... filled template ..."
|
|
|
51
51
|
- `{DESCRIPTION}` - Brief summary
|
|
52
52
|
- `{SCOPED_TEST_COMMANDS}` - the scoped verification commands the reviewer may run, or `none`
|
|
53
53
|
|
|
54
|
-
**3. Act on feedback:**
|
|
55
|
-
- Fix Critical issues immediately
|
|
56
|
-
- Fix Moderate issues before proceeding
|
|
57
|
-
- Note Minor issues for later
|
|
58
|
-
- Push back if reviewer is wrong (with reasoning)
|
|
59
|
-
|
|
60
54
|
**Fix rounds.** Critical and Moderate findings trigger a fix round; when dispatched from an orchestrating skill, fixes go to `implementer` subagents (per the orchestrator's no-self-coding rule), fanned out per `dispatching-parallel-agents` "Fix fan-out" when the review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings. Before fanning out, validate the review's `Parallel-safe:` line with the structural probe in `dispatching-parallel-agents` § Fix fan-out (exactly-one-line grammar check, one re-ask, then explicit sequential fallback). After integration and the project's test command, re-dispatch the reviewer once on the integrated delta in the foreground with top-level `async: false`; await its terminal result. If Critical or Moderate findings remain, run one more fix round and one more foreground re-review; still failing → escalate to the user. Minor findings never trigger the fan-out.
|
|
61
55
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
```
|
|
65
|
-
[Just completed Task 2: Add verification function]
|
|
66
|
-
|
|
67
|
-
You: Let me request code review before proceeding.
|
|
68
|
-
|
|
69
|
-
BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
|
|
70
|
-
HEAD_SHA=$(git rev-parse HEAD)
|
|
71
|
-
|
|
72
|
-
[Dispatch code-reviewer subagent]
|
|
73
|
-
WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
|
|
74
|
-
PLAN_OR_REQUIREMENTS: Task 2 from doc/plans/deployment-plan.md
|
|
75
|
-
BASE_SHA: a7981ec
|
|
76
|
-
HEAD_SHA: 3df7661
|
|
77
|
-
SCOPED_TEST_COMMANDS: none (whole-branch review; orchestrator gate owns execution)
|
|
78
|
-
DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
|
|
79
|
-
|
|
80
|
-
[Subagent returns]:
|
|
81
|
-
Strengths: Clean architecture, real tests
|
|
82
|
-
Issues:
|
|
83
|
-
Moderate: Missing progress indicators
|
|
84
|
-
Minor: Magic number (100) for reporting interval
|
|
85
|
-
Assessment: Ready to proceed
|
|
86
|
-
|
|
87
|
-
You: [Fix progress indicators]
|
|
88
|
-
[Continue to Task 3]
|
|
89
|
-
```
|
|
56
|
+
Take the recipient stance from `receiving-code-review`: verify each finding, answer a wrong finding with evidence, defer Minor items explicitly.
|
|
90
57
|
|
|
91
58
|
## Integration with Workflows
|
|
92
59
|
|
|
@@ -107,13 +74,8 @@ You: [Fix progress indicators]
|
|
|
107
74
|
- Proceed with unfixed Moderate issues
|
|
108
75
|
- Argue with valid technical feedback
|
|
109
76
|
|
|
110
|
-
**If reviewer wrong:**
|
|
111
|
-
- Push back with technical reasoning
|
|
112
|
-
- Show code/tests that prove it works
|
|
113
|
-
- Request clarification
|
|
114
|
-
|
|
115
77
|
See template at: `code-reviewer.md` in this skill directory
|
|
116
78
|
|
|
117
79
|
## Project overrides
|
|
118
80
|
|
|
119
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
81
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -15,7 +15,7 @@ You are reviewing code changes for production readiness.
|
|
|
15
15
|
2. Compare against {PLAN_OR_REQUIREMENTS}
|
|
16
16
|
3. Check code quality, architecture, testing
|
|
17
17
|
4. Categorize issues by severity
|
|
18
|
-
5.
|
|
18
|
+
5. Report each plan deviation as a finding: what the plan says, what the code does, whether the deviation is acceptable.
|
|
19
19
|
6. Assess production readiness
|
|
20
20
|
|
|
21
21
|
SCOPED_TEST_COMMANDS: {SCOPED_TEST_COMMANDS}
|
|
@@ -25,9 +25,7 @@ SCOPED_TEST_COMMANDS: {SCOPED_TEST_COMMANDS}
|
|
|
25
25
|
Before writing the report:
|
|
26
26
|
|
|
27
27
|
- **Not everything is Critical.** Reserve Critical for bugs, data loss, security, broken functionality. A missing helper method is Moderate. A naming preference is Minor.
|
|
28
|
-
- **Lead with strengths.** Accurate praise earns the implementer's trust on the critique that follows. Generic praise ("good code") undermines it.
|
|
29
28
|
- **If you wouldn't block a PR over it, it's not Critical.** Be honest with yourself about severity before assigning it.
|
|
30
|
-
- **Plan deviations get their own treatment.** If the implementation diverged from the spec/plan — added scope, removed scope, changed an interface — call it out under a dedicated "Plan Deviations" heading, not buried in Critical or Minor.
|
|
31
29
|
|
|
32
30
|
## What Was Implemented
|
|
33
31
|
|
|
@@ -80,124 +78,4 @@ git diff {BASE_SHA}..{HEAD_SHA}
|
|
|
80
78
|
- Documentation complete?
|
|
81
79
|
- No obvious bugs?
|
|
82
80
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
### Strengths
|
|
86
|
-
[What's well done? Be specific.]
|
|
87
|
-
|
|
88
|
-
### Plan Deviations
|
|
89
|
-
[Did the implementation diverge from {PLAN_OR_REQUIREMENTS}? List each deviation with: what the spec said, what the code does, whether the deviation is acceptable. If none, write "None."]
|
|
90
|
-
|
|
91
|
-
### Issues
|
|
92
|
-
|
|
93
|
-
#### Critical (Must Fix)
|
|
94
|
-
[Bugs, security issues, data loss risks, broken functionality]
|
|
95
|
-
|
|
96
|
-
#### Moderate (Should Fix)
|
|
97
|
-
[Architecture problems, missing features, poor error handling, test gaps]
|
|
98
|
-
|
|
99
|
-
#### Minor (Nice to Have)
|
|
100
|
-
[Code style, optimization opportunities, documentation improvements]
|
|
101
|
-
|
|
102
|
-
**For each issue:**
|
|
103
|
-
- `Fn` label - globally unique, numbered across the whole report (no restart per severity section)
|
|
104
|
-
- File:line reference
|
|
105
|
-
- What's wrong
|
|
106
|
-
- Why it matters
|
|
107
|
-
- How to fix (if not obvious)
|
|
108
|
-
- `touched-files:` - files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
|
|
109
|
-
- `touched-resources:` - shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
|
|
110
|
-
|
|
111
|
-
### Recommendations
|
|
112
|
-
[Improvements for code quality, architecture, or process]
|
|
113
|
-
|
|
114
|
-
### Assessment
|
|
115
|
-
|
|
116
|
-
**Ready to merge?** [Yes/No/With fixes]
|
|
117
|
-
|
|
118
|
-
**Reasoning:** [Technical assessment in 1-2 sentences]
|
|
119
|
-
|
|
120
|
-
### Fix-concurrency certification
|
|
121
|
-
|
|
122
|
-
On any issue-bearing review, emit one partition line over the
|
|
123
|
-
`Fn` IDs assigned above:
|
|
124
|
-
|
|
125
|
-
<!-- grammar identical to agents/conformance-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
|
|
126
|
-
|
|
127
|
-
```
|
|
128
|
-
Parallel-safe: <group>[; <group>]*
|
|
129
|
-
<group> = <comma-separated finding-id list> " disjoint"
|
|
130
|
-
| <finding-id> " conflicts " <finding-id> " (" <reason> ")"
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
|
|
134
|
-
|
|
135
|
-
IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
|
|
136
|
-
concurrently). Any file OR runtime-resource overlap between two findings' fixes
|
|
137
|
-
forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
|
|
138
|
-
port, fixture, external service, shared temp path. When you cannot confidently
|
|
139
|
-
certify a pair disjoint, mark them `conflicts` (conservative default = serial).
|
|
140
|
-
|
|
141
|
-
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.
|
|
142
|
-
|
|
143
|
-
## Critical Rules
|
|
144
|
-
|
|
145
|
-
**DO:**
|
|
146
|
-
- Categorize by actual severity (not everything is Critical)
|
|
147
|
-
- Be specific (file:line, not vague)
|
|
148
|
-
- Explain WHY issues matter
|
|
149
|
-
- Acknowledge strengths
|
|
150
|
-
- Give clear verdict
|
|
151
|
-
|
|
152
|
-
**DON'T:**
|
|
153
|
-
- Say "looks good" without checking
|
|
154
|
-
- Mark nitpicks as Critical
|
|
155
|
-
- Give feedback on code you didn't review
|
|
156
|
-
- Be vague ("improve error handling")
|
|
157
|
-
- Avoid giving a clear verdict
|
|
158
|
-
|
|
159
|
-
## Example Output
|
|
160
|
-
|
|
161
|
-
```
|
|
162
|
-
### Strengths
|
|
163
|
-
- Clean database schema with proper migrations (db.ts:15-42)
|
|
164
|
-
- Comprehensive test coverage (18 tests, all edge cases)
|
|
165
|
-
- Good error handling with fallbacks (summarizer.ts:85-92)
|
|
166
|
-
|
|
167
|
-
### Issues
|
|
168
|
-
|
|
169
|
-
#### Moderate
|
|
170
|
-
F1. **Missing help text in CLI wrapper**
|
|
171
|
-
- File: index-conversations:1-31
|
|
172
|
-
- Issue: No --help flag, users won't discover --concurrency
|
|
173
|
-
- Fix: Add --help case with usage examples
|
|
174
|
-
- touched-files: index-conversations.ts
|
|
175
|
-
- touched-resources: none
|
|
176
|
-
|
|
177
|
-
F2. **Date validation missing**
|
|
178
|
-
- File: search.ts:25-27
|
|
179
|
-
- Issue: Invalid dates silently return no results
|
|
180
|
-
- Fix: Validate ISO format, throw error with example
|
|
181
|
-
- touched-files: search.ts
|
|
182
|
-
- touched-resources: none
|
|
183
|
-
|
|
184
|
-
#### Minor
|
|
185
|
-
F3. **Progress indicators**
|
|
186
|
-
- File: indexer.ts:130
|
|
187
|
-
- Issue: No "X of Y" counter for long operations
|
|
188
|
-
- Impact: Users don't know how long to wait
|
|
189
|
-
- touched-files: indexer.ts
|
|
190
|
-
- touched-resources: none
|
|
191
|
-
|
|
192
|
-
### Recommendations
|
|
193
|
-
- Add progress reporting for user experience
|
|
194
|
-
- Consider config file for excluded projects (portability)
|
|
195
|
-
|
|
196
|
-
### Assessment
|
|
197
|
-
|
|
198
|
-
**Ready to merge: With fixes**
|
|
199
|
-
|
|
200
|
-
**Reasoning:** Core implementation is solid with good architecture and tests. Moderate issues (help text, date validation) are easily fixed and don't affect core functionality.
|
|
201
|
-
|
|
202
|
-
Parallel-safe: F1,F2,F3 disjoint
|
|
203
|
-
```
|
|
81
|
+
Report in the output format `agents/code-reviewer.md` defines in your system prompt.
|
|
@@ -159,4 +159,4 @@ Single pass — no automatic re-roast loop. The user can invoke this skill again
|
|
|
159
159
|
|
|
160
160
|
## Project overrides
|
|
161
161
|
|
|
162
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
162
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -246,7 +246,7 @@ Claims about user-visible/UI behavior need evidence: screenshots/artifacts via r
|
|
|
246
246
|
|
|
247
247
|
## Ticket wording
|
|
248
248
|
|
|
249
|
-
Read `reference/ticket-wording.md` (resolve the path against this skill's own directory) and apply it - the self-containment contract lives there; a link alone is not the contract in hand. Repo comms style (found via the ladder) still tunes tone and format - where tone and format explicitly exclude density and brevity - but the contract (its rules 2-8) yields only to an overrides-file section that explicitly addresses ticket wording (e.g. a `## Ticket wording` heading in the gauntlet overrides file).
|
|
249
|
+
Read `reference/ticket-wording.md` (resolve the path against this skill's own directory) and apply it - the self-containment contract lives there; a link alone is not the contract in hand. Repo comms style (found via the ladder) still tunes tone and format - where tone and format explicitly exclude density and brevity - but the contract (its rules 2-8) yields only to an overrides-file section that explicitly addresses ticket wording (e.g. a `## Ticket wording` heading in the gauntlet overrides file). Do not let generic density/brevity norms from the capability ladder, AGENTS.md, or `## conventions` weaken the ticket-wording contract; apply a conventions override to it only when the rule explicitly addresses ticket wording. Remaining defaults:
|
|
250
250
|
|
|
251
251
|
- **Minimal-to-actionable, split scoping:** Context/Problem/Idea are the shortest prose that passes the contract's self-containment test - understandable and triagable by a reader who has never opened the repo; the ACs remain the part a stranger (human or LLM) can act on AND verify - implementer-facing per contract rule 1. Every sentence earns its place.
|
|
252
252
|
- Active voice, named actor; no filler ("comprehensive", "successfully", restated-goal paragraphs).
|
|
@@ -320,4 +320,4 @@ Read this when applying the AC integrity gate (drafting, repairing, or adjudicat
|
|
|
320
320
|
|
|
321
321
|
## Project overrides
|
|
322
322
|
|
|
323
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
323
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -179,7 +179,7 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
|
|
|
179
179
|
|
|
180
180
|
**Caveat:** each task must be independently runnable and verifiable in a fresh worktree — no reliance on uncommitted local state. `pi-cohort` symlinks `node_modules`; repos needing other per-worktree setup must account for it.
|
|
181
181
|
|
|
182
|
-
|
|
182
|
+
Pass the worktree's absolute path as the top-level `cwd` on every dispatch; rule and rationale: `dispatching-parallel-agents` "pi-cohort Integration".
|
|
183
183
|
|
|
184
184
|
```bash
|
|
185
185
|
REPORT_DIR=$(mktemp -d)
|
|
@@ -226,20 +226,52 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
|
|
|
226
226
|
|
|
227
227
|
**Happy-path run - first action of this step, only when the plan header carries a `**Happy path:**` line or the diff selects a row.** The overrides file's `## Happy path` table (schema in the README overrides contract) names path-prefixed rows; the plan header's line is the plan-time default.
|
|
228
228
|
|
|
229
|
-
1.
|
|
230
|
-
2.
|
|
231
|
-
3. Snapshot `git -C "<worktree>" status --porcelain --untracked-files=all`, then run, with `<duration>` = the row's `Timeout` (default `10m`) and `HP_CMD` holding the row's command verbatim:
|
|
229
|
+
1. Re-derive the row from `git -C "<worktree>" diff --name-only <base>..HEAD` (`<base>` = the branch point): two or more non-`cross-cutting` rows, or a path inside the `cross-cutting` row's own `Paths` and inside no other row's -> `cross-cutting`, taking precedence (no `cross-cutting` row -> no run and no outcome line); else paths inside exactly one non-`cross-cutting` row's `Paths` -> that row; none -> no run and no outcome line. Run the diff-derived row; when it differs from the header label, record `row: <diff-derived> (header: <label>)` in `summary.txt`.
|
|
230
|
+
2. Substitute shell-quoted literal values for every placeholder in this one bash block: the absolute worktree path, command verbatim, first command token after leading `NAME=value` assignments, duration (default `10m`), diff-derived row, and optional header label (use the row label when absent). Derive the token from the declared command without evaluating it or parsing general shell grammar. Run the entire block in one tool call; do not carry shell variables between calls. Read its printed summary path and outcome for subsequent tools.
|
|
232
231
|
|
|
232
|
+
<!-- happy-path-shell -->
|
|
233
233
|
```bash
|
|
234
|
-
|
|
235
|
-
|
|
234
|
+
HP_WORKTREE={{HP_WORKTREE}}
|
|
235
|
+
HP_CMD={{HP_COMMAND}}
|
|
236
|
+
HP_TOKEN={{HP_TOKEN}}
|
|
237
|
+
HP_DURATION={{HP_DURATION}}
|
|
238
|
+
HP_ROW={{HP_ROW}}
|
|
239
|
+
HP_HEADER={{HP_HEADER}}
|
|
240
|
+
HP_DIR=$(mktemp -d) || exit 1
|
|
241
|
+
HEAD=$(git -C "$HP_WORKTREE" rev-parse HEAD) || exit 1
|
|
242
|
+
HP_LABEL=$HP_ROW
|
|
243
|
+
if [[ "$HP_HEADER" != "$HP_ROW" ]]; then HP_LABEL="$HP_ROW (header: $HP_HEADER)"; fi
|
|
244
|
+
if ! TO=$(command -v timeout || command -v gtimeout); then
|
|
245
|
+
OUTCOME='happy-path: not run - no timeout binary'
|
|
246
|
+
elif [[ -z "$HP_TOKEN" || -z "${HP_CMD//[[:space:]]/}" ]] || ! (cd "$HP_WORKTREE" && command -v "$HP_TOKEN" >/dev/null); then
|
|
247
|
+
OUTCOME='happy-path: not run - command not found'
|
|
248
|
+
else
|
|
249
|
+
BEFORE=$(git -C "$HP_WORKTREE" status --porcelain --untracked-files=all) || exit 1
|
|
250
|
+
if (cd "$HP_WORKTREE" && "$TO" -k 30s "$HP_DURATION" bash -c "$HP_CMD") >"$HP_DIR/transcript.log" 2>&1; then
|
|
251
|
+
EXIT=0
|
|
252
|
+
else
|
|
253
|
+
EXIT=$?
|
|
254
|
+
fi
|
|
255
|
+
AFTER=$(git -C "$HP_WORKTREE" status --porcelain --untracked-files=all) || exit 1
|
|
256
|
+
if [[ "$BEFORE" != "$AFTER" ]]; then
|
|
257
|
+
OUTCOME="happy-path: failed - dirtied worktree: ${AFTER//$'\n'/; }"
|
|
258
|
+
elif [[ "$EXIT" == 0 ]]; then
|
|
259
|
+
OUTCOME='happy-path: passed'
|
|
260
|
+
elif [[ "$EXIT" == 75 ]]; then
|
|
261
|
+
OUTCOME="happy-path: not run - environment unavailable: $(tail -n 1 "$HP_DIR/transcript.log")"
|
|
262
|
+
elif [[ "$EXIT" == 124 || "$EXIT" == 137 ]]; then
|
|
263
|
+
OUTCOME="happy-path: failed - timed out after $HP_DURATION"
|
|
264
|
+
elif [[ "$EXIT" == 126 ]]; then
|
|
265
|
+
OUTCOME='happy-path: not run - not executable'
|
|
266
|
+
else
|
|
267
|
+
OUTCOME="happy-path: failed (exit $EXIT)"
|
|
268
|
+
fi
|
|
269
|
+
fi
|
|
270
|
+
{ printf '%s\nhead: %s\nrow: %s\n' "$OUTCOME" "$HEAD" "$HP_LABEL"; if [[ -f "$HP_DIR/transcript.log" ]]; then printf '\n'; tail -n 200 "$HP_DIR/transcript.log"; fi; } >"$HP_DIR/summary.txt" || exit 1
|
|
271
|
+
printf 'summary: %s\noutcome: %s\n' "$HP_DIR/summary.txt" "$OUTCOME"
|
|
236
272
|
```
|
|
237
273
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
```bash
|
|
241
|
-
{ echo "<outcome line per table>"; echo "head: $(git -C "<abs worktree path>" rev-parse HEAD)"; echo "row: <label>"; echo; tail -n 200 "$HP_DIR/transcript.log"; } >"$HP_DIR/summary.txt"
|
|
242
|
-
```
|
|
274
|
+
3. If the block exits non-zero or its printed summary is missing/unreadable, stop verification and report the shell error; never dispatch conformance with the selected run omitted. Distinguish this runner failure from a command's `failed`/`not run` outcome recorded in a readable summary. Treat any status difference (tracked or untracked residue) as failed regardless of exit code. Never stage or commit the listed paths as deliverables; remove untracked residue and restore tracked residue (`git -C "<worktree>" checkout -- <paths>`) explicitly before the conformance dispatch, so the tree is clean when the audit-time input rule runs.
|
|
243
275
|
|
|
244
276
|
| Condition | Outcome line |
|
|
245
277
|
|---|---|
|
|
@@ -252,7 +284,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
|
|
|
252
284
|
| any other non-zero | `happy-path: failed (exit <n>)` |
|
|
253
285
|
| no header line and no diff-derived row | no run, no outcome line |
|
|
254
286
|
|
|
255
|
-
A timeout is `failed`, not `not run`: a consumer that never receives its message hangs, and the reviewer must see it; `not run` is reserved for a command that never executed. `timeout -k 30s` sends `TERM` then `KILL`; a script that does not trap `TERM` leaves its stack up, and the next run's exit 75 surfaces that. The full `transcript.log` stays in `$HP_DIR` for the human; the reviewer receives `summary.txt` only (outcome, `head:`, `row:`, 200-line tail). A `failed` or `not run` outcome never stops the flow and never becomes a repair item at this step - it is evidence for the audit; `$HP_DIR` and the outcome carry into the fix loop per `conformance-check.md`.
|
|
287
|
+
A timeout is `failed`, not `not run`: a consumer that never receives its message hangs, and the reviewer must see it; `not run` is reserved for a command that never executed. `timeout -k 30s` sends `TERM` then `KILL`; a script that does not trap `TERM` leaves its stack up, and the next run's exit 75 surfaces that. The full `transcript.log` stays in `$HP_DIR` for the human; the reviewer receives `summary.txt` only (outcome, `head:`, `row:`, 200-line tail). A `failed` or `not run` outcome never stops the flow and never becomes a repair item at this step - it is evidence for the audit; `$HP_DIR` and the outcome carry into the fix loop per `conformance-check.md`. Never split the shell block across calls.
|
|
256
288
|
|
|
257
289
|
Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-2 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, the full diff, and - when a run happened - `Happy path: <abs path to $HP_DIR/summary.txt> (<outcome>)` (`<outcome>` = the outcome line without its `happy-path: ` prefix). Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop reuses durable `Gn` gap indices as defined in conformance-check.md; it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; on escalation, do not complete verify, stop and report.
|
|
258
290
|
4. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`, then - exactly when a happy-path run happened - `happy-path: <value of the reviewer's Happy path: line from the final audit, the text after Happy path: >`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.
|
|
@@ -286,4 +318,4 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
|
|
|
286
318
|
|
|
287
319
|
## Project overrides
|
|
288
320
|
|
|
289
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
321
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -23,11 +23,7 @@ Dispatch a subagent with the code-reviewer template:
|
|
|
23
23
|
- Is the implementation following the file structure from the plan?
|
|
24
24
|
- 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.)
|
|
25
25
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
Emit finding IDs and the `Parallel-safe:` line per that contract, then the `Behaviour-change:` line.
|
|
29
|
-
|
|
30
|
-
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.
|
|
26
|
+
Read `Verdict:` and the footer lines from the report; `agents/code-reviewer.md` defines its format.
|
|
31
27
|
|
|
32
28
|
## Re-review: trajectory verdict
|
|
33
29
|
|
|
@@ -103,7 +103,7 @@ Dispatch a subagent with this prompt:
|
|
|
103
103
|
|
|
104
104
|
**Testing:**
|
|
105
105
|
- Do tests actually verify behavior (not just mock behavior)?
|
|
106
|
-
- Did I follow TDD
|
|
106
|
+
- Did I follow TDD (step 2)?
|
|
107
107
|
- Are tests comprehensive?
|
|
108
108
|
|
|
109
109
|
If you find issues during self-review, fix them now before reporting.
|
|
@@ -91,32 +91,7 @@ Dispatch a subagent with this prompt:
|
|
|
91
91
|
|
|
92
92
|
**Verify by reading code, not by trusting report.**
|
|
93
93
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
Label every finding with a globally unique ID `F1..Fn`, numbered across the whole
|
|
97
|
-
report (no restart per severity section). Each finding carries:
|
|
98
|
-
|
|
99
|
-
- `touched-files:` — files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
|
|
100
|
-
- `touched-resources:` — shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
|
|
101
|
-
|
|
102
|
-
On any issue-bearing review, end the findings with one partition line (this is the
|
|
103
|
-
final line of the report unless a re-review trajectory verdict is also required — see below):
|
|
104
|
-
|
|
105
|
-
<!-- grammar identical to agents/conformance-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
Parallel-safe: <group>[; <group>]*
|
|
109
|
-
<group> = <comma-separated finding-id list> " disjoint"
|
|
110
|
-
| <finding-id> " conflicts " <finding-id> " (" <reason> ")"
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
|
|
114
|
-
|
|
115
|
-
IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
|
|
116
|
-
concurrently). Any file OR runtime-resource overlap between two findings' fixes
|
|
117
|
-
forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
|
|
118
|
-
port, fixture, external service, shared temp path. When you cannot confidently
|
|
119
|
-
certify a pair disjoint, mark them `conflicts` (conservative default = serial).
|
|
94
|
+
Report in the output format `agents/spec-reviewer.md` defines in your system prompt.
|
|
120
95
|
|
|
121
96
|
## Re-review: trajectory verdict
|
|
122
97
|
|
|
@@ -144,8 +119,4 @@ Dispatch a subagent with this prompt:
|
|
|
144
119
|
|
|
145
120
|
If you found no issues, report success as usual and omit this line.
|
|
146
121
|
First reviews (no previous-report section) omit this line.
|
|
147
|
-
|
|
148
|
-
Report:
|
|
149
|
-
- ✅ Spec compliant (if everything matches after code inspection)
|
|
150
|
-
- ❌ Issues found: [list specifically what's missing or extra, with file:line references]
|
|
151
122
|
```
|
|
@@ -227,4 +227,4 @@ phase_tracker({ action: "complete", phase: "implement" })
|
|
|
227
227
|
|
|
228
228
|
## Project overrides
|
|
229
229
|
|
|
230
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
230
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -200,4 +200,4 @@ Re-run tests after rebasing.
|
|
|
200
200
|
|
|
201
201
|
## Project overrides
|
|
202
202
|
|
|
203
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
203
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -168,4 +168,4 @@ phase_tracker({ action: "complete", phase: "verify" })
|
|
|
168
168
|
|
|
169
169
|
## Project overrides
|
|
170
170
|
|
|
171
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
171
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -309,4 +309,4 @@ Auto-invoke `/skill:subagent-driven-development` in this session. Do not wait fo
|
|
|
309
309
|
|
|
310
310
|
## Project overrides
|
|
311
311
|
|
|
312
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
312
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|
|
@@ -438,4 +438,4 @@ If you follow TDD for code, follow it for skills.
|
|
|
438
438
|
|
|
439
439
|
## Project overrides
|
|
440
440
|
|
|
441
|
-
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it.
|
|
441
|
+
If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
|