@rune-kit/rune 2.10.0 → 2.12.0

package/skills/preflight/SKILL.md

@@ -1,415 +1,415 @@
----
-name: preflight
-description: Pre-commit quality gate that catches "almost right" code. Goes beyond linting — checks logic correctness, error handling, regressions, and completeness.
-metadata:
-  author: runedev
-  version: "0.8.0"
-  layer: L2
-  model: sonnet
-  group: quality
-  tools: "Read, Bash, Glob, Grep"
-  emit: preflight.passed, preflight.blocked
-  listen: code.changed
----
-
-# preflight
-
-## Purpose
-
-<HARD-GATE>
-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.
-</HARD-GATE>
-
-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:**
-
-```typescript
-// 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);
-}
-```
-
-```typescript
-// 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:**
-
-```typescript
-// 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, <5 files), or CLAUDE.md/conventions.md explicitly says "no conventions yet."
-
-### Step 4.3 — Eval Verification
-
-If `.rune/evals/` directory exists with eval definition files, verify eval results as part of the quality gate.
-
-| Check | Action | Severity |
-|-------|--------|----------|
-| Capability eval defined but not run | Feature has `.rune/evals/<feature>.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.
-
-<HARD-GATE>
-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.
-</HARD-GATE>
-
-#### 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:
-
-| 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) < 44×44px | WARN: "Touch target too small at {file}:{line}" |
-| **Missing states** | Components fetching data without loading/error/empty states | WARN: "Async component at {file} missing [loading|error|empty] state" |
-| **Icon accessibility** | Decorative icons without `aria-hidden="true"`, functional icons without `aria-label` | WARN: "Icon at {file}:{line} missing aria attribute" |
-| **Inline styles** | `style={{` or `style=` attribute usage instead of classes/tokens | WARN: "Inline style at {file}:{line} — use CSS class or Tailwind" |
-| **Font loading** | Custom font imports without `font-display: swap` or Next.js font optimization | WARN: "Font at {file} may cause layout shift — add font-display: swap" |
-| **Placeholder content** | Strings like "Lorem ipsum", "TODO", "placeholder", "test text" in JSX/template | BLOCK: "Placeholder content at {file}:{line} — replace before shipping" |
-
-**Skip if**: Diff contains only test files, config files, or non-UI code (detected by absence of JSX/template syntax).
-
-#### 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 |
-
-3. 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
-
-4. 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–59 | Poor | WARN (escalate to developer) |
-| 0–39 | Critical | BLOCK |
-
-Score is appended to the Preflight Report footer. Useful for tracking quality trend across sprints when cook logs preflight scores to `.rune/metrics/`.
-
-
-### Step 5 — Security Sub-Check
-Invoke `rune:sentinel` on the changed files. Attach sentinel's output verbatim under the "Security" section of the preflight report. If sentinel returns BLOCK, preflight verdict is also BLOCK.
-
-### Step 6 — Generate Verdict
-Aggregate all findings:
-- Any BLOCK from sentinel OR a logic issue that would cause data corruption or security bypass → overall **BLOCK**
-- Any missing error handling, regression risk with no tests, or incomplete feature → **WARN**
-- Only style or best-practice suggestions → **PASS**
-
-Report PASS, WARN, or BLOCK. For WARN, list each item the developer must acknowledge. For BLOCK, list each item that must be fixed before proceeding.
-
-## Output Format
-
-```
-## Preflight Report
-- **Status**: PASS | WARN | BLOCK
-- **Files Checked**: [count]
-- **Changes**: +[added] -[removed] lines across [files] files
-
-### Logic Issues
-- `path/to/file.ts:42` — null-deref: `user.name` accessed without null check
-- `path/to/api.ts:85` — missing-await: async database call not awaited
-
-### Error Handling
-- `path/to/handler.ts:20` — bare-catch: error swallowed silently
-
-### Regression Risk
-- `utils/format.ts` — changed function used by 5 modules, 2 have tests, 3 untested (WARN)
-
-### Completeness
-- `api/users.ts` — new POST endpoint missing input validation schema
-- `components/Form.tsx` — no loading state during submission
-
-### Coherence
-- `api/users.ts` — uses `res.json()` but project convention is `sendResponse()` wrapper
-- `utils/newHelper.ts` — placed in utils/ but project uses helpers/ directory
-
-### Security (from sentinel)
-- [sentinel findings if any]
-
-### Composite Score
-- Logic: [score] | Error: [score] | Completeness: [score] | Coherence: [score] | Regression: [score]
-- **Preflight Score**: [weighted value] → Grade: [Excellent/Good/Fair/Poor/Critical]
-
-### Verdict
-WARN — 3 issues found (0 blocking, 3 must-acknowledge). Resolve before commit or explicitly acknowledge each WARN.
-```
-
-## Constraints
-
-1. MUST check: logic errors, error handling, edge cases, type safety, naming conventions
-2. MUST reference specific file:line for every finding
-3. MUST NOT skip edge case analysis — "happy path works" is insufficient
-4. MUST verify error messages are user-friendly and don't leak internal details
-5. MUST check that async operations have proper error handling and cleanup
-
-## Returns
-
-| Artifact | Format | Location |
-|----------|--------|----------|
-| Preflight report | Markdown | inline (chat output) |
-| Issue list (BLOCK/WARN by category) | Markdown list | inline |
-| Preflight health score | Markdown table | inline (footer of report) |
-| Spec compliance verdict | Markdown table | inline |
-| Domain quality findings | Markdown section | inline |
-
-## Sharp Edges
-
-| Failure Mode | Severity | Mitigation |
-|---|---|---|
-| Stopping at first BLOCK finding without checking remaining files | HIGH | Aggregate all findings first — developer needs the complete list, not just the first blocker |
-| "Happy path works" accepted as sufficient | HIGH | CONSTRAINT blocks this — edge case analysis is mandatory on every function |
-| Calling verification directly instead of the test skill | MEDIUM | Preflight calls rune:test for test suite execution; rune:verification for lint/type/build checks |
-| Skipping sentinel sub-check because "this file doesn't look security-relevant" | HIGH | MUST invoke sentinel — security relevance is sentinel's job to determine, not preflight's |
-| Skipping Stage A (spec compliance) when plan is available | HIGH | If cook provides an approved plan, Stage A is mandatory — catches incomplete implementations |
-| Agent modified files not in plan without flagging | MEDIUM | Stage A flags unplanned file changes as WARN — scope creep detection |
-| Domain hooks not triggered when pack is installed | HIGH | Step 4.5 auto-detects file patterns — if pack is installed but hooks don't fire, check file pattern matching |
-| Domain hooks overriding generic checks | HIGH | HARD-GATE: domain hooks are ADDITIVE — they never replace Steps 1-4 |
-| Pack Hard-Stop Thresholds ignored in preflight | MEDIUM | Step 4.5 Pack Integration must read installed pack thresholds — test with each new pack |
-
-## Done When
-
-- Every changed function traced for null-deref, missing-await, and off-by-one
-- Error handling verified on all async functions and HTTP calls
-- Regression impact assessed — dependent files identified via scout
-- Completeness checklist passed (validation schema, loading/error states, test file)
-- Sentinel invoked and its output attached in Security section
-- Structured report emitted with PASS / WARN / BLOCK verdict and file:line for every finding
-
-## Cost Profile
-
-~2000-4000 tokens input, ~500-1500 tokens output. Sonnet for logic analysis quality.
+---
+name: preflight
+description: Pre-commit quality gate that catches "almost right" code. Goes beyond linting — checks logic correctness, error handling, regressions, and completeness.
+metadata:
+  author: runedev
+  version: "1.0.0"
+  layer: L2
+  model: sonnet
+  group: quality
+  tools: "Read, Bash, Glob, Grep"
+  emit: preflight.passed, preflight.blocked
+  listen: code.changed
+---
+
+# preflight
+
+## Purpose
+
+<HARD-GATE>
+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.
+</HARD-GATE>
+
+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:**
+
+```typescript
+// 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);
+}
+```
+
+```typescript
+// 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:**
+
+```typescript
+// 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, <5 files), or CLAUDE.md/conventions.md explicitly says "no conventions yet."
+
+### Step 4.3 — Eval Verification
+
+If `.rune/evals/` directory exists with eval definition files, verify eval results as part of the quality gate.
+
+| Check | Action | Severity |
+|-------|--------|----------|
+| Capability eval defined but not run | Feature has `.rune/evals/<feature>.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.
+
+<HARD-GATE>
+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.
+</HARD-GATE>
+
+#### 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:
+
+| 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) < 44×44px | WARN: "Touch target too small at {file}:{line}" |
+| **Missing states** | Components fetching data without loading/error/empty states | WARN: "Async component at {file} missing [loading|error|empty] state" |
+| **Icon accessibility** | Decorative icons without `aria-hidden="true"`, functional icons without `aria-label` | WARN: "Icon at {file}:{line} missing aria attribute" |
+| **Inline styles** | `style={{` or `style=` attribute usage instead of classes/tokens | WARN: "Inline style at {file}:{line} — use CSS class or Tailwind" |
+| **Font loading** | Custom font imports without `font-display: swap` or Next.js font optimization | WARN: "Font at {file} may cause layout shift — add font-display: swap" |
+| **Placeholder content** | Strings like "Lorem ipsum", "TODO", "placeholder", "test text" in JSX/template | BLOCK: "Placeholder content at {file}:{line} — replace before shipping" |
+
+**Skip if**: Diff contains only test files, config files, or non-UI code (detected by absence of JSX/template syntax).
+
+#### 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 |
+
+3. 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
+
+4. 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–59 | Poor | WARN (escalate to developer) |
+| 0–39 | Critical | BLOCK |
+
+Score is appended to the Preflight Report footer. Useful for tracking quality trend across sprints when cook logs preflight scores to `.rune/metrics/`.
+
+
+### Step 5 — Security Sub-Check
+Invoke `rune:sentinel` on the changed files. Attach sentinel's output verbatim under the "Security" section of the preflight report. If sentinel returns BLOCK, preflight verdict is also BLOCK.
+
+### Step 6 — Generate Verdict
+Aggregate all findings:
+- Any BLOCK from sentinel OR a logic issue that would cause data corruption or security bypass → overall **BLOCK**
+- Any missing error handling, regression risk with no tests, or incomplete feature → **WARN**
+- Only style or best-practice suggestions → **PASS**
+
+Report PASS, WARN, or BLOCK. For WARN, list each item the developer must acknowledge. For BLOCK, list each item that must be fixed before proceeding.
+
+## Output Format
+
+```
+## Preflight Report
+- **Status**: PASS | WARN | BLOCK
+- **Files Checked**: [count]
+- **Changes**: +[added] -[removed] lines across [files] files
+
+### Logic Issues
+- `path/to/file.ts:42` — null-deref: `user.name` accessed without null check
+- `path/to/api.ts:85` — missing-await: async database call not awaited
+
+### Error Handling
+- `path/to/handler.ts:20` — bare-catch: error swallowed silently
+
+### Regression Risk
+- `utils/format.ts` — changed function used by 5 modules, 2 have tests, 3 untested (WARN)
+
+### Completeness
+- `api/users.ts` — new POST endpoint missing input validation schema
+- `components/Form.tsx` — no loading state during submission
+
+### Coherence
+- `api/users.ts` — uses `res.json()` but project convention is `sendResponse()` wrapper
+- `utils/newHelper.ts` — placed in utils/ but project uses helpers/ directory
+
+### Security (from sentinel)
+- [sentinel findings if any]
+
+### Composite Score
+- Logic: [score] | Error: [score] | Completeness: [score] | Coherence: [score] | Regression: [score]
+- **Preflight Score**: [weighted value] → Grade: [Excellent/Good/Fair/Poor/Critical]
+
+### Verdict
+WARN — 3 issues found (0 blocking, 3 must-acknowledge). Resolve before commit or explicitly acknowledge each WARN.
+```
+
+## Constraints
+
+1. MUST check: logic errors, error handling, edge cases, type safety, naming conventions
+2. MUST reference specific file:line for every finding
+3. MUST NOT skip edge case analysis — "happy path works" is insufficient
+4. MUST verify error messages are user-friendly and don't leak internal details
+5. MUST check that async operations have proper error handling and cleanup
+
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| Preflight report | Markdown | inline (chat output) |
+| Issue list (BLOCK/WARN by category) | Markdown list | inline |
+| Preflight health score | Markdown table | inline (footer of report) |
+| Spec compliance verdict | Markdown table | inline |
+| Domain quality findings | Markdown section | inline |
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Stopping at first BLOCK finding without checking remaining files | HIGH | Aggregate all findings first — developer needs the complete list, not just the first blocker |
+| "Happy path works" accepted as sufficient | HIGH | CONSTRAINT blocks this — edge case analysis is mandatory on every function |
+| Calling verification directly instead of the test skill | MEDIUM | Preflight calls rune:test for test suite execution; rune:verification for lint/type/build checks |
+| Skipping sentinel sub-check because "this file doesn't look security-relevant" | HIGH | MUST invoke sentinel — security relevance is sentinel's job to determine, not preflight's |
+| Skipping Stage A (spec compliance) when plan is available | HIGH | If cook provides an approved plan, Stage A is mandatory — catches incomplete implementations |
+| Agent modified files not in plan without flagging | MEDIUM | Stage A flags unplanned file changes as WARN — scope creep detection |
+| Domain hooks not triggered when pack is installed | HIGH | Step 4.5 auto-detects file patterns — if pack is installed but hooks don't fire, check file pattern matching |
+| Domain hooks overriding generic checks | HIGH | HARD-GATE: domain hooks are ADDITIVE — they never replace Steps 1-4 |
+| Pack Hard-Stop Thresholds ignored in preflight | MEDIUM | Step 4.5 Pack Integration must read installed pack thresholds — test with each new pack |
+
+## Done When
+
+- Every changed function traced for null-deref, missing-await, and off-by-one
+- Error handling verified on all async functions and HTTP calls
+- Regression impact assessed — dependent files identified via scout
+- Completeness checklist passed (validation schema, loading/error states, test file)
+- Sentinel invoked and its output attached in Security section
+- Structured report emitted with PASS / WARN / BLOCK verdict and file:line for every finding
+
+## Cost Profile
+
+~2000-4000 tokens input, ~500-1500 tokens output. Sonnet for logic analysis quality.