buildanything 1.8.0 → 2.1.1

package/protocols/design-md-spec.md

@@ -0,0 +1,362 @@
+<!--
+Vendored from https://github.com/google-labs-code/design.md/blob/main/docs/spec.md
+Pinned commit: 8ecd4645b957e6a683a05fb9c79cd6c9028873d0
+Upstream license: Apache License 2.0 (see NOTICE for attribution)
+Do not edit this file by hand. Re-vendor by re-running the curl command from CLAUDE.md.
+-->
+
+<!-- Generated from spec.mdx + spec-config.ts | version: alpha -->
+<!-- Do not edit directly. Run `bun run spec:gen` to regenerate. -->
+
+# DESIGN.md Format
+
+DESIGN.md is a self-contained, plain-text representation of a design system. It defines the visual identity of a brand and product, thereby ensuring that these stylistic choices can be followed across design sessions and between different AI agents and tools.  As a human-readable, open-format document, it serves as a living source of truth that both humans and AI can understand and refine.
+
+A DESIGN.md file contains two parts: An optional YAML frontmatter, and a markdown body. The YAML front matter contains machine-readable design tokens. The markdown body sections provide human-readable design rationale and guidance. Prose may use descriptive color names (e.g., "Midnight Forest Green") that correspond to systematic token names (e.g., `primary`). The tokens are the normative values; the prose provides context for how to apply them.
+
+# Design Tokens
+
+DESIGN.md may embed design tokens in a structured format. The system that we use to describe design tokens is inspired by the
+[Design Token JSON spec](https://www.designtokens.org/tr/2025.10/format/#abstract). Specifically, we adopt the concept of typed token groups (colors, typography, spacing) and the `{path.to.token}` reference syntax for cross-referencing values.
+
+These tokens are easily converted from or to `tokens.json`, Figma variables, and Tailwind theme configs.
+
+Design tokens are embedded as YAML front matter at the beginning of the file. The front matter block must begin with a line containing exactly `---` and end with a line containing exactly `---`. The YAML content between these delimiters is parsed according to the schema defined below.
+
+Example:
+
+```yaml
+---
+version: alpha
+name: Daylight Prestige
+colors:
+  primary: "#1A1C1E"
+  secondary: "#6C7278"
+  tertiary: "#B8422E"
+typography:
+  h1:
+    fontFamily: Public Sans
+    fontSize: 48px
+    fontWeight: 600
+    lineHeight: 1.1
+    letterSpacing: -0.02em
+---
+```
+
+## Schema
+
+Below is the schema for the design tokens defined in the front matter:
+
+```yaml
+version: <string>          # optional, current version: "alpha"
+name: <string>
+description: <string>      # optional
+colors:
+  <token-name>: <Color>
+typography:
+  <token-name>: <Typography>
+rounded:
+  <scale-level>: <Dimension>
+spacing:
+  <scale-level>: <Dimension | number>
+components:
+  <component-name>:
+    <token-name>: <string|token reference>
+```
+
+The `<scale-level>` placeholder represents a named level in a sizing or spacing scale. Common level names include `xs`, `sm`, `md`, `lg`, `xl`, and `full`. Any descriptive string key is valid.
+
+**Color**: A color value must start with "#" followed by a hex color code in the SRGB color space.
+
+- `fontFamily` (string)
+- `fontSize` (Dimension)
+- `fontWeight` (number) - A numeric font weight value (e.g., `400`, `700`). In YAML, this may be expressed as either a bare number or a quoted string; both are equivalent.
+- `lineHeight` (Dimension | number) - Accepts either a Dimension (e.g., `24px`, `1.5rem`) or a unitless number (e.g., `1.6`). A unitless number represents a multiplier of the element's `fontSize`, which is the recommended CSS practice.
+- `letterSpacing` (Dimension)
+- `fontFeature` (string) - configures
+  [`font-feature-settings`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-feature-settings).
+- `fontVariation` (string) - configures
+  [`font-variation-settings`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-variation-settings).
+
+**Dimension**: A dimension value is a string with a unit suffix. Valid units are: px, em, rem.
+
+**Token References**: A token reference must be wrapped in curly braces, and contain an object path to another value in the YAML tree. For most token groups, the reference must point to a primitive value (e.g., `colors.primary-60`), not a group (e.g., `colors`). Within the `components` section, references to composite values (e.g., `{typography.label-md}`) are permitted.
+
+# Sections
+
+Every `DESIGN.md` follows the same structure. Sections can be omitted if they're not relevant to your project, but those present should appear in the sequence listed below. All sections use `<h2>` (`##`) headings. An optional `<h1>` heading may appear for document titling purposes but is not parsed as a section.
+
+### Section Order
+
+1. **Overview** (also: "Brand & Style")
+2. **Colors**
+3. **Typography**
+4. **Layout** (also: "Layout & Spacing")
+5. **Elevation & Depth** (also: "Elevation")
+6. **Shapes**
+7. **Components**
+8. **Do's and Don'ts**
+
+### Prose and Tokens
+
+## Overview
+
+Also known as "Brand & Style".
+
+This section is a holistic description of a product's look and feel. It defines the brand personality, target audience, and the emotional response the UI should evoke, such as whether it should feel playful or professional, dense or spacious. It serves as foundational context for guiding the agent's high-level stylistic decisions when a specific rule or token isn't explicitly defined.
+
+## Colors
+
+This section defines the color palettes for the design system.
+
+At least the `primary` color palette must be defined, and additional color palettes may be defined as needed.
+
+When there are multiple color palettes, the design system may assign a semantic role for each palette. A common convention is to name the palettes in this order: `primary`, `secondary`, `tertiary`, and `neutral`.
+
+Example:
+
+```markdown
+## Colors
+
+The palette is rooted in high-contrast neutrals and a single, evocative accent color.
+
+- **Primary (#1A1C1E):** A deep ink used for headlines and core text to provide
+  maximum readability and a sense of permanence.
+- **Secondary (#6C7278):** A sophisticated slate used primarily for utilitarian
+  elements like borders, captions, and metadata.
+- **Tertiary (#B8422E):** A vibrant earthy red as the sole driver for
+  interaction, used exclusively for primary actions and critical highlights.
+- **Neutral (#F7F5F2):** A warm limestone that serves as the foundation for all
+  pages, providing a softer, more organic feel than pure white.
+```
+
+### Design Tokens
+
+The `colors` section defines all color design tokens. The color tokens should be derived from the key color palettes defined in the markdown prose. The exact mapping from color palettes to color tokens may follow any consistent naming convention.
+
+It is a
+map\<string, Color>, that maps the name of the color token to its value.
+
+```yaml
+colors:
+  primary: "#1A1C1E"
+  secondary: "#6C7278"
+  tertiary: "#B8422E"
+  neutral: "#F7F5F2"
+```
+
+## Typography
+
+This section defines typography levels.
+
+Most design systems have 9 - 15 typography levels. The design system may prescribe a role for each typography level.
+
+A common naming convention for typography levels is to use semantic categories such as `headline`, `display`, `body`, `label`, `caption`. Each category may further be divided into different sizes, such as `small`, `medium`, and `large`.
+
+Example:
+
+```markdown
+## Typography
+
+The typography strategy leverages two distinct weights of **Public Sans** for
+the narrative and **Space Grotesk** for technical data.
+
+- **Headlines:** Set in Public Sans Semi-Bold to establish an institutional
+  and trustworthy voice.
+- **Body:** Public Sans Regular at 16px ensures contemporary professionalism
+  and long-form readability.
+- **Labels:** Space Grotesk is used for all technical data, timestamps, and
+  metadata. Its geometric construction evokes the precision of a digital
+  stopwatch. Labels are strictly uppercase with generous letter spacing.
+```
+
+### Design Tokens
+
+The `typography` section defines the precise font properties for the typography design tokens.
+
+It is a
+map\<string, Typography>
+
+```yaml
+typography:
+  h1:
+    fontFamily: Public Sans
+    fontSize: 48px
+    fontWeight: 600
+    lineHeight: 1.1
+    letterSpacing: -0.02em
+  body-md:
+    fontFamily: Public Sans
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1.6
+  label-caps:
+    fontFamily: Space Grotesk
+    fontSize: 12px
+    fontWeight: 500
+    lineHeight: 1
+    letterSpacing: 0.1em
+```
+
+## Layout
+
+Also known as "Layout & Spacing".
+
+This section describes the layout and spacing strategy.
+
+Many design systems follow a grid-based layout. Others, like Liquid Glass, use margins, safe areas, and dynamic padding.
+
+Example:
+
+```markdown
+## Layout
+
+The layout follows a **Fluid Grid** model for mobile devices and a
+**Fixed-Max-Width Grid** for desktop (max 1200px).
+
+A strict 8px spacing scale (with a 4px half-step for micro-adjustments) is used to maintain a consistent rhythm. Components are grouped using "containment" principles, where related items are housed in cards with generous internal padding (24px) to emphasize the soft, approachable nature of the brand.
+```
+
+### Design Tokens
+
+The spacing section defines the spacing design tokens. These may include spacing units that are useful for implementing the layout model. For example, a fixed grid layout may have spacing units for column spans, gutters, and margins.
+
+It is a
+map\<string, Dimension | number> that maps the spacing scale identifier to a dimension value or a unitless number (e.g., column counts or ratios).
+
+```yaml
+spacing:
+  base: 16px
+  xs: 4px
+  sm: 8px
+  md: 16px
+  lg: 32px
+  xl: 64px
+  gutter: 24px
+  margin: 32px
+```
+
+## Elevation & Depth
+
+Also known as "Elevation".
+
+This section describes how visual hierarchy is conveyed based on the design style. If elevation is used, it defines the required styling (spread, blur, color). For flat designs, this section explains the alternative methods used to convey visual hierarchy (e.g., borders, color contrast).
+
+Example:
+
+```markdown
+## Elevation & Depth
+
+Depth is achieved through **Tonal Layers** rather than heavy shadows. The
+background uses a soft off-white or very light green, while primary content sits on pure white cards.
+```
+
+## Shapes
+
+This section describes how visual elements are shaped.
+
+Example:
+
+```markdown
+## Shapes
+
+The shape language is defined by **Architectural Sharpness**. All interactive
+elements, containers, and inputs utilize a minimal **4px corner radius**. This
+provides just enough softness to feel modern while maintaining a rigid,
+engineered aesthetic.
+```
+
+### Design Tokens
+
+The `rounded` section defines the design tokens for rounded corners used in
+buttons, cards, and other rectangular shapes.
+
+It is a map\<string, Dimension>.
+
+```yaml
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 12px
+  full: 9999px
+```
+
+## Components
+
+This section provides style guidance for component atoms within the design system. The following are common component types. Design systems are encouraged to define additional components relevant to their domain.
+
+* **Buttons**: Covers primary, secondary, and tertiary variants, including sizing, padding, and states.
+* **Chips**: Covers selection chips, filter chips, and action chips.
+* **Lists**: Covers styling for list items, dividers, and leading/trailing elements.
+* **Tooltips**: Covers positioning, colors, and timing.
+* **Checkboxes**: Covers checked, unchecked, and indeterminate states.
+* **Radio buttons**: Covers selected and unselected states.
+* **Input fields**: Covers text inputs, text areas, labels, helper text, and error states.
+
+> **Note:** The components specification is actively evolving. The current structure provides intentional flexibility for domain-specific component definitions while the spec matures.
+
+### Design Tokens
+
+The components section defines a collection of design tokens used to ensure consistent styling of common components. It's a map\<string, map\<string, string>> that maps a component identifier to a group of sub token names and values. The design token values may be literal values, or references to previously defined design tokens.
+
+**Variants**. A component may have a variant for different UI states such as active, hover, pressed, etc. Those variant components may be defined under a different but related key, for example, "button-primary", "button-primary-hover", "button-primary-active". The agent will consider all variants and make the appropriate styling decisions.
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.primary-60}"
+    textColor: "{colors.primary-20}"
+    rounded: "{rounded.md}"
+    padding: 12px
+  button-primary-hover:
+    backgroundColor: "{colors.primary-70}"
+```
+
+### Component Property Tokens
+
+Each component has a set of properties that are themselves design tokens:
+
+- backgroundColor: \<Color\>
+- textColor: \<Color\>
+- typography: \<Typography\>
+- rounded: \<Dimension\>
+- padding: \<Dimension\>
+- size: \<Dimension\>
+- height: \<Dimension\>
+- width: \<Dimension\>
+
+## Do's and Don'ts
+
+This section provides practical guidelines and common pitfalls. These act as guardrails when creating designs.
+
+```markdown
+## Do's and Don'ts
+
+- Do use the primary color only for the single most important action per screen
+- Don't mix rounded and sharp corners in the same view
+- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
+- Don't use more than two font weights on a single screen
+```
+
+# Recommended Token Names (Non-Normative)
+
+The following names are commonly used across design systems. They are not required but are provided as guidance for consistency.
+
+**Colors:** `primary`, `secondary`, `tertiary`, `neutral`, `surface`, `on-surface`, `error`
+
+**Typography:** `headline-display`, `headline-lg`, `headline-md`, `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`
+
+**Rounded:** `none`, `sm`, `md`, `lg`, `xl`, `full`
+
+# Consumer Behavior for Unknown Content
+
+When a DESIGN.md consumer encounters content not defined by this spec:
+
+| Scenario | Behavior | Example |
+|---|---|---|
+| Unknown section heading | Preserve; do not error | `## Iconography` |
+| Unknown color token name | Accept if value is valid | `surface-container-high: '#ede7dd'` |
+| Unknown typography token name | Accept as valid typography | `telemetry-data` |
+| Unknown spacing value | Accept; store as string if not a valid dimension | `grid-columns: '5'` |
+| Unknown component property | Accept with warning | `borderColor` |
+| Duplicate section heading | Error; reject the file | Two `## Colors` headings |

