Vinhnxv Rune Plugin Arc

/rune:arc — End-to-End Orchestration Pipeline

Chains forty-five phases into a single automated pipeline. Each phase runs as its own Claude Code turn with fresh context — the arc-phase-stop-hook.sh drives phase iteration via the Stop hook pattern. Artifact-based handoff connects phases. Checkpoint state enables resume after failure.

Context budget advisory: Full arc run: 45 phases x ~3.5min avg = ~154 minutes (lower bound). Context compaction is almost guaranteed in a single session. For constrained sessions, use --no-forge to skip Phase 1 enrichment, or split into multiple /rune:arc --resume sessions. The PreCompact hook saves checkpoint state automatically.

Load skills: roundtable-circle, context-weaving, rune-echoes, rune-orchestration, elicitation, codex-cli, team-sdk, testing, agent-browser, polling-guard, zsh-compat, design-sync

CRITICAL — Agent Teams Enforcement (ATE-1)

EVERY phase that summons agents MUST follow this exact pattern. No exceptions.

1. TeamCreate({ team_name: "{phase-prefix}-{id}" })     ← CREATE TEAM FIRST
2. TaskCreate({ subject: ..., description: ... })         ← CREATE TASKS
3. Agent({ team_name: "...", name: "...",                  ← SPAWN WITH team_name
     subagent_type: "general-purpose",                    ← ALWAYS general-purpose
     prompt: "You are {agent-name}...", ... })             ← IDENTITY VIA PROMPT
4. Monitor → Shutdown → TeamDelete with fallback          ← CLEANUP

NEVER DO:

• Agent({ ... }) without team_name — bare Agent calls bypass Agent Teams entirely.
• Using named subagent_type values — always use subagent_type: "general-purpose" and inject agent identity via the prompt.

ENFORCEMENT: The enforce-teams.sh PreToolUse hook blocks bare Agent calls when a Rune workflow is active.

Phase Number → Name Mapping

The pipeline uses named phases (not numeric IDs) in PHASE_ORDER. The numeric labels below are for human reference only — execution order is always determined by position in PHASE_ORDER.

Execution order: The "Exec Order" column shows the actual sequence. Phase numbers (#) are for human reference only and are non-monotonic — e.g., 5.8 (gap_remediation) runs before 5.7 (goldmask_verification). Always use PHASE_ORDER array position, not numeric IDs. Total: 45 phases.

Usage

/rune:arc <plan_file.md>              # Full pipeline
/rune:arc <plan_file.md> --no-forge   # Skip research enrichment
/rune:arc <plan_file.md> --approve    # Require human approval for work tasks
/rune:arc --resume                    # Resume from last checkpoint
/rune:arc <plan_file.md> --skip-freshness   # Skip freshness validation
/rune:arc <plan_file.md> --confirm          # Pause on all-CONCERN escalation
/rune:arc <plan_file.md> --no-pr           # Skip PR creation (Phase 9)
/rune:arc <plan_file.md> --no-merge        # Skip auto-merge (Phase 9.5)
/rune:arc <plan_file.md> --draft           # Create PR as draft
/rune:arc <plan_file.md> --bot-review     # Enable bot review wait + comment resolution
/rune:arc <plan_file.md> --no-bot-review  # Force-disable bot review
/rune:arc <plan_file.md> --no-accept-external  # Prompt when unrelated changes detected (default: accept)

Flags

Note: Worktree mode for /rune:strive (Phase 5) is activated via work.worktree.enabled: true in talisman.yml, not via a --worktree flag on arc.

External Changes Policy (accept_external_changes)

When --accept-external is passed (or arc.defaults.accept_external_changes: true in talisman), the pipeline tolerates commits on the working branch that are NOT part of the plan. This is common when:

• Running /rune:arc-batch where prior arcs leave commits on the branch
• Running /rune:audit or manual bug fixes in a parallel session that commit to the same branch
• Cherry-picking hotfixes onto the arc's working branch

Behavior when enabled:

• Do NOT pause or prompt the user about unrelated changes — continue autonomously
• Gap analysis evaluates only plan criteria coverage; external changes are not flagged as drift
• Code review reviews all changes but does not halt for code outside plan scope
• All commits (plan-related and external) are included in the PR

Default: true (accept external changes silently). Use --no-accept-external or arc.defaults.accept_external_changes: false to restore the prompting behavior.

Workflow Lock (writer)

const lockConflicts = Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_check_conflicts "writer"`)
if (lockConflicts.includes("CONFLICT")) {
  AskUserQuestion({ question: `Active workflow conflict:\n${lockConflicts}\nProceed anyway?` })
}
Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_acquire_lock "arc" "writer"`)

