@tyroneross/build-loop 0.30.3

package/skills/build-loop/scanners/require-visual-evidence.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+// SPDX-License-Identifier: Apache-2.0
+//
+// require-visual-evidence.mjs — BL-1 gate
+//
+// Rejects UI-touching chunks whose only verification evidence is symbol/string
+// presence (nm / strings / grep over compiled binaries / `git grep` over source).
+//
+// Trigger surfaces (called by build-orchestrator):
+//   - Phase 3 chunk-close (commit step) when `uiTouched: true`
+//   - Phase 4 sub-step B (Validate) when `uiTarget != null` and any changed
+//     file matches the UI-file globs below
+//
+// Input (--envelope-file <path>): a JSON file with the implementer/chunk
+// return envelope, at minimum:
+//   {
+//     "uiTarget": "macos" | "mobile" | "web" | null,
+//     "files_changed": ["...", "..."],
+//     "verification": "<freeform string describing how the implementer verified>",
+//     "evidence_paths": ["screenshots/foo.png", ...]   // optional
+//   }
+// Extra fields are ignored. Missing fields are treated conservatively
+// (no claim => no evidence).
+//
+// Exit codes:
+//   0  pass            — non-UI diff OR genuine visual/AX evidence present
+//   1  warn            — UI diff + ambiguous evidence; agent should clarify
+//   2  reject          — UI diff + ONLY symbol/string evidence; BLOCK chunk-close
+//   3  malformed       — envelope unreadable / invalid JSON
+//
+// Always writes a JSON object to stdout:
+//   { verdict, reason, ui_changed, ui_files, symbol_only, accepted_evidence }
+//
+// Stdlib-only. No dependencies. Mirrors the shape of audit-design-rules.mjs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// --- UI file detection ------------------------------------------------------
+
+const UI_FILE_PATTERNS = [
+  /(^|\/)Views\//,            // Apple-platform convention
+  /\.swift$/,                 // any Swift source (heuristic — paired w/ uiTarget)
+  /\.tsx$/,
+  /\.jsx$/,
+  /\.vue$/,
+  /\.svelte$/,
+  /(^|\/)components?\/.+\.(ts|js)$/,
+  /(^|\/)pages?\/.+\.(ts|js)$/,
+  /(^|\/)app\/.+\.(ts|js)$/,
+];
+
+function isUiFile(p) {
+  return UI_FILE_PATTERNS.some((rx) => rx.test(p));
+}
+
+// --- Evidence classification ------------------------------------------------
+
+// Accepted visual/AX evidence — any one of these in the verification text
+// or as an evidence path is enough to clear the gate.
+const ACCEPTED_EVIDENCE_TOKENS = [
+  // Screenshot / image artifacts
+  /screenshot/i,
+  /\.png\b/i,
+  /\.jpe?g\b/i,
+  // AX tree dumps
+  /\bax[-_ ]?tree\b/i,
+  /accessibility[-_ ]?tree/i,
+  // macOS / iOS native verification
+  /native[-_ ]?ax[-_ ]?driver/i,
+  /\bxcrun simctl io booted screenshot\b/i,
+  /\bidb ui\b/i,
+  // IBR + scan
+  /\bscan_macos\b/i,
+  /\bibr\b[^a-z]*scan/i,
+  /ssim/i,
+  // Web rendering
+  /\bplaywright\b/i,
+  /\bpuppeteer\b/i,
+  /\bui[-_ ]?validator\b/i,
+  /dev[-_ ]?server.*(?:screenshot|render)/i,
+  // PID-anchored verification (the running app was actually looked at)
+  /\bpid[:= ]\s*\d+/i,
+];
+
+// Symbol-only evidence — `nm`, `strings`, `grep` over compiled output, or
+// a "the identifier exists therefore the UI is correct" claim. These DO NOT
+// satisfy the gate on their own.
+const SYMBOL_ONLY_TOKENS = [
+  /\bnm\s+[^\n]*\.(?:app|dylib|framework|so|exe|dll|o|a|bundle)/i,
+  /\bstrings\s+/i,
+  /\botool\s+-[lL]\b/i,
+  /\bgit grep\b/i,
+  /\bgrep\b.*(?:Sources|Views|src)\//i,
+  /\bsymbol(?:s)?\s+(?:present|exist|found)/i,
+  /\bidentifier(?:s)?\s+(?:present|exist|found)/i,
+  /\bcompiles?\s+(?:cleanly|successfully)/i,   // build-only claim
+];
+
+function classifyEvidence(verificationText, evidencePaths) {
+  const acceptedHits = [];
+  const symbolHits = [];
+
+  const haystacks = [verificationText, ...(evidencePaths || [])];
+  for (const text of haystacks) {
+    if (typeof text !== 'string') continue;
+    for (const rx of ACCEPTED_EVIDENCE_TOKENS) {
+      if (rx.test(text)) acceptedHits.push(rx.source);
+    }
+    for (const rx of SYMBOL_ONLY_TOKENS) {
+      if (rx.test(text)) symbolHits.push(rx.source);
+    }
+  }
+  return {
+    accepted_evidence: [...new Set(acceptedHits)],
+    symbol_signals: [...new Set(symbolHits)],
+  };
+}
+
+// --- Main -------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { envelopeFile: null, root: '.' };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--envelope-file') args.envelopeFile = argv[++i];
+    else if (a === '--root') args.root = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      // Embedded usage so stdlib-only -- no separate help file
+      process.stdout.write(
+        'Usage: require-visual-evidence.mjs --envelope-file <path> [--root <project-root>]\n'
+      );
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+function emit(verdict, reason, extras) {
+  const out = { verdict, reason, ...extras };
+  process.stdout.write(JSON.stringify(out) + '\n');
+  if (verdict === 'pass') process.exit(0);
+  if (verdict === 'warn') process.exit(1);
+  if (verdict === 'reject') process.exit(2);
+  process.exit(3);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.envelopeFile) {
+    emit('malformed', '--envelope-file is required', {});
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(args.envelopeFile, 'utf8');
+  } catch (err) {
+    emit('malformed', `cannot read envelope: ${err.message}`, {});
+  }
+
+  let env;
+  try {
+    env = JSON.parse(raw);
+  } catch (err) {
+    emit('malformed', `invalid JSON: ${err.message}`, {});
+  }
+
+  const uiTarget = env.uiTarget ?? null;
+  const filesChanged = Array.isArray(env.files_changed) ? env.files_changed : [];
+  const verification = typeof env.verification === 'string' ? env.verification : '';
+  const evidencePaths = Array.isArray(env.evidence_paths) ? env.evidence_paths : [];
+
+  // Skip when no UI target is configured for this build.
+  if (uiTarget === null || uiTarget === undefined) {
+    emit('pass', 'uiTarget is null; gate does not apply', {
+      ui_changed: false,
+      ui_files: [],
+      symbol_only: false,
+      accepted_evidence: [],
+    });
+  }
+
+  // Skip when this chunk didn't touch any UI file.
+  const uiFiles = filesChanged.filter(isUiFile);
+  if (uiFiles.length === 0) {
+    emit('pass', 'no UI files changed in this chunk', {
+      ui_changed: false,
+      ui_files: [],
+      symbol_only: false,
+      accepted_evidence: [],
+    });
+  }
+
+  // UI was touched — evidence is required.
+  const { accepted_evidence, symbol_signals } = classifyEvidence(verification, evidencePaths);
+
+  if (accepted_evidence.length > 0) {
+    emit('pass', 'visual/AX evidence present', {
+      ui_changed: true,
+      ui_files: uiFiles,
+      symbol_only: false,
+      accepted_evidence,
+    });
+  }
+
+  if (symbol_signals.length > 0) {
+    emit(
+      'reject',
+      'symbol/string-only evidence is NOT a substitute for visual/AX verification. ' +
+        'Required: render the running app (pid-anchored) and capture a screenshot, AX-tree dump, ' +
+        'or scan result. See skills/build-loop/phases/ui-validation.md §"Visual validation".',
+      {
+        ui_changed: true,
+        ui_files: uiFiles,
+        symbol_only: true,
+        accepted_evidence: [],
+        symbol_signals,
+      }
+    );
+  }
+
+  // No accepted evidence AND no symbol-only signal — verification text is
+  // ambiguous (empty, unrelated, or in an unknown shape). Surface a warning
+  // and let the orchestrator decide whether to re-prompt the implementer.
+  emit(
+    'warn',
+    'no recognized visual/AX evidence in the envelope and no symbol-only signal either; ' +
+      're-prompt the implementer to attach a screenshot, AX-tree dump, or scan result.',
+    {
+      ui_changed: true,
+      ui_files: uiFiles,
+      symbol_only: false,
+      accepted_evidence: [],
+    }
+  );
+}
+
+main();

