Appraise

Runtime context (preprocessor snapshot):

• Active workflows: !find tmp -maxdepth 1 -name '.rune-*-*.json' -exec grep -l '"running"' {} + 2>/dev/null | wc -l | tr -d ' '
• Current branch: !git branch --show-current 2>/dev/null || echo "unknown"

/rune:appraise — Multi-Agent Code Review

Orchestrate a multi-agent code review using the Roundtable Circle architecture. Each Ash gets its own dedicated context window via Agent Teams.

Load skills: roundtable-circle, context-weaving, rune-orchestration, team-sdk

Spec-Aware Review (Discipline Integration)

When a plan_file_path is available (passed via arc Phase 6, or set in the inscription context), reviewers receive plan acceptance criteria in their inscription context. This enables spec-aware review — checking "does code match spec" in addition to "is code good".

Plan context injection (3 items added to reviewer inscription):

1. Plan file path + extracted acceptance criteria (AC-N entries)
2. Plan type (feat/fix/refactor from frontmatter) — affects what to look for
3. Reviewer SOW: Which criteria this reviewer is responsible for checking

Review findings can reference plan criteria IDs (AC-N) when applicable:

BACK-003 (P2): AC-2.3 (rate limiting) not fully implemented — missing 429 response code

Without plan: Standard code quality review ("Code is clean, LGTM") With plan: Spec-aware review ("AC-3 timeout handling not implemented in src/api.ts")

Activation: Automatic when plan_file_path is in the orchestration params or inscription context. No flag needed — the presence of plan context activates spec-aware behavior.

Orchestration Parameters

Appraise sets these parameters before delegating to the shared orchestration-phases.md:

const params = {
  scope: "diff",                          // Always diff for appraise (changed files only)
  depth: flags['--deep'] ? "deep" : "standard",  // Standard by default, deep with --deep
  teamPrefix: "rune-review",
  outputDir: `tmp/reviews/${identifier}/`,
  stateFilePrefix: "tmp/.rune-review",
  identifier,                              // "{gitHash}-{shortSession}"
  timeoutMs: 600_000,                      // 10 min
  label: "Review",
  workflow: "rune-review",
  focusArea: "full",                       // Appraise has no --focus flag
  // + configDir, ownerPid, sessionId (session isolation)
  // + selectedAsh, fileList, maxAgents, flags
}

Standard depth (default): Single-pass review with up to 7 Wave 1 Ashes. Identical to pre-deep behavior.

Deep depth (--deep): Multi-wave review. Phase 3 loops over waves from selectWaves(). Each wave creates its own team, tasks, and monitor cycle. See orchestration-phases.md for the full wave execution loop.

Flags

Partial mode is useful for reviewing a subset of changes before committing.

Deep mode runs 3 waves of review with up to 18 Ashes total. See orchestration-phases.md for the wave execution pattern and wave-scheduling.md for wave selection logic.

Dry-run mode executes Phase 0 (Pre-flight) and Phase 1 (Rune Gaze) only, then displays changed files classified by type, which Ash would be summoned, file assignments per Ash, estimated team size, and chunk plan if file count exceeds CHUNK_THRESHOLD. No teams, tasks, state files, or agents are created. If --deep + --partial is used, displays a warning about sparse findings from investigation Ashes.

Flag Interactions

Workflow Lock (reader)

const lockConflicts = Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_check_conflicts "reader"`)
if (lockConflicts.includes("CONFLICT")) {
  AskUserQuestion({ question: `Active workflow conflict:\n${lockConflicts}\nProceed anyway?` })
} else if (lockConflicts.includes("ADVISORY")) {
  // ADVISORY = reader/planner + writer coexistence (see workflow-lock.sh compatibility matrix)
  // SEC-6 FIX: sanitize lockConflicts output before interpolation
  const sanitizedConflicts = lockConflicts.replace(/[<>&"']/g, '')
  log(`Other workflow(s) detected in separate session(s):\n${sanitizedConflicts}\nCross-session concurrency is supported — proceeding normally.`)
}
Bash(`cd "${CWD}" && source plugins/rune/scripts/lib/workflow-lock.sh && rune_acquire_lock "appraise" "reader"`)

Phase 0: Pre-flight

Collect changed files and generate diff ranges. For detailed scope algorithms, staged/unstaged/HEAD~N detection, chunk routing, and --scope-file override logic — see review-scope.md.

Core steps:

1. Detect default_branch from git remote/fallback
2. Build changed_files — committed + staged + unstaged + untracked (or staged-only for --partial)
3. Filter: remove non-existent files, symlinks
4. Generate diff ranges for Phase 5.3 scope tagging (see diff-scope.md)

Abort conditions:

• No changed files → "Nothing to review. Make some changes first."
• Only non-reviewable files → "No reviewable changes found."

After file collection — route to chunked path if changed_files.length > CHUNK_THRESHOLD and --no-chunk is not set. Route to multi-pass if --cycles N with N > 1. Note: --cycles N is an alternative to chunking — it runs N standalone review passes with TOME merge between passes, useful for catching issues that require multiple passes.

Phase 0.3: Context Intelligence

Gathers PR metadata and linked issue context. Injects contextIntel into inscription.json (Phase 2). Includes sanitizeUntrustedText() for CDX-001/CVE-2021-42574 protection. Skipped when no gh CLI or --partial. Always enabled in v3.x.

Phase 0.4: Linter Detection

Discovers project linters (eslint, prettier, ruff, clippy, etc.) to suppress duplicate findings. SEC-/VEIL- findings are NEVER suppressed. Always enabled in v3.x.

See phase-0.3-0.4-context-and-linter.md for full pseudocode and sanitization function.

Phase 0.5: Lore Layer (Risk Intelligence)

Runs BEFORE team creation. Summons lore-analyst as a bare Agent (no team yet — ATE-1 exemption). Outputs risk-map.json and lore-analysis.md. Re-sorts changed_files by risk tier (CRITICAL → HIGH → MEDIUM → LOW → STALE).

Skip conditions: non-git repo, --no-lore, fewer than 5 commits in lookback window (G5 guard). Lore layer is enabled by default in v3.x.

Phase 0.6: Context Building (Conditional)

Runs BEFORE team creation. Spawns context-builder as a bare Agent (no TaskCreate, no team_name — same pattern as Phase 0.5 Lore Layer). Produces context-map.md for injection into Ash prompts.

Gate logic (hardcoded in v3.x):

const contextBuilding = "auto"
const threshold = { lines: 500, files: 5 }
const timeoutMs = 60000

if (flags['--dry-run']) → skip
if (diffLineCount > threshold.lines || fileCount >= threshold.files) → run
else → skip("[Context] Skipped — diff below threshold ({diffLineCount} lines, {fileCount} files)")

Execution (blocking bare Agent with elapsed-time timeout check; note the timeout is a post-hoc elapsed-time warning, not a hard preemptive kill — the Agent tool does not support explicit timeouts):

const contextOutputPath = `${outputDir}context-map.md`

// Sanitize file paths before injecting into prompt (SEC-002)
// Strip newlines/carriage returns that could inject instructions, truncate long paths
const sanitizedFiles = changedFiles.map(f =>
  f.replace(/[\n\r]/g, '').slice(0, 256)
)

// Use blocking Agent call; elapsed-time check below is advisory only (not a hard timeout)
const contextStartTime = Date.now()
Agent({
  subagent_type: "rune:research:context-builder",
  prompt: `Build a LIGHTWEIGHT context map for code review (not full audit).

SCOPE: Only analyze these changed files and their direct imports:
${sanitizedFiles.map(f => '- ' + f).join('\n')}

OUTPUT: Write to ${contextOutputPath}. Format:
## Trust Boundaries (max 5 entries)
- [BOUNDARY-N] {description} at {file:line} via {mechanism}
## Data Flow Paths (max 5 entries)
- [FLOW-N] {source} → {transform} → {sink} (files: {list})
## State Invariants (max 5 entries)
- [INV-N] {description} — ENFORCED|ASSUMED at {file:line}
## Entry Points (max 5 entries)
- [ENTRY-N] {route/handler} at {file:line} — reaches changed code via {path}
## Key Dependencies (max 5 entries)
- [DEP-N] {module} — guarantees: {what it provides}