Pre-flight

See arc-preflight.md for the full pre-flight sequence.

Read and execute the arc-preflight.md algorithm at dispatcher init.

Plan Freshness Check (FRESH-1)

See freshness-gate.md for the full algorithm.

Read and execute the algorithm. Store freshnessResult for checkpoint initialization below.

Context Monitoring Bridge Check (non-blocking advisory)

const bridgePattern = `/tmp/rune-ctx-*.json`
const bridgeFiles = Bash(`ls ${bridgePattern} 2>/dev/null | head -1`).trim()
if (!bridgeFiles) {
  warn(`Context monitoring bridge not detected.`)
}
const ctxBridgeFile = bridgeFiles || null

Phase Constants

Read arc-phase-constants.md for PHASE_ORDER, PHASE_TIMEOUTS, CYCLE_BUDGET, calculateDynamicTimeout(), FORBIDDEN_PHASE_KEYS, and updateCascadeTracker().

Initialize Checkpoint (ARC-2)

See arc-checkpoint-init.md for the full initialization.

Read and execute the arc-checkpoint-init.md algorithm.

Inter-Phase Cleanup Guard (ARC-6)

See arc-preflight.md for prePhaseCleanup().

Read(references/arc-preflight.md)
Read(references/arc-phase-cleanup.md)

Stale Arc Team Scan

See arc-preflight.md for the stale team scan algorithm.

Status (--status)

Early return — display current arc phase, progress, and elapsed time without entering the pipeline.

if (args.includes("--status")) {
  const output = Bash(`"${RUNE_PLUGIN_ROOT}/scripts/rune-status.sh"`)
  // Display current phase, elapsed time, completed/total phases
  return output
}

Resume (--resume)

See arc-resume.md for the full resume algorithm.

if (args.includes("--resume")) {
  Read(references/arc-preflight.md)
  Read(references/arc-phase-cleanup.md)
  Read and execute the arc-resume.md algorithm.
}

Pre-Flight: State File Conflict Detection

Enforces ONE arc at a time — checks for existing state files from previous or concurrent sessions. Handles 6 cases (F1-F6) including hard blocks, resume prompts, and stale cleanup.

See arc-state-conflict.md for the full conflict detection algorithm and case table.

Phase Loop State File

Co-located with checkpoint init (v2.6.0): The phase loop state file is now written as part of arc-checkpoint-init.md, immediately after the checkpoint Write() call. This eliminates the "missing state file" bug where the LLM wrote the checkpoint but skipped this step under context pressure.

If you are here during execution, the state file (.rune/arc-phase-loop.local.md) should already exist. If it does not, the safety guard in "First Phase Invocation" below will catch and recover.

See arc-phase-loop-state.md for the state file schema reference.

Discipline Integration

Integrates at 3 points: Phase 5 (work loop with AC criteria), Phase 8.5 (SCR/proof metrics), Post-Arc (echo persist). Config: discipline.enabled (default: true), discipline.block_on_fail (default: false). See strive/references/discipline-work-loop.md and discipline/references/metrics-schema.md.

Blind AC Verification (Phase 5 — strive-internal)

When blind_verification.enabled: true in talisman, strive Phase 4.6 runs a blind AC verification gate within the work phase. A blind-validation-agent receives ONLY the plan's acceptance criteria and the committed code — no worker context, no task files, no implementation notes. This is NOT a separate arc phase; it runs inside /rune:strive as a quality gate before Phase 5 (echo persist). Config: blind_verification.model (default: "sonnet"), blind_verification.fail_on_partial (default: false), blind_verification.max_remediation (default: 1), blind_verification.timeout_ms (default: 120000).

QA Discipline Protocol

Independent QA gates enforce quality obligations at every gated phase. The Tarnished (orchestrator) and all phase agents MUST adhere to these 6 obligations:

1. No self-evaluation: The Tarnished MUST NOT evaluate its own phase output. QA agents are spawned as independent teammates with read-only access to phase artifacts. QA verdicts cannot be overridden programmatically.

2. Verdict file contract: Every QA gate MUST produce a verdict JSON file at tmp/arc/{id}/qa/{phase}-verdict.json before the stop hook advances. Missing verdict files default to FAIL with timed_out: true.