package/skills/build-loop/templates/backlog-item.md

@@ -0,0 +1,35 @@
+---
+title: {title}
+created: {created}
+source: {source}
+classify: {classify}
+effort: {effort}
+status: {status}
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# {title}
+
+## Problem
+
+{problem}
+
+## Proposed approach
+
+{proposed_approach}
+
+## Why deferred
+
+{why_deferred}
+
+---
+
+**Field reference:**
+
+- `classify`: SAFE (no side-effects) | RISKY (touches infra/schema/auth) | DECISION (needs user confirmation) | PRODUCTION (live-traffic impact)
+- `effort`: XS (<1h) | S (1–4h) | M (half-day) | L (1–2 days) | XL (>2 days). No dollar costs — t-shirt sizing only.
+- `status`: open | in-progress | done
+- `source`: free-form — who/what surfaced this item (e.g. "user steering 2026-05-30", "Phase 6 Learn run-abc", "self-review")
+
+Backlog items are **longer-lived** than `issues/` (current-run bugs). They survive across runs and are only drained when status becomes `done` or the item is explicitly removed.

package/skills/build-loop/templates/codex-worker-prompt.md

@@ -0,0 +1,89 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Codex Worker Prompt Template
+
+You are a Codex worker inside a Build Loop run. You are not alone in the codebase. Do not revert edits made by others; adapt around them and report conflicts.
+
+## Task
+
+<one concrete outcome>
+
+## Ownership
+
+Owns:
+- <exact files/directories this worker may edit>
+
+Does not own:
+- <files/directories/responsibilities this worker must not edit>
+
+## Context
+
+- Goal: <goal from .build-loop/goal.md>
+- Intent: <north star/update intent relevant to this task>
+- Current state: <short facts from assessment>
+- Dependencies: <upstream tasks or known constraints>
+
+## Interface Contract
+
+- <function/route/schema/component/CLI/doc contract to preserve or expose>
+
+## Implementation Rules
+
+- Keep the change scoped to owned files.
+- Prefer the repo's existing patterns over new abstractions.
+- Do not add dependencies unless the lead explicitly assigned that.
+- Surface pre-existing issues separately from task changes.
+- If ownership is unclear, stop and report the conflict instead of broadening scope.
+
+## Validation
+
+Run if feasible:
+
+```bash
+<validation command>
+```
+
+If validation is not feasible, explain why and what the lead should run.
+
+## Return Format
+
+Changed files:
+- <path>: <what changed>
+
+Validation:
+- <command or "not run">: <result or reason>
+
+Integration notes:
+- <contract, migration, or ordering notes>
+
+Unresolved risks:
+- <risk or "none known">
+
+## decision_ledger (REQUIRED when plan has synthesis_dimensions)
+
+When the originating plan includes a `synthesis_dimensions:` block, your return envelope MUST include a `decision_ledger` array with one entry per dimension. Each entry documents *why* the chosen value was selected — not just *what* was applied. Empty array `[]` is only valid when the plan has no `synthesis_dimensions` block.
+
+Example (two entries for placement and cta_tier dimensions):
+
+```json
+"decision_ledger": [
+  {
+    "dimension": "placement_MyComponent",
+    "owner": "plan",
+    "locked_value": "after `<ParentRow>` in path/to/Component.tsx",
+    "alternatives_rejected": ["before `<ParentRow>` — plan specified after"],
+    "evidence_file": "path/to/Component.tsx",
+    "on_new_decision": "flag"
+  },
+  {
+    "dimension": "cta_tier_save_button",
+    "owner": "plan",
+    "locked_value": "primary",
+    "alternatives_rejected": ["secondary — insufficient weight for primary conversion action"],
+    "evidence_file": "path/to/Component.tsx",
+    "on_new_decision": "flag"
+  }
+]
+```
+
+Full schema: `references/implementer-envelope-schema.md` §"decision_ledger in detail".