package/protocols/fake-data-detector.md

@@ -51,7 +51,7 @@ Write findings to `docs/plans/.build-state.md` under `## Fake Data Detector`:
 |---|-----------|---------|----------------|----------|---------------|
 
 <HARD-GATE>
-CRITICAL findings block the Reality Checker (Step 6.3). Do not proceed past Phase 6.2d until all CRITICAL findings are resolved or explicitly accepted by the user.
+CRITICAL findings route through the Feedback Synthesizer (Step 5.4) and Fix loop (Step 5.5) — they do NOT block inline. The synthesizer classifies and routes them like all other finding streams.
 </HARD-GATE>
 
 ---

package/protocols/ios-context.md

@@ -4,7 +4,7 @@ _Loaded by every iOS implementation agent when `project_type=ios`. Not loaded in
 
 ## Credits
 - Core rules derived from **twostraws/SwiftAgents** (Paul Hudson) — MIT-style open guide.
-- HIG baseline + iOS 26 platform awareness adapted from **johnrogers/claude-swift-engineering** skills (`ios-hig`, `ios-26-platform`).
+- HIG baseline + iOS 26 platform awareness adapted from **johnrogers/claude-swift-engineering** skills (granular `hig-foundations` + `hig-components-*` family, `ios-26-platform`).
 - Tool-preference hierarchy and post-training-cutoff watch-terms **paraphrased** from Apple's Xcode 26 `AgentSystemPromptAddition` template (Apple copyright — paraphrased, never quoted).
 
 ---