3. GUARD 9 retry budget: QA retries are capped at MAX_QA_RETRIES (2), which MUST remain strictly less than MAX_PHASE_DISPATCHES - 1 (currently 3). Exceeding this invariant triggers GUARD 9 destruction of the state file. Do NOT increase MAX_QA_RETRIES without first raising MAX_PHASE_DISPATCHES in the stop hook.

4. Score transparency: All QA scores (artifact, quality, completeness, overall) are persisted in verdict files and surfaced in the QA Dashboard (tmp/arc/{id}/qa/dashboard.md). No phase may suppress or alter QA scores after they are written.

5. Human escalation: When QA fails after max retries, the pipeline MUST escalate to the human via AskUserQuestion — never silently skip or auto-pass a failed gate.

6. Dashboard generation: After the last QA-gated phase completes, generateQADashboard(arcId) MUST be called to produce the consolidated pipeline quality summary. The dashboard is injected into the PR body (Phase 9) for reviewer visibility.

See arc-phase-qa-gate.md for the full QA gate architecture, scoring system, and per-phase checklists.

First Phase Invocation

Execute the first pending phase from the checkpoint. The Stop hook (arc-phase-stop-hook.sh) handles all subsequent phases automatically.

CRITICAL — Single-Phase-Per-Turn Rule: You MUST execute exactly ONE phase per turn, then STOP responding. Do NOT batch-process multiple phases in a single turn. Do NOT skip conditional phases (semantic_verification, design_extraction, design_prototype, task_decomposition) based on assumptions — each phase has its own gate logic in its reference file that MUST be executed. The Stop hook advances to the next phase automatically. Violating this rule causes phases to be skipped without proper gate evaluation.

// ── SAFETY GUARD: Verify phase loop state file exists before first phase ──
// FIX (v2.6.0): Catches the case where checkpoint init completed but state file
// write was skipped (context pressure, LLM shortcutting, or error between steps).
// Without this file, the Stop hook silently exits 0 and the arc stalls after Phase 1.
const stateFilePath = '.rune/arc-phase-loop.local.md'
const stateFileExists = Bash(`test -f "${stateFilePath}" && echo "ok" || echo "missing"`).trim()
if (stateFileExists !== 'ok') {
  warn('RECOVERY: Phase loop state file missing — recreating from checkpoint.')
  // Reconstruct from checkpoint data (checkpoint was written successfully)
  const cp = JSON.parse(Read(checkpointPath))
  const recoverySessionId = "${CLAUDE_SESSION_ID}" || Bash('echo "${RUNE_SESSION_ID:-}"').trim() || 'unknown'
  const recoveryBranch = Bash("git branch --show-current 2>/dev/null").trim() || 'main'
  const recoveryOwnerPid = Bash('echo $PPID').trim()

  // ── INTEG-RECOVERY validation (v2.29.8): Validate checkpoint fields before propagating ──
  // BUG FIX: If checkpoint has corrupt config_dir (e.g., tmp/arc/...), the recovery path
  // would propagate the corruption to the new state file, bypassing all 3 layers of validation.
  // Resolve config_dir from CLAUDE_CONFIG_DIR directly — do NOT trust checkpoint's config_dir.
  const recoveryConfigDir = Bash('cd "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" 2>/dev/null && pwd -P').trim()
  if (!recoveryConfigDir || recoveryConfigDir.startsWith('tmp/') || recoveryConfigDir.includes('/tmp/arc/')) {
    throw new Error(`FATAL (INTEG-RECOVERY-001): Resolved config_dir "${recoveryConfigDir}" is invalid. Cannot recover state file.`)
  }
  if (!recoveryOwnerPid || !/^\d+$/.test(recoveryOwnerPid)) {
    throw new Error(`FATAL (INTEG-RECOVERY-002): owner_pid "${recoveryOwnerPid}" is invalid.`)
  }
  if (recoverySessionId === 'unknown') {
    throw new Error(`FATAL (INTEG-RECOVERY-003): session_id is unknown — cannot recover state file without session identity.`)
  }
  if (!cp.plan_file || cp.plan_file === 'null') {
    throw new Error(`FATAL (INTEG-RECOVERY-004): checkpoint.plan_file is empty/null — cannot recover.`)
  }
  // Warn if checkpoint config_dir was corrupt (the bug we're fixing)
  if (cp.config_dir && (cp.config_dir.startsWith('tmp/') || cp.config_dir.includes('/tmp/arc/'))) {
    warn(`INTEG-RECOVERY: Checkpoint had corrupt config_dir="${cp.config_dir}" — using fresh resolution "${recoveryConfigDir}" instead.`)
  }

  const recoveryContent = `---
active: true
iteration: 0
max_iterations: 66
checkpoint_path: ${checkpointPath}
plan_file: ${cp.plan_file}
branch: ${recoveryBranch}
arc_flags: ${(cp.flags?.no_forge ? '--no-forge ' : '') + (cp.flags?.approve ? '--approve ' : '') + (cp.flags?.no_test ? '--no-test ' : '')}
config_dir: ${recoveryConfigDir}
owner_pid: ${recoveryOwnerPid}
session_id: ${recoverySessionId}
compact_pending: false
user_cancelled: false
cancel_reason: null
cancelled_at: null
stop_reason: null
---
`
  Write(stateFilePath, recoveryContent)

  // Post-write verification (same pattern as arc-checkpoint-init.md)
  const recoveryVerifyConfigDir = Bash('grep "^config_dir:" .rune/arc-phase-loop.local.md | sed "s/^config_dir: //"').trim()
  if (recoveryVerifyConfigDir !== recoveryConfigDir) {
    throw new Error(`FATAL (INTEG-RECOVERY-POST): Written config_dir "${recoveryVerifyConfigDir}" ≠ expected "${recoveryConfigDir}".`)
  }
  log('Phase loop state file recovered successfully.')
}

