seo-blog

SEO Blog Writer · Master Orchestrator (v3.7)

Production-grade content factory for the Google + AI search dual front.

⛔ STOP — READ THIS FIRST: Deterministic Runner-Driven Execution (v3.14)

When the intent is /article (full pipeline), you DRIVE THE PIPELINE WITH THE RUNNER, not by hand. DO NOT read the pipeline prose in this file and decide stages yourself. DO NOT call orchestrator --action next/verify manually between stages — the RUNNER does that for you. DO NOT write artifact JSON files (fact-check.json, humanizer-report.json, review.json) manually.

Why a runner now drives (v3.14, 2026-06-03)

Before v3.14 the orchestrator was a PASSIVE state machine and the LLM had to hand-drive all ~30 stages — calling --action next, running/dispatching each stage, then --action verify — between EVERY stage, for EVERY article. That manual ritual is exactly where steps got skipped or driven out of order (2026-05-26 "23/35 skipped"; 2026-06-02 "geo skipped"; 2026-06-03 "stage records missed + heavy by-hand driving"). Enforcement made bad outcomes detectable at the gates, but execution was only as reliable as operator discipline. scripts/pipeline/run_pipeline.py now drives the loop in CODE: it runs/launches/checks every BASH/BACKGROUND/CHECK stage itself and records it, and STOPS only to hand you the handful of LLM stages that genuinely need a subagent. Your surface area drops from "orchestrate 30 stages" to "service the LLM stages I'm handed."

The Loop (execute this after state.json is created)

REPEAT:
  1. result = Bash("python -m scripts.pipeline.run_pipeline --workspace {task_id} --json"
                   [+ " --completed-llm {last_llm_stage}" if you just finished one])

  2. Read result.action:
     "COMPLETE"      → DONE. Proceed to the publish-confirmation step.
     "DISPATCH_LLM"  → Dispatch Agent(subagent_type=result.subagent_type, prompt=result.dispatch_prompt).
                       If subagent_type is "", execute result.description inline (format-selector /
                       outline-architect / meta-builder are inline LLM stages).
                       After the subagent finishes, confirm every path in result.expected_outputs exists,
                       then GOTO 1 with --completed-llm {result.stage}.
                       ⚠ TRANSIENT NO-OP (v3.38.3): a dispatched subagent can occasionally return
                       with ZERO tool uses and no output files (harness init glitch — a 2026-07-09
                       humanizer did this, returning only a garbled system-reminder). expected_outputs
                       will be missing: simply RE-DISPATCH the same subagent once before investigating
                       anything else. Same rule when a subagent dies mid-run to an API/session error
                       (a geo-auditor was killed this way in the same batch): check whether its
                       evidence artifact landed on disk; if not, re-dispatch — the draft itself is
                       usually untouched.
     "GATE_FAILED"   → A lint/quality gate found defects (result.gate). Route to repair (fix the draft
                       or re-dispatch the responsible subagent per subskills/cross-cutting/repair-orchestrator),
                       then GOTO 1 (the runner re-runs the failed stage).
     "WAIT"          → A CHECK isn't ready (e.g. Fork B image gen still running). Wait briefly, GOTO 1.
     "BLOCKED"       → A stage is missing inputs (result.missing_inputs). Fix them, GOTO 1.
     "ERROR"         → A BASH stage crashed (result.detail). Inspect, fix, GOTO 1.
     "LOCKED"        → Another run_pipeline driver is ALREADY active on this workspace (exit 30).
                       Wait for it to return, then GOTO 1. NEVER delete the .pipeline-driver.lock
                       sidecar and NEVER launch a second driver call while one is still running —
                       the 2026-07-07 batch double-published 2 of 3 posts exactly this way (a bare
                       status-check invocation re-dispatched the in-flight wordpress-publisher).