feat: flesh out check-phase with parallel reviewer spawning protocol
This commit is contained in:
@@ -76,6 +76,107 @@ Use the higher severity. Don't double-count in the verdict.
|
||||
→ Build cycle feedback (see orchestration skill) and feed to Plan phase
|
||||
```
|
||||
|
||||
## Reviewer Spawning Protocol
|
||||
|
||||
This section defines the exact sequence for spawning reviewers in the Check phase.
|
||||
|
||||
### Step 1: Guardian First (mandatory)
|
||||
|
||||
Guardian always runs first, before any other reviewer. It receives the Maker's git diff and the proposal's risk section only.
|
||||
|
||||
**Context for Guardian:**
|
||||
- `git diff main...<maker-branch>` (the actual code changes)
|
||||
- Risk section from `plan-creator.md` (if present)
|
||||
- Do NOT include: Explorer research, full proposal, other reviewer outputs
|
||||
|
||||
```
|
||||
Agent(
|
||||
description: "Guardian: security and risk review for <task>",
|
||||
prompt: "You are the GUARDIAN archetype.
|
||||
Review the diff: <maker's diff>
|
||||
Proposal risks: <risk section from plan-creator.md>
|
||||
Assess: security vulnerabilities, reliability risks, breaking changes, dependency risks.
|
||||
Output: APPROVED or REJECTED with findings in the standardized format.
|
||||
Each finding: | Location | Severity | Category | Description | Fix |",
|
||||
model: <resolve_model guardian $WORKFLOW>
|
||||
)
|
||||
```
|
||||
|
||||
Save output to `.archeflow/artifacts/${RUN_ID}/check-guardian.md`.
|
||||
|
||||
### Step 2: A2 Fast-Path Evaluation
|
||||
|
||||
After Guardian completes, parse its output before spawning other reviewers:
|
||||
|
||||
```bash
|
||||
CRITICAL_COUNT=$(grep -ci "CRITICAL" ".archeflow/artifacts/${RUN_ID}/check-guardian.md" || echo 0)
|
||||
WARNING_COUNT=$(grep -ci "WARNING" ".archeflow/artifacts/${RUN_ID}/check-guardian.md" || echo 0)
|
||||
|
||||
if [[ "$CRITICAL_COUNT" -eq 0 && "$WARNING_COUNT" -eq 0 && "$ESCALATED" != "true" ]]; then
|
||||
# A2 fast-path: skip remaining reviewers
|
||||
echo "Guardian fast-path: 0 CRITICAL, 0 WARNING — skipping remaining reviewers."
|
||||
# Proceed directly to Act phase
|
||||
fi
|
||||
```
|
||||
|
||||
**Exception:** First cycle of `thorough` workflows always spawns all reviewers, even if Guardian is clean.
|
||||
|
||||
### Step 3: Parallel Reviewer Spawning
|
||||
|
||||
If A2 does not trigger, spawn remaining reviewers in parallel based on workflow:
|
||||
|
||||
| Workflow | Reviewers (after Guardian) |
|
||||
|----------|--------------------------|
|
||||
| `fast` | None (Guardian only) |
|
||||
| `fast` (escalated via A1) | Skeptic + Sage |
|
||||
| `standard` | Skeptic + Sage |
|
||||
| `thorough` | Skeptic + Sage + Trickster |
|
||||
|
||||
Spawn all applicable reviewers in a single message with multiple Agent calls:
|
||||
|
||||
```
|
||||
# Standard workflow example — spawn Skeptic and Sage in parallel:
|
||||
Agent(
|
||||
description: "Skeptic: challenge assumptions for <task>",
|
||||
prompt: "<Skeptic prompt with Creator's proposal>",
|
||||
model: <resolve_model skeptic $WORKFLOW>
|
||||
)
|
||||
|
||||
Agent(
|
||||
description: "Sage: holistic quality review for <task>",
|
||||
prompt: "<Sage prompt with proposal + diff + implementation summary>",
|
||||
model: <resolve_model sage $WORKFLOW>
|
||||
)
|
||||
```
|
||||
|
||||
Each reviewer gets context per the attention filters defined in `archeflow:orchestration`:
|
||||
- **Skeptic:** Creator's proposal (assumptions section focus)
|
||||
- **Sage:** Creator's proposal + Maker's diff + implementation summary
|
||||
- **Trickster:** Maker's diff only
|
||||
|
||||
### Step 4: Collect Results
|
||||
|
||||
Wait for all spawned reviewers to return. For each:
|
||||
1. Save output to `.archeflow/artifacts/${RUN_ID}/check-<archetype>.md`
|
||||
2. Emit `review.verdict` event with findings
|
||||
3. Record sequence number for DAG parent tracking
|
||||
|
||||
### Timeout Handling
|
||||
|
||||
Each reviewer has a **5-minute timeout**. If a reviewer does not return within 5 minutes:
|
||||
1. Emit `agent.complete` with `"error": true, "reason": "timeout"`
|
||||
2. Log a WARNING — do not block the run
|
||||
3. Treat the timed-out reviewer as having delivered no findings (neither approved nor rejected)
|
||||
4. Proceed with available verdicts
|
||||
|
||||
If Guardian times out, this is a blocking failure — abort the Check phase and report to the user.
|
||||
|
||||
### Re-Check Protocol (Act Phase Fixes)
|
||||
|
||||
When the Act phase routes findings back to the Maker and the Maker applies fixes in a subsequent cycle, the Check phase re-runs with the updated diff. Reviewers who previously rejected should focus on whether their specific findings were addressed. The structured feedback from `act-feedback.md` provides the mapping of which findings were routed where.
|
||||
|
||||
---
|
||||
|
||||
## Why Structured Findings Matter
|
||||
|
||||
The standardized format enables:
|
||||
|
||||
@@ -194,6 +194,8 @@ Agent(
|
||||
|
||||
Spawn Guardian **first**. After Guardian completes, check adaptation rule A2 (fast-path). If A2 triggers (0 CRITICAL, 0 WARNING, non-escalated workflow), skip remaining reviewers and proceed to Act. Otherwise, spawn remaining reviewers **in parallel**.
|
||||
|
||||
**Reviewer spawning protocol:** The canonical sequence (Guardian first, A2 evaluation, parallel spawning, timeout handling) is defined in `archeflow:check-phase` under "Reviewer Spawning Protocol". Follow that protocol for the exact spawning order, context per reviewer, and timeout rules.
|
||||
|
||||
### Guardian (always runs first)
|
||||
|
||||
**Context to include:** Maker's git diff, proposal risk section only.
|
||||
|
||||
Reference in New Issue
Block a user