opencode-swarm 7.126.6 → 7.127.1
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/.opencode/skills/issue-tracer/SKILL.md +7 -6
- package/.opencode/skills/issue-tracer/references/install.md +5 -3
- package/.opencode/skills/swarm-pr-feedback/SKILL.md +87 -13
- package/.opencode/skills/swarm-pr-review/SKILL.md +313 -109
- package/.opencode/skills/swarm-pr-review/references/parser-dry-run.md +5 -3
- package/.opencode/skills/swarm-pr-review/references/prompt-templates.md +5 -5
- package/dist/background/candidate-parser.d.ts +1 -0
- package/dist/background/pending-delegations.d.ts +7 -0
- package/dist/background/workspace-snapshot.d.ts +20 -0
- package/dist/cli/{curator-llm-factory-ffseqhr4.js → curator-llm-factory-4t2h2p60.js} +3 -3
- package/dist/cli/{curator-zmff7bha.js → curator-qqd1fvvg.js} +3 -3
- package/dist/cli/{guardrail-explain-n4eyw2ak.js → guardrail-explain-4yg67c3t.js} +4 -4
- package/dist/cli/{hive-promoter-s60fcnq0.js → hive-promoter-14jh86kj.js} +3 -3
- package/dist/cli/{index-mg54y5gc.js → index-40zn444p.js} +38 -1
- package/dist/cli/{index-w3q49fy4.js → index-8cnpsbk5.js} +1 -1
- package/dist/cli/{index-8exjgmrz.js → index-bn3w6ym4.js} +49 -24
- package/dist/cli/{index-0cz1ws47.js → index-ecxwhwz7.js} +2 -0
- package/dist/cli/{index-p3cksay8.js → index-pbw1ncre.js} +4 -4
- package/dist/cli/index.js +3 -3
- package/dist/cli/{pending-delegations-7j8xqg5f.js → pending-delegations-a1bbpp8b.js} +1 -1
- package/dist/cli/{workspace-snapshot-c9pxxt9a.js → workspace-snapshot-aa0ggevw.js} +3 -1
- package/dist/commands/registry.d.ts +1 -1
- package/dist/hooks/pr-workflow-gate.d.ts +45 -1
- package/dist/hooks/pr-workflow-response-gate.d.ts +7 -5
- package/dist/index.js +22 -17
- package/dist/tools/dispatch-lanes.d.ts +5 -0
- package/package.json +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: swarm-pr-review
|
|
3
3
|
audience: swarm-plugin
|
|
4
|
-
description: Run a graph-guided, tool-augmented PR review using context packing, parallel exploration, mandatory repository-agnostic
|
|
4
|
+
description: Run a graph-guided, tool-augmented PR review using context packing, parallel exploration, mandatory repository-agnostic risk-family coverage with dispatch scaled to diff size and risk, independent reviewer validation, critic challenge, and metrics writeback. Use for deep pull request review with low false-positive tolerance and high recall in any repository, on any agent harness (structured lane controller, native parallel subagents, or single-context sequential passes).
|
|
5
5
|
disable-model-invocation: true
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -11,7 +11,7 @@ Run a structured, high-confidence PR review that maximizes valid findings withou
|
|
|
11
11
|
|
|
12
12
|
The review ladder is:
|
|
13
13
|
|
|
14
|
-
**Scope → obligations → context pack → deterministic signals → parallel explorers →
|
|
14
|
+
**Scope → obligations → context pack → deterministic signals → parallel explorers → repository-agnostic risk-family coverage (dispatch scaled by depth tier) → independent reviewer validation → critic challenge → grouped synthesis → metrics / knowledge writeback.**
|
|
15
15
|
|
|
16
16
|
## Handoff To PR Feedback
|
|
17
17
|
|
|
@@ -23,12 +23,15 @@ without running a fresh broad review.
|
|
|
23
23
|
|
|
24
24
|
When a review finishes with actionable validated findings, stop and ask the user
|
|
25
25
|
whether to continue into `swarm-pr-feedback`. Do not auto-dispatch fix work from
|
|
26
|
-
`PR_REVIEW`. Instead, write a handoff artifact under
|
|
27
|
-
`.swarm/pr-review/<run_id>/feedback-handoff.json`
|
|
28
|
-
|
|
26
|
+
`PR_REVIEW`. Instead, write a handoff artifact — under Profile A,
|
|
27
|
+
`.swarm/pr-review/<run_id>/feedback-handoff.json` via `write_pr_review_artifact`;
|
|
28
|
+
under Profiles B/C (no controller — see Runtime Capability Profiles),
|
|
29
|
+
`pr-review/<run_id>/feedback-handoff.json` inside your session/task workspace,
|
|
30
|
+
never under `.swarm/` — and include the continuation prompt with that exact
|
|
31
|
+
path substituted for `<handoff_artifact_path>`:
|
|
29
32
|
|
|
30
33
|
```text
|
|
31
|
-
/swarm pr-feedback <PR_URL> continue from
|
|
34
|
+
/swarm pr-feedback <PR_URL> continue from <handoff_artifact_path>
|
|
32
35
|
```
|
|
33
36
|
|
|
34
37
|
`<run_id>` is a stable identifier for this review run, such as
|
|
@@ -55,11 +58,69 @@ Never APPROVE a PR with unresolved CRITICAL findings. Do not silently drop overc
|
|
|
55
58
|
|
|
56
59
|
---
|
|
57
60
|
|
|
61
|
+
## Runtime Capability Profiles
|
|
62
|
+
|
|
63
|
+
This protocol runs on any agent harness. Before Phase 0, detect which profile
|
|
64
|
+
this session is in by checking the actual tool list — never assume from the
|
|
65
|
+
harness name, and never guess:
|
|
66
|
+
|
|
67
|
+
- **Profile A — structured PR-workflow controller.** The swarm plugin's
|
|
68
|
+
controller tools are available in this session: `dispatch_lanes_async`,
|
|
69
|
+
`collect_lane_results`, `retrieve_lane_output`, `parse_lane_candidates`,
|
|
70
|
+
`write_pr_review_artifact`, `write_pr_review_trigger_eval`,
|
|
71
|
+
`complete_pr_workflow`. Typical host: OpenCode with the swarm plugin. The
|
|
72
|
+
controller mechanically enforces this skill's accounting: it computes the
|
|
73
|
+
depth tier itself from the bound merge-base diff (never from caller
|
|
74
|
+
claims), enforces the tier's lane floors and full dimension/family
|
|
75
|
+
partitions for consolidated dispatch, and gates structured reviewer/critic
|
|
76
|
+
batches and the response gate. Its acceptance rules are authoritative, and
|
|
77
|
+
where the scaled-dispatch guidance below is more permissive than the
|
|
78
|
+
active controller, the controller wins. Bypassing an active controller —
|
|
79
|
+
blocking `dispatch_lanes`, direct Task/agent dispatch, prose verdicts — is
|
|
80
|
+
BLOCKED.
|
|
81
|
+
- **Profile B — native parallel subagents, no controller.** The controller
|
|
82
|
+
tools are absent, but the harness can spawn independent fresh-context
|
|
83
|
+
subagents (for example Claude Code's `Agent`/`Task` tool, or the native
|
|
84
|
+
subagent mechanisms in Codex and ZCode). Run the same phases, role
|
|
85
|
+
boundaries, row contracts, and join barriers; you are the accounting layer
|
|
86
|
+
the controller would otherwise be: bind the exact `pr_head_sha` in every
|
|
87
|
+
lane prompt, record per-lane provenance (lane id, head SHA) on every ledger
|
|
88
|
+
row, settle every lane before the next phase begins, and persist ledgers to
|
|
89
|
+
files in your harness's session/task workspace. Never write runtime
|
|
90
|
+
artifacts under `.swarm/` — that directory belongs to the plugin controller.
|
|
91
|
+
- **Profile C — single context, no subagents.** The harness cannot spawn
|
|
92
|
+
independent subagents in-session. Execute the same phases as strictly
|
|
93
|
+
separated sequential passes — candidate generation, then reviewer
|
|
94
|
+
validation, then critic challenge — re-deriving rather than restating
|
|
95
|
+
earlier reasoning in each pass, with the same ledger rows and per-family
|
|
96
|
+
attestations. Disclose in the validation provenance that reviewer/critic
|
|
97
|
+
independence was procedural (separate passes in one context), not
|
|
98
|
+
contextual.
|
|
99
|
+
|
|
100
|
+
| Harness (typical) | Profile | Lane dispatch | Ledger persistence | Completion gate |
|
|
101
|
+
|---|---|---|---|---|
|
|
102
|
+
| OpenCode + swarm plugin | A | `dispatch_lanes_async` / `collect_lane_results` | `write_pr_review_artifact`, `write_pr_review_trigger_eval` | `complete_pr_workflow` |
|
|
103
|
+
| Claude Code | B | parallel `Agent`/`Task` subagents | ledger files in the session task workspace | Pre-Synthesis Gate checklist |
|
|
104
|
+
| OpenAI Codex | B | parallel subagents (fresh context) | ledger files in working notes | Pre-Synthesis Gate checklist |
|
|
105
|
+
| ZCode | B | parallel subagents (fresh context) | ledger files in working notes | Pre-Synthesis Gate checklist |
|
|
106
|
+
|
|
107
|
+
Verify each row against your own current tool list before relying on it; a
|
|
108
|
+
harness may gain or lose capabilities between versions. OpenCode, Claude Code,
|
|
109
|
+
Codex, and ZCode can all spawn fresh-context subagents in current versions —
|
|
110
|
+
run Profile B wherever the session actually exposes that capability, and
|
|
111
|
+
reserve Profile C for sessions that genuinely lack a subagent mechanism; never
|
|
112
|
+
assign a harness to Profile C by name alone. The absence of the controller is
|
|
113
|
+
NOT a BLOCKED condition — Profiles B and C are first-class execution paths, not degraded fallbacks.
|
|
114
|
+
BLOCKED is reserved for bypassing an active controller and for coverage gaps
|
|
115
|
+
that remain unclosable after bounded retries on any profile.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
58
119
|
## Review Modes
|
|
59
120
|
|
|
60
121
|
### Default layered workflow
|
|
61
122
|
|
|
62
|
-
Always run the default
|
|
123
|
+
Always run the default layered workflow (mechanically enforced under Profile A). Explorers produce only candidates. The orchestrator does not confirm or disprove candidates.
|
|
63
124
|
|
|
64
125
|
### Council mode — opt in only
|
|
65
126
|
|
|
@@ -73,7 +134,7 @@ Council mode applies only when the user explicitly says one of:
|
|
|
73
134
|
- `[MODE: PR_REVIEW … council=true]`
|
|
74
135
|
- `assume all work is wrong`
|
|
75
136
|
|
|
76
|
-
Council mode supplements the default mechanical workflow; it never replaces or weakens it. Even when council mode is triggered, first complete the exact-six
|
|
137
|
+
Council mode supplements the default mechanical workflow; it never replaces or weakens it. Even when council mode is triggered, first complete the base-dimension coverage (the tier-floored base dispatch under Profile A — the exact-six wave at depth tier L), micro-lane ledger persistence, and every repository-agnostic risk-family evaluation at the same exact `pr_head_sha`. Route supplementary council output into the candidate ledger before independent reviewer classification. If the council request arrives after classification has begun, run the council as an additional candidate pass and dispatch a new structured reviewer batch for those candidates before synthesis.
|
|
77
138
|
|
|
78
139
|
---
|
|
79
140
|
|
|
@@ -85,8 +146,8 @@ The orchestrator may:
|
|
|
85
146
|
|
|
86
147
|
- determine scope,
|
|
87
148
|
- build or request the context pack,
|
|
88
|
-
- launch explorers and
|
|
89
|
-
- extract candidates from lane artifacts via `parse_lane_candidates` or
|
|
149
|
+
- launch explorers and the full risk-family micro coverage (every family evaluated; lane count per depth tier and profile),
|
|
150
|
+
- extract candidates from lane artifacts via `parse_lane_candidates` (Profile A) or by collecting the structured `[CANDIDATE]` rows from lane reports (Profiles B/C),
|
|
90
151
|
- filter, group, and chunk candidates for reviewer dispatch,
|
|
91
152
|
- route candidates to reviewers,
|
|
92
153
|
- route reviewer-confirmed findings to critics,
|
|
@@ -99,7 +160,7 @@ The orchestrator MUST NOT:
|
|
|
99
160
|
- silently downgrade or discard an explorer candidate,
|
|
100
161
|
- treat tool output as a confirmed finding,
|
|
101
162
|
- report a finding that no reviewer validated,
|
|
102
|
-
- classify or judge candidates based on preview text alone — always use the structured parser output.
|
|
163
|
+
- classify or judge candidates based on preview text alone — always use the structured parser output (Profile A) or the verbatim-collected `[CANDIDATE]` rows (Profiles B/C).
|
|
103
164
|
|
|
104
165
|
If the orchestrator catches itself validating code, it must stop and delegate validation to a reviewer subagent.
|
|
105
166
|
|
|
@@ -139,8 +200,10 @@ Before launching explorers (Phase 3), perform this exact standalone sequence:
|
|
|
139
200
|
1. Resolve and retain the authoritative full `pr_head_sha` from PR metadata.
|
|
140
201
|
2. Verify the working tree is clean with `git status --porcelain`. If tracked
|
|
141
202
|
changes exist, call `prepare_pr_workflow_checkout` with every explicit dirty
|
|
142
|
-
tracked path
|
|
143
|
-
|
|
203
|
+
tracked path (Profile A). Without the controller, do not blind-stash over
|
|
204
|
+
dirty state: surface tracked changes to the user, or abort. Do not issue
|
|
205
|
+
`git stash` through shell. The controller never stashes untracked files;
|
|
206
|
+
move or remove those manually, or abort.
|
|
144
207
|
3. Fetch the PR head as one standalone command, for example
|
|
145
208
|
`git fetch origin refs/pull/<N>/head`. Do not compose fetch and checkout.
|
|
146
209
|
4. Prove the full commit exists locally with
|
|
@@ -149,12 +212,14 @@ Before launching explorers (Phase 3), perform this exact standalone sequence:
|
|
|
149
212
|
`git switch --detach <full_pr_head_sha>`. Do not use `--track FETCH_HEAD`:
|
|
150
213
|
`FETCH_HEAD` is not a remote-tracking branch.
|
|
151
214
|
6. Confirm `git rev-parse HEAD` equals the full `pr_head_sha`, bind that exact
|
|
152
|
-
head through the first PR-review controller call
|
|
215
|
+
head (Profile A: through the first PR-review controller call; Profiles B/C:
|
|
216
|
+
record it at the top of the findings ledger and repeat it in every lane
|
|
217
|
+
prompt), and finish this before dispatching explorer lanes.
|
|
153
218
|
|
|
154
219
|
Explorer agents read files from the working tree, not from git history. Passing
|
|
155
220
|
the commit range in a prompt cannot substitute for this checkout because
|
|
156
221
|
`Read` / `Glob` / `Grep` operate on the filesystem.
|
|
157
|
-
- Explicitly pass the verified merge-base range (`base_sha...pr_head_sha`) in every explorer delegation so explorers inspect exactly the
|
|
222
|
+
- Explicitly pass the verified merge-base range (`base_sha...pr_head_sha`) in every explorer delegation so explorers inspect exactly the bound PR diff. Include `base_ref` only as the live ref used to recompute `base_sha`; do not substitute a two-dot branch-tip range.
|
|
158
223
|
|
|
159
224
|
If refs cannot be fetched or checked out, state the limitation in the context pack.
|
|
160
225
|
|
|
@@ -359,10 +424,11 @@ For each new commit on the remote:
|
|
|
359
424
|
hand off?
|
|
360
425
|
- Does the remote commit introduce a new branch-state fact the handoff should
|
|
361
426
|
mention?
|
|
362
|
-
3. **Default stance: prefer the remote state as the next baseline.**
|
|
427
|
+
3. **Default stance: prefer the remote state as the next baseline.** When the
|
|
428
|
+
bundled copy is available (plugin runtimes), run the
|
|
363
429
|
`file:.swarm/bundled-skills/parallel-work-check/SKILL.md`
|
|
364
|
-
protocol for the formal decision template
|
|
365
|
-
handoff artifact.
|
|
430
|
+
protocol for the formal decision template; otherwise apply the three
|
|
431
|
+
outcomes below directly. Record the outcome in the handoff artifact.
|
|
366
432
|
|
|
367
433
|
### Step 3 — Three outcomes
|
|
368
434
|
|
|
@@ -476,10 +542,12 @@ The context pack must include, when available:
|
|
|
476
542
|
|
|
477
543
|
## Review Finding Persistence
|
|
478
544
|
|
|
479
|
-
Do not rely on conversation context to preserve review findings.
|
|
480
|
-
`write_pr_review_artifact` with `kind: "findings"`; the controller creates
|
|
481
|
-
appends `.swarm/pr-review/<run_id>/findings.jsonl` without granting generic
|
|
482
|
-
write authority over `.swarm/`.
|
|
545
|
+
Do not rely on conversation context to preserve review findings. On Profile A,
|
|
546
|
+
use `write_pr_review_artifact` with `kind: "findings"`; the controller creates
|
|
547
|
+
and appends `.swarm/pr-review/<run_id>/findings.jsonl` without granting generic
|
|
548
|
+
write authority over `.swarm/`. On Profiles B/C, append the same records to a
|
|
549
|
+
`findings.jsonl` ledger file in your harness's session/task workspace (never
|
|
550
|
+
under `.swarm/`), with the review head SHA recorded at the top of the file.
|
|
483
551
|
|
|
484
552
|
Each persisted finding record must include at least:
|
|
485
553
|
|
|
@@ -498,7 +566,9 @@ Minimum field contract:
|
|
|
498
566
|
- `next_action`: the next required action, such as `route_to_reviewer`,
|
|
499
567
|
`route_to_critic`, `report`, `suppress_with_reason`, or `handoff_to_feedback`.
|
|
500
568
|
|
|
501
|
-
Persist after every major validation boundary
|
|
569
|
+
Persist after every major validation boundary (Profile A via the controller
|
|
570
|
+
calls below; Profiles B/C by appending the same boundary-tagged records to the
|
|
571
|
+
ledger file):
|
|
502
572
|
|
|
503
573
|
1. **Post-explorer:** after Phase 3/4 candidate parsing and before reviewer
|
|
504
574
|
dispatch, call `write_pr_review_artifact` with `boundary: "post_explorer"`
|
|
@@ -614,7 +684,45 @@ Tool candidate rules:
|
|
|
614
684
|
|
|
615
685
|
## Phase 3: Parallel Base Explorer Lanes
|
|
616
686
|
|
|
617
|
-
|
|
687
|
+
### Review depth tiers (size × risk)
|
|
688
|
+
|
|
689
|
+
Before dispatching, classify the PR into a depth tier from the context pack.
|
|
690
|
+
Record the tier and the active capability profile in the ledger and in the
|
|
691
|
+
final validation provenance. The tier scales how many subagents you spawn —
|
|
692
|
+
never which review dimensions or risk families get evaluated:
|
|
693
|
+
|
|
694
|
+
| Tier | Diff shape | Dispatch shape (Profiles B/C) |
|
|
695
|
+
|---|---|---|
|
|
696
|
+
| S | ≤ ~50 changed lines, ≤ 3 files, no risk triggers | Consolidate: 1–2 explorer lanes covering all six dimensions (B), or one candidate-generation pass (C); Phase 4 risk families fold into the same lanes as an explicit per-family checklist |
|
|
697
|
+
| M | ≤ ~500 changed lines, or any risk trigger | Dedicated lanes for the triggered dimensions/families; consolidate the remaining thin dimensions into 1–2 lanes |
|
|
698
|
+
| L | > ~500 changed lines, > ~20 files, multi-subsystem, or security-sensitive surface | Full fan-out: one lane per dimension (six) and per-family micro dispatch in Phase 4 |
|
|
699
|
+
|
|
700
|
+
Risk triggers (any one escalates to at least tier M, and the triggered
|
|
701
|
+
dimension/family always gets a dedicated lane at M and above):
|
|
702
|
+
auth/identity/sessions/permissions/secrets/cryptography; untrusted-input
|
|
703
|
+
parsing or new input/output boundaries; subprocess/shell/filesystem execution;
|
|
704
|
+
concurrency, state machines, retries, caching; dependency, lockfile, install,
|
|
705
|
+
CI, or release changes; public API, schema, config, or migration changes;
|
|
706
|
+
payments or PII handling; generated, vendored, or binary artifacts.
|
|
707
|
+
|
|
708
|
+
Scaling is one-directional: a larger tier or an active controller may demand
|
|
709
|
+
more lanes than the table; nothing — repository size, elapsed time, token
|
|
710
|
+
cost, or predicted simplicity — permits fewer lanes than the classified tier,
|
|
711
|
+
and no tier permits skipping a dimension or family. Under Profile A the
|
|
712
|
+
controller computes the tier itself from the bound `base_sha...pr_head_sha`
|
|
713
|
+
diff (`--numstat` totals; an uncomputable diff fails strict to tier L) and
|
|
714
|
+
mechanically enforces the matching floors on every base and micro batch —
|
|
715
|
+
initial waves and retries alike: tier L requires the historical
|
|
716
|
+
full fan-out (six singleton base lanes, one micro-lane per family, on every
|
|
717
|
+
batch, not only the first), while
|
|
718
|
+
tiers S and M accept consolidated lanes that declare their complete
|
|
719
|
+
`owned_workflow_lanes` set — every dimension and family still owned exactly
|
|
720
|
+
once and attested per family. Risk triggers remain caller-side escalation on
|
|
721
|
+
every profile: dispatch MORE than the floor whenever a trigger warrants it.
|
|
722
|
+
|
|
723
|
+
### Dispatch
|
|
724
|
+
|
|
725
|
+
Under Profile A, launch all base lanes with `dispatch_lanes_async`. Pass the six
|
|
618
726
|
lane specs together, set `mode: "swarm-pr-review:base"`, assign each lane its
|
|
619
727
|
exact `workflow_lane` identifier from the table below, set `max_concurrent` to
|
|
620
728
|
`6`, bind the batch with the exact current `pr_head_sha`, record the returned
|
|
@@ -633,9 +741,23 @@ field, or have lanes read it from a file by absolute path, instead of inlining
|
|
|
633
741
|
the same large blob into all six prompts — oversized inline prompts produce
|
|
634
742
|
malformed or truncated tool-call JSON and force clumsy file workarounds.
|
|
635
743
|
|
|
636
|
-
|
|
744
|
+
All six dimensions must be covered on every PR — "small PR", "docs-only", and
|
|
745
|
+
"CI-only" change what each dimension examines, never whether it is evaluated.
|
|
746
|
+
Every dimension ends in its own `[CANDIDATE]` rows or a fully populated
|
|
747
|
+
per-dimension `[CLEAN]` attestation. Under Profile A at depth tier L this is an exact six-lane gate, not a soft target: the controller rejects an initial base wave with fewer than six singleton lanes, and the review is BLOCKED until the missing lanes are dispatched and settled; "time-saving" is not an exception. At tiers S and M the controller instead requires the initial wave's `owned_workflow_lanes` to partition all six dimensions exactly once across at least the tier's lane floor (S ≥ 1, M ≥ 3, `max_concurrent` equal to the lane count), and settlement demands per-dimension attestation from every consolidated lane — a lane that fails any owned dimension fails them all. Under Profiles B/C, the depth tier governs lane count the same way — a tier-S diff may cover the six dimensions in one or two consolidated lanes — while dimension coverage and per-dimension attestation remain mandatory.
|
|
637
748
|
|
|
638
|
-
|
|
749
|
+
Under Profile B, dispatch the same wave as parallel subagents through your
|
|
750
|
+
harness's subagent tool: one subagent per dimension by default, consolidated
|
|
751
|
+
per the depth tier for small diffs. Every lane prompt must carry the exact
|
|
752
|
+
`pr_head_sha`, the verified `base_sha...pr_head_sha` range, its assigned
|
|
753
|
+
`workflow_lane` identifier(s), and the explorer context contract below; append
|
|
754
|
+
every returned report to the findings ledger with its lane id and head SHA
|
|
755
|
+
before any reviewer dispatch. Under Profile C, run the same lanes as
|
|
756
|
+
sequential candidate-generation passes with the same per-lane ledger records.
|
|
757
|
+
The join barrier is universal: all base lanes settle before Phase 4 completes
|
|
758
|
+
or synthesis begins, whichever layer enforces it.
|
|
759
|
+
|
|
760
|
+
**Incremental collection (Profile A):** While base lanes are running, poll with `collect_lane_results` (without `wait` (or `wait: false`)) to check progress and process settled lanes as they complete — call `retrieve_lane_output` for full text when `output_ref` is present, then extract candidates via `parse_lane_candidates`, update the candidate ledger, validate output quality — while continuing independent architect work (obligation refinement, micro-lane trigger checks, local reads) between polls. Only use `wait: true` if lanes are still pending and no more independent work remains. Under Profile B, harvest each subagent report as it completes and update the ledger between arrivals; block on stragglers only when no independent work remains.
|
|
639
761
|
|
|
640
762
|
Before Phase 4 or synthesis, all base lanes must be settled. `dispatch_lanes_async` accepts a maximum of 8 lanes per call; base lanes (6) and micro-lanes (Phase 4) are dispatched in separate calls by design. Do not let one lane's conclusions bias another lane.
|
|
641
763
|
|
|
@@ -645,14 +767,14 @@ Before Phase 4 or synthesis, all base lanes must be settled. `dispatch_lanes_asy
|
|
|
645
767
|
|
|
646
768
|
For ANY lane that failed (either mode):
|
|
647
769
|
1. **Retry** (max 2 attempts) with materially different parameters — different session or prompt decomposition, while preserving the required structured async mode and exact head provenance.
|
|
648
|
-
2. If a base lane fails, retry only the failed `workflow_lane` identifiers with `dispatch_lanes_async`, `mode: "swarm-pr-review:base"`, the same exact `pr_head_sha`, and explorer agents. The durable gate joins successful provenance across the initial wave and retry batches.
|
|
770
|
+
2. If a base lane fails under Profile A, retry only the failed `workflow_lane` identifiers with `dispatch_lanes_async`, `mode: "swarm-pr-review:base"`, the same exact `pr_head_sha`, and explorer agents. The durable gate joins successful provenance across the initial wave and retry batches. While that controller is active, blocking `dispatch_lanes` and direct Task dispatch are not equivalent because they cannot satisfy the structured provenance gate. Under Profiles B/C, retry only the failed `workflow_lane` identifiers with a fresh subagent or pass, the same exact `pr_head_sha`, and a materially different prompt decomposition.
|
|
649
771
|
3. If no equivalent alternative can be verified, **STOP and surface the lane failure to the user as BLOCKED** with the lane id, scope, failure mode, retry attempts, and why equivalence could not be proven. Do not present partial findings, do not issue a review verdict, and do not synthesize from successful lanes. A low-quality partial review is worse than no review.
|
|
650
772
|
|
|
651
773
|
### Candidate extraction via parser
|
|
652
774
|
|
|
653
|
-
|
|
654
|
-
that carries an `output_ref`. The orchestrator MUST use the
|
|
655
|
-
rather than preview-text extraction:
|
|
775
|
+
Under Profile A, after `collect_lane_results` returns for base lanes, process
|
|
776
|
+
each lane result that carries an `output_ref`. The orchestrator MUST use the
|
|
777
|
+
candidate parser rather than preview-text extraction:
|
|
656
778
|
|
|
657
779
|
1. For each `output_ref`, call `parse_lane_candidates` with `output_ref`,
|
|
658
780
|
`producer: "swarm-pr-review"`, and `expected_family: "base_explorer"`. The parser reads
|
|
@@ -669,16 +791,21 @@ rather than preview-text extraction:
|
|
|
669
791
|
4. Stage reviewer-sized chunks, but do not dispatch reviewers yet. Phase 4 must
|
|
670
792
|
complete trigger accounting and settle every launched micro-lane first.
|
|
671
793
|
|
|
672
|
-
If a lane has `output_degraded: true`, `transcript_incomplete: true`, or no usable `output_ref`, apply the COVERAGE GATE (Phase 3). Do not use blocking or direct-Task fallbacks, mark affected candidates UNVERIFIED to proceed, or infer candidate absence from a preview.
|
|
794
|
+
If a lane has `output_degraded: true`, `transcript_incomplete: true`, or no usable `output_ref`, apply the COVERAGE GATE (Phase 3). Do not use blocking or direct-Task fallbacks while the controller is active, mark affected candidates UNVERIFIED to proceed, or infer candidate absence from a preview. Under Profiles B/C, a truncated, empty, or attestation-free subagent report is the same lane-output failure and takes the same COVERAGE GATE.
|
|
673
795
|
|
|
674
796
|
After candidate parsing and before reviewer dispatch, persist the post-explorer
|
|
675
797
|
candidate ledger using the Review Finding Persistence contract. This is the
|
|
676
798
|
durable recovery point for context compaction before Phase 6.
|
|
677
799
|
|
|
678
|
-
**
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
800
|
+
**Profiles B/C row convention:** without the parser, the `[CANDIDATE]` row
|
|
801
|
+
format is the extraction contract itself. Explorers emit the rows directly in
|
|
802
|
+
their reports (see the Explorer Prompt Template reference); the orchestrator
|
|
803
|
+
collects them verbatim, validates each row's field count and lane id, and
|
|
804
|
+
treats malformed rows — or output with neither `[CANDIDATE]` rows nor a fully
|
|
805
|
+
populated `[CLEAN]` attestation — as a lane-output failure under the COVERAGE
|
|
806
|
+
GATE. If the parser is unavailable under Profile A, the same row convention
|
|
807
|
+
applies as a fallback, but the orchestrator SHOULD use the parser as the
|
|
808
|
+
primary extraction mechanism.
|
|
682
809
|
|
|
683
810
|
**lane id uniqueness for parallel dispatches:** When re-dispatching failed or
|
|
684
811
|
re-running explorer lanes, every `dispatch_lanes_async` or `dispatch_lanes`
|
|
@@ -688,15 +815,18 @@ in the same batch unless intentionally replacing that exact lane before dispatch
|
|
|
688
815
|
|
|
689
816
|
Explorers optimize for recall. Over-reporting is expected. Explorers produce candidates only.
|
|
690
817
|
|
|
691
|
-
The six
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
`common_prompt` and viewing it through a different lens. Six
|
|
695
|
-
high-assurance
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
818
|
+
The six dimensions are a fixed **check-type** partition, not an area
|
|
819
|
+
partition: every PR needs all six review dimensions, and the lanes
|
|
820
|
+
deliberately overlap by file, each receiving the same diff (via
|
|
821
|
+
`common_prompt` under Profile A) and viewing it through a different lens. Six
|
|
822
|
+
dimensions are this workflow's high-assurance coverage floor, not a claim that
|
|
823
|
+
research proves a universal optimal agent count — the published evidence
|
|
824
|
+
favors complementary, distinct-lens reviewers over duplicated generalists, and
|
|
825
|
+
finding rates rise with diff size, which is why dispatch (not coverage)
|
|
826
|
+
follows the depth tier. Repository policy may add scrutiny but may never
|
|
827
|
+
reduce the six dimensions. Coverage is guaranteed by all six dimensions
|
|
828
|
+
reading the whole diff, so the disjoint-partition rule that governs area-split
|
|
829
|
+
fan-outs does not apply.
|
|
700
830
|
|
|
701
831
|
| `workflow_lane` | Focus | Required checks |
|
|
702
832
|
|---|---|---|
|
|
@@ -718,7 +848,7 @@ Every explorer must inspect or explicitly mark unavailable:
|
|
|
718
848
|
5. the nearest relevant test or missing-test location,
|
|
719
849
|
6. deterministic signal entries mapped to its files/symbols,
|
|
720
850
|
7. relevant Swarm knowledge/evidence entries, if present.
|
|
721
|
-
8. the exact
|
|
851
|
+
8. the exact bound review range to analyze (`base_sha...pr_head_sha`),
|
|
722
852
|
|
|
723
853
|
### Explorer output format
|
|
724
854
|
|
|
@@ -729,9 +859,10 @@ artifact and extracts these records. The canonical record shape is:
|
|
|
729
859
|
[CANDIDATE] | candidate_id | lane | severity | category | file:line | claim | evidence_summary | impact_context | confidence: LOW/MEDIUM/HIGH
|
|
730
860
|
```
|
|
731
861
|
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
862
|
+
Under Profile A the parser normalizes this into a structured `candidates[]`
|
|
863
|
+
array. On Profiles B/C — and as a Profile A fallback when the parser is
|
|
864
|
+
unavailable — the explorer emits the `[CANDIDATE]` row format directly in the
|
|
865
|
+
lane output as the extraction contract.
|
|
735
866
|
|
|
736
867
|
Explorers must not use `CONFIRMED`, `DISPROVED`, or `PRE_EXISTING`.
|
|
737
868
|
|
|
@@ -758,19 +889,32 @@ in the micro-lane map and print a mandatory ledger with one row per map row:
|
|
|
758
889
|
|
|
759
890
|
Focus evidence must name the changed files, manifests, imports/symbols, semantic
|
|
760
891
|
signals, or explicit absence conditions the lane should examine. `MATCHED` means
|
|
761
|
-
the
|
|
892
|
+
the family's evaluation is required, not that a keyword heuristic guessed
|
|
893
|
+
applicability.
|
|
762
894
|
Repository identity, technology stack, PR size, elapsed time, or predicted risk
|
|
763
895
|
never justifies skipping a row.
|
|
764
896
|
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
897
|
+
Every row in the map is a risk **family** that must be evaluated against the
|
|
898
|
+
diff on every PR, in every repository. What scales with the depth tier is the
|
|
899
|
+
dispatch shape — how many subagents carry that evaluation — never the
|
|
900
|
+
evaluation itself. Each family must end in its own attestation: `[CANDIDATE]`
|
|
901
|
+
rows naming the family, or one fully populated per-family `[CLEAN]` row.
|
|
902
|
+
|
|
903
|
+
**Profile A dispatch.** Launch the micro coverage with
|
|
904
|
+
`dispatch_lanes_async` and `mode: "swarm-pr-review:micro"`. At depth tier L,
|
|
905
|
+
dispatch one focused micro-lane for every row, each lane's
|
|
906
|
+
`workflow_lane` equal to its trigger ID; because the dispatcher accepts at
|
|
907
|
+
most eight lanes per call, split the
|
|
908
|
+
eleven mandatory micro-lanes across bounded async batches. At tiers S and M,
|
|
909
|
+
consolidated lanes may each own several families: set `workflow_lane` to one
|
|
910
|
+
owned trigger ID and declare the complete `owned_workflow_lanes` set — every
|
|
911
|
+
family owned exactly once across the dispatch, and every owned family
|
|
912
|
+
attested in that lane's output, or the lane fails for all of them. Include
|
|
913
|
+
the complete exact-set
|
|
914
|
+
`trigger_evaluation` ledger and the same exact current `pr_head_sha` in every
|
|
915
|
+
micro dispatch, in a separate batch from base lanes. The runtime rejects
|
|
772
916
|
unrelated or duplicate micro-lanes within a batch, and final ledger persistence
|
|
773
|
-
rejects any row whose completed
|
|
917
|
+
rejects any row whose completed owning-lane provenance is absent.
|
|
774
918
|
Poll incrementally, then settle every launched lane. Persist
|
|
775
919
|
the complete ledger with `write_pr_review_trigger_eval`; its rows use the stable
|
|
776
920
|
trigger IDs below, and every row includes its returned `source_batch_id` and
|
|
@@ -781,16 +925,43 @@ pass the exact reviewed merge-base as `base_sha`, the exact live base branch
|
|
|
781
925
|
tip/ref used to compute it as `base_ref`, and the same `pr_head_sha` to the
|
|
782
926
|
writer. The writer runs bounded `git merge-base -- <base_ref> <pr_head_sha>` and
|
|
783
927
|
rejects any claimed `base_sha` that is not the exact result. It accepts only the
|
|
784
|
-
exact eleven-row `MATCHED` set backed by
|
|
785
|
-
|
|
786
|
-
|
|
928
|
+
exact eleven-row `MATCHED` set, each row backed by a completed, non-degraded,
|
|
929
|
+
exact-head artifact from a lane that declared ownership of that family and
|
|
930
|
+
attested every family it owns. It never uses keyword
|
|
931
|
+
classification as permission to waive a family. Any head mismatch makes
|
|
787
932
|
persistence fail.
|
|
788
933
|
Do not add trigger results to the finding-status enum.
|
|
789
934
|
|
|
790
|
-
|
|
935
|
+
**Profiles B/C dispatch.** Scale the lane shape to the depth tier while
|
|
936
|
+
keeping all eleven family evaluations:
|
|
937
|
+
|
|
938
|
+
- Tier L: one focused lane per family, mirroring Profile A.
|
|
939
|
+
- Tier M: a dedicated lane for every risk-triggered family; consolidate the
|
|
940
|
+
remaining families into one or two sweep lanes that each carry an explicit
|
|
941
|
+
per-family checklist.
|
|
942
|
+
- Tier S: fold the full eleven-family checklist into the base wave's lanes
|
|
943
|
+
(B) or into one consolidated micro sweep or sequential checklist pass (C).
|
|
944
|
+
|
|
945
|
+
Whatever the dispatch shape: the ledger keeps one `[TRIGGER-EVAL]` row per
|
|
946
|
+
family; each row's focus evidence names the lane or pass that evaluated it;
|
|
947
|
+
each family gets its own `[CANDIDATE]`/`[CLEAN]` attestation naming the family
|
|
948
|
+
id; and the completed ledger is persisted as `trigger-eval.json` in the
|
|
949
|
+
session/task workspace before reviewer dispatch. A family with no attestation
|
|
950
|
+
row is an unclosed coverage gap, exactly as if a Profile A lane had failed.
|
|
951
|
+
|
|
952
|
+
For each micro `output_ref` (Profile A), call `parse_lane_candidates` with
|
|
791
953
|
`producer: "swarm-pr-review"`, `expected_family: "micro_lane"`, and
|
|
792
954
|
`expected_micro_lane` set to the launch-micro-lane value from the
|
|
793
|
-
provenance-linked trigger row.
|
|
955
|
+
provenance-linked trigger row. When the artifact came from a consolidated
|
|
956
|
+
tier-S/M lane (its dispatch declared more than one `owned_workflow_lanes`
|
|
957
|
+
entry), also pass `expected_micro_lanes` set to that lane's complete
|
|
958
|
+
`owned_workflow_lanes` array — the same set already declared at micro
|
|
959
|
+
dispatch time. Without it, the parser has no way to tell a sibling owned
|
|
960
|
+
family's row from a genuinely out-of-scope one: every row belonging to the
|
|
961
|
+
lane's other owned families is treated as a parse error instead of being
|
|
962
|
+
skipped as out-of-scope, which can also invalidate that lane's own otherwise-valid
|
|
963
|
+
`[CLEAN]` attestation for the family being extracted. Omit `expected_micro_lanes`
|
|
964
|
+
only for a singleton (tier-L) lane. Accept a candidate only when its `producer`,
|
|
794
965
|
`source_batch_id`, and `source_lane_id` match an allow-listed tuple from the
|
|
795
966
|
original or retry micro dispatch and its `micro_lane` matches that trigger row;
|
|
796
967
|
never filter acceptance by `row_format_family`. A zero-candidate artifact is
|
|
@@ -802,7 +973,7 @@ errors, zero malformed rows, and a complete, non-degraded source:
|
|
|
802
973
|
[CLEAN] | micro_lane | coverage_scope | evidence
|
|
803
974
|
```
|
|
804
975
|
|
|
805
|
-
Header-only or malformed zero output is `UNATTESTED`; apply the COVERAGE GATE (Phase 3).
|
|
976
|
+
Header-only or malformed zero output is `UNATTESTED`; apply the COVERAGE GATE (Phase 3). Under Profile A, the structured async PR-workflow path is required to preserve `L1`, exact-head, batch, and workflow-lane provenance; the active controller rejects blocking and direct-Task substitutes, and Task-derived findings or CLEAN prose cannot satisfy Phase 4's controller ledger. Under Profiles B/C, acceptance is the row contract itself: accept a candidate or clean row only when its `micro_lane` field matches the trigger row it claims, and treat prose-only "clean" claims as `UNATTESTED`.
|
|
806
977
|
|
|
807
978
|
Each micro-lane receives:
|
|
808
979
|
|
|
@@ -812,17 +983,19 @@ Each micro-lane receives:
|
|
|
812
983
|
- relevant deterministic signals,
|
|
813
984
|
- related historical knowledge with quarantine/staleness status,
|
|
814
985
|
- expected invariants,
|
|
815
|
-
- structured candidate output
|
|
816
|
-
the micro-lane
|
|
986
|
+
- structured candidate output — parser-extracted under Profile A; on Profiles
|
|
987
|
+
B/C the micro-lane emits `[CANDIDATE]`/`[CLEAN]` rows directly as the
|
|
988
|
+
extraction contract.
|
|
817
989
|
|
|
818
990
|
### Repository-agnostic mandatory micro-lane map
|
|
819
991
|
|
|
820
|
-
Every row
|
|
821
|
-
cannot waive it: semantic applicability is not reliably
|
|
822
|
-
keywords, so `NO-MATCH` is invalid. Repository policy
|
|
823
|
-
specialist review outside this canonical ledger, but
|
|
824
|
-
replaces these portable rows. The `unclassified-risk`
|
|
825
|
-
novel failure modes and classification
|
|
992
|
+
Every row is evaluated in every repository. Diff/context analysis focuses each
|
|
993
|
+
family's evaluation but cannot waive it: semantic applicability is not reliably
|
|
994
|
+
decidable from paths or keywords, so `NO-MATCH` is invalid. Repository policy
|
|
995
|
+
may require supplementary specialist review outside this canonical ledger, but
|
|
996
|
+
supplementary work never replaces these portable rows. The `unclassified-risk`
|
|
997
|
+
family is always evaluated to cover novel failure modes and classification
|
|
998
|
+
gaps.
|
|
826
999
|
|
|
827
1000
|
> **Trigger-ID namespace — do not mix (issue #1931).** The `trigger_id` field
|
|
828
1001
|
> passed to `write_pr_review_trigger_eval` accepts **only** the 11 micro-lane
|
|
@@ -864,7 +1037,7 @@ Micro-lane output format:
|
|
|
864
1037
|
|
|
865
1038
|
## Phase 5: Swarm-Native Verifier Routing
|
|
866
1039
|
|
|
867
|
-
Use Swarm-native agents and artifacts when available. If exact agent names are unavailable, route the same task to the closest equivalent reviewer/critic role.
|
|
1040
|
+
Use Swarm-native agents and artifacts when available. If exact agent names are unavailable, route the same task to the closest equivalent reviewer/critic role. On harnesses without the plugin, most `.swarm/` artifacts will not exist: mark those rows N/A in the validation provenance rather than fabricating them.
|
|
868
1041
|
|
|
869
1042
|
| Swarm verifier / artifact | When to use | Purpose |
|
|
870
1043
|
|---|---|---|
|
|
@@ -883,39 +1056,49 @@ Verifier output is advisory until incorporated by the independent reviewer or cr
|
|
|
883
1056
|
## Phase 6: Independent Reviewer Confirmation
|
|
884
1057
|
|
|
885
1058
|
**Reviewer-dispatch join barrier:** reviewer dispatch MUST NOT begin until the micro-lane ledger is
|
|
886
|
-
complete and persisted,
|
|
887
|
-
|
|
888
|
-
|
|
1059
|
+
complete and persisted, every launched micro lane is settled with all eleven
|
|
1060
|
+
families attested (under Profile A: all eleven micro-lanes settled), and every
|
|
1061
|
+
accepted micro result has parser-derived provenance (Profile A) or a valid
|
|
1062
|
+
CLEAN attestation.
|
|
889
1063
|
|
|
890
1064
|
Route candidates to reviewer subagents. The orchestrator routes candidates
|
|
891
|
-
in bounded chunks produced by the
|
|
1065
|
+
in bounded chunks produced by the candidate extraction in Phase 3-4. Each
|
|
892
1066
|
reviewer lane receives a bounded list of candidates from a single chunk — by
|
|
893
1067
|
file area, category, or count — not the full candidate set. The reviewer must
|
|
894
1068
|
re-read the candidate's file:line evidence and relevant context pack entries
|
|
895
1069
|
directly.
|
|
896
1070
|
|
|
897
|
-
|
|
1071
|
+
Under Profile A, dispatch reviewer chunks with `dispatch_lanes_async`,
|
|
898
1072
|
`mode: "swarm-pr-review:reviewer"`, a unique non-empty `workflow_lane` per
|
|
899
1073
|
chunk, `review_item_ids` containing the exact candidate IDs assigned to that
|
|
900
1074
|
chunk, reviewer-role agents only, and the same exact `pr_head_sha`. The runtime
|
|
901
1075
|
requires one parseable `[REVIEWED]` row for every structurally assigned ID; a
|
|
902
1076
|
single marker or partial subset cannot settle the lane. Direct Task
|
|
903
|
-
reviewers are rejected because they cannot carry the
|
|
904
|
-
provenance
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
1077
|
+
reviewers are rejected by the active controller because they cannot carry the
|
|
1078
|
+
durable batch and head provenance it requires. Under Profile B, dispatch each
|
|
1079
|
+
chunk to a fresh reviewer subagent — never the agent or conversation that
|
|
1080
|
+
generated the candidates — carrying the chunk's candidate IDs, the exact
|
|
1081
|
+
`pr_head_sha`, and the required checks below. Under Profile C, run a separate
|
|
1082
|
+
reviewer pass per chunk that re-reads every cited file:line before
|
|
1083
|
+
classifying. The one-parseable-`[REVIEWED]`-row-per-assigned-ID contract is
|
|
1084
|
+
universal.
|
|
1085
|
+
|
|
1086
|
+
Under Profile A, for every structured PR-review dispatch, the runtime appends
|
|
1087
|
+
an authoritative controller block after caller-authored prompt text. It binds the exact
|
|
908
1088
|
`workflow_lane`, PR head, content revision, declared scope, and assigned item
|
|
909
1089
|
IDs and explicitly forbids speed/time/token waivers. Caller prompt text cannot
|
|
910
1090
|
override that block; output with placeholders, invented IDs, generic assurances,
|
|
911
1091
|
or evidence unrelated to the bound lane does not settle the artifact.
|
|
912
1092
|
|
|
913
|
-
Reviewer ownership is not accepted as an architect assertion.
|
|
914
|
-
derives the immutable candidate inventory from the
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
1093
|
+
Reviewer ownership is not accepted as an architect assertion. Under Profile A,
|
|
1094
|
+
the controller derives the immutable candidate inventory from the
|
|
1095
|
+
integrity-checked base, mandatory micro-lane, and council artifacts; under
|
|
1096
|
+
Profiles B/C, the orchestrator derives the same inventory from the persisted
|
|
1097
|
+
ledgers. Either way, the union of `review_item_ids` must equal that inventory
|
|
1098
|
+
exactly, with no omitted or invented IDs. If discovery produces no candidates,
|
|
1099
|
+
the derived sentinel is `CLEAN-REVIEW`, which still requires one independent
|
|
1100
|
+
semantic reviewer row (a fresh subagent on Profile B; a separate reviewer pass
|
|
1101
|
+
on Profile C).
|
|
919
1102
|
|
|
920
1103
|
Candidate IDs must therefore be globally unique across every discovery
|
|
921
1104
|
artifact in the run. Prefix IDs with the stable workflow-lane ID (or use
|
|
@@ -1031,12 +1214,16 @@ new reviewer rows happen to be identical. Dispatch a fresh critic wave from the
|
|
|
1031
1214
|
latest coherent reviewer batch; critic evidence can never predate the reviewer
|
|
1032
1215
|
evidence it purports to challenge.
|
|
1033
1216
|
|
|
1034
|
-
|
|
1217
|
+
Under Profile A, dispatch critic chunks with `dispatch_lanes_async`,
|
|
1035
1218
|
`mode: "swarm-pr-review:critic"`, a unique non-empty `workflow_lane` per
|
|
1036
1219
|
chunk, `review_item_ids` containing the exact finding IDs assigned to that
|
|
1037
1220
|
chunk, critic-role agents only, and the same exact `pr_head_sha`. The runtime
|
|
1038
1221
|
requires one parseable `[CRITIC]` row for every structurally assigned ID and
|
|
1039
1222
|
requires one coherent fully successful exact reviewer batch before a critic wave.
|
|
1223
|
+
Under Profile B, dispatch each critic chunk to a fresh subagent that was
|
|
1224
|
+
neither the explorer nor the reviewer for those findings; under Profile C, run
|
|
1225
|
+
a separate critic pass. The one-parseable-`[CRITIC]`-row-per-assigned-ID
|
|
1226
|
+
contract and the reviewer-before-critic ordering are universal.
|
|
1040
1227
|
|
|
1041
1228
|
The critic must challenge:
|
|
1042
1229
|
|
|
@@ -1071,7 +1258,7 @@ BLOCKED. Terminal critic rows are cross-field checked: `DISPROVED` requires
|
|
|
1071
1258
|
`NONE`, `UPHELD` requires CRITICAL/HIGH/MEDIUM, and `DOWNGRADED` cannot remain
|
|
1072
1259
|
CRITICAL.
|
|
1073
1260
|
|
|
1074
|
-
**COVERAGE GATE alignment:** Critic lane failures apply the COVERAGE GATE (Phase 3)
|
|
1261
|
+
**COVERAGE GATE alignment:** Critic lane failures apply the COVERAGE GATE (Phase 3) — under Profile A via `dispatch_lanes_async` with `mode: "swarm-pr-review:critic"` and the same exact `pr_head_sha`; under Profiles B/C via a fresh critic subagent or pass. Do NOT mark findings UNVERIFIED or continue past the gap. The orchestrator NEVER fabricates a critic verdict by parsing prose, by tolerating a planning preamble, by presenting partial findings, or by silently accepting reduced coverage.
|
|
1075
1262
|
|
|
1076
1263
|
Refuted findings become `DISPROVED` or `ADVISORY`, depending on critic rationale. Downgrades must be listed in the final validation provenance.
|
|
1077
1264
|
|
|
@@ -1137,8 +1324,9 @@ F-001 | severity | category | root cause | affected file:line refs | reviewer |
|
|
|
1137
1324
|
At the end of the review, include review quality metrics in the final report's
|
|
1138
1325
|
validation provenance. Persist them only through an invoked evidence tool and
|
|
1139
1326
|
record the exact `.swarm/evidence/` path returned by that tool; if no invoked
|
|
1140
|
-
tool supports metrics, state `NOT PERSISTED —
|
|
1141
|
-
|
|
1327
|
+
tool supports metrics (including all of Profiles B/C), state `NOT PERSISTED —
|
|
1328
|
+
no metrics evidence writer` and keep the metrics block in the final report and
|
|
1329
|
+
session ledger rather than naming a nonexistent command or path.
|
|
1142
1330
|
|
|
1143
1331
|
Record:
|
|
1144
1332
|
|
|
@@ -1211,7 +1399,7 @@ Council mode is opt-in only and adversarial.
|
|
|
1211
1399
|
When triggered:
|
|
1212
1400
|
|
|
1213
1401
|
1. Build the same context pack as default mode.
|
|
1214
|
-
2. After the default
|
|
1402
|
+
2. After the default base-dimension and risk-family coverage is complete, launch all supplementary council agents. Under Profile A, use one `dispatch_lanes_async` call with `mode: "swarm-pr-review:council"`, the same exact `pr_head_sha`, and one unique `workflow_lane` per council member; continue independent context preparation while they run, polling with `collect_lane_results` (without `wait`) to process settled agents incrementally, and use `wait: true` only when no independent work remains. All agents must be settled and their candidates added to the ledger before reviewer classification; under Profile A the runtime enforces this join barrier, and blocking, sequential, or direct-Task fallback is not equivalent to the structured council dispatch — bypassing the active controller is `BLOCKED`. Under Profile B, dispatch council members as parallel subagents with the same marker contract and settle them all before reviewer classification; under Profile C, run each council lens as a separate sequential pass.
|
|
1215
1403
|
3. Each council agent assumes all work is wrong until code evidence proves otherwise.
|
|
1216
1404
|
4. Each agent hunts within its lane only.
|
|
1217
1405
|
5. Agents return the same mechanically parseable candidate contract as other discovery lanes: one `[CANDIDATE]` row per `EVIDENCE_FOUND` or `SUSPICIOUS` claim, or a fully populated `[CLEAN] | workflow_lane | coverage_scope | evidence` row when no candidate survives. Council prose without one of those markers does not settle the lane.
|
|
@@ -1272,9 +1460,9 @@ Council findings are supplementary, not authoritative overrides. Do not adopt co
|
|
|
1272
1460
|
11. Obligation precedence is deterministic. Do not skip higher-precedence sources to fill gaps with LLM synthesis.
|
|
1273
1461
|
12. Do not leak secrets from logs, evidence bundles, config files, URLs, or scanner output.
|
|
1274
1462
|
13. Do not recommend destructive git or filesystem actions as fixes unless they are clearly scoped, safe, and necessary.
|
|
1275
|
-
14. If subagents fail, timeout, or return malformed output, retry with corrected parameters (max 2 attempts) through the same structured `dispatch_lanes_async` workflow mode and exact `pr_head_sha
|
|
1463
|
+
14. If subagents fail, timeout, or return malformed output, retry with corrected parameters (max 2 attempts) through the dispatch mechanism of the active profile — Profile A: the same structured `dispatch_lanes_async` workflow mode and exact `pr_head_sha`, where blocking or direct-Task dispatch cannot preserve the durable provenance contract and is not an equivalent fallback; Profiles B/C: a fresh subagent or pass bound to the same exact `pr_head_sha`. If retries fail, the affected coverage dimension is BLOCKED and must be surfaced to the user before synthesis. Do not fabricate validation results, do not present partial findings, and do not silently mark candidates UNVERIFIED to proceed past the gap.
|
|
1276
1464
|
|
|
1277
|
-
15. If context pack, repo graph, deterministic signals, or Swarm artifacts are unavailable, retry with alternative access paths. If unavailable after retry, the affected coverage dimension is BLOCKED and must be surfaced to the user. Do not proceed to synthesis with unclosed coverage gaps under a "best available evidence" rationale — the architect is not authorized to produce a degraded review.
|
|
1465
|
+
15. If context pack, repo graph, deterministic signals, or Swarm artifacts are unavailable, retry with alternative access paths. If a source that should exist on the active profile is still unavailable after retry, the affected coverage dimension is BLOCKED and must be surfaced to the user. A source that cannot exist on the active profile (for example `.swarm/` artifacts outside Profile A) is marked N/A in the validation provenance instead — N/A is disclosure, never a waiver of the dimensions and families that must still be covered. Do not proceed to synthesis with unclosed coverage gaps under a "best available evidence" rationale — the architect is not authorized to produce a degraded review.
|
|
1278
1466
|
|
|
1279
1467
|
---
|
|
1280
1468
|
|
|
@@ -1284,14 +1472,15 @@ Before writing the final output, print this checklist with filled values. Every
|
|
|
1284
1472
|
|
|
1285
1473
|
```text
|
|
1286
1474
|
[VALIDATION] scope selected: ___
|
|
1475
|
+
[VALIDATION] capability profile (A/B/C) and depth tier (S/M/L): ___ / ___
|
|
1287
1476
|
[VALIDATION] context pack built: YES/NO — ___
|
|
1288
1477
|
[VALIDATION] obligation count: ___
|
|
1289
1478
|
[VALIDATION] repo graph / impact cone source: ___
|
|
1290
1479
|
[VALIDATION] deterministic signals ingested: ___
|
|
1291
|
-
[VALIDATION]
|
|
1292
|
-
[VALIDATION] base
|
|
1293
|
-
[VALIDATION] base explorer lanes returned: ___ /
|
|
1294
|
-
[VALIDATION]
|
|
1480
|
+
[VALIDATION] lane dispatch mechanism: controller / native subagents / sequential passes — ___
|
|
1481
|
+
[VALIDATION] base dimensions covered with attestation: ___ / 6 (lanes dispatched: ___)
|
|
1482
|
+
[VALIDATION] base explorer lanes returned: ___ / ___
|
|
1483
|
+
[VALIDATION] micro risk families evaluated and attested: ___ / 11 OR BLOCKED — <missing rows> (micro lanes dispatched: ___)
|
|
1295
1484
|
[VALIDATION] Swarm verifier routing used: ___
|
|
1296
1485
|
[VALIDATION] raw candidates: ___
|
|
1297
1486
|
[VALIDATION] tool candidates: ___
|
|
@@ -1411,9 +1600,12 @@ Explain the recommendation in one short paragraph and list required actions befo
|
|
|
1411
1600
|
## Feedback handoff
|
|
1412
1601
|
|
|
1413
1602
|
When the review produced actionable validated findings or operational blockers,
|
|
1414
|
-
call `write_pr_review_artifact` with `kind: "handoff"
|
|
1603
|
+
call `write_pr_review_artifact` with `kind: "handoff"` (Profile A). The controller writes
|
|
1415
1604
|
`.swarm/pr-review/<run_id>/feedback-handoff.json` only when its finding IDs
|
|
1416
|
-
exactly match the latest confirmed `handoff_to_feedback` records.
|
|
1605
|
+
exactly match the latest confirmed `handoff_to_feedback` records. On Profiles
|
|
1606
|
+
B/C, write the same handoff content to the session/task workspace path
|
|
1607
|
+
described in "Handoff To PR Feedback" and reference that path in the
|
|
1608
|
+
continuation prompt. Include:
|
|
1417
1609
|
|
|
1418
1610
|
- the handoff artifact path,
|
|
1419
1611
|
- the preserved finding IDs and provenance that `swarm-pr-feedback` must carry
|
|
@@ -1421,28 +1613,37 @@ exactly match the latest confirmed `handoff_to_feedback` records. Include:
|
|
|
1421
1613
|
- and an explicit question asking whether to continue into
|
|
1422
1614
|
`swarm-pr-feedback`.
|
|
1423
1615
|
|
|
1424
|
-
Use this exact continuation prompt format
|
|
1616
|
+
Use this exact continuation prompt format, substituting the exact path from
|
|
1617
|
+
whichever profile applies (`.swarm/pr-review/<run_id>/feedback-handoff.json`
|
|
1618
|
+
under Profile A, or the session/task workspace path under Profiles B/C — never
|
|
1619
|
+
mix the two):
|
|
1425
1620
|
|
|
1426
1621
|
```text
|
|
1427
|
-
/swarm pr-feedback <PR_URL> continue from
|
|
1622
|
+
/swarm pr-feedback <PR_URL> continue from <handoff_artifact_path>
|
|
1428
1623
|
```
|
|
1429
1624
|
|
|
1430
1625
|
---
|
|
1431
1626
|
|
|
1432
1627
|
For reviewer, critic, and explorer prompt templates, read `references/prompt-templates.md`.
|
|
1433
1628
|
|
|
1434
|
-
|
|
1435
|
-
user-facing final report, call `complete_pr_workflow` with
|
|
1436
|
-
the same exact
|
|
1629
|
+
Under Profile A, after metrics and durable review artifacts are complete, but
|
|
1630
|
+
before emitting the user-facing final report, call `complete_pr_workflow` with
|
|
1631
|
+
mode `PR_REVIEW` and the same exact
|
|
1437
1632
|
`pr_head_sha`. The tool refuses to clear the session gate while required base,
|
|
1438
1633
|
trigger, declared reviewer/critic, or open-lane obligations remain incomplete.
|
|
1439
|
-
While the gate remains active, the runtime
|
|
1440
|
-
|
|
1634
|
+
While the gate remains active, the runtime prepends a workflow-active banner
|
|
1635
|
+
to architect text parts (the model's text is preserved below the banner) and
|
|
1636
|
+
re-wakes an idle parent session. A
|
|
1441
1637
|
user interruption pauses every automatic wake path until a later explicit user
|
|
1442
1638
|
turn settles; the durable gate remains available to continue or abort. Only
|
|
1443
1639
|
emit the final report after the completion tool confirms that the gate cleared.
|
|
1444
1640
|
|
|
1445
|
-
|
|
1641
|
+
Under Profiles B/C, no mechanical response gate exists: the Pre-Synthesis Gate
|
|
1642
|
+
checklist is the completion gate. Emit the final report only after every
|
|
1643
|
+
checklist line is filled, every dimension and family is attested, and every
|
|
1644
|
+
BLOCKED item is surfaced.
|
|
1645
|
+
|
|
1646
|
+
## Aborting an unrecoverable review (Profile A)
|
|
1446
1647
|
|
|
1447
1648
|
The mechanical gate can leave the session stuck if the PR head cannot be
|
|
1448
1649
|
fetched or checked out — for example when a compound `git fetch … && git
|
|
@@ -1476,3 +1677,6 @@ unproductive wakes, and the only exits are:
|
|
|
1476
1677
|
Abort is a recovery tool, not a coverage shortcut. Use it only when the
|
|
1477
1678
|
bind/checkout path is genuinely unreachable; never use it to skip a
|
|
1478
1679
|
coverage obligation that is merely expensive or inconvenient.
|
|
1680
|
+
|
|
1681
|
+
On Profiles B/C there is no durable gate or auto-resume loop to clear: if the
|
|
1682
|
+
head bind is genuinely unreachable, report the blocker to the user and stop.
|