feat: flesh out check-phase with parallel reviewer spawning protocol

This commit is contained in:
2026-04-04 08:40:03 +02:00
parent 5e2117c9be
commit c5174e88eb
2 changed files with 103 additions and 0 deletions

View File

@@ -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: