Preflight

preflight

Purpose

Preflight verdict of BLOCK stops the pipeline. The calling skill (cook, deploy, launch) MUST halt until all BLOCK findings are resolved and preflight re-runs clean.

Pre-commit quality gate that catches "almost right" code — the kind that compiles and passes linting but has logic errors, missing error handling, or incomplete implementations. Goes beyond static analysis to check data flow, edge cases, async correctness, and regression impact. The last defense before code enters the repository.

Triggers

• Called automatically by cook before commit phase
• Called by fix after applying fixes (verify fix quality)
• /rune preflight — manual quality check
• Auto-trigger: when staged changes exceed 100 LOC

Calls (outbound)

• scout (L2): find code affected by changes (dependency tracing)
• sentinel (L2): security sub-check on changed files
• hallucination-guard (L3): verify imports and API references exist
• test (L2): run test suite as pre-commit check

Called By (inbound)

• cook (L1): before commit phase — mandatory gate

Check Categories

LOGIC       — data flow errors, edge case misses, async bugs
ERROR       — missing try/catch, bare catches, unhelpful error messages
REGRESSION  — untested impact zones, breaking changes to public API
COMPLETE    — missing validation, missing loading states, missing tests
SECURITY    — delegated to sentinel
IMPORTS     — delegated to hallucination-guard

Executable Steps

Stage A — Spec Compliance (Plan vs Diff)

Before checking code quality, verify the code matches what was planned.

Use Bash to get the diff: git diff --cached (staged) or git diff HEAD (all changes). Use Read to load the approved plan from the calling skill (cook passes plan context).

Check each plan phase against the diff:

| Plan says... | Diff shows... | Verdict | |---|---|---| | "Add function X to file Y" | Function X exists in file Y | PASS | | "Add function X to file Y" | Function X missing | BLOCK — incomplete implementation | | "Modify function Z" | Function Z untouched | BLOCK — planned change not applied | | Nothing about file W | File W modified | WARN — out-of-scope change (scope creep) |

Output: List of plan-vs-diff mismatches. Any missing planned change = BLOCK. Any unplanned change = WARN.

If no plan is available (manual preflight invocation), skip Stage A and proceed to Step 1.

Step 1 — Logic Review

Use Read to load each changed file. For every modified function or method:

• Trace the data flow from input to output. Identify where a null, undefined, empty array, or 0 value would cause a runtime error or wrong result.
• Check async/await: every async function that calls an async operation must await it. Identify missing await that would cause race conditions or unhandled promise rejections.
• Check boundary conditions: off-by-one in loops, array index out of bounds, division by zero.
• Check type coercions: implicit == comparisons that could produce wrong results, string-to-number conversions without validation.

Common patterns to flag:

// BAD — missing await (race condition)
async function processOrder(orderId: string) {
  const order = db.orders.findById(orderId); // order is a Promise, not a value
  return calculateTotal(order.items); // crashes: order.items is undefined
}
// GOOD
async function processOrder(orderId: string) {
  const order = await db.orders.findById(orderId);
  return calculateTotal(order.items);
}

// BAD — sequential independent I/O
const user = await fetchUser(id);
const permissions = await fetchPermissions(id); // waits unnecessarily
// GOOD — parallel
const [user, permissions] = await Promise.all([fetchUser(id), fetchPermissions(id)]);

Flag each issue with: file path, line number, category (null-deref | missing-await | off-by-one | type-coerce), and a one-line description.

Step 2 — Error Handling

For every changed file, verify:

• Every async function has a try/catch block OR the caller explicitly handles the rejected promise.
• No bare catch(e) {} or except: pass — every catch must log or rethrow with context.
• Every fetch / HTTP client call checks the response status before consuming the body.
• Error messages are user-friendly: no raw stack traces, no internal variable names exposed to the client.
• API route handlers return appropriate HTTP status codes (4xx for client errors, 5xx for server errors).

Common patterns to flag:

// BAD — swallowed exception
try {
  await saveUser(data);
} catch (e) {} // silent failure, caller never knows

// BAD — leaks internals to client
app.use((err, req, res, next) => {
  res.status(500).json({ error: err.stack }); // exposes stack trace
});
// GOOD — log internally, generic message to client
app.use((err, req, res, next) => {
  logger.error(err);
  res.status(500).json({ error: 'Internal server error' });
});

Flag each violation with: file path, line number, category (bare-catch | missing-status-check | raw-error-exposure), and description.

Step 3 — Regression Check

Use rune:scout to identify all files that import or depend on the changed files/functions. For each dependent file:

• Check if the changed function signature is still compatible (parameter count, types, return type).
• Check if the dependent file has tests that cover the interaction with the changed code.
• Flag untested impact zones: dependents with zero test coverage of the affected code path.