package/skills/build-loop/templates/ui-subagent-prompt.md

@@ -0,0 +1,179 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UI Subagent Prompt — Design Rule Preamble
+
+> Prepended verbatim to every build-loop subagent prompt that touches UI files. Do NOT replace with a link — agents miss links.
+
+---
+
+## Required reading BEFORE you touch any UI file
+
+Load these skills and follow them. Not optional.
+
+- **All UI work**: `calm-precision`
+- **All non-trivial UI work**: read `.build-loop/app-contract/ui.md` when present. The `## Design Direction` and `## Design Hierarchy Registry` sections are the binding build-loop-owned style source. If it names a `selected_structure` from `recent-design-structures.md`, implement that structure through the app contract; do not re-pick a different one.
+- **SwiftUI / Apple platforms**: use `apple-dev` only when the task needs Apple implementation or deployment details.
+- **React / Vue / web**: use `frontend-design` only when the user or orchestrator explicitly requests that external guidance.
+
+If a skill is unavailable, proceed but note it in your output.
+
+Calm Precision is the structural baseline and a required design consideration gate: hierarchy, grouping, action weight, disclosure, motion, accessibility, copy clarity, functional integrity, and their perceptual-science foundations. The app contract decides the selected structure and surface treatment on top of that baseline.
+
+Before editing UI, identify which Calm Precision principles are relevant to this change and how they constrain the implementation. Do not treat Calm Precision as background reference or taste language. If `.build-loop/app-contract/ui.md` contains `## Calm Precision Core Considerations`, apply that section as binding guidance. If the section is missing for non-trivial UI work, still run the consideration pass locally and report it in your return envelope as `CALM PRECISION CHECK: <principles> -> <implementation effect>`.
+
+## UI input/output contract
+
+Before editing, read the task's `## UI Input/Output Contract` section. If it is missing and the task is not copy-only, return `status: blocked` and name the missing contract.
+
+For every changed screen/component, apply the contract exactly:
+
+1. Every user input has a named structural type, content format, persistence intent, validation rule, and input control.
+2. Every system output has a named source, content format, renderer, loading/error/empty state, and overflow/copy/fallback behavior.
+3. Domain actions are named as verbs (submit, approve, publish, reorder, export), not hidden inside generic update language.
+4. Voice, file, image, chart, map, AI-generated, and streaming surfaces include a modality-specific fallback.
+5. Rich text, Markdown, HTML, JSON, and AI output include sanitization/rendering rules.
+6. Create/update/delete/domain actions include auth/authz behavior for denied users: hidden, disabled, or 403/empty view.
+
+If you need to deviate from the contract, report `CONTRACT DEVIATION: <surface> — <reason> — <replacement>`.
+
+## Mockup-vs-rule conflict policy
+
+Mockups are **intent**. Design rules are **law**. When they conflict, the rule wins. No exceptions, no judgment calls — replicate the rule, not the pixel.
+
+Required behavior on conflict:
+1. Implement per the rule.
+2. Add a line to your output: `RULE BEATS MOCKUP: <rule-id> overrides <mockup-element>. Reason: <one sentence>.`
+
+Skipping this line means the orchestrator can't audit your decisions. Don't skip.
+
+## Anti-pattern checklist (zero tolerance)
+
+Every UI file you write or modify must pass this checklist before you return.
+
+1. **No status pills.** Status indicators use text color only. Never `.background(opacity).clipShape(Capsule())` (SwiftUI) or `bg-X-500 rounded-full` (Tailwind) near a chip / badge / status / trend / score identifier. Color and weight create hierarchy, not boxes.
+
+2. **Reduce Motion gates every animation.** No `.repeatForever`, `withAnimation`, `.easeInOut(duration:)`, `animate-pulse`, `animate-spin` without the platform-correct guard.
+   - SwiftUI: `@Environment(\.accessibilityReduceMotion) private var reduceMotion`, then `if !reduceMotion { withAnimation(...) }`
+   - Web: pair every animation utility with its `motion-reduce:` variant or media-query equivalent
+
+3. **Theme tokens, not literals.**
+   - SwiftUI: no raw `UIColor(red:green:blue:)` outside `Theme/`. No literal `.cornerRadius(N)` — use `Theme.cornerSmall/Medium/Large/XL`.
+   - Web: no `#hex` outside theme/tokens files. No `text-[Npx]` arbitrary sizes.
+
+4. **Dynamic Type / responsive type.** Body copy uses theme tokens (`Theme.fontBody`, `Theme.fontCaption`), not `.font(.system(size: N))`. Numeric chips and tabular layouts may use fixed sizes.
+
+5. **Every icon has a label.** Icon-only `Image(systemName: "...")` (SwiftUI) or `<Icon />` (web) gets an explicit `accessibilityLabel` / `aria-label`, OR is wrapped in a `Button` whose label covers it.
+
+6. **Touch targets.** Mobile: 44pt minimum. Primary thumb-zone actions (record, submit during capture): 88pt minimum.
+
+7. **VoiceOver matches visible text.** Don't strip signs (`abs()`) for one but not the other. Keep numeric conventions consistent across visible label and accessibility label.
+
+8. **No fake buttons.** Every interactive element has a working backend handler. No placeholder onTap, no "Coming soon" without the affordance being hidden or marked.
+
+9. **Floating tab bar / system overlays don't clip your content.** iOS 26's floating tab bar overlays the bottom ~92pt of the window. Android navigation gesture inset is similar. Web bottom-fixed nav same idea. **Every scrollable surface needs an explicit bottom inset** so the last row clears the bar at scroll-end:
+   - SwiftUI ScrollView: append `Color.clear.frame(height: 100)` as the last child of the inner VStack, OR use `.contentMargins(.bottom, 100, for: .scrollContent)`
+   - SwiftUI List: `.safeAreaInset(edge: .bottom) { Color.clear.frame(height: 100) }`
+   - Web: equivalent `pb-24` / `padding-block-end: 6rem` on the scrollable container
+   `safeAreaPadding` alone is not sufficient — it pushes the ScrollView frame, not the scrollable content area. This shipped broken in a real build (build 53) because the rule wasn't on the checklist.
+
+10. **Numeric/text fields constrain width.** Long dim names ("Engagement", "Conciseness") wrap or squeeze adjacent columns when no width policy is set. For row layouts where label + score columns coexist:
+    - Labels: `.lineLimit(1).minimumScaleFactor(0.75)` — shrink, don't wrap
+    - Right-side numeric column: `.fixedSize(horizontal: true, vertical: false)` — never sacrifice the timestamp/score for label width
+
+11. **Custom-drawn arcs / charts: render the half you mean.** SwiftUI's `Path.addArc` `clockwise:` flag is counter-intuitive in the user-space (y-flipped) coordinate system. `clockwise: false` from 180° to 360° draws the TOP half. `clockwise: true` draws the BOTTOM half. Use `Circle().trim(from:to:).rotationEffect(_:)` for predictable results. Track strokes against dark backgrounds need at least `Theme.textMuted.opacity(0.25)` contrast — not `surfacePrimary` (which is too close to background luminance). This shipped a literal upside-down semicircle (build 53/55) before being caught visually.
+
+## Required SwiftUI environment hooks
+
+When your file contains any animation:
+
+```swift
+@Environment(\.accessibilityReduceMotion) private var reduceMotion
+
+// Then everywhere you animate:
+if !reduceMotion {
+    withAnimation(...) { ... }
+}
+```
+
+## Verification before you return
+
+Mandatory pre-return steps:
+
+1. **Build.** Platform default — SwiftUI: `xcodegen generate && xcodebuild build`. Web: `pnpm build` or project equivalent.
+
+2. **UI input/output contract check.** Verify the changed files still satisfy the task's contract. Confirm all inputs, outputs, states, modality fallbacks, validation/security rules, and traceability entries are implemented or explicitly marked not applicable.
+
+3. **Design-rule scan.** If `${CLAUDE_PLUGIN_ROOT}/skills/build-loop/scanners/audit-design-rules.mjs` exists, run:
+   ```
+   node "${CLAUDE_PLUGIN_ROOT}/skills/build-loop/scanners/audit-design-rules.mjs" --root=<project> --platform=<swiftui|react|web>
+   ```
+   **Zero must-fix findings.** Must-fix blocks return.
+
+   **No "out of scope" framing for warnings.** Drift from a rule in any user-facing file is drift, regardless of whether this commit "owns" that file. If your task changes one screen and the scanner shows warnings on adjacent screens, fix the warnings too — the user lives in the app, they don't see commit boundaries. The only acceptable warning is one you explicitly justify in your output (e.g. "fixed font size on numeric chip — Dynamic Type would break tabular alignment"). "Pre-existing" is not a reason; it's a backlog.
+
+4. **Visual validation (REQUIRED for UI work; enforced gate, not prose).** The scanner catches static anti-patterns. It cannot catch rendering bugs — an upside-down arc, an invisible track, a clipped row, a chip that wraps. **If you touched a Views/ file, you must render the actual screen and look at it.** The orchestrator runs `scanners/require-visual-evidence.mjs` (BL-1 gate) at chunk-close and at Phase 4-B Validate: symbol/string-only evidence (`nm`, `strings`, `git grep`, "identifier present", "compiles cleanly") is automatically rejected with exit 2 and the chunk is routed back to Iterate. Required artifacts are a screenshot path anchored to the running app's pid, an AX-tree dump, or a scan/SSIM/ui-validator result.
+
+   - **macOS (`uiTarget: "macos"`)**: macOS has no simulator. Prefer the built-in `native-ax-driver` against the running `.app` (pid-anchored AX-tree dump + element actions) OR — if the IBR plugin is installed in this project — IBR `scan_macos`. Capture a screenshot via `screencapture -l <window-id>` or the AX driver's screenshot helper; do NOT use `xcrun simctl` (it does not target macOS). If neither verifier is reachable, return `status: blocked` naming the unreachable tool — do NOT fall back to `nm`/`strings`.
+   - **iOS / watchOS (`uiTarget: "mobile"`)**: install on simulator, launch, capture via `xcrun simctl io booted screenshot` or `idb ui` for interaction. If your change is in a returning-user code path, seed test data first (see "DebugSeeder pattern" below).
+   - **Web (`uiTarget: "web"`)**: open the changed route with the host's available browser/screenshot tooling against the dev server URL — `ui-validator` is the primary surface; Playwright/Puppeteer/showcase capture are acceptable alternatives.
+
+   Compare against the mockup if one exists. Look for: arc/chart geometry rendering correctly, score values positioned where the mockup shows them, no rows clipped behind floating bars / tab bars / safe areas, no text wrapping unexpectedly, no overlapping elements. Real shipped bugs (build 53–55: gauge upside-down with stray ticks; multiple tabs clipping last row behind iOS 26 floating bar) were only caught by visual inspection.
+
+   If browser/simulator tooling is unavailable, document this in your output as a known gap rather than skipping the step silently.
+
+5. If the scanner doesn't exist (older build-loop install), you still must self-audit against the checklist above before returning.
+
+## DebugSeeder pattern (testability for returning-user views)
+
+Many UI states are only reachable after the user has done something — completed N drills, set a name, joined a streak. Manually doing 7 drills before you can verify a Home returning-user view is not a sustainable verification path. **Add a debug-only seeder so any subagent (or a human reviewer) can verify these states in seconds.**
+
+Pattern (SwiftUI/SwiftData example):
+
+```swift
+// ExampleApp/Services/DebugSeeder.swift
+#if DEBUG
+import Foundation
+import SwiftData
+
+enum DebugSeeder {
+    static func seedIfEmpty(context: ModelContext) {
+        let existing = (try? context.fetch(FetchDescriptor<Session>())) ?? []
+        guard existing.isEmpty else { return }
+        // ... insert representative test data spanning a meaningful range
+        try? context.save()
+    }
+}
+#endif
+```
+
+```swift
+// ExampleApp.swift init()
+#if DEBUG
+if CommandLine.arguments.contains("-SeedDebugSessions") {
+    DebugSeeder.seedIfEmpty(context: container.mainContext)
+}
+#endif
+```
+
+Then launch:
+```
+xcrun simctl launch booted <bundle-id> -SeedDebugSessions YES
+```
+
+For multi-tab apps, also add a `-SelectedTab N` launch arg so any tab can be opened directly without taps. Both are gated by `#if DEBUG` and compile out of release builds — zero production cost.
+
+**Use the seeder.** Subagents that report "I trust the math, ship it" without rendering the actual screen will miss visual bugs. Build 55 shipped a broken gauge because no one rendered it. Build 56 caught it because the seeder existed. The seeder pays for itself the first time it catches a bug.
+
+## Output requirements
+
+Your output to the orchestrator must include:
+
+- Files created / modified
+- Build result (✅ / ❌)
+- UI input/output contract result: covered surfaces, deviations, and any N/A entries
+- Scanner result on changed files: must-fix count (must be 0), warn count
+- Every `RULE BEATS MOCKUP:` decision (one line each)
+- Every `CONTRACT DEVIATION:` decision (one line each)
+- Any anti-pattern you intentionally left in place + why (must be explicitly justified, not silently shipped)
+
+Returning without these sections forces the orchestrator to re-prompt you. Don't skip.

package/skills/build-loop/templates/ux-fix-plan.md

@@ -0,0 +1,40 @@
+---
+id: {id}
+dimension: {dimension}
+severity: {severity}
+label: {label}
+architecture_impact: {architecture_impact}
+files_touched:
+{files_touched_yaml}
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UX Fix Plan: {label}
+
+**Hint**: {hint}
+
+## Evidence
+
+{evidence}
+
+## Proposed fix
+
+{proposed_fix}
+
+## Rollback
+
+```bash
+{rollback}
+```
+
+## Notes
+
+- `architecture_impact: true` means this fix introduces a new component, data
+  flow, navigation graph, schema migration, or auth provider change. The
+  orchestrator must surface it in Review-F for explicit user confirmation
+  before Iterate dequeues it.
+- `architecture_impact: false` entries are auto-fixable in the next Iterate
+  cycle, parallelized when independent (`files_touched` disjoint).
+- `severity: minor` entries never reach this template — they live in the
+  Review-F report only.