// Check for context-critical shutdown signal before starting next phase (Layer 1)
const shutdownSignalCheck = (() => {
  try {
    const sid = "${CLAUDE_SESSION_ID}" || Bash(`echo "\${RUNE_SESSION_ID:-}"`).trim()
    const signalPath = `tmp/.rune-shutdown-signal-${sid}.json`
    const signal = JSON.parse(Read(signalPath))
    return signal?.signal === "context_warning"
  } catch { return false }
})()

if (shutdownSignalCheck) {
  warn("CTX-WARNING: Context pressure detected between phases. Skipping remaining phases.")
  // Mark remaining phases as skipped in checkpoint
  for (const p of PHASE_ORDER) {
    if (checkpoint.phases[p]?.status === 'pending') {
      checkpoint.phases[p].status = 'skipped'
      checkpoint.phases[p].skip_reason = 'context_pressure'
    }
  }
  Write(checkpointPath, checkpoint)
  return
}

// Find first pending phase
const firstPending = PHASE_ORDER.find(p => checkpoint.phases[p]?.status === 'pending')
if (!firstPending) {
  log("All phases already complete. Nothing to execute.")
  return
}

// Schema v19: stamp phase start time before executing
checkpoint.phases[firstPending].started_at = new Date().toISOString()
Write(checkpointPath, checkpoint)

// Read and execute the phase reference file
const refFile = getPhaseReferenceFile(firstPending)
Read(refFile)
// Execute the phase algorithm as described in the reference file.
// When done, update checkpoint.phases[firstPending].status to "completed".
// Schema v19: stamp phase completion time and compute duration
const completionTs = Date.now()
checkpoint.phases[firstPending].completed_at = new Date(completionTs).toISOString()
const phaseStartMs = new Date(checkpoint.phases[firstPending].started_at).getTime()
checkpoint.totals = checkpoint.totals ?? { phase_times: {}, total_duration_ms: null, cost_at_completion: null }
const phaseDuration = completionTs - phaseStartMs
checkpoint.totals.phase_times[firstPending] = Number.isFinite(phaseDuration) && phaseDuration >= 0
  ? phaseDuration : null
// Then STOP responding — the Stop hook will advance to the next phase.

Phase-to-reference mapping: See arc-phase-stop-hook.sh _phase_ref() function for the canonical phase → reference file mapping.

Timing instrumentation: Each phase MUST stamp started_at before execution and completed_at + totals.phase_times[phaseName] (duration in ms) after. The Stop hook re-injects this same pattern for all subsequent phases via the phase prompt template. The totals.phase_times map accumulates durations across the full pipeline.

Spec Continuity (Plan Path Propagation)

The plan_file path written to the phase loop state file and checkpoint is propagated to downstream phases that need the original plan specification as their source-of-truth. Each phase reference file reads plan_file from the checkpoint before spawning agents.

Rule: Phases that consume plan_file_path MUST read it from checkpoint.plan_file (not from the state file or flags). Workers receive it as planFilePath in their context prompt so they can cross-reference the original spec, even when the pipeline spans multiple sessions via --resume.