Flag each regression risk with: dependent file path, what changed, whether tests exist, severity (breaking | degraded | untested).

Step 4 — Completeness Check

Verify that new code ships complete:

• New API endpoint → has input validation schema (Zod, Pydantic, Joi, etc.)
• New React/Svelte component → has loading state AND error state
• New feature → has at least one test file
• New configuration option → has documentation (inline comment or docs file)
• New database query → has corresponding migration file if schema changed

Framework-specific completeness (apply only if detected):

• React component with async data → must have loading state AND error state
• Next.js Server Action → must have try/catch and return typed result
• FastAPI endpoint → must have Pydantic request/response models
• Django ViewSet → must have explicit permission_classes
• Express route → must have input validation middleware before handler

If any completeness item is missing, flag as WARN with: what is missing, which file needs it.

Step 4.2 — Coherence Check

Verify that new code is consistent with existing project patterns — not just correct, but coherent with the codebase it lives in.

| Check | What To Look For | Severity | |-------|------------------|----------| | Naming conventions | New functions/variables follow project's existing naming style (camelCase, snake_case, etc.) | WARN | | File organization | New files placed in correct directory per project structure (e.g., utils/ not lib/, components/ not ui/) | WARN | | Import patterns | Uses project's established import style (absolute vs relative, barrel exports vs direct) | WARN | | Error handling style | Matches project's existing pattern (Result type, try/catch, error codes) | WARN | | State management | Uses same state approach as rest of project (Zustand, context, stores) | BLOCK if different paradigm | | API patterns | Follows existing response format, middleware chain, auth pattern | BLOCK if diverges | | Design system usage | Uses existing design tokens/components, not inline overrides | WARN |

Detection: Read 2-3 existing files in the same directory as the change. Compare patterns. Flag divergences.

