buildanything 1.7.1 → 2.0.0

package/protocols/architecture-schema.md

@@ -0,0 +1,171 @@
+# architecture.md Anchor Convention
+
+## Purpose
+
+Phase 2.3's architecture synthesizer emits `docs/plans/architecture.md` with **stable section anchors** so that Phase 5.1 implementer agents can receive content-addressed **refs** (file path + anchor name) instead of pasted content slices. This document defines the required top-level sections, the anchor naming convention, the minimum subsection anchors each top-level section must provide, the exact ref format Phase 5.1 prompts inject, and the synthesizer's output contract. Introduced in Wave 1 (W1-4) to close the capdotai Phase 5 regression where the orchestrator loaded a 43KB architecture doc into its own context 48 times to slice it — violating the "dispatcher not doer" HARD-GATE at `commands/build.md:24` and burning ~528K tokens on slicing alone.
+
+## Required top-level sections
+
+The synthesized `architecture.md` MUST contain these top-level headings, in this order:
+
+- `# Overview`
+- `# Frontend`
+- `# Backend`
+- `# Data Model`
+- `# Security`
+- `# Infrastructure`
+- `# MVP Scope`
+- `# Out of Scope`
+
+For iOS builds, `# Frontend` MAY be titled `# App` and `# Backend` MAY be omitted if the app is fully on-device (the `refs.json` index reflects whatever headings exist). For web builds, all eight headings are required.
+
+## Anchor naming rules
+
+- Anchors are **kebab-case** within a section — lowercase, hyphen-separated, no spaces.
+- Subsections use a **nested anchor** of the form `parent/child`. For example, `frontend/checkout` refers to a `## Checkout` subsection under `# Frontend`.
+- Anchors must be **stable across synthesizer reruns**. A rerun of the synthesizer on the same inputs must produce the same anchors, so that refs cached in `refs.json` or in implementer prompts do not break.
+- Anchors are **referenced via `architecture.md#parent/child`** in prompt bodies and in `refs.json`. The `#` separator is a plain markdown fragment — no special escaping.
+- Deeper nesting (`parent/child/grandchild`) is allowed but discouraged. Prefer two levels.
+- Anchor names MUST NOT include spaces, uppercase letters, punctuation other than `-` and `/`, or numeric prefixes like `1-frontend`.
+
+## Required subsection anchors (minimum)
+
+Every synthesized `architecture.md` MUST provide at least these subsection anchors under the named top-level section. Additional subsections are allowed; fewer is a synthesizer failure.
+
+### Under `# Frontend`
+
+- `frontend/layout` — page hierarchy, routing, navigation structure. MUST state whether the product exposes a public, unauthenticated, content-indexable surface (yes / no / partial) — downstream SEO skill loading keys off this answer.
+- `frontend/components` — core component list and responsibilities.
+- `frontend/state` — state management approach (stores, context, local state boundaries).
+- `frontend/styling` — design tokens, CSS/styling approach.
+
+### Under `# Backend`
+
+- `backend/services` — service boundaries and responsibilities.
+- `backend/api` — API contracts (routes, request/response shapes).
+- `backend/persistence` — data layer, ORM choice, query patterns.
+
+### Under `# Data Model`
+
+- `data-model/entities` — entities and their relationships.
+- `data-model/migrations` — migration strategy (omit only if no persistence layer exists).
+
+### Under `# Security`
+
+- `security/auth` — authentication and authorization model.
+- `security/input-validation` — boundary validation rules.
+- `security/secrets` — secret storage and rotation.
+
+## Ref format used by implementer prompts
+
+Phase 5.1 implementer prompts inject a `ARCHITECTURE REFS:` block in place of pasted architecture content. The block is parsed by the implementer agent, which uses the `Read` tool to fetch refs on demand.
+
+```
+ARCHITECTURE REFS:
+  - architecture.md#frontend/checkout (primary)
+  - architecture.md#data-model/orders (secondary — read if touching order creation)
+  - architecture.md#security/auth (read if touching /api/checkout)
+```
+
+Rules:
+
+- `(primary)` — the implementer MUST Read this ref before starting work.
+- `(secondary — read if touching X)` — conditional; the implementer reads only if the task description overlaps with the hint.
+- Refs are one per line, bullet-prefixed `-`, with two-space indent.
+- File paths are relative to the repo root. Anchors are kebab-case per the rules above.
+
+The orchestrator NEVER pastes section content into the implementer prompt. It emits only refs. If the implementer needs more context, it Reads additional refs or opens the full `architecture.md`.
+
+## Phase 2.3 synthesizer output contract
+
+The Phase 2.3 architecture synthesizer MUST produce one artifact:
+
+1. `docs/plans/architecture.md` — the human-readable architecture doc, containing:
+   - All eight required top-level headings (or the iOS-adjusted set).
+   - All required subsection anchors for each top-level section present.
+   - Prose content under each subsection sufficient for an implementer to ground their work.
+
+The synthesizer does NOT write `refs.json`. The Phase 2.2 Refs Indexer owns that file (see below).
+
+The synthesizer MUST fail loudly (emit a BLOCKED verdict) if it cannot produce all required subsection anchors — e.g., if the architecture is too thin to have a meaningful `security/auth` section, the synthesizer stubs the anchor with a one-line "N/A — {reason}" rather than omitting it.
+
+## refs.json — the live downstream docs index
+
+`refs.json` is the live downstream docs index. It covers every anchor in:
+
+- `design-doc.md` (THE PRD)
+- `architecture.md`
+- `sprint-tasks.md`
+- `visual-design-spec.md` (if exists)
+- `quality-targets.json` (via flat key anchors)
+
+Writer: Phase 2.2 Refs Indexer step (dispatched as INTERNAL inline role-string). Consumers: Phase 3+ agents via the Briefing Officer per-task context map (no full pastes). Phase 1 raw research files are NOT in `refs.json` — they are spent after Phase 2 hybrid routing distributes them to architects.
+
+The Phase 2.2 Refs Indexer (INTERNAL inline role-string dispatched by the orchestrator) is the sole writer of `refs.json`. It runs after the architecture synthesizer and Sprint Breakdown steps, reads the live docs (`design-doc.md`, `architecture.md`, `sprint-tasks.md`, `visual-design-spec.md` if exists, `quality-targets.json`), and emits the multi-doc anchor index.
+
+See `commands/build.md` Phase 2.2 Step 2.3 Refs Indexer dispatch for the exact generation prompt.
+
+## refs.json example
+
+```json
+{
+  "schema_version": "2.0",
+  "generated_at": "2026-04-13T10:00:00Z",
+  "generated_by": "Phase 2.2 Refs Indexer",
+  "anchors": [
+    {
+      "file_path": "docs/plans/design-doc.md",
+      "anchor": "#persona",
+      "topic": "primary user persona + JTBD",
+      "line_start": 12,
+      "line_end": 38
+    },
+    {
+      "file_path": "docs/plans/architecture.md",
+      "anchor": "#frontend/checkout",
+      "topic": "checkout flow component tree",
+      "line_start": 102,
+      "line_end": 145
+    },
+    {
+      "file_path": "docs/plans/architecture.md",
+      "anchor": "#data-model/orders",
+      "topic": "Orders entity, status enum, relations to users and items",
+      "line_start": 302,
+      "line_end": 358
+    },
+    {
+      "file_path": "docs/plans/sprint-tasks.md",
+      "anchor": "#sprint-1-task-3",
+      "topic": "wire checkout form to /api/checkout",
+      "line_start": 88,
+      "line_end": 104
+    }
+  ]
+}
+```
+
+Fields:
+
+- `schema_version` (string) — currently `"2.0"`. Bumped from `1` when the index was extended from architecture-only to the multi-doc scope above.
+- `generated_at` (ISO 8601) — Refs Indexer run timestamp.
+- `generated_by` (string) — `"Phase 2.2 Refs Indexer"`.
+- `anchors` (array) — one entry per anchor across all indexed files. Each: `{file_path, anchor, topic, line_start, line_end}`.
+  - `file_path` — repo-relative path of the file the anchor lives in. Required. Tells consumers which document to `Read`.
+  - `anchor` — the markdown fragment, including the leading `#` (e.g. `#frontend/checkout`, `#persona`). For `quality-targets.json` entries, the anchor is the flat key name.
+  - `topic` — one-sentence summary used by the Briefing Officer to pick refs without reading the file.
+  - `line_start`, `line_end` — optional but recommended. Allow consumers to `Read` just the section instead of the whole file.
+
+## Validation
+
+A synthesized `architecture.md` plus `refs.json` pair is well-formed iff:
+
+1. All required top-level headings exist in `architecture.md` (grep `^# {Heading}$` for each).
+2. All required subsection anchors resolve to real `## Heading` lines under the correct parent. (A heading `## Checkout` under `# Frontend` resolves the anchor `frontend/checkout`.)
+3. `refs.json` parses as valid JSON against the shape above.
+4. Every architecture-scoped entry in `refs.json.anchors[]` (those with `file_path` ending in `architecture.md`) resolves to a real heading in `architecture.md` at the claimed `line_start`.
+5. Every required anchor from this document appears in `refs.json.anchors` with the correct `file_path`.
+6. No `(file_path, anchor)` pair appears twice in `refs.json.anchors`.
+7. `schema_version` is `"2.0"` and `generated_by` is `"Phase 2.2 Refs Indexer"`.
+
+The Wave 1 `buildanything:verify` protocol runs these checks after Phase 2.3 completes. A failure flips the Phase 2 verdict to `NEEDS_WORK` and re-dispatches the Refs Indexer (or the synthesizer, if the missing anchors indicate `architecture.md` itself is incomplete) with a directive listing the missing anchors.