Post-Arc (Final Phase)

MANDATORY: These steps run after Phase 9.5 MERGE (the last phase). The Stop hook injects a completion prompt when all phases are done. You MUST read and execute arc-phase-completion-stamp.md and post-arc.md — do NOT skip them or just present a summary. The plan file update is the primary deliverable of this phase.

Timing Totals + Completion Stamp (schema v19)

Before calling the Plan Completion Stamp, record arc-level timing metrics:

// Schema v19: record arc completion time and total duration
const completedAtTs = new Date().toISOString()
checkpoint.completed_at = completedAtTs
checkpoint.totals = checkpoint.totals ?? { phase_times: {}, total_duration_ms: null, cost_at_completion: null }
const totalDuration = Date.now() - new Date(checkpoint.started_at).getTime()
if (!Number.isFinite(totalDuration) || totalDuration < 0) {
  warn(`Arc timing anomaly: computed duration ${totalDuration}ms — setting to null`)
  checkpoint.totals.total_duration_ms = null
} else {
  checkpoint.totals.total_duration_ms = totalDuration
}

// Read cost from statusline bridge file (non-blocking — skip if unavailable)
if (ctxBridgeFile) {
  try {
    const bridge = JSON.parse(Bash(`cat "${ctxBridgeFile}" 2>/dev/null`))
    checkpoint.totals.cost_at_completion = bridge.cost ?? null
  } catch (e) { /* bridge unavailable — leave null */ }
}
Write(checkpointPath, checkpoint)

Plan Completion Stamp

See arc-phase-completion-stamp.md. Runs FIRST after merge — writes persistent record before context-heavy steps.

Result Signal (automatic)

Written automatically by arc-result-signal-writer.sh PostToolUse hook. No manual call needed. See arc-result-signal.md.

Echo Persist + Completion Report

See post-arc.md for echo persist and completion report template.

Discipline accountability echo: When discipline.enabled: true and convergence metrics exist in the arc checkpoint, write a pipeline-level discipline echo to .rune/echoes/discipline/MEMORY.md with aggregate SCR, first-pass rate, failure code distribution, and trend detection vs historical averages. See discipline/references/accountability-protocol.md for the full echo format and trend detection algorithm.

Proof Manifest Persistence (Discipline Integration, v1.173.0)

Persists the proof manifest (SCR + DSR per criterion) as a PR comment after ship/merge. Includes code compliance and design compliance (when design_sync.enabled). Uses --body-file for injection-safe PR comments.

See arc-proof-manifest.md for the full manifest schema and persistence logic.

Lock Release

Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_release_all_locks`)

Final Sweep (ARC-9) + Response Completion

See post-arc.md. 30-second budget. After sweep, finish your response immediately — IGNORE zombie teammate messages (Stop hook handles cleanup).

References

• Architecture & Pipeline Overview — Pipeline diagram, orchestrator design, transition contracts
• Phase Constants — PHASE_ORDER, PHASE_TIMEOUTS, CYCLE_BUDGET, shared utilities
• Failure Policy — Per-phase failure handling matrix
• Checkpoint Init — Schema v20, 3-layer config resolution
• Resume — Checkpoint restoration, schema migration
• Pre-flight — Git state, branch creation, stale team scan, prePhaseCleanup
• Phase Cleanup — postPhaseCleanup, PHASE_PREFIX_MAP
• Freshness Gate — 5-signal plan drift detection
• Phase Tool Matrix — Per-phase tool restrictions and time budgets
• Delegation Checklist — Phase delegation contracts (RUN/SKIP/ADAPT)
• Naming Conventions — Gate/validator/sentinel/guard taxonomy
• Post-Arc — Echo persist, completion report, ARC-9 sweep
• Completion Stamp — Plan file completion record
• Result Signal — Deterministic completion signal for stop hooks
• Stagnation Sentinel — Error pattern detection, budget enforcement
• Codex Phases — Phases 2.8, 4.5, 5.6, 7.8, 8.55
• Task Decomposition — Phase 4.5
• Design Extraction — Phase 3 (conditional)
• Storybook Verification — Phase 3.3 (conditional: storybook.enabled)
• Design Verification — Phase 5.2 (conditional)
• State Conflict Detection — Pre-flight F1-F6 conflict cases
• Phase Loop State — State file template for Stop hook driver
• Proof Manifest — Discipline proof manifest persistence (v1.173.0)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.