@@ -114,7 +114,7 @@ Glass applies to navigation chrome only, never content; gate iOS 26 APIs behind
 
 ## 8. HIG Compliance Baseline
 
-HIG compliance — see `skills/ios/ios-hig/` for full reference.
+HIG compliance — start with `skills/ios/hig-foundations/`; granular `skills/ios/hig-components-*` skills (content, controls, dialogs, layout, menus, search, status, system) cover specific component categories, and `hig-inputs`, `hig-patterns`, `hig-platforms`, `hig-project-context`, `hig-technologies` cover the remaining HIG surface area.
 Non-negotiables: 44pt touch targets, Dynamic Type support, dark mode parity, VoiceOver labels, Reduce Motion respect.
 Permission requests must be contextual with purpose strings; haptics rare and meaningful only.
 
@@ -129,7 +129,7 @@ Permission requests must be contextual with purpose strings; haptics rare and me
 - Documentation comments on public API.
 - **Never commit secrets.** API keys go in `.xcconfig` (gitignored) or the keychain.
 - **Localization:** if the project uses `Localizable.xcstrings`, add user-facing strings as **symbol keys** (e.g. `helloWorld`) with `extractionState: "manual"`, accessed via generated symbols: `Text(.helloWorld)`. Offer to translate new keys into all supported languages.