package/protocols/build-fix.md

@@ -0,0 +1,52 @@
+# Build-Fix Protocol (One Error at a Time)
+
+You are the orchestrator. A build, type-check, or lint check has failed. Do NOT dump all errors on a fix agent. Most build errors cascade — fixing the root cause clears 5-10 downstream errors.
+
+## When to Use
+
+When the Verification Protocol reports FAIL on Build, Type-Check, or Lint checks. Also usable during Phase 4 scaffolding or Phase 5 implementation when builds break.
+
+## Step 1: Extract First Error
+
+Parse the failure output from the verification agent. Extract the FIRST error only:
+- File path
+- Line number (if available)
+- Error message
+
+Ignore all other errors. They are likely cascading from this one.
+
+## Step 2: Fix
+
+Call the Agent tool — description: "Fix [error]" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: S] Fix this single build error. FILE: [path]. LINE: [number]. ERROR: [message]. Fix this specific error. Do not fix other errors. Do not refactor. Commit: 'fix: [error description]'."
+
+> Pass ONLY the single error. Do not show the fix agent the full error log.
+
+## Step 3: Rebuild
+
+Re-run ONLY the failing check (not all 6 verification checks). Count errors in the new output.
+
+## Step 4: Evaluate
+
+- **0 errors:** DONE. Return FIXED to the calling protocol.
+- **Error count decreased:** Log "CASCADE: fixed 1 error, resolved [N] total." Return to Step 1 with the new first error.
+- **Error count same or increased:** The fix was bad. Revert: `git revert HEAD --no-edit`. Try the SECOND error from the original output instead. If already tried 2 different errors, return FAILED.
+- **Iteration count >= 5:** Return PARTIAL with remaining error count.
+
+## Step 5: Report
+
+Return to the orchestrator one of:
+- **FIXED** — all errors resolved
+- **PARTIAL** — [N] errors remain after 5 iterations
+- **FAILED** — could not make progress
+
+---
+
+## Rules
+
+- ONE error per fix agent. Never show a fix agent multiple errors.
+- Revert bad fixes immediately. Do not accumulate broken fixes.
+- Max 5 fix iterations per build-fix invocation.
+- The fix agent is a SEPARATE agent from the verification agent. Fresh context.
+- Track iteration count and error count delta in `docs/plans/.build-state.md`.

