run-bridge

name	run-bridge
description	Run Bridge — Autonomous Excellence Loop
capabilities	{"schema_version":1,"read_files":true,"search_code":true,"write_files":true,"execute_commands":true,"web_access":true,"user_interaction":true,"agent_spawn":true,"task_management":true}
cost-profile	unbounded
parallel_threshold	2000
timeout_minutes	480
zones	{"system":{"path":".claude","permission":"read"},"state":{"paths":["grimoires/loa",".beads",".run"],"permission":"read-write"},"app":{"paths":["src","lib","app"],"permission":"read-write"}}

Run Bridge — Autonomous Excellence Loop

Overview

The Run Bridge skill orchestrates an iterative improvement loop:

1. Execute sprint plan via /run sprint-plan
2. Invoke Bridgebuilder review on the resulting changes
3. Parse findings into structured JSON
4. Generate a new sprint plan from findings
5. Repeat until findings "flatline" (kaironic termination)

Each iteration leaves a GitHub trail (PR comments, vision links) and captures speculative insights in the Vision Registry. On completion, Grounded Truth is regenerated and RTFM validation runs as a final gate.

Cost

Estimated per invocation: $10–$20/depth-5 run (see Cost Matrix) External providers called: Codex Opus 4.7 (Bridgebuilder review), GPT-5.3-codex (cross-review dissent) To cap spend: Set hounfour.metering.budget.daily_micro_usd in .loa.config.yaml. Budget enforcement is active when hounfour.metering.enabled: true. If cost is a concern: Run /loa setup — the wizard will guide you to a budget-appropriate configuration.

Pricing verified: 2026-04-15. Prices change — recheck before large commitments.

Workflow

Phase 0: Input Guardrails

Check danger level (high) — requires explicit opt-in:

• run_bridge.enabled: true in .loa.config.yaml
• Not on a protected branch

Phase 1: Argument Parsing