-- **PrivacyInfo.xcprivacy ownership:** the `ios-info-plist-hardening` skill (Phase 4 Foundation) owns creating `PrivacyInfo.xcprivacy` — NOT Phase 7 Ship. Any required-reason API declarations, tracking domains, and collected-data-type entries must land in Phase 4 alongside Info.plist hardening.
+- **PrivacyInfo.xcprivacy ownership:** the `ios-info-plist-hardening` skill (Phase 4 Step 4.0 Scaffold) owns creating `PrivacyInfo.xcprivacy` — NOT Phase 7 Ship. Any required-reason API declarations, tracking domains, and collected-data-type entries must land in Phase 4 alongside Info.plist hardening.
 
 ---
 
@@ -164,7 +164,7 @@ When MCP servers are available, **always prefer them** over generic file or shel
 
 ## iOS Feature Flag Schema
 
-These flags gate Phase 5 skill loading and Phase 4 entitlement generation. Orchestrator resolves them at the end of Phase 2 (see `commands/build.md` → Phase 2 "Feature Flag Resolution") and persists them to `docs/plans/.build-state.md` under an `ios_features:` key.
+These flags gate Phase 4 per-task skill loading and Phase 4 Step 4.0 entitlement generation. Orchestrator resolves them at the end of Phase 2 (see `commands/build.md` → Phase 2 "Feature Flag Resolution") and persists them to `docs/plans/.build-state.md` under an `ios_features:` key.
 
 ```yaml
 ios_features:
@@ -186,7 +186,7 @@ ios_features:
   appleWatch: bool
 ```
 
