buildanything 1.8.0 → 2.1.1

package/protocols/launch-readiness.md

@@ -0,0 +1,262 @@
+# Launch Readiness Review Protocol
+
+You are the orchestrator. You are about to run a Launch Readiness Review (LRR) — a multi-chapter, independent-verdict gate that sits between the Phase 6 Reality Check and Phase 7.
+
+## Purpose
+
+LRR replaces the monolithic Reality Checker verdict with five independent chapter verdicts plus a mechanical aggregator.
+
+## Chapters
+
+LRR runs **five chapters**: Eng-Quality, Security, SRE, A11y, and Brand Guardian.
+
+Future consideration: A Data Privacy/Compliance chapter (covering GDPR consent flows, data retention policies, PII handling, cookie consent, privacy manifest completeness for iOS) is not included in the current 5-chapter panel. For regulated industries (healthcare, finance, education), the orchestrator SHOULD add a 6th chapter by dispatching `security-reviewer` with a privacy-focused prompt. This is advisory, not a HARD-GATE.
+
+Requirements coverage is evaluated as a sub-input of the Eng-Quality chapter. There is no separate PM chapter, no `pm.json` file, and the LRR Aggregator runs exactly once. The Eng-Quality chapter agent reads the Design Doc + `sprint-tasks.md` scope directly alongside its other evidence and emits COVERED/PARTIAL/MISSING per feature inline on its own verdict (see the `requirements_coverage` field in the schema below). There is no separate Step 7.0 dispatch and no Aggregator re-run.
+
+### Primary evidence inputs
+
+| Chapter | Primary evidence inputs |
+|---|---|
+| Eng-Quality | `architecture.md`, `task-outputs/`, `verify.md` check outputs, test results, eval results, Design Doc + `sprint-tasks.md` scope (read directly for the Requirements Coverage sub-input) |
+| Security | `evidence/fake-data-audit.md`, Phase 5 security audit output, eval-harness security cases |
+| SRE | Phase 5 performance-audit outputs, Performance Benchmarker evidence, NFRs from `sprint-tasks.md`, reliability checks |
+| A11y | Phase 5 a11y audit output, Phase 3.7 `a11y-design-review.md`, WCAG 2.2 AA runtime findings, per-page accessibility findings |
+| Brand Guardian | `DESIGN.md` (full file — Overview/Brand DNA/Do's and Don'ts + YAML tokens), `docs/plans/design-references.md`, Playwright screenshots under `docs/plans/evidence/` matching product pages |
+
+## Chapter verdict schema
+
+Each chapter agent runs fresh-context, reads its own slice of the evidence manifest, and writes a verdict file with this shape:
+
+```json
+{
+  "chapter": "eng-quality | security | sre | a11y | brand-guardian",
+  "verdict": "PASS | CONCERNS | BLOCK",
+  "override_blocks_launch": false,
+  "evidence_files_read": ["docs/plans/evidence/..."],
+  "findings": [
+    {"severity": "block|concern|info", "description": "...", "evidence_ref": "path", "related_decision_id": "D-2-03"}
+  ],
+  "follow_up_spawned": false,
+  "follow_up_findings": null
+}
+```
+
+The **Eng-Quality** chapter additionally carries the Requirements Coverage sub-input inline on its verdict:
+
+```json
+{
+  "requirements_coverage": [
+    {"feature": "string", "status": "COVERED | PARTIAL | MISSING", "note": "optional string"}
+  ]
+}
+```
+
+This field carries the PM coverage signal directly on the Eng-Quality verdict — there is no separate `pm.json` file and no separate PM dispatch. The Eng-Quality chapter agent reads the Design Doc + `sprint-tasks.md` scope as part of its own evidence sweep and emits the coverage list alongside its code-quality judgment.
+
+<HARD-GATE>
+SCHEMA CONTRACT:
+
+- `verdict` MUST be one of `PASS | CONCERNS | BLOCK`. `CONCERNS` means "I have concerns but won't block" and is aggregated as NEEDS WORK. `BLOCK` means "this fails my chapter's criteria" and is aggregated as NEEDS WORK unless `override_blocks_launch: true`.
+- `override_blocks_launch: true` is a veto-of-vetoes — no other chapter's PASS can override it. Only legal when `verdict == BLOCK`.
+- `evidence_files_read` MUST be non-empty. A verdict file with empty `evidence_files_read` is treated as malformed. "Looks good to me" verdicts are not permitted.
+- `follow_up_spawned` is only legal for the **Security** and **SRE** chapters. Brand Guardian and A11y chapters CANNOT spawn follow-ups — they render their verdict on what they can read and write it directly.
+</HARD-GATE>
+
+## A11y chapter rules
+
+The A11y chapter gates on WCAG 2.2 AA runtime findings from the Phase 5 accessibility audit and the Phase 3.7 a11y design review.
+
+- **PASS** if: zero Critical findings AND zero Serious findings AND zero failed WCAG 2.2 AA success criteria (runtime-measurable ones).
+- **CONCERNS** if: zero Critical AND 1-3 Serious findings (reviewable but not blocking).
+- **BLOCK** if: any Critical finding OR >3 Serious findings OR any failed WCAG 2.2 AA success criterion.
+
+Runtime measurement is required — spec-only compliance is not sufficient. Evidence must come from a Playwright + axe-core sweep (or equivalent) run against the actual built product pages, not the design system route alone.
+
+## Brand Guardian chapter rules
+
+The Brand Guardian chapter gates on **DNA drift** — did the built product stay true to the 6-axis Visual DNA locked at Phase 3.0?
+
+Prepend this anti-sycophancy preamble **verbatim** to the chapter dispatch prompt (stolen from ECC `gan-evaluator`):
+
+> "Your natural tendency is to be encouraging. Fight it. Default verdict: NEEDS WORK. You are not here to validate — you are here to find the gap."
+
+The chapter agent reads: `DESIGN.md` (the locked 7-axis DNA card lives at `## Overview > ### Brand DNA`; YAML tokens are what Phase 4 was supposed to honor; `## Do's and Don'ts` are the explicit guardrails), `docs/plans/design-references.md`, and Playwright screenshots under `docs/plans/evidence/` matching **product pages** (not just `/design-system`).
+
+Scoring — 6 DNA axes (20 pts each = 120) + 5 craft dimensions (20 pts each = 100) = **220 total**, target **≥ 180**.
+
+- **PASS** if: DNA score ≥ 180 AND craft score ≥ 75 AND no single axis scoring < 12/20.
+- **CONCERNS** if: DNA score 150-179 OR any single axis scoring 10-12/20.
+- **BLOCK** if: DNA score < 150 OR any axis scoring < 10/20.
+
+Every finding must cite a specific element with a `file:line` reference and reference either the DNA card or a `design-references.md` path. Vague findings ("the hero needs work") are not admissible — they are rejected by the Aggregator's schema check and the verdict defaults to CONCERNS. Brand Guardian is forbidden from rubber-stamping.
+
+## Follow-up investigation flow (Security and SRE only)
+
+Security and SRE — and only these chapters — may spawn one read-only follow-up investigation per LRR round. Eng-Quality, A11y, and Brand Guardian render their verdict on what they can read and rely on the existing NEEDS_WORK loop when concerns arise.
+
+The trigger is now tightened: follow-ups fire **only on a BLOCK verdict**. The previous "or suspicious, need to verify" escape hatch is gone — suspicion without a BLOCK is recorded as a CONCERNS verdict, not as a follow-up spawn.
+
+```
+Security/SRE chapter agent runs → reads evidence manifest + 2-3 targeted files
+  |
+  If verdict = PASS or CONCERNS → write lrr/{chapter}.json, done (1 dispatch)
+  |
+  If verdict = BLOCK → CAN spawn ONE follow-up (no longer legal on "suspicion")
+  |
+  Follow-up agent spawned with:
+    - Mode: read-only (no Write, no Edit, no Bash write ops)
+    - Allowed tools: Read, Grep, Glob
+    - Max tool calls: 15 (enforced via prompt + self-report)
+    - Scope: single named concern from parent chapter's findings
+    - Returns typed JSON (see below)
+  |
+  Parent chapter reads follow-up output + its own earlier findings,
+  validates follow-up schema, writes FINAL lrr/{chapter}.json with
+  follow_up_findings populated.
+```
+
+### Follow-up return schema
+
+```json
+{
+  "confirmed": true,
+  "evidence": ["path1", "path2"],
+  "findings": [
+    {"severity": "block|concern|info", "description": "...", "evidence_ref": "path"}
+  ],
+  "tool_calls_used": 12
+}
+```
+
+<HARD-GATE>
+HARD CAPS ON FOLLOW-UPS:
+
+- **Max 1 follow-up per chapter per LRR round.** No follow-ups spawning follow-ups — investigation chains are banned because that is where dispatch counts actually explode.
+- **Read-only.** Allowed tools: Read, Grep, Glob. No Write, no Edit, no Bash write ops. If the follow-up finds a real fix, it documents it — the fix is executed in a separate Phase 6 NEEDS_WORK cycle, never inline.
+- **15 tool call cap, self-reported via `tool_calls_used`.** Parent chapter validates `tool_calls_used <= 15` before accepting the follow-up output.
+- **Only Security and SRE have the power.** Eng-Quality, A11y, and Brand Guardian chapters with concerns write a CONCERNS verdict; they do not spawn follow-ups.
+- **BLOCK-only trigger.** A follow-up can only be spawned when the parent chapter's verdict is BLOCK. Concerns without a BLOCK are logged as CONCERNS; they do not justify a second dispatch.
+</HARD-GATE>
+
+SDK enforcement (Stage 5+): When dispatched via `claude-agent-sdk`, follow-up investigations MUST use `allowedTools: ["Read", "Grep", "Glob", "Bash(read-only)"]` to enforce read-only at the SDK level. The prompt-level instruction ("Read/Grep/Glob only") remains as defense-in-depth for non-SDK mode. The `maxTurns: 15` cap is enforced by the SDK harness, not self-reported.
+
+## Fallback on malformed or timed-out follow-up
+
+<HARD-GATE>
+DEFAULT: HARD BLOCK WITH `override_blocks_launch: true`.
+
+If a Security/SRE follow-up times out, returns invalid JSON, or reports `tool_calls_used > 15`, the parent chapter writes:
+
+```json
+{
+  "chapter": "security|sre",
+  "verdict": "BLOCK",
+  "reason": "follow_up_malformed",
+  "override_blocks_launch": true,
+  "detail": "Follow-up returned {timeout|invalid_json|cap_violation} — cannot verify security/reliability claim, blocking per pessimistic default"
+}
+```
+
+A security or reliability check that cannot produce a typed result is itself a signal — pessimistic-block is the only safe default. You cannot ship a build whose security check is unverifiable.
+</HARD-GATE>
+
+## LRR Aggregator
+
+The Reality Checker keeps its evidence-manifest sweep role but its verdict generation is replaced by LRR aggregation. The Aggregator now runs a **5-step flow**: file-completeness checkpoint → apply the 6 rules → BLOCK routing via the decision log → classification for NEEDS WORK findings → READY handoff.
+
+### Step 1: File-completeness checkpoint (NEW barrier)
+
+Before applying any aggregation rule, the Aggregator MUST Glob `docs/plans/evidence/lrr/*.json` and verify all 5 expected chapter files exist and parse as valid JSON:
+
+- `eng-quality.json`
+- `security.json`
+- `sre.json`
+- `a11y.json`
+- `brand-guardian.json`
+
+The Aggregator does **not** expect or read any `pm.json` file. Requirements coverage lives inline on the Eng-Quality verdict (`requirements_coverage` field) and is not a separate artifact.
+
+If any of the 5 required files are missing, OR any file fails to parse as valid JSON, OR any file is missing required schema fields (`chapter`, `verdict`, non-empty `evidence_files_read`), the Aggregator:
+
+1. Logs `LRR INCOMPLETE: missing [filename] / malformed [filename]` to `docs/plans/build-log.md`.
+2. Writes `docs/plans/evidence/lrr-aggregate.json` with `combined_verdict = INCOMPLETE` and the list of missing/malformed files.
+3. STOPS — does **NOT** proceed to the 6 aggregation rules.
+
+This is the partial-glob race fix — the explicit roster check makes the race impossible: the Aggregator fails loudly instead of silently under-counting.
+
+### Step 2: Apply the 6 aggregation rules
+
+Once all 5 chapter files are present and parseable, the Aggregator applies these rules:
+
+1. **ANY `override_blocks_launch: true`** → `combined_verdict = BLOCKED`, regardless of other verdicts. This is the veto-of-vetoes rule.
+2. **ALL verdicts `PASS` AND zero follow-ups spawned** → `combined_verdict = PRODUCTION READY`.
+3. **ANY verdict `BLOCK` with `override_blocks_launch: false`** → `combined_verdict = NEEDS WORK`, with that chapter's findings routed into the existing fix-and-retest loop.
+4. **ANY verdict `CONCERNS`** → `combined_verdict = NEEDS WORK`, concerns logged to `build-log.md` for later triage.
+5. **Follow-up spawned AND `follow_up.confirmed: true`** → treat the parent chapter's verdict as if it were `BLOCK` (since the follow-up confirmed the concern).
+6. **Contradictions between chapters on typed fields** → `combined_verdict = BLOCKED` with the specific finding `cross-chapter contradiction: {field} differs between {chapter_a} and {chapter_b}`.
+
+Rule 6 detects cross-chapter conflicts mechanically on typed fields only — no chapter reads another's draft, preserving fresh-context independence.
+
+### Step 3: BLOCK routing via `decisions.jsonl` `decided_by` lookup
+
+When the Aggregator determines `combined_verdict = BLOCKED` or `NEEDS WORK` via a BLOCK finding, it MUST NOT stop and wait. Instead:
+
+1. For each BLOCK finding in the aggregated output, read the `related_decision_id` field on the finding.
+2. Read `docs/plans/decisions.jsonl` and find the row with that `decision_id`.
+3. Read the `decided_by` field — this is the phase that authored the original decision (e.g., `architect` or `design-brand-guardian`). Cross-reference with the `phase` field on the row to disambiguate between phases that share a `decided_by` value.
+4. Route the finding BACKWARD to that phase as re-entry input. The build resumes at that phase with the BLOCK finding as a correction signal.
+
+If no `related_decision_id` is present on the finding (legacy finding, or a non-decision-backed issue such as a runtime crash or a fresh test failure), fall back to the legacy routing: classify by severity and route to Phase 4 (code-level) or Phase 2 (structural) per Step 4 below.
+
+This replaces "BLOCKED → return to failing step" with author-aware re-entry — a BLOCK on an auth model flaw routes to the Phase 2 architecture synthesizer who authored the decision, not the Phase 4 implementer.
+
+### Step 4: Classification for NEEDS WORK findings
+
+For any NEEDS WORK findings that did not carry a `related_decision_id` (and therefore fell through Step 3's `decided_by` lookup), the Aggregator applies the existing legacy classification:
+
+- **code-level** findings (test failure, runtime error, lint/type error, per-file bug) → route to Phase 4 target task.
+- **structural** findings (architectural mismatch, API contract violation, persistence model error, DNA drift at the component-library layer) → route to Phase 2 or Phase 3 per the finding's domain.
+- **CONCERNS** entries (no BLOCK) → logged to `build-log.md` for triage, do not block launch on their own.
+
+### Step 5: READY handoff
+
+If Step 2 resolves to `combined_verdict = PRODUCTION READY`, the Aggregator writes `docs/plans/evidence/lrr-aggregate.json` with the combined verdict, per-chapter summaries, and forwards to Phase 7 (Launch). No backward routing is triggered — the build moves forward.
+
+## File paths
+
+- Chapter verdicts: `docs/plans/evidence/lrr/{eng-quality,security,sre,a11y,brand-guardian}.json`
+- Aggregator output: `docs/plans/evidence/lrr-aggregate.json`
+
+## Token budget
+
+~12-17K tokens per LRR cycle, net of PM fold-in: five chapter dispatches at 2-3K each, plus the nested `pr-test-analyzer` sub-dispatch inside Eng-Quality at ~1.5-2K, plus one aggregator at 1-2K. The Aggregator runs exactly once per cycle.
+
+
+## Design Notes (non-operational)
+
+### Rationale: single-verdict failure mode
+
+The current Reality Checker collapses code quality, security, reliability, accessibility, and product completeness into a single verdict from a single agent — the exact failure mode matrix organizations exist to prevent. Independence matters most for Security and SRE: production incidents from those chapters are asymmetric in consequence — a security finding that goes unchallenged is a breach; a reliability finding is an outage. That asymmetry justifies the extra dispatch power and the pessimistic-block fallback.
+
+### Structural shifts from the prior 5-chapter panel
+
+- **Eng and QA merged into Eng-Quality.** More than half of their evidence overlapped (tests, verify outputs, task-level quality signals), and two nearly-identical verdicts produced two-thirds the signal of one coherent view.
+- **A11y is a new seat.** The WCAG gap was the biggest coverage hole in the prior panel — a mechanical contrast field on the old Design chapter is not a runtime accessibility check.
+- **Brand Guardian replaces the Design mechanical check.** The prior Design chapter was a 15-line threshold on a Phase 3 metric score — theater, not judgment.
+
+### Why each chapter cannot be folded
+
+- **Eng-Quality:** Merged from the previous Eng+QA chapters because >50% of their evidence overlapped, which produced two near-identical verdicts instead of one stronger one.
+- **Security:** Production breach risk is asymmetric, so an independent chapter runs fresh-context against security evidence with the power to veto launch outright.
+- **SRE:** Now explicitly reads Performance Benchmarker evidence (previously unclear which chapter owned perf NFRs), plus reliability checks and NFR thresholds from `sprint-tasks.md`.
+- **A11y:** The prior Design chapter had a mechanical contrast check and nothing runtime. A11y reads the Phase 5 runtime accessibility sweep and the Phase 3.7 design review, and gates on Critical/Serious finding counts.
+- **Brand Guardian:** Reads the locked DNA card + rendered screenshots + visual design spec + design references, and judges drift from the DNA. Taste judgment, not checklist theater.
+
+### Rule 6 — anchoring cost rationale
+
+A naive matrix-org design would have Security read Eng-Quality's draft to catch disagreements — that reintroduces the exact anchoring bias that fresh-context-per-chapter is designed to prevent (Madaan et al. Self-Refine; Gou et al. CRITIC). Instead, the aggregator does the cross-chapter check mechanically on typed fields only. Typed fields are mechanically diffable; free-form findings prose is not — and the prose is where the anchoring bias would come from.
+
+### Why under `evidence/`
+
+The existing evidence manifest sweep picks up anything under `docs/plans/evidence/` for free, and these files ARE evidence — typed attestations from independent chapters. Putting them elsewhere would create a second manifest path the aggregator has to know about separately.

package/protocols/metric-loop.md

@@ -19,6 +19,8 @@ Metric: [what you're measuring, in one sentence]
 How to measure: [what the measurement agent should do — run tests, audit code, check criteria, etc.]
 Target: [score 0-100 at which you stop]
 Max iterations: [hard cap, default 5]
+Scoring Criteria Checklist: [extracted in Step 0.5 — see .build-state.json]
+Extraction method: [mechanical | one-shot-dispatch | mixed]
 ```
 
 Then create a score log table:
@@ -36,11 +38,53 @@ Sub-step: [5.1 Implement | 5.1b Cleanup | 5.2 Metric Loop | 5.3 Loop Exit | 5.4
 ```
 This tells the orchestrator exactly where to resume after context compaction.
 
+## Step 0.5: Extract Scoring Criteria
+
+Before the first measurement, extract a **Scoring Criteria Checklist** from the stable reference docs. This checklist is the critic's scoring input for every iteration — it replaces raw doc injection.
+
+### Why
+
+Reference docs (DNA cards, design specs, architecture docs, acceptance criteria) do not change during the loop. Pre-injecting them into every critic prompt wastes ~20-30K tokens per iteration. The checklist extracts the exact scoring values once and passes ~1-2K tokens instead.
+
+### Extraction mechanism (per doc type)
+
+Use the cheapest mechanism that preserves fidelity:
+
+| Source doc type | Structure | Extraction mechanism | Cost |
+|-----------------|-----------|---------------------|------|
+| Structured (named fields with explicit values) — e.g., `DESIGN.md` YAML front matter (`colors`, `typography`, `components`) and `## Overview > ### Brand DNA` axes, `sprint-tasks.md` Behavioral Test field | YAML/markdown with named axes, fields, or sections | **Mechanical** — orchestrator parses and copies the values directly. No LLM reasoning. | ~0 tokens |
+| Semi-structured (values spread across prose sections) — e.g., `visual-design-spec.md`, Phase 5 audit findings | Long-form with explicit values in multiple sections | **One-shot extractor dispatch** — single agent call reads the full doc once and outputs the structured checklist. | ~20-25K one-time |
+| Unstructured (visual references, screenshots, mood boards) — e.g., `design-references.md` | Screenshot URLs, visual comps | **Not extracted.** Referenced by path in the checklist. Iteration 1 MAY read on-demand; iteration 2+ MUST NOT unless diagnosis explicitly flags a visual-reference gap. | 0 tokens |
+
+**Rule: if the source doc has named fields with explicit values, extraction is mechanical (no dispatch). If values are spread across prose sections, use a one-shot extractor dispatch. Never use orchestrator LLM reasoning for extraction — it burns the tokens you're trying to save.**
+
+### Persist the checklist
+
+Write the checklist to `.build-state.json` under `active_metric_loop.scoring_criteria_checklist`. Record the extraction method in `active_metric_loop.extraction_method` (one of: `mechanical`, `one-shot-dispatch`, `mixed`). The rendered `.build-state.md` view reflects it automatically.
+
+### Checklist format
+
+```
+Scoring Criteria Checklist
+Source docs: [list of source doc paths]
+Extracted at: [timestamp]
+Extraction method: [mechanical | one-shot-dispatch | mixed]
+
+[Structured criteria with exact values, organized by scoring dimension]
+
+Reference Anchors:
+- [path] (iteration 1 MAY read; iteration 2+ MUST NOT unless diagnosis flags gap)
+```
+
+The format is flexible — adapt it to the phase and artifact. The protocol gives a template, not a rigid schema. What matters: exact values, not summaries; organized by scoring dimension; reference anchors for unstructured docs.
+
 ## Step 1: MEASURE
 
 Call the Agent tool — description: "Measure [metric]" — prompt:
 
-"[How to measure, from your metric definition]. Score the current state 0-100. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
+"SCORING CRITERIA CHECKLIST: [paste the checklist from Step 0.5 — NOT the raw reference docs]. [How to measure, from your metric definition]. Score the current state 0-100 against the checklist criteria. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
+
+> **Pass the Scoring Criteria Checklist (from Step 0.5) to the measurement agent. Do NOT paste full reference docs into the prompt. The agent retains Read access for on-demand lookups if the checklist doesn't cover a specific detail, but the prompt must not pre-inject stable docs.**
 
 Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file paths for diagnosis in Step 3. Record the score to `docs/plans/.build-state.md`. The full findings list is useful for diagnosis but does NOT need to persist in your context across iterations — once you've picked the top issue, the details of lower-priority findings can go. Append a row to the score log in `docs/plans/.build-state.md`:
 
@@ -52,12 +96,19 @@ Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file path
 Stop the loop if ANY of these:
 
 - **Score >= target** → done. Log "Target met at iteration [N]."
+- **Iter-1 short-circuit: score >= target + 10 on the first measurement** → done. Log "Short-circuit at iteration 1. Score: [N]." and record `exit_reason: "short_circuit_iter1"` in the loop state.
 - **Iteration >= max** → done. Log "Max iterations reached. Final score: [N]."
 - **Stall: last 2 scores show no improvement** (delta <= 0 twice in a row) → done. Log "Stalled at score [N]."
 
+### Early exit — iter-1 short-circuit
+If the first measurement (iter-1) scores >= `target + 10`, exit the loop immediately and commit the iter-1 output. Log `exit_reason: "short_circuit_iter1"` in the loop state. The 10-point margin guards against measurement noise at the boundary; a genuinely excellent first pass does not need rework.
+
 On stall or max iterations:
 - **Interactive mode:** present score history + top remaining issue to user. Ask for direction.
-- **Autonomous mode:** if score >= 60% of target, accept with warning. Otherwise skip. Log to `docs/plans/build-log.md`.
+- **Autonomous mode:**
+  - If score >= target: done (this branch is already handled in Step 2's exit conditions; included here for completeness).
+  - If score >= 60% of target AND no CRITICAL issues remain in the measurement: accept with WARNING. Log to `docs/plans/build-log.md` with the warning text and the score history. The orchestrator may proceed to the next phase, but the warning MUST be surfaced in the Phase 7 Completion Report's "Verification Gap" section.
+  - If score < 60% of target OR any CRITICAL issue remains: HALT. Do NOT skip. Log "METRIC LOOP: BLOCKED" to `docs/plans/.build-state.md` with the score history and the unresolved issues. Either (a) re-dispatch the fix agent with the unresolved issues, OR (b) abort the build with a directive to the user. The orchestrator may NOT silently proceed past a metric loop that did not converge.
 
 If not exiting, continue to Step 3.
 
@@ -73,6 +124,11 @@ Call the Agent tool — description: "Fix [top issue]" — mode: "bypassPermissi
 
 > **Do NOT pass the measurement agent's full findings to this agent. Only pass the single diagnosed issue and relevant file paths.**
 
+### Iteration-aware context rule
+
+- **Iteration 1 generator** receives the full phase context header + task description (the generator needs full context for its first pass).
+- **Iteration 2+ generator** receives ONLY: (a) the single top issue from diagnosis, (b) the relevant file paths, (c) the specific criteria values from the Scoring Criteria Checklist that relate to the top issue. The full `[CONTEXT header above]` preamble is NOT re-injected. The generator already has the codebase from iteration 1 — it only needs the delta.
+
 ## Step 5: LOOP
 
 Return to Step 1. Re-measure the artifact after the fix.
@@ -91,3 +147,7 @@ AUTHOR-BIAS ELIMINATION: The measurement agent and the fix agent must NEVER shar
 - Track ALL scores in `docs/plans/.build-state.md` so the history survives context compaction.
 - If context was compacted mid-loop: read `docs/plans/.build-state.md`, find the Active Metric Loop section, resume from the last recorded iteration.
 - CONTEXT HYGIENE: Measurement agents are analysis agents — read their full output for diagnosis. But once you've picked the top issue (Step 3) and dispatched the fix (Step 4), the detailed findings from THAT iteration are spent. Don't accumulate findings across iterations — each measurement is fresh.
+<STABLE-CONTEXT-RULE>
+STABLE CONTEXT RULE: Reference docs that do not change during the loop (design specs, DNA cards, architecture docs, acceptance criteria) MUST be extracted into the Scoring Criteria Checklist at Step 0.5 and passed as the checklist — never re-injected as raw content into iteration 2+ prompts. Fresh artifacts (screenshots, test results, rendered output) are fetched each iteration. This is the primary token-saving mechanism: ~1-2K checklist vs ~20-30K raw docs per iteration.
+</STABLE-CONTEXT-RULE>
+- CHECKLIST FALLBACK: If no Scoring Criteria Checklist is provided (Step 0.5 was skipped or caller did not pass one), the critic falls back to raw doc reads. The orchestrator MUST log a WARN to `docs/plans/build-log.md`: "Metric loop iteration [N]: no scoring criteria checklist provided, falling back to raw doc reads." Callers SHOULD always provide a checklist. New callers that omit it will trigger the WARN, making silent regressions visible.

package/protocols/page-spec-schema.md

@@ -0,0 +1,234 @@
+# Page Spec Schema
+
+## Purpose
+
+Step 3.3's UX architect (`design-ux-architect`) produces page specs alongside `ux-architecture.md` — flows and layouts are created together because they inform each other. One file per screen is emitted to `docs/plans/page-specs/{screen-name}.md`. Each file is the spatial blueprint for a single screen — ASCII wireframe + structured metadata — so Phase 4 implementers know exactly what to build without interpreting prose. This protocol defines the required sections, wireframe format, platform conventions, and validation rules.
+
+## Inputs
+
+The page spec writer reads these artifacts before producing any page spec:
+
+- `docs/plans/product-spec.md` — feature states, data requirements, persona constraints, screen inventory (SOURCE OF TRUTH for what each screen does)
+- `docs/plans/architecture.md` — frontend component hierarchy, routing, API contracts
+- `DESIGN.md` `## Overview > ### Brand DNA` — 7-axis DNA card (Density axis drives layout decisions)
+- `docs/plans/component-manifest.md` — library component picks per slot
+- `docs/plans/design-references/` — competitor/inspiration screenshots for layout reference
+
+NOTE: `visual-design-spec.md` does NOT exist yet when page specs are produced (it's created at Step 3.4, after Step 3.3). Page specs use the DNA Density axis for spatial decisions (Airy vs Dense) and the component manifest for component choices. Exact spacing values and typography ramp are applied by Phase 4 implementers when they build from the visual design spec.
+
+## Questions Answered
+
+Page specs close three questions from the Phase 0-3 question map:
+
+- **Q50** — Screen layouts (spatial arrangement of every element)
+- **Q51** — Content hierarchy (what's primary, secondary, tertiary per screen)
+- **Q53** — Key copy per screen (headings, CTAs, empty states, errors)
+
+## File Convention
+
+- Path: `docs/plans/page-specs/{screen-name}.md` (kebab-case)
+- Anchors: `page-specs/{screen-name}#wireframe`, `page-specs/{screen-name}#content-hierarchy`, `page-specs/{screen-name}#key-copy`, etc.
+- One file per screen in the product-spec Screen Inventory. Multi-step flows (e.g., checkout) get one file per step.
+
+## Required Sections
+
+Every page spec MUST contain these sections, in this order.
+
+### 1. Screen Overview
+
+One line: what this screen is, which feature(s) it serves.
+
+### 2. ASCII Wireframe
+
+Spatial layout using box-drawing characters. Desktop wireframe required for all platforms. Mobile wireframe required for web projects. Section labels inside brackets map to Content Hierarchy entries.
+
+### 3. Content Hierarchy
+
+Ordered list (top → bottom, primary → tertiary) of every content section. Each entry: section name, data shown, component from manifest (or `custom`), data source (API endpoint or `local`/`computed`), visual weight (`primary`/`secondary`/`tertiary`).
+
+### 4. Key Copy
+
+Headings, CTAs, labels, empty state messages, error messages for this screen. Not every string — the ones that set the tone and guide implementation.
+
+### 5. Responsive Behavior (web only)
+
+What changes at each breakpoint: desktop (1024px+), tablet (768px), mobile (375px). What reflows, collapses, or hides.
+
+### 6. Platform Conventions
+
+Which platform patterns this screen follows. iOS: navigation stack, tab bar, sheets. Web: sidebar state, breadcrumbs, header nav. Reference the relevant HIG pattern or web convention.
+
+### 7. Data Loading
+
+What's fetched on mount, loading skeleton description, refresh strategy (pull-to-refresh, auto-refresh, manual).
+
+### 8. States
+
+Reference to product-spec feature states, plus screen-specific visual states: skeleton loading, partial data, stale indicator, empty, error.
+
+## ASCII Wireframe Format
+
+**Characters:** `┌ ┐ └ ┘ ─ │ ├ ┤ ┬ ┴ ┼`
+
+**Rules:**
+- Label every section inside brackets: `[Header]`, `[Sidebar]`, `[KPI Cards]`
+- Show relative sizing — sidebar narrower than main content
+- Desktop wireframe: ~60 chars wide
+- Mobile wireframe: ~30 chars wide
+- Include placeholder text for key copy: `[Place Order]`, `[Your cart is empty...]`
+- Density axis from visual-dna.md drives spacing: Airy = generous gaps between sections, fewer items visible. Dense = compact rows, more items per viewport.
+
+## Platform-Specific Wireframe Conventions
+
+**Web SaaS:** Sidebar + main content area. Header with nav. Sidebar collapses to hamburger on mobile.
+
+**iOS:** Navigation bar at top (title, back button if applicable), content area, tab bar at bottom. Standard HIG layout patterns. See iOS-specific conventions section below for full requirements.
+
+**Dashboard/Analytics:** Filter bar, card grid, chart placement. Dense layout with data tables.
+
+**CLI:** No wireframe. Show command output format with example terminal session instead.
+
+**Mobile (React Native/Expo):** Follow target platform conventions — iOS patterns if iOS, Material if Android, cross-platform neutral if both.
+
+### iOS-specific wireframe conventions
+
+When `project_type=ios`, page-specs follow these conventions:
+
+- **Single viewport:** iPhone 16 Pro (393×852 logical) as the primary; iPad layout deltas captured as a Notes section. No second mobile/desktop view.
+- **Navigation annotation:** name the parent NavigationStack / TabView / sheet and the back/dismiss gesture per screen.
+- **Component refs:** every interactive element references a DESIGN.md `components:` token name (e.g., `button-primary`, `list-row-grouped`, `card-elevated`) — these are SwiftUI view modifiers at Phase 4.
+- **Dynamic Type:** declare which typography role tokens the screen uses; flag any layout that breaks at xxxLarge.
+- **Safe-area handling:** name top/bottom safe-area treatments (large title vs nav bar; tab bar inset).
+- **Data loading strategy:** async/await + `.task` modifier vs `ObservableObject` reference; loading/error/empty states sourced from product-spec.md per-feature sections.
+
+## Validation Checklist
+
+1. Every screen in product-spec.md Screen Inventory has a page spec file
+2. Every page spec has all 8 required sections (skip Responsive Behavior for non-web)
+3. Every content hierarchy entry references a component from `component-manifest.md` or marks it `custom`
+4. Every data source references an API endpoint from `architecture.md#backend/api` or marks it `local`/`computed`
+5. ASCII wireframe exists for desktop (and mobile for web projects)
+6. Section labels in wireframe match content hierarchy entry names
+7. Key copy includes at least: one heading, one primary CTA, one empty state message
+
+## Worked Example: Dashboard (Web SaaS)
+
+```markdown
+# Page Spec: Dashboard
+
+## Screen Overview
+
+Main dashboard — KPI summary, recent activity, and quick actions. Features: Dashboard, Notifications.
+
+## ASCII Wireframe
+
+### Desktop (1024px+)
+
+┌──────────────────────────────────────────────────────────┐
+│ [Header]                          [Search] [Avatar ▼]    │
+├────────────┬─────────────────────────────────────────────┤
+│ [Sidebar]  │ [Page Title: Dashboard]                     │
+│            │                                             │
+│  Dashboard │ ┌─────────┐ ┌─────────┐ ┌─────────┐        │
+│  Orders    │ │[KPI:    ]│ │[KPI:    ]│ │[KPI:    ]│       │
+│  Products  │ │ Revenue  │ │ Orders   │ │ Users    │       │
+│  Customers │ │ $12,340  │ │ 142      │ │ 1,203    │       │
+│  Settings  │ └─────────┘ └─────────┘ └─────────┘        │
+│            │                                             │
+│            │ ┌──────────────────────────────────────┐    │
+│            │ │[Revenue Chart]                       │    │
+│            │ │                                      │    │
+│            │ │  ▁▂▃▅▆▇█▇▆▅▃▂▁▂▃▅▆▇                │    │
+│            │ │                                      │    │
+│            │ └──────────────────────────────────────┘    │
+│            │                                             │
+│            │ ┌──────────────────────────────────────┐    │
+│            │ │[Activity Feed]                       │    │
+│            │ │ • New order #1042 — 2m ago           │    │
+│            │ │ • User signed up — 15m ago           │    │
+│            │ │ • Payment received — 1h ago          │    │
+│            │ └──────────────────────────────────────┘    │
+├────────────┴─────────────────────────────────────────────┤
+│ [Footer]                                                 │
+└──────────────────────────────────────────────────────────┘
+
+### Mobile (375px)
+
+┌────────────────────────────┐
+│ [Header]  [☰]   [Avatar]  │
+├────────────────────────────┤
+│ [Page Title: Dashboard]    │
+│                            │
+│ ┌────────────────────────┐ │
+│ │[KPI: Revenue]  $12,340 │ │
+│ └────────────────────────┘ │
+│ ┌────────────────────────┐ │
+│ │[KPI: Orders]   142     │ │
+│ └────────────────────────┘ │
+│ ┌────────────────────────┐ │
+│ │[KPI: Users]    1,203   │ │
+│ └────────────────────────┘ │
+│                            │
+│ ┌────────────────────────┐ │
+│ │[Revenue Chart]         │ │
+│ │ ▁▂▃▅▆▇█▇▆▅▃▂▁▂▃▅▆▇   │ │
+│ └────────────────────────┘ │
+│                            │
+│ ┌────────────────────────┐ │
+│ │[Activity Feed]         │ │
+│ │ • New order — 2m ago   │ │
+│ │ • Signup — 15m ago     │ │
+│ │ • Payment — 1h ago     │ │
+│ └────────────────────────┘ │
+└────────────────────────────┘
+
+## Content Hierarchy
+
+| # | Section | Data Shown | Component | Data Source | Weight |
+|---|---------|-----------|-----------|-------------|--------|
+| 1 | KPI Cards | Revenue, order count, active users (current period + delta) | `StatCard` from manifest | `GET /api/dashboard/kpis` | primary |
+| 2 | Revenue Chart | 30-day revenue trend line | `AreaChart` from manifest | `GET /api/dashboard/revenue?range=30d` | primary |
+| 3 | Activity Feed | Last 10 events (orders, signups, payments) with relative timestamps | `FeedList` from manifest | `GET /api/dashboard/activity?limit=10` | secondary |
+| 4 | Header | App logo, search, user avatar dropdown | `AppHeader` from manifest | `local` (user session) | tertiary |
+| 5 | Sidebar | Navigation links with active state, unread badge on notifications | `SideNav` from manifest | `local` (route) + `GET /api/notifications/count` | tertiary |
+
+## Key Copy
+
+- **Page heading:** "Dashboard"
+- **KPI labels:** "Revenue" · "Orders" · "Active Users"
+- **KPI delta format:** "+12% vs last period" / "−3% vs last period"
+- **Activity feed heading:** "Recent Activity"
+- **Empty activity state:** "No activity yet. Once your first order comes in, you'll see it here."
+- **Error state:** "Couldn't load dashboard data. Check your connection and try again." CTA: [Retry]
+- **Stale indicator:** "Last updated 5 minutes ago" (appears after 60s without refresh)
+
+## Responsive Behavior
+
+| Breakpoint | Changes |
+|-----------|---------|
+| Desktop (1024px+) | Sidebar visible. KPI cards in 3-column row. Chart full width of main area. |
+| Tablet (768px) | Sidebar collapses to icon-only rail. KPI cards in 3-column row (narrower). Chart full width. |
+| Mobile (375px) | Sidebar hidden behind hamburger menu. KPI cards stack vertically (full width each). Chart full width. Activity feed below chart. |
+
+## Platform Conventions
+
+- **Web SaaS pattern:** Persistent sidebar navigation with active-state highlight on current page. Header with global search and user menu. Breadcrumbs not needed (top-level screen).
+- **Sidebar:** Collapsible — user preference persisted in local storage. Icon-only mode at tablet breakpoint.
+- **Data refresh:** No pull-to-refresh (web). Auto-refresh every 60s via polling. Manual refresh button in header.
+
+## Data Loading
+
+- **On mount:** Parallel fetch `GET /api/dashboard/kpis`, `GET /api/dashboard/revenue?range=30d`, `GET /api/dashboard/activity?limit=10`
+- **Loading skeleton:** 3 shimmer rectangles for KPI cards (same dimensions as loaded cards). Chart area shows shimmer block. Activity feed shows 3 shimmer rows with avatar circle + text lines.
+- **Refresh:** Auto-poll every 60s. Stale indicator appears if last successful fetch > 60s ago. No full-page reload — data swaps in place.
+
+## States
+
+- **From product-spec:** `initial`, `loading`, `loaded`, `empty`, `error`, `stale`
+- **Screen-specific visuals:**
+  - `skeleton-loading` — shimmer cards + shimmer chart + shimmer feed rows (see Data Loading)
+  - `partial-data` — KPIs loaded but chart still loading: show KPI cards, chart area shows shimmer
+  - `stale` — data older than 60s: subtle "Last updated X ago" badge below page title
+  - `empty` — new account, no data yet: KPI cards show "—", chart shows flat line, activity feed shows empty state copy
+  - `error` — fetch failed: inline error banner with retry button, no full-page error
+```