CONSTRAINTS:
- Total output MUST be under 80 lines (2000 token budget)
- ONLY map architecture relevant to the changed files
- Cite file:line for every claim
- COMPREHENSION ONLY — do NOT report vulnerabilities
- Time budget: 45 seconds (leave 15s buffer for I/O)`,
  model: "sonnet"
})

// Check timeout after blocking call returns (timeoutMs hardcoded to 60000 in v3.x)
// Known limitation: context_building_timeout is a soft budget advisory via prompt instruction,
// not a hard platform-level timeout. The Agent tool does not support explicit timeouts.
const contextElapsed = Date.now() - contextStartTime
if (contextElapsed > timeoutMs) {
  warn(`[Context] Context building exceeded ${timeoutMs}ms (took ${contextElapsed}ms)`)
}

// Read output with existence check
contextMap = null
try {
  const content = Read(contextOutputPath)
  if (content && content.trim().length >= 100) {
    contextMap = content
    log(`[Context] Built context map — ${countEntries(content)} entries (${contextElapsed}ms)`)
  } else {
    log("[Context] Context map too small or empty — proceeding without context")
  }
} catch {
  log("[Context] Context builder timed out or failed — proceeding without context")
}

Skip conditions: --dry-run, diff below auto thresholds (500 lines / 5 files).

Phase 1: Rune Gaze (Scope Selection)

Classifies changed files by extension → selects Ashes. Custom Ash discovery (agent-backed + CLI-backed) happens here. --dry-run exits after this phase.

See phase-1-rune-gaze.md for full classification table, UX gate, and dry-run exit. See rune-gaze.md for the base algorithm.

Phase 2: Forge Team

Creates session-scoped identifier ({gitHash}-{shortSession}), writes state file with session isolation, generates inscription.json (diff_scope + context_intelligence + linter_context), runs teamTransition protocol, creates signal dir, and creates one task per Ash.

See phase-2-forge-team.md for full pseudocode. See engines.md for teamTransition protocol.

Phase 3: Summon Ash

Read and execute ash-summoning.md for the full prompt generation contract, inscription contract, custom Ashes, CLI-backed Ashes, and elicitation sage security context.

Key rules:

• Summon ALL selected Ash in a single message (parallel execution)
• Built-in Ash: load prompt from ../../agents/{category}/{role}.md
• Custom Ash: use wrapper template from roundtable-circle/references/custom-ashes.md
• Write file list to tmp/reviews/{identifier}/changed-files.txt — do NOT embed raw paths in prompts (SEC-006)

Phase 4: Monitor

Poll TaskList with timeout guard until all tasks complete. Uses the shared polling utility — see skills/roundtable-circle/references/monitor-utility.md.

POLL_INTERVAL = 30          // seconds
MAX_ITERATIONS = 20         // ceil(600_000 / 30_000) = 20 cycles = 10 min timeout
STALE_WARN = 300_000        // 5 minutes

for iteration in 1..MAX_ITERATIONS:
  1. Call TaskList tool            ← MANDATORY every cycle
  2. Count completed vs ashCount
  3. If completed >= ashCount → break
  4. Check stale: any task in_progress > 5 min → log warning
  5. Call Bash("sleep 30", { run_in_background: true })

Stale detection: If a task is in_progress for > 5 minutes, log a warning. No auto-release — review Ash findings are non-fungible.

Phase 4.5 + Phase 5 + Phase 5.3 + Phase 5.5 + Phase 6

Read and execute tome-aggregation.md for the full Runebinder aggregation, Doubt Seer cross-examination, diff-scope tagging, and Truthsight verification protocols.

Summary of phases:

• Phase 4.5 (Doubt Seer): Disabled by default in v3.x (doubt_seer.enabled = false). When enabled, cross-examines P1/P2 findings with 5-min timeout. VERDICT: BLOCK sets workflow_blocked flag.
• Phase 5 (Runebinder): Aggregates all Ash findings. Deduplicates using the canonical v3.x dedup hierarchy: SEC > BACK > VEIL > DOUBT > PY > TSR > RST > PHP > FAPI > DJG > LARV > SQLA > TDD > DDD > DI > API > DOM > PERF > FLOW > DOC > QUAL > FRONT > DES > AESTH > UXF > UXC > CDX (hardcoded — see references/v3-defaults.md settings.dedup_hierarchy). Writes TOME.md. Every finding MUST be wrapped in <!-- RUNE:FINDING ... --> markers for mend parsing. (UXH/UXI retired in v3.0.0-alpha.3 — see CHANGELOG.)
• Phase 5.3 (Diff-Scope Tagging): Orchestrator-only. Tags findings with scope="in-diff" or scope="pre-existing".
• Phase 6 (Truthsight): Layer 0 inline checks + Layer 2 verifier for P1 findings.

Phase 7: Cleanup

Dynamic member discovery → shutdown_request → grace period → TeamDelete with retry-with-backoff (4 attempts) → filesystem fallback → release workflow lock → update state file → present TOME → auto-mend or interactive prompt.

See phase-7-cleanup.md for full pseudocode.

Error Handling