-**Read contract:** Phase 4 (`ios-entitlements-generator`) and Phase 5 (skill loader) MUST read this block from `.build-state.md` before acting. A skill gated by flag `X` is loaded only when `ios_features.X == true`. Unset flags default to `false`.
+**Read contract:** Phase 4 Step 4.0 (`ios-entitlements-generator`) and Phase 4 per-task flow (skill loader) MUST read this block from `.build-state.md` before acting. A skill gated by flag `X` is loaded only when `ios_features.X == true`. Unset flags default to `false`.
 
 ---
 
@@ -206,18 +206,17 @@ _Per-phase skill bundle — orchestrator loads the relevant subset based on curr
 
 ### Phase 3 — Design
 - `agents/ios-swift-ui-design.md` — visual intake (mockups → SwiftUI plan)
-- `skills/ios/ios-hig/` — HIG compliance reference
+- `skills/ios/hig-foundations/` + granular `hig-*` skills — HIG compliance (see agent shortlists for per-agent selection)
 - `skills/ios/swiftui-design-principles/` — 10-rule visual polish
 - `skills/ios/swiftui-liquid-glass/` — iOS 26 glass decision tree
-- `skills/ios/writing-for-interfaces/` — microcopy (if not yet ported, TBD)
 
-### Phase 4 — Foundation
+### Phase 4 — Build (Step 4.0 Scaffold)
 - `skills/ios/ios-entitlements-generator/` (stub)
 - `skills/ios/ios-info-plist-hardening/` (stub)
 
-### Phase 5 — Build
+### Phase 4 — Build (Step 4.1+ per-task flow)
 - `skills/ios/swiftui-pro/` (every UI write)
-- `skills/ios/swift-concurrency/` (async/actor/Sendable)
+- `skills/ios/swift-concurrency-6-2/` (async/actor/Sendable — Swift 6.2 single-threaded default)
 - `skills/ios/swiftdata-pro/` (@Model/@Query usage)
 - `skills/ios/swift-accessibility/` (every UI write — a11y first-draft)
 - `skills/ios/swift-security-expert/` (Keychain/Crypto/auth)
@@ -225,7 +224,7 @@ _Per-phase skill bundle — orchestrator loads the relevant subset based on curr
 - AI feature: `agents/ios-foundation-models-specialist.md`
 - IAP feature: `agents/ios-storekit-specialist.md`
 
-### Phase 6 — Harden
+### Phase 5 — Audit
 _Dispatches to `/verify` + `/ux-review` + `/fix` iOS twins in sequence. Each twin has its own skill bundle inline in its command file._
 
 ### Phase 7 — Ship (optional)

package/protocols/ios-fake-data-detector.md

