feat(agents): W5 seo/geo 3-mode pipelines — collect sonnet / judge opus pin / template sonnet (BDR-077)

seo-analyzer + geo-analyzer gain MODE: collect|judge|template around the dispatcher (mode-based, zero body-text moves — seo-data fetch-wiring locks survive; opus pin kept = fail-safe direction, a forgotten override over-tiers but never downgrades judgment). Run-scoped gitignored signals handoff (.audit/*-signals-<RUNID>.md + COLLECTION COMPLETE sentinel), judge fails closed on absent/mismatched/unsealed signals. /seo rewired to 3 phases (domains parallel per phase) + DISPATCHER ERROR CONTRACT (mute/ERROR judge never carried into templating; retry once, escalate); /geo same single-domain; legacy no-MODE single-shot kept on the opus pin for /harden narrow-scope + /onboard report-only. Dropped /geo's 'ask and I relay' fiction (dispatched agents cannot ask). In-wave smokes PASSED disk-verified: collect signals+sentinel; judge ERROR-verdict on wrong RUNID; real judge = honest N/A + deterministic engine + full scoring grammar; template = complete envelope + verbatim sentinel + zero re-derivation. Census §18 (125 pass — one vacuous line-wrapped lock caught by the census itself and fixed), make test exit 0.
2026-07-19 23:23:10 +02:00
parent 6886622ecf
commit 9e4ebb4cf4
5 changed files with 213 additions and 37 deletions
@@ -36,26 +36,50 @@ terminated by `READY TO APPLY — awaiting dispatcher confirmation`, and this
 skill applies it. Applying from here (one dispatch level, no nested spawn)
 is what makes fixes land on any Claude Code version.

-## STEP 1 — Dispatch geo-analyzer (audit + bundle)
+## STEP 1 — Run the geo pipeline (collect → judge → template, BDR-077)

+Gather depth + business context HERE first (ask the user in this loop if
+needed — a dispatched agent cannot ask). Mint `RUNID=$(date +%s)-geo`.
+Pass the same CONTEXT block ($ARGUMENTS + gathered context) VERBATIM to
+every phase (LRN-126). Clean `.audit/geo-signals-<RUNID>.md` after apply.
+
+**A — collect (sonnet):**
+```
+Agent(subagent_type="geo-analyzer", model="sonnet")
+prompt: "MODE: collect
+RUNID: <RUNID>
+Dispatched from /geo. Context: <CONTEXT>
+Execute STEP 0-5 per your spec, write the signals file + COLLECTION
+COMPLETE sentinel, emit the COLLECT REPORT, stop."
+```
+
+**B — judge (opus pin, no override):**
 ```
 Agent(subagent_type="geo-analyzer")
-prompt: """
-Dispatched from /geo. Execute your full spec at
-~/.claude/agents/geo-analyzer.md (STEP 0 onward — gather depth + business
-context as needed; if you must ask the user, ask and I relay).
+prompt: "MODE: judge
+RUNID: <RUNID>
+Context: <CONTEXT>
+Load .audit/geo-signals-<RUNID>.md (fail closed per your spec), run STEP
+6-12, report scoring + findings + action plan + triage batches."
+```
+**ERROR CONTRACT:** `GEO JUDGE — VERDICT: ERROR(…)` or a mute judge →
+STOP: no template, no apply. Surface verbatim, retry ONCE with a fresh
+collect+judge, then escalate. Never carry a mute/ERROR judge into
+templating.

-Produce your report:
- If .claude/audits/SEO.md already exists → merge findings into its
-  §7 — Optimisation GEO / IA.
- Else write .claude/audits/GEO.md.
-
-Then emit the `## FIX BUNDLE` (STEP 13) terminated by the verbatim
-`READY TO APPLY — awaiting dispatcher confirmation` sentinel. Do NOT apply
-any fix and do NOT dispatch any sub-agent — /geo applies your bundle.
-
-$ARGUMENTS
-"""
+**C — template (sonnet):**
+```
+Agent(subagent_type="geo-analyzer", model="sonnet")
+prompt: "MODE: template
+Context: <CONTEXT>
+JUDGE REPORT (verbatim, ground truth — never re-derive a score):
+<the judge report>
+Run STEP 13-15. Produce your report: if .claude/audits/SEO.md already
+exists → merge findings into its §7 — Optimisation GEO / IA; else write
+.claude/audits/GEO.md. Then emit the `## FIX BUNDLE` terminated by the
+verbatim `READY TO APPLY — awaiting dispatcher confirmation` sentinel.
+Do NOT apply any fix and do NOT dispatch any sub-agent — /geo applies
+your bundle."
 ```

 ## STEP 1b — CHALLENGE THE FIX BUNDLE (advisory, before apply)
@@ -302,14 +302,31 @@ still carries this rule for its applier:
 If `Edit` is insufficient (full-template refactor), the item is escalated
 as a cross-agent note → §11 user action instead.

-## STEP 1 — Spawn both agents IN PARALLEL
+## STEP 1 — Run both domain pipelines (3 phases; domains parallel per phase)

-Issue both `Agent` tool calls **in the same message** (parallel tool
-calls). The harness runs them concurrently.
+BDR-077: each domain runs collect (sonnet) → judge (opus pin) → template
+(sonnet), the two domains IN PARALLEL at every phase (both `Agent` calls
+in the same message). Mint run ids first: `RUNID_SEO=$(date +%s)-seo`,
+`RUNID_GEO=$(date +%s)-geo`. The CONTEXT payloads below are the SHARED
+CONTEXT of each domain — pass them VERBATIM to every phase dispatch of
+that domain (LRN-126). Clean both `.audit/*-signals-*.md` files after
+STEP 2.
+
+**DISPATCHER ERROR CONTRACT (fail-closed at the pipeline, not just the
+judge):** a `SEO JUDGE — VERDICT: ERROR(…)` / `GEO JUDGE — VERDICT:
+ERROR(…)`, a mute judge, or a BLOCKED collect → STOP that domain: NO
+template dispatch, NO L1 apply for it. Surface the error verbatim, retry
+ONCE with a fresh collect+judge for that domain; a 2nd failure →
+escalate to the human. A mute or ERROR judge is NEVER carried into
+templating.
+
+**PHASE A — collect (both domains, one message):**

 ```
-Agent(subagent_type="seo-analyzer")
+Agent(subagent_type="seo-analyzer", model="sonnet")
 prompt: """
+MODE: collect
+RUNID: <RUNID_SEO>
 Dispatched from /seo. Context:

 AUDIT DEPTH: <LOCAL|FULL>
@@ -379,18 +396,15 @@ SHARED-FILE EDIT DISCIPLINE (carried into each bundle item):
  legal pages, new city/service pages.
 - If full-template refactor is needed, emit as a cross-agent note → §11.

-Execute your agent spec at ~/.claude/agents/seo-analyzer.md starting
-at STEP 2 (skip STEP 0 and STEP 1 — context is provided above).
-
-At STEP 13, emit the STRUCTURED ENVELOPE for merging (not a standalone
-SEO.md), INCLUDING the `## FIX BUNDLE` section terminated by the verbatim
-`READY TO APPLY — awaiting dispatcher confirmation` sentinel. Do NOT apply
-any fix, do NOT dispatch any sub-agent, do NOT write SEO.md — /seo applies
-your bundle in STEP 1.5 and merges the reports.
+Execute MODE: collect per your spec — STEP 2-5 only (context above
+replaces STEP 0-1). Write the signals file + COLLECTION COMPLETE
+sentinel, emit the COLLECT REPORT, stop. No scoring, no bundle.
 """

-Agent(subagent_type="geo-analyzer")
+Agent(subagent_type="geo-analyzer", model="sonnet")
 prompt: """
+MODE: collect
+RUNID: <RUNID_GEO>
 Dispatched from /seo. Context:

 AUDIT DEPTH: <LOCAL|FULL>
@@ -436,17 +450,62 @@ SHARED-FILE EDIT DISCIPLINE (carried into each bundle item):
  llms-full.txt.
 - If full-template refactor is needed, emit as a cross-agent note → §11.

-Execute your agent spec at ~/.claude/agents/geo-analyzer.md starting
-at STEP 2 (skip STEP 0 and STEP 1 — context is provided above).
-
-At STEP 14, emit the STRUCTURED ENVELOPE for merging (not a standalone
-GEO.md), INCLUDING the `## FIX BUNDLE` section terminated by the verbatim
-`READY TO APPLY — awaiting dispatcher confirmation` sentinel. Do NOT apply
-any fix, do NOT dispatch any sub-agent, do NOT write GEO.md/SEO.md — /seo
-applies your bundle in STEP 1.5 and merges the reports.
+Execute MODE: collect per your spec — STEP 2-5 only (context above
+replaces STEP 0-1). Write the signals file + COLLECTION COMPLETE
+sentinel, emit the COLLECT REPORT, stop. No scoring, no bundle.
 """
 ```

+**PHASE B — judge (both domains, one message, AFTER both COLLECT REPORTs
+are DONE):** no `model=` override — the opus frontmatter pins apply.
+
+```
+Agent(subagent_type="seo-analyzer")
+prompt: "MODE: judge
+RUNID: <RUNID_SEO>
+<the seo SHARED CONTEXT verbatim>
+Load .audit/seo-signals-<RUNID_SEO>.md (fail closed per your spec), run
+STEP 6-11, report scoring + findings + action plan + triage batches."
+
+Agent(subagent_type="geo-analyzer")
+prompt: "MODE: judge
+RUNID: <RUNID_GEO>
+<the geo SHARED CONTEXT verbatim>
+Load .audit/geo-signals-<RUNID_GEO>.md (fail closed per your spec), run
+STEP 6-12, report scoring + findings + action plan + triage batches."
+```
+
+Apply the DISPATCHER ERROR CONTRACT above on each returned verdict.
+
+**PHASE C — template (both domains, one message, only for domains whose
+judge is DONE):**
+
+```
+Agent(subagent_type="seo-analyzer", model="sonnet")
+prompt: "MODE: template
+<the seo SHARED CONTEXT verbatim>
+JUDGE REPORT (verbatim, ground truth — never re-derive a score):
+<the seo judge report>
+Run STEP 12-14: emit the STRUCTURED ENVELOPE for merging (not a
+standalone SEO.md), INCLUDING the `## FIX BUNDLE` section terminated by
+the verbatim `READY TO APPLY — awaiting dispatcher confirmation`
+sentinel. Do NOT apply any fix, do NOT dispatch any sub-agent, do NOT
+write SEO.md — /seo applies your bundle in STEP 1.5 and merges the
+reports."
+
+Agent(subagent_type="geo-analyzer", model="sonnet")
+prompt: "MODE: template
+<the geo SHARED CONTEXT verbatim>
+JUDGE REPORT (verbatim, ground truth — never re-derive a score):
+<the geo judge report>
+Run STEP 13-15: emit the STRUCTURED ENVELOPE for merging (not a
+standalone GEO.md), INCLUDING the `## FIX BUNDLE` section terminated by
+the verbatim `READY TO APPLY — awaiting dispatcher confirmation`
+sentinel. Do NOT apply any fix, do NOT dispatch any sub-agent, do NOT
+write GEO.md/SEO.md — /seo applies your bundle in STEP 1.5 and merges
+the reports."
+```
+
 ## STEP 1b — CHALLENGE THE FIX BUNDLE (advisory, before apply)
 Both envelopes now carry a `## FIX BUNDLE` — worth attacking before any edit lands.
 **Skip if intervention mode = conservative** (nothing is applied). Else persist both