package/protocols/cleanup.md

@@ -0,0 +1,54 @@
+# Cleanup Protocol (De-Sloppify)
+
+You are the orchestrator. An implementation agent just finished a task. Before running the metric loop, you run a focused cleanup pass on the changed files.
+
+## When to Skip
+
+If the implementation was trivial — single config file change, < 20 lines changed total — skip this protocol. The overhead isn't worth it.
+
+## Step 1: Collect the Changeset
+
+Get the authoritative list of files changed by running `git diff --name-only HEAD~1` (or checking the implementation agent's commit). Do not rely solely on the agent's self-reported file list — use git as the source of truth. This is the cleanup scope. Nothing outside this list gets touched.
+
+## Step 2: Invoke the Cleanup Agent
+
+Call the Agent tool — description: "Cleanup [task name]" — mode: "bypassPermissions" — prompt:
+
+"You are a code quality cleanup agent. Your job is to improve code quality in the files listed below WITHOUT changing behavior.
+
+FILES IN SCOPE:
+[list of files changed by the implementer]
+
+ACCEPTANCE CRITERIA (do not break these):
+[paste the task's acceptance criteria]
+
+FIX these issues if you find them:
+- Naming inconsistencies (variables, functions, files)
+- Dead code and unused imports
+- Redundant or duplicate imports
+- Unclear variable or function names
+- Missing error handling
+- Code style violations
+- Obvious DRY violations within the changed files
+
+DO NOT:
+- Add features or change behavior
+- Modify the architecture or file structure
+- Touch files outside the list above
+- Refactor code that wasn't part of this task
+- Modify tests unless fixing a broken assertion caused by the implementer
+
+When finished, commit: 'refactor: cleanup [task name]'."
+
+## Step 3: Verify
+
+After the cleanup agent finishes, spot-check that acceptance criteria still hold. If the cleanup agent broke something, revert its commit and log the issue to `docs/plans/build-log.md`. Then proceed to the metric loop without cleanup.
+
+---
+
+## Rules
+
+- The cleanup agent is a SEPARATE Agent tool call from the implementer. No cleaning your own mess.
+- Scope is sacred. Only files from the implementation changeset. Zero exceptions.
+- This runs AFTER implementation, BEFORE the metric loop.
+- If cleanup breaks acceptance criteria, revert and skip. Never block the metric loop on a cleanup failure.

package/protocols/decision-log.md

@@ -0,0 +1,131 @@
+# Decision Log Protocol
+
+This is the append-only decision log that captures rejected alternatives alongside the chosen approach, with a natural-language revisit criterion for each rejection. It feeds two loops: the learnings pipeline at Step 6.0.1 (cross-run PITFALL capture) and the Phase 0 resume handler (preserving the *why* across build sessions). Without this log the build remembers *what* it chose but forgets *what it rejected and under what conditions to reconsider*.
+
+## Schema
+
+Rows live in `docs/plans/decisions.jsonl`, one JSON object per line, append-only. NEVER rewrite or truncate this file.
+
+```json
+{
+  "decision_id": "D-<phase>-<seq>",
+  "phase": "2.2",
+  "timestamp": "<ISO8601>",
+  "decision": "chose SQLite over Postgres for MVP persistence",
+  "chosen_approach": "SQLite with single-file .db in project root",
+  "rejected_alternatives": [
+    {
+      "approach": "Postgres via Supabase",
+      "reason": "adds infra setup to Phase 0 prereqs; overkill for single-user MVP",
+      "revisit_criterion": "multi-user access OR >10k rows OR concurrent writes"
+    }
+  ],
+  "decided_by": "<agent-role-string>",
+  "ref": "architecture.md#backend/persistence",
+  "status": "open"
+}
+```
+
+`decided_by` is a free-form string naming the agent role that authored the decision (e.g., `architect`, `implementer`, `design-brand-guardian`, `ux-architect`, `human`, `design-critic`). The orchestrator does not validate against a fixed enum — the set of writing agents changes as new phases ship, and a brittle whitelist would force a schema migration every time. The LRR Aggregator matches on the string value directly against its known-agent registry; unknown values fall through to the legacy classification path in Step 4.
+
+Findings in LRR chapter verdicts may reference a decision row via the `related_decision_id` field, which the LRR Aggregator uses for backward routing (see `protocols/launch-readiness.md` Aggregator Step 3). The `related_decision_id` lives on the **finding** object inside a chapter verdict, not on the decision row itself — it is the pointer from a finding back to the decision that authored the choice being violated.
+
+The `status` field takes one of three values:
+
+- `open` — decision stands, revisit criterion has not fired
+- `triggered` — Reality Checker matched the revisit criterion against current evidence this build
+- `resolved` — a later decision row supersedes this one; the log still shows both
+
+## Hard Field Constraints
+
+- Max **3 rejected alternatives** per decision row
+- Max **2 sentences** per `reason` field
+- Max **1 sentence** per `revisit_criterion` (natural language assertion)
+- Max **5 decision rows per phase** (typical 2-3)
+- Total per build: **15-25 rows max, ~500-1000 tokens worst case**
+- File path: `docs/plans/decisions.jsonl` — append-only, NEVER rewrite or truncate
+
+A row that exceeds any of these limits is a bug in the writing agent, not a permission to raise the limit. Split one decision into two rows before relaxing the constraints.
+
+## Natural-Language `revisit_criterion` Format
+
+The criterion is a one-sentence assertion the Reality Checker can semantically match against build evidence. Write it as the condition under which the rejected alternative would become correct. Do NOT write it as a metric threshold tied to a Phase 6 vocabulary that may not exist yet.
+
+Examples:
+
+- `"multi-user access OR >10k rows OR concurrent writes"`
+- `"user requests server-side rendering"`
+- `"bundle size exceeds 500KB gzipped"`
+- `"first-paint latency regresses below 2s on 4G"`
+
+If you cannot write the criterion in one sentence, the rejection is probably not yet crisp enough to log — revisit the decision first, log it second.
+
+## Author Assignment
+
+Author = the agent that made the call. The orchestrator NEVER writes decision rows itself.
+
+| Phase | Writer | Example decisions |
+|-------|--------|-------------------|
+| 1 (Brainstorm) | Brainstorm synthesis agent | Tech stack, data model, scope boundary |
+| 2.2 (Architecture) | Architecture synthesizer | API contract, service boundary, persistence, auth model |
+| 3 (Design) | [DEFERRED — currently no author until Phase 3 changes ship] | Visual direction kill rationales |
+| 4 (Build) | Implementer — ONLY if deviating from planned task | Deviation rationale |
+
+Phases 0, 6, 7 do not write decisions.
+
+## Readers
+
+Three consumers, each reads a bounded slice:
+
+1. **Phase 0 Resume Handler (on `--resume`)** — reads the top 5 most recent rows sorted by `decision_id` desc, filtered to the current phase and upstream phases. Injects short fields + `ref` anchor into rehydration context alongside `architecture.md`. Never reads all rows.
+
+2. **Step 6.0 Reality Checker (Dissent Log Revisit Pass)** — reads all rows where `status == "open"` and `revisit_criterion` is non-empty. Semantically evaluates each criterion against the current build's evidence manifest. For any triggered row, emits a structural finding of the form `"revisit-criterion-triggered: D-N-M — [criterion]"` in `specific_findings[]` and contributes to `combined_verdict` (triggered → at minimum NEEDS WORK).
+
+3. **Step 6.0.1 Learnings Harvester** — reads the Reality Checker's triggered findings and appends one PITFALL row per trigger to `learnings.jsonl` with `provenance.decision_id` back-referencing the source row. This is the cross-run PITFALL capture path, distinct from the in-run metric-loop post-hoc harvest.
+
+## Subagents Never Write Directly
+
+Subagents return `deviation_row` objects in their structured result. The orchestrator forwards each row through the `scribe_decision` MCP tool — the single writer for `docs/plans/decisions.jsonl`. The MCP owns `decision_id` allocation (`D-{phase}-<seq>`), stamps `timestamp` and `status: "open"`, validates against `decisions.schema.json`, and atomically appends the line. The orchestrator MUST NOT Write or Edit this file directly; subagents MUST NOT either. Specialist agents still author the row fields to preserve original language — they just don't touch the file.
+
+## Worked Examples
+
+**Phase 2.2 architecture — persistence layer (cross-domain deviation):**
+
+```json
+{
+  "decision_id": "D-2-03",
+  "phase": "2.2",
+  "timestamp": "2026-04-13T16:05:41Z",
+  "decision": "chose SQLite over Postgres for MVP persistence",
+  "chosen_approach": "SQLite with single-file .db in project root, migrations via drizzle-kit",
+  "rejected_alternatives": [
+    {
+      "approach": "Postgres via Supabase",
+      "reason": "adds infra setup to Phase 0 prereqs; overkill for single-user MVP.",
+      "revisit_criterion": "multi-user access OR >10k rows OR concurrent writes"
+    },
+    {
+      "approach": "JSON file on disk",
+      "reason": "no query layer, no migrations, no referential integrity.",
+      "revisit_criterion": "schema stabilizes AND row count stays under 500"
+    }
+  ],
+  "decided_by": "architect",
+  "ref": "architecture.md#backend/persistence",
+  "status": "open"
+}
+```
+
+## Token Budget
+
+| Item | Budget |
+|------|--------|
+| decisions.jsonl on disk per build | 500-1000 tokens worst case |
+| Reality Checker read (Step 6.0) | ~200 tokens |
+| Resume handler read (Phase 0) | ~300 tokens |
+| Learnings harvester read (Step 6.0.1) | ~200 tokens |
+| **Total per build** | **~1.2-1.7K tokens** |
+
+## Ref Field Convention
+
+Every row carries a `ref` anchor (e.g., `architecture.md#backend/persistence` or `visual-design-spec.md#<anchor>`) that downstream readers use to widen context without pasting prose. The resume handler passes the row's short fields *plus* the ref — the resumed agent reads the anchor via its own Read tool if it needs the full context. This matches the existing `refs.json` pattern in `commands/build.md` (primary/secondary anchors handed to implementers instead of pasted content), and keeps rehydration token cost bounded to ~300 tokens for the top 5 rows regardless of how much architectural prose sits behind each anchor.

package/protocols/eval-harness.md

@@ -0,0 +1,61 @@
+# Eval Harness Protocol
+
+You are the orchestrator. Phase 6.1 audits are complete. Before running the metric loop, define formal eval cases that are concrete, executable, and reproducible. This replaces subjective narrative audits with deterministic pass/fail tests.
+
+## How This Differs from the Metric Loop
+
+The metric loop scores quality 0-100; the eval harness tests specific behaviors as binary pass/fail. Eval failures feed into the metric loop as concrete issues.
+
+## Step 0: Define Eval Cases
+
+YOU (the orchestrator) define eval cases based on:
+- Audit findings from Phase 6.1 (highest-severity items first)
+- Architecture doc (API contracts, auth model, data validation rules)
+- Design doc (core user flows, edge cases)
+
+Write eval cases to `docs/plans/.build-state.md` under `## Eval Harness`:
+
+| # | Name | Action | Expected Result | pass@k | Severity |
+|---|------|--------|-----------------|--------|----------|
+
+**Severity thresholds (non-negotiable):**
+- CRITICAL: pass@5 (must pass 5/5 — 100% reliability)
+- HIGH: pass@4 (must pass 4/5 — 80% reliability)
+- MEDIUM: pass@3 (must pass 3/5 — 60% reliability)
+
+Aim for 8-15 eval cases. Cover: auth boundaries, input validation, error handling, core happy path, primary edge cases.
+
+**Eval cases must be concrete and executable** — actual commands (curl, function calls, UI interactions), not descriptions. Bad: "Auth should work." Good: "curl -X GET /api/recipes without Authorization header → expect 401."
+
+For UI flows, use agent-browser: "agent-browser open http://localhost:3000/dashboard → agent-browser click @e3 (Submit button) → agent-browser wait --text \"Order confirmed\" → expect page contains confirmation ID". These are concrete and executable via agent-browser CLI.
+
+## Step 1: Run Eval
+
+Call the Agent tool — description: "Run eval harness" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: M] Run these eval cases. For each case, execute the action the specified number of times (k). Report per case: PASS (N/k passed, meets threshold) or FAIL (N/k passed, below threshold). Include the actual result on failures. For eval cases that specify agent-browser commands, start the dev server first, then execute the agent-browser sequence. Capture annotated screenshots on failure. [paste eval case table]"
+
+<HARD-GATE>
+The eval agent RUNS cases. It does NOT define them. Case definition is the orchestrator's job.
+</HARD-GATE>
+
+## Step 2: Score
+
+Count PASS cases / total cases. This is the eval baseline. Record to `docs/plans/.build-state.md`.
+
+## Step 3: Feed into Metric Loop
+
+Any FAIL case with severity CRITICAL or HIGH becomes a candidate issue for the Phase 6.2 metric loop. Pass the failure details (case name, action, expected vs actual) as context when defining the metric loop's metric.
+
+## Step 4: Re-evaluate After Metric Loop
+
+After the Phase 6.2 metric loop exits, re-run the eval harness. All CRITICAL cases must now pass. If any CRITICAL case still fails, flag it for the Reality Checker in Step 6.3.
+
+---
+
+## Rules
+
+- Eval cases are defined by the ORCHESTRATOR, not by the eval agent.
+- pass@k thresholds are non-negotiable per severity level.
+- Re-run eval after metric loop to verify fixes — this is the exit gate.
+- Eval failures feed into the metric loop as specific, concrete issues — not vague audit findings.

package/protocols/fake-data-detector.md

@@ -0,0 +1,64 @@
+# Fake Data Detector Protocol
+
+You are the orchestrator. Phase 6.2d detects mock, fake, or hardcoded data masquerading as real functionality. This catches projects 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)" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: M] Grep the codebase for fake data patterns. Exclude test files (`**/*.test.*`, `**/*.spec.*`, `__tests__/`), seed files (`**/seed*`, `**/migrate*`), Storybook (`**/*.stories.*`), and `.env.example`. For each match, report file:line, the pattern matched, and why it is suspicious. Patterns to check:
+
+1. `Math.random()` generating business data (prices, scores, metrics) — ignore ID/key generation
+2. Hardcoded arrays/objects posing as API responses (e.g., `const users = [{id: 1, name: "John"...}]` in production source)
+3. `setTimeout`/`setInterval` faking async operations (simulating streaming, polling, or delays that should be real network calls)
+4. Strings: 'lorem ipsum', 'placeholder', 'sample data', 'test data' in production source
+5. `console.log` faking real output (e.g., `console.log("Trade executed: +$500")`)
+6. Fetch/axios calls to `localhost` or hardcoded URLs that should be env vars
+7. WebSocket connections that never process real data (`new WebSocket` with no `onmessage` handler or a handler that ignores the event)"
+
+## Step 2: Dynamic Analysis (HAR Files)
+
+Check `docs/plans/evidence/*/` for `.har` files from smoke tests. If none exist, skip to Step 3.
+
+If HAR files exist, call the Agent tool — description: "Detect fake data (dynamic)" — mode: "bypassPermissions" — prompt:
+
+"[COMPLEXITY: S] Parse HAR files in `docs/plans/evidence/*/`. Flag:
+
+1. Zero external API calls during a full app exercise (everything served locally)
+2. All API responses with identical structure and timing (cached/hardcoded)
+3. No WebSocket frames when app claims to stream data
+4. API calls returning 200 with identical response bodies across multiple requests"
+
+## Step 3: Classify Findings
+
+Assign severity to each finding:
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | Production data is fake — business logic relies on `Math.random()`, hardcoded objects substitute for real API calls |
+| HIGH | Mock data in production code path — simulated delays, placeholder strings in user-facing output |
+| MEDIUM | Suspicious pattern — hardcoded localhost URLs, WebSocket stubs that may be development leftovers |
+
+## Step 4: Report
+
+Write findings to `docs/plans/.build-state.md` under `## Fake Data Detector`:
+
+| # | File:Line | Pattern | Why Suspicious | Severity | Suggested Fix |
+|---|-----------|---------|----------------|----------|---------------|
+
+<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.
+</HARD-GATE>
+
+---
+
+## Rules
+
+- ONE agent for static checks, ONE agent for dynamic checks. Do not combine.
+- If no HAR files exist, run static checks only. Do not fail the protocol for missing HAR files.
+- Do NOT flag: seed/migration data, test fixtures, `.env.example`, Storybook demos, or explicit dev mock servers (MSW, json-server).
+- Every finding must include a file:line reference. No vague "the codebase has fake data" reports.