@@ -0,0 +1,65 @@
+# iOS Fake Data Detector Protocol
+
+You are the orchestrator. Phase 6.2d detects mock, fake, or hardcoded data masquerading as real functionality in iOS/Swift projects. This catches apps that look complete but run on canned responses, simulated delays, or placeholder content.
+
+## When to Run
+
+Run as a single agent in Phase 6.2d, after the eval harness and metric loop. CRITICAL findings block the Reality Checker in Step 6.3.
+
+## Step 1: Static Analysis
+
+Call the Agent tool — description: "Detect fake data (static, iOS)" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: M] Grep the codebase for fake data patterns. Exclude test targets (`*Tests/`, `*UITests/`), `#Preview` blocks (data defined AND consumed within the block), seed/fixture files (`**/Fixtures/`, `**/Seeds/`), `.xcconfig` files, and `Package.swift`. For each match, report file:line, the pattern matched, and why it is suspicious. Patterns to check:
+
+1. `UUID()` generating business data IDs (prices, orders, transactions) — ignore SwiftUI view identity or test helpers
+2. Hardcoded arrays/dictionaries posing as API responses (e.g., `let users = [User(name: "John"...)]` in production source, not inside `#Preview`)
+3. `Task.sleep` / `Thread.sleep` faking async operations (simulating network latency or streaming that should be real API calls)
+4. Strings: 'Lorem ipsum', 'placeholder', 'sample data', 'test data', 'TODO', 'FIXME' in user-facing `Text()`, `Label()`, `.navigationTitle()`, or `LocalizedStringKey`
+5. `print()` / `debugPrint()` faking real output (e.g., `print("Order placed successfully")`) — ignore `#if DEBUG` guarded prints
+6. Hardcoded URLs (`"https://..."`, `"http://..."`) not sourced from `Info.plist`, `.xcconfig`, `ProcessInfo.processInfo.environment`, or a config enum/struct
+7. `#Preview` sample data leaking into production — data factories or static properties defined inside `#Preview` that are also referenced by production views or view models
+8. Mock `URLSession` / `URLProtocol` subclasses included in the main app target (not test targets)
+9. Hardcoded JSON strings as API response stubs (e.g., multi-line string literals containing `{` with key-value pairs used in `JSONDecoder().decode`)
+10. `UserDefaults` storing structured domain data (arrays of models, user profiles, transaction history) that should live in SwiftData / CloudKit / a proper persistence layer"
+
+## Step 2: Dynamic Analysis (Instruments / Network Trace)
+
+Check `docs/plans/evidence/*/` for `.trace` or network capture files from Maestro/smoke tests. If none exist, skip to Step 3.
+
+If trace files exist, call the Agent tool — description: "Detect fake data (dynamic, iOS)" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: S] Parse trace/network capture files in `docs/plans/evidence/*/`. Flag:
+
+1. Zero external API calls during a full app exercise (all data local or hardcoded)
+2. Identical response bodies across different endpoint calls
+3. No error handling paths exercised (no non-200 status codes observed, no alert/error UI triggered)"
+
+## Step 3: Classify Findings
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | Production code using hardcoded data that should come from an API — business logic relies on `UUID()` for real IDs, hardcoded arrays substitute for real API responses |
+| HIGH | Mock networking left in release target — `URLProtocol` subclass in main target, simulated delays via `Task.sleep` |
+| MEDIUM | Placeholder strings in user-facing UI — 'Lorem ipsum' in `Text()`, 'TODO' in navigation titles |
+| LOW | Debug prints in production code — `print()` / `debugPrint()` outside `#if DEBUG` |
+
+## Step 4: Report
+
+Write findings to `docs/plans/evidence/fake-data-audit.md`:
+
+| # | File:Line | Pattern | Why Suspicious | Severity | Suggested Fix |
+|---|-----------|---------|----------------|----------|---------------|
+
+<HARD-GATE>
+CRITICAL findings route through the Feedback Synthesizer (Step 5.4) and Fix loop (Step 5.5) — they do NOT block inline. The synthesizer classifies and routes them like all other finding streams.
+</HARD-GATE>
+
+---
+
+## Rules
+
+- ONE agent for static checks, ONE agent for dynamic checks. Do not combine.
+- If no trace files exist, run static checks only. Do not fail the protocol for missing traces.
+- Do NOT flag: test target code, data defined and consumed entirely within `#Preview`, seed/fixture data, `.xcconfig` values, `Package.swift` dependencies, or explicit dev mock servers behind `#if DEBUG` / compile-time flags.
+- Every finding must include a file:line reference. No vague "the codebase has fake data" reports.