Argument	Flag	Default
depth	--depth N	3 (max 5)
per_sprint	--per-sprint	false
resume	--resume	false
from	--from PHASE	—
single_iteration	--single-iteration	false (Issue #473)
no_silent_noop_detect	--no-silent-noop-detect	false (Issue #473)

--single-iteration (cycle-058, Issue #473): processes exactly one iteration body and exits. State is preserved so --resume --single-iteration picks up the next iteration. Use this when the calling skill wants to act on the SIGNAL:* lines from each iteration before the next one starts — rather than letting all iterations fire in one shell invocation where the skill has no chance to intercept.

Silent-no-op detection (cycle-058, Issue #473): at the end of a completed run, the orchestrator checks .run/bridge-reviews/ for findings files. If zero were produced across all iterations, it fails loud with exit 3 and an actionable error message. This prevents the scenario where SIGNAL:* lines fire via shell pipe but no skill acts on them, leading to silent JACKED_OUT with 0 findings. Pass --no-silent-noop-detect to opt out (intended for tests and CI scenarios where you want to validate flag parsing without producing real reviews).

Phase 2: Orchestrator Invocation

Invoke bridge-orchestrator.sh with translated flags:

.claude/scripts/bridge-orchestrator.sh \
  --depth "$depth" \
  ${per_sprint:+--per-sprint} \
  ${resume:+--resume} \
  ${from:+--from "$from"}

The orchestrator manages the state machine:

PREFLIGHT → JACK_IN → ITERATING ↔ ITERATING → FINALIZING → JACKED_OUT
                         ↓                        ↓
                       HALTED                    HALTED

Phase 3: Iteration Loop

For each iteration, the orchestrator emits SIGNAL lines that this skill interprets and acts on:

Signal	Action
GENERATE_SPRINT_FROM_FINDINGS	Create sprint plan from parsed findings
RUN_SPRINT_PLAN	Execute /run sprint-plan
RUN_PER_SPRINT	Execute per-sprint mode
PIPELINE_SELF_REVIEW	Detect .claude/ changes → run Red Team against pipeline SDDs (gated by run_bridge.pipeline_self_review.enabled)
RED_TEAM_CODE	Run red-team-code-vs-design.sh against SDD sections for implemented code (gated by red_team.code_vs_design.enabled)
BRIDGEBUILDER_REVIEW	Invoke Bridgebuilder on changes
VISION_CAPTURE	Check findings for VISION/SPECULATION severity → invoke bridge-vision-capture.sh (gated by vision_registry.bridge_auto_capture)
GITHUB_TRAIL	Run bridge-github-trail.sh
FLATLINE_CHECK	Evaluate flatline condition
LORE_DISCOVERY	Run lore-discover.sh → call vision_check_lore_elevation() for visions with refs > 0 (v1.42.0)

PIPELINE_SELF_REVIEW (cycle-046)

Before the Bridgebuilder review, the pipeline can review changes to itself:

1. Gate check: run_bridge.pipeline_self_review.enabled: true in config
2. Detection: pipeline-self-review.sh --base-branch main --output-dir <output>
   • Runs git diff --name-only main...HEAD -- .claude/scripts/ .claude/skills/ .claude/data/ .claude/protocols/
   • If no pipeline files changed → skip silently
3. SDD Resolution: Maps changed files to governing SDDs via .claude/data/pipeline-sdd-map.json
4. Self-Review: Invokes red-team-code-vs-design.sh against each resolved SDD
5. Output: Findings posted as PR comment with [Pipeline Self-Review] prefix

This addresses the "pipeline bugs have multiplicative impact" insight — the review infrastructure should examine itself with the same rigor it examines application code.

Red Team Gate Placement (cycle-047)

The Red Team code-vs-design gate (red-team-code-vs-design.sh) runs before the Bridgebuilder review, after code has been implemented. This placement is deliberate:

RUN_SPRINT_PLAN → PIPELINE_SELF_REVIEW → RED_TEAM_CODE → BRIDGEBUILDER_REVIEW → FLATLINE_CHECK

Why before Bridgebuilder, not after:

• Red Team checks code-vs-SDD compliance (did the code match the design?)
• Bridgebuilder reviews quality and architecture (is the design evolving well?)
• Compliance findings should be fixed before the Bridgebuilder sees the code, otherwise the Bridgebuilder wastes attention on compliance drift that will be fixed

Why after implementation, not before:

• Red Team needs actual code diff to compare against the SDD
• Pre-implementation Red Team is the /red-team skill (design-phase, attacks-only)
• Post-implementation Red Team is red-team-code-vs-design.sh (compliance check)

Relationship to reviewer/auditor in /run:

• /run cycle: implement → /review-sprint → /audit-sprint (per-sprint quality gates)
• Bridge cycle: sprint-plan → Red Team → Bridgebuilder (cross-iteration quality gates)
• These are complementary — /run gates check sprint-level quality, bridge gates check iteration-level architectural drift

Configuration:

# .loa.config.yaml
red_team:
  enabled: true
  code_vs_design:
    enabled: true          # Enable Red Team code-vs-design in bridge iterations

VISION_CAPTURE → LORE_DISCOVERY Chain (v1.42.0)

After BRIDGEBUILDER_REVIEW completes and findings are parsed:

1. VISION_CAPTURE (conditional):

   • Only fires when vision_registry.bridge_auto_capture: true in .loa.config.yaml
   • Filters parsed findings for VISION or SPECULATION severity
   • Invokes bridge-vision-capture.sh with findings JSON path
   • Creates vision entries in grimoires/loa/visions/entries/
   • Updates grimoires/loa/visions/index.md

2. LORE_DISCOVERY (always after VISION_CAPTURE):

   • Invokes lore-discover.sh to extract patterns from bridge reviews
   • Sources vision-lib.sh and calls vision_check_lore_elevation() for each vision with refs > 0
   • If elevation threshold met, calls vision_generate_lore_entry() and vision_append_lore_entry()
   • Logs elevation events to trajectory JSONL

Data flow: bridge finding JSON → vision entry → index update → lore elevation check

Phase 3.1: Enriched Bridgebuilder Review

When the BRIDGEBUILDER_REVIEW signal fires, execute this 10-step workflow:

1. Persona Integrity Check: Read persona path from config (yq '.run_bridge.bridgebuilder.persona_path' .loa.config.yaml, default: .claude/data/bridgebuilder-persona.md). Compare sha256sum <persona_path> against the base-branch version (git show origin/main:<persona_path> | sha256sum). If hashes differ, log WARNING and fall back to the base-branch version. If base-branch version doesn't exist (first deployment), proceed with local copy.

2. Persona Content Validation: Verify all 5 required sections exist and are non-empty:

   • # Bridgebuilder
   • ## Identity
   • ## Voice
   • ## Review Output Format
   • ## Content Policy If any section is missing or empty, log WARNING and disable persona enrichment for this iteration (fall back to unadorned review).

3. Lore Load: Query lore index for relevant entries from both discovered patterns AND elevated visions (closing the autopoietic loop):

   categories=$(yq '.run_bridge.lore.categories[]' .loa.config.yaml 2>/dev/null)
   # Load from both patterns.yaml (discovered patterns) and visions.yaml (elevated visions)
   

   Load short fields inline in the review prompt. Use context for teaching moments. The visions.yaml source ensures that insights which accumulated enough references through the vision registry feed back into future bridge reviews.

4. Embody Persona: Include the persona file content in the review prompt as the agent's identity and voice instructions. The persona defines HOW to review, not WHAT to review.

5. Dual-Stream Review: The review agent produces two streams:

   • Findings stream: Structured JSON inside <!-- bridge-findings-start/end --> markers. Includes enriched fields (faang_parallel, metaphor, teachable_moment, connection) and PRAISE findings when warranted.
   • Insights stream: Rich prose surrounding the findings block — opening context, architectural meditations, FAANG parallels, closing reflections.

6. Save Full Review: Write complete review (both streams) to .run/bridge-reviews/{bridge_id}-iter{N}-full.md with 0600 permissions.

7. Size Enforcement (SDD 3.5.1):

   • Body ≤ 65KB: post as-is
   • Body > 65KB: truncate prose, preserve findings JSON block
   • Body > 256KB: extract findings-only fallback

8. Content Redaction (SDD 3.5.2, Flatline SKP-006): Apply redact_security_content() with gitleaks-inspired patterns (AWS AKIA, GitHub ghp_/gho_/ghs_/ghr_, JWT eyJ, generic secrets). Allowlist protects sha256 hashes in markers and base64 diagram URLs.

9. Post-Redaction Safety Check (Flatline SKP-006): Scan redacted output for known secret prefixes (ghp_, gho_, AKIA, eyJ). If any remain, block posting and log error with line reference. The full review is still available in .run/.

10. Parse + Post: Parse findings via bridge-findings-parser.sh (JSON path with legacy fallback), then post via bridge-github-trail.sh comment.

Phase 4: Finalization

After loop termination (flatline or max depth):

1. Ground Truth Update: Run ground-truth-gen.sh --mode checksums
2. RTFM Gate: Test GT index.md, README.md, new protocol docs
   • All PASS → continue
   • FAILURE → generate 1 fix sprint, re-test (max 1 retry)
   • Second FAILURE → log warning, continue
3. Final PR Update: Update PR body with complete bridge summary

Phase 5: Progress Reporting

Report final metrics from .run/bridge-state.json:

• Total iterations completed
• Total sprints executed
• Total files changed
• Total findings addressed
• Total visions captured
• Flatline status

Configuration

run_bridge:
  enabled: true
  defaults:
    depth: 3
    per_sprint: false
    flatline_threshold: 0.05
    consecutive_flatline: 2
  timeouts:
    per_iteration_hours: 4
    total_hours: 24
  github_trail:
    post_comments: true
    update_pr_body: true
  ground_truth:
    enabled: true
  vision_registry:
    enabled: true
    auto_capture: true
  rtfm:
    enabled: true
    max_fix_iterations: 1
  lore:
    enabled: true
    categories:
      - mibera
      - neuromancer

Error Handling

Error	Cause	Resolution
"run_bridge.enabled is not true"	Config not set	Set run_bridge.enabled: true
"Cannot run bridge on protected branch"	On main/master	Switch to feature branch
"Sprint plan not found"	Missing sprint.md	Run /sprint-plan first
"Per-iteration timeout exceeded"	Single iteration too slow	Reduce sprint scope
"Total timeout exceeded"	Overall time limit hit	Resume with /run-bridge --resume

Constraints

• C-BRIDGE-001: ALWAYS use /run sprint-plan within bridge iterations
• C-BRIDGE-002: ALWAYS post Bridgebuilder review as PR comment
• C-BRIDGE-003: ALWAYS ensure GT claims cite file:line references
• C-BRIDGE-004: ALWAYS use YAML format for lore entries
• C-BRIDGE-005: ALWAYS include source bridge iteration and PR in vision entries