Skip if: Project has no established patterns (greenfield, .md with CAP-* entries but no results | WARN: "Capability evals defined but not executed" | | Regression eval failing | Any REG-* eval with status=fail | BLOCK: "Regression detected — existing behavior broken" | | Capability eval below threshold | CAP-* eval pass@k below defined threshold | WARN: "Capability eval below threshold (X% vs Y% required)" | | No eval file for new feature | New feature added (detected by new test files + new source files) but no .rune/evals/` entry | INFO: "Consider defining capability evals for new feature" |

Skip if: No .rune/evals/ directory exists (project hasn't adopted eval-driven development).

Step 4.5 — Domain Quality Hooks

Apply domain-specific quality checks based on detected file types in the diff. These extend the generic completeness checks in Step 4 with deeper domain validation.

Domain hooks are additive — they add checks, never remove generic ones from Steps 1-4. If a domain hook flags BLOCK, the overall preflight verdict is BLOCK regardless of other steps.

Hook Selection (auto-detect from diff)

| Detected Pattern | Domain Hook | Key Checks | |-----------------|-------------|------------| | migrations/*.sql, *.migration.* | Database | Rollback script present, no bare DROP/DELETE, migration tested | | openapi.*, *.graphql, *.proto | API Contract | Breaking changes flagged, version bumped, deprecated fields documented | | docs/policies/*, PRIVACY*, TERMS* | Legal/Compliance | No placeholder text, review date current, practice matches policy | | **/billing*, **/payment*, **/invoice* | Financial | Decimal precision correct, currency locale-aware, no hardcoded rates | | *.tsx, *.jsx, *.svelte, *.vue, components/* | UI/Frontend | Design token compliance, animation a11y, touch targets, visual hierarchy | | skills/*/SKILL.md, extensions/*/PACK.md | Rune Skill | Frontmatter valid, all required sections present, word count within layer budget | | *.test.*, *.spec.*, __tests__/* | Test Quality | No .skip/.only left in, assertions present (not empty tests), no hardcoded timeouts |

Domain Hook Execution

For each detected domain, run its checks on the relevant files in the diff:

1. Identify which domain hooks apply based on changed file patterns
2. Load domain-specific check rules (inline above, or from pack reference files if a pack is installed)
3. Scan each relevant file for domain violations
4. Classify findings: BLOCK (data loss risk, breaking contract) or WARN (best practice, incomplete)
5. Append to preflight report under ### Domain Quality section

UI/Frontend Domain Checks

When UI/Frontend hook is triggered, run these checks on all .tsx/.jsx/.svelte/.vue files in the diff.

Preamble — load design contract: If .rune/design-system.md exists, read it once. Apply the project's Scale Minimums block over the defaults below (e.g., a project declaring body ≥18px should flag 16px body text). If the file is absent, use defaults and emit a LOW advisory: "No .rune/design-system.md — run rune design to lock visual decisions."

| Check | What to Scan | Severity | |-------|-------------|----------| | Design token compliance | Hardcoded colors (#fff, rgb(, hsl() instead of CSS variables or Tailwind tokens | WARN: "Hardcoded color at {file}:{line} — use design token" | | UI-SPEC drift | If .rune/ui-spec.md exists, compare component decisions (card style, form layout, nav type) against spec | BLOCK: "Component at {file} uses bordered cards but UI-SPEC locks elevated cards" | | Animation accessibility | Animations/transitions without prefers-reduced-motion guard | WARN: "Animation at {file}:{line} missing reduced-motion check" | | Touch target size | Interactive elements with explicit small sizing (w-5 h-5, p-0.5 on buttons/links) or primary body regions (not meta/secondary) | WARN: "Body text below 16px at {file}:{line} — reads as AI boilerplate" | | **Scale Minimum — hero display** | with text-3xl or smaller (30px) when the heading is in a hero/landing section | WARN: "Hero heading below 48px at {file}:{line} — insufficient visual hierarchy" | | **Hand-rolled SVG for standard icons** | Inline , , form hints, table captions) is allowed at 14px. The check only fires on primary body regions — paragraphs inside , , card body, marketing hero/features. Use common sense or an explicit data-scale="meta"` attribute to opt out.

Exception for hand-rolled SVG: Project logos, data visualizations (charts/graphs via d3/recharts/visx), and human-designed illustrations are never flagged. The check fires only when class/comment context names a standard icon.

Pack Integration

When a domain pack is installed (e.g., @rune-pro/finance, @rune-pro/legal), preflight checks the pack's Hard-Stop Thresholds table and applies matching rules to staged files. This means:

• Installing @rune-pro/finance automatically adds financial quality gates to preflight
• Installing @rune-pro/legal automatically adds compliance checks to preflight
• No manual configuration needed — pack presence = hooks active

Output Section

### Domain Quality
- **Domains detected**: [Database, Financial]
- `migrations/003-add-billing.sql` — BLOCK: DROP TABLE without rollback script
- `src/billing/invoice.ts:42` — WARN: price calculation uses `toFixed(2)` instead of `Intl.NumberFormat`

Step 4.6 — Organization Approval Requirements (Business)

If .rune/org/org.md exists, load organization approval workflows and enforce them as additional quality gates.

1. Read .rune/org/org.md and extract ## Policies, ## Approval Flows, and ## Governance Level
2. Apply organization-level quality requirements:

| Org Policy | Preflight Check | Severity | |------------|----------------|----------| | minimum_reviewers | Verify PR has required reviewer count before merge | WARN: "Org requires {N} reviewers" | | self-merge_allowed | If "Never" or "No", flag self-merge attempts | BLOCK if org prohibits | | required_checks | Verify all org-required checks (tests, security scan, type check, lint) are passing | BLOCK if missing | | staging_required | If "Yes", verify staging deployment exists before production | WARN if no staging step | | feature_flags | If "Required for user-facing changes", flag new UI without feature flag | WARN | | cross-domain_changes | If changes span multiple team domains, require reviewer from each | WARN |

1. Load ## Approval Flows > ### Feature Launch and display the required approval chain:

• Output: "Org approval chain: {flow}" so developer knows the full pipeline
• If governance level is "Maximum", flag any attempt to skip gates

1. Append org findings under ### Organization Requirements section:

### Organization Requirements
- **Org template**: [startup|mid-size|enterprise]
- **Governance level**: [Minimal|Moderate|Maximum]
- **Minimum reviewers**: 2 (1 must be director+)
- **Required checks**: tests (≥80% coverage), security scan, type check, lint
- **Approval chain**: contributor proposes → lead reviews → vp approves → deploy
- WARN: Self-merge not allowed per org policy

If .rune/org/org.md does not exist, skip and log INFO: "no org config, organization requirements check skipped".

Step 4.8 — Preflight Composite Score

After all domain hooks (Step 4.5) and completeness checks (Step 4) complete, compute a Preflight Health Score to make the verdict numeric and comparable across runs.

Formula

Preflight Score = (Logic × 0.30) + (Error Handling × 0.20) + (Completeness × 0.20) + (Coherence × 0.15) + (Regression Risk × 0.15)

5 verification axes (Completeness + Correctness via Logic + Coherence — 3D verification model):

Each dimension is scored per staged files:

• 0 BLOCK findings in dimension → 100
• 1 BLOCK → dimension capped at 30
• 1 WARN → dimension capped at 75
• Each additional WARN → subtract 10 (floor: 40)

Grade Thresholds

| Score | Grade | Verdict | |-------|-------|---------| | 90–100 | Excellent | PASS | | 75–89 | Good | PASS with notes | | 60–74 | Fair | WARN | | 40

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Rune-kit
• Source: Rune-kit/rune
• License: MIT

Install and usage instructions live in the source repository linked above.