forgedock 1.0.17 → 1.0.19

package/docs/design/abc-benchmark.md

@@ -0,0 +1,195 @@
+# The ABC Benchmark — Methodology
+
+> **Status:** Foundation spec for issue #878 (milestone #13, UI Taste Harness).
+> The benchmark is the milestone's **fitness function** — built *before* the harness. It is what tells us
+> whether each lever the harness adds actually moves design quality. Harness development reduces to one
+> question this rig answers: *"did arm A's score against C go up?"*
+>
+> Companion to [design-spec-schema](design-spec-schema.md) (#881), [reference-corpus](reference-corpus.md) (#880),
+> and the [`/design-bench`](../../commands/design-bench.md) command spec.
+> Results are carried as a `FORGE:BENCH_SCORECARD` annotation — registered in
+> [`../FORGE-PROTOCOL.md`](../FORGE-PROTOCOL.md).
+
+## Why this exists first
+
+A taste benchmark is not a test we run at the end. It is the reward signal. Without it, every "improvement" to
+the harness is a guess. With it, each lever (archetype sampling, anti-slop negatives, the critique loop) is a
+measurable hypothesis: add the lever, re-run the benchmark, confirm arm A's win-rate against C went up. Build the
+ruler before building the thing it measures.
+
+## The three arms — same input, one variable
+
+The **input is a single design-blind product brief** derived from a real reference page. It describes only what the
+product *does* — no "make it like X", no colors, no type, no layout hints. The real product name is **anonymized**
+so the generation model cannot recall the real brand's design from training. (Brand recall would measure memory,
+not taste, and would unfairly inflate arm B — see [Anonymization](#anonymization-is-load-bearing).)
+
+| Arm | What it is | Role |
+|-----|------------|------|
+| **A** | **ForgeDock harness** — the brief run through the `/design` pipeline (#888). | The thing under test. |
+| **B** | **Raw frontier model**, one shot, no tools, no iteration, given the same brief. | Control / lower bound. |
+| **C** | **The real reference page** the brief was stripped from. | Gold standard + judge calibration. |
+
+**The one variable rule.** Arms A and B MUST use the **same generation model**. The harness (its pipeline,
+structured design language, render→critique loop) is then the *only* difference between A and B — which is exactly
+what makes the A-vs-B delta attributable to the harness. If A and B use different models, you are benchmarking
+models, not the harness. This is non-negotiable.
+
+## C does double duty
+
+C is both the gold standard and a **free validity check on the judge**:
+
+- As gold standard, win-rate against C is the primary metric for A and B.
+- As calibration, if the judge ever ranks C **below** A or B in the blind pairwise comparison, the judge is
+  miscalibrated — its result for that run is suspect and flagged in the scorecard. A real, professionally designed,
+  funded-SaaS page losing to a one-shot generation is a judge defect, not a harness triumph.
+
+## Rendering — kill the confounds
+
+All three arms are rendered through the **identical** pipeline so the only thing the judge compares is design, not
+rendering artifacts.
+
+- **Self-contained HTML** for arms A and B (Tailwind CDN is fine; no build step).
+- **Playwright** (milestone render dependency) renders all three at:
+  - **1440px** desktop and **390px** mobile,
+  - `networkidle` + fonts loaded before capture,
+  - **full-page** screenshot.
+- **C is captured through the same pipeline.** Trim cookie banners and hero video so C is compared on its design,
+  not on a consent modal. Document any trim applied to C in the run record for reproducibility.
+
+## Judging — three layers
+
+The judge is a **named, independent stage**. See [Anti-Goodhart](#anti-goodhart-judge-independence) — it MUST NOT
+be the harness's own critique loop (#882).
+
+### Layer 1 — Blind randomized pairwise (primary metric)
+
+The judge sees **two anonymized screenshots in shuffled order** and answers one question:
+
+> *"Which reads more like a professionally designed, well-funded SaaS landing page?"*
+
+Run all three pairings: **A-vs-C**, **B-vs-C**, **A-vs-B**. Screenshots carry no arm labels; left/right order is
+randomized per comparison. **Metric = win-rate against C.** The harness improves when A's win-rate against C rises
+(and ideally approaches or exceeds B's gap to C closing).
+
+### Layer 2 — Rubric (1–5 per dimension)
+
+A per-arm absolute score across six dimensions:
+
+| Dimension | Looks for |
+|-----------|-----------|
+| Hierarchy | clear primary action, deliberate reading order |
+| Typography | confident scale, non-default families, tight headline tracking |
+| Color discipline | restrained palette, one accent, no "AI gradient" tell |
+| Whitespace rhythm | composed negative space, not uniform padding |
+| Originality vs slop | a committed direction, not the hero→3-cards→testimonial→CTA mean |
+| Mobile | the 390px capture holds up, not a squished desktop |
+
+### Layer 3 — Slop detector (binary checklist)
+
+A nearly objective pass/fail checklist over the **negatives** corpus (#880): default Inter at default weights,
+slate/indigo gradient, rounded-everything, boilerplate section skeleton, stock 3D blobs, etc. Each negative is a
+yes/no. The slop score is the count of negatives present (lower is better).
+
+## Two non-negotiable methodology rules
+
+### n=1 is a lie
+
+Taste output is high-variance. A single generation per arm tells you almost nothing. **Run 3–5 generations per arm
+across 3–5 products** and report **distributions** — win-rate over runs, and the mean and spread of rubric scores.
+The scorecard aggregator (`scripts/bench-scorecard.mjs`) **rejects runs with n<3** to enforce this.
+
+### Anti-Goodhart — judge independence
+
+The benchmark judge **MUST be independent from the harness's own critique loop (#882)**. If the harness optimizes
+against the same judge that scores the benchmark, you are training to the test — the number goes up while real
+quality does not. Concretely: the benchmark judge uses its own prompt and is invoked as a distinct stage; it does
+**not** import, share state with, or reuse the #882 critique judge. This independence is asserted in both this doc
+and the [`/design-bench`](../../commands/design-bench.md) command spec.
+
+## Anonymization is load-bearing
+
+Each brief is derived from a real reference (arm C) but uses an **anonymized product name** and strips every visual
+cue. The mapping from anonymized brief → real reference lives in
+[`fixtures/briefs/README.md`](fixtures/briefs/README.md) (kept separate from the briefs so the generator never sees
+it). A real brand name in a brief lets the model reproduce that brand's actual page from training — measuring recall,
+not taste, and inflating arm B. Treat any real-brand leak in a brief as a fixture bug.
+
+## Seed inputs (fixtures)
+
+Briefs are **fixed and hand-written**, kept as reproducible fixtures under
+[`fixtures/briefs/`](fixtures/briefs/): **Cadence**, **Tender**, **Slipstream**, **Voltage**, **Plume**. Fixed
+inputs are what make the benchmark reproducible across runs and over time — the same five briefs are re-run as the
+harness evolves, so score movement is attributable to the harness, not to changing inputs.
+
+## Scorecard schema
+
+The aggregator consumes a **runs file** (the raw per-run judge output) and emits a **scorecard**.
+
+### Input — runs file (`runs.json`)
+
+```jsonc
+{
+  "corpus_version": "2026.2",       // grammar snapshot the briefs were designed against
+  "generation_model": "…",          // the SAME model used for arms A and B
+  "judge_model": "…",               // the INDEPENDENT benchmark judge (not #882)
+  "products": [
+    {
+      "product": "Voltage",          // anonymized brief name
+      "reference": "modal.com",      // real arm-C reference (internal record only)
+      "runs": [
+        {
+          "run": 1,
+          "pairwise": {              // winner of each blind pairwise comparison
+            "A_vs_C": "C",           // "A" | "B" | "C" | "tie"
+            "B_vs_C": "C",
+            "A_vs_B": "A"
+          },
+          "rubric": {                // 1–5 per arm per dimension
+            "A": { "hierarchy": 4, "typography": 3, "color": 4, "whitespace": 4, "originality": 3, "mobile": 4 },
+            "B": { "hierarchy": 3, "typography": 2, "color": 2, "whitespace": 3, "originality": 2, "mobile": 3 },
+            "C": { "hierarchy": 5, "typography": 5, "color": 5, "whitespace": 5, "originality": 5, "mobile": 5 }
+          },
+          "slop": {                  // count of negatives present (lower is better)
+            "A": 1, "B": 4, "C": 0
+          }
+        }
+        // … runs 2..n (n >= 3)
+      ]
+    }
+    // … 3–5 products
+  ]
+}
+```
+
+### Output — scorecard
+
+```jsonc
+{
+  "n_products": 5,
+  "n_runs_per_product": 4,
+  "win_rate_vs_C": {                 // primary metric — fraction of runs the arm beat C
+    "A": { "mean": 0.15, "by_product": { "Voltage": 0.25, "…": 0.10 } },
+    "B": { "mean": 0.05, "by_product": { "…": 0.00 } }
+  },
+  "a_vs_b_win_rate": 0.70,           // fraction of runs A beat B (the harness delta)
+  "rubric": {                        // mean + spread per arm per dimension across all runs
+    "A": { "hierarchy": { "mean": 3.8, "stdev": 0.6 }, "…": {} },
+    "B": { "…": {} },
+    "C": { "…": {} }
+  },
+  "slop": {                          // mean negatives present per arm (lower better)
+    "A": 1.2, "B": 3.9, "C": 0.1
+  },
+  "judge_calibration": {             // C must win A-vs-C and B-vs-C; flag if not
+    "miscalibrated_runs": [],        // runs where C lost to A or B
+    "ok": true
+  }
+}
+```
+
+## Running the benchmark
+
+The full reproducible workflow — reference URL → brief → render arms → judge → scorecard — is driven by the
+[`/design-bench`](../../commands/design-bench.md) command. The deterministic aggregation step is
+`node scripts/bench-scorecard.mjs runs.json`.

package/docs/design/design-architect-rationale.md

@@ -0,0 +1,123 @@
+# Design-Architect Phase & FORGE:DESIGN_RATIONALE — the designer's diary
+
+> **Status:** Committed foundation — design-architect phase spec for issue #886 (milestone #13).
+> The reasoning-before-generation phase. Produces the [DESIGN_SPEC](design-spec-schema.md) (#881);
+> queries [design-memory](design-memory.md) (#887); read by generate + the critique loop (#882).
+> Extended: motion tier selection added as diary step 5 (#1043); product mock decision added as diary step 6 (#1045); scroll narrative planning added as diary step 7.5 (#1046).
+
+## Why this exists
+
+Everything else in the harness (spec, effects, critique loop) can still **raw-dog** the output: jump straight to a
+page and defend it afterward. A page produced without deliberation is a guess. What separates craft from a guess is
+**thinking before generating** — and capturing that thinking so it's reviewable.
+
+ForgeDock already does this for code: `investigate → architect → implement → validate`, where the *architect* phase
+reasons about *how* before any code is written, and writes a FORGE annotation the next stage reads. **A design harness
+without a design-architect phase is just vibes.** So this is not a new paradigm — it is the ForgeDock pattern applied
+to design:
+
+```
+design-investigate (what's the message?) → design-architect (diary + rationale → spec) → generate → critique-loop
+```
+
+The architect phase's output is a `FORGE:DESIGN_RATIONALE` annotation — the diary — which *produces* the
+[DESIGN_SPEC](design-spec-schema.md) instead of the spec appearing from nowhere.
+
+## The diary — structured chain of thought
+
+The phase must reason through all ten, in order. This is what a designer's diary actually contains.
+
+1. **Intent & emotional register** — One core message. One feeling to evoke (trust / speed / power / craft / play).
+   What should the visitor feel, and what should they do?
+2. **Audience & objection** — Who lands here? What do they already believe? What is the single objection this page
+   must overcome?
+3. **Communication hierarchy** — What gets said 1st, 2nd, 3rd. This *is* the visual hierarchy — it is derived from
+   meaning, not chosen as decoration. (Feeds `layout_grammar.sections` in the spec.)
+4. **Direction & why** — The chosen archetype/concept *and the reasoning for it* — why it serves this message for this
+   audience. **Plus the alternatives considered and explicitly rejected, and why.** (Rejection is where taste shows.)
+5. **Motion tier & hero technique** — Which motion tier (1–3) from the [corpus hero motion vocabulary](reference-corpus.md#hero-motion-vocabulary--making-the-hero-feel-alive)
+   is appropriate for this archetype and product nature? Which specific technique? Commit to both. The default per-archetype
+   motion profile in the corpus is the starting point; deviation requires explicit reasoning. Every page requires a
+   committed motion posture — "no motion" for `bold-brutalist` or `minimal-luxury` is a valid deliberate choice, but
+   it must be stated, not omitted.
+   - Feeds `motion.tier` and `motion.hero_technique` in the [DESIGN_SPEC](design-spec-schema.md).
+   - If a video placeholder is appropriate (Tier 3): set `motion.video_placeholder: true` — the generator scaffolds
+     the HTML and CSS gradient poster.
+   - State the `prefers-reduced-motion` fallback explicitly (e.g., "gradient-shift pauses; text remains visible").
+6. **Product mock decision** — Does this brief imply a product interface that can be shown live in the hero? <!-- Added: forge#1045 -->
+   Consult the [interactive product mock vocabulary](reference-corpus.md#interactive-product-mock-vocabulary) to
+   identify the matching product type.
+   - **Decision signals**: does the brief describe a dashboard, issue board, payment flow, deploy pipeline, code
+     API, or inbox? → commit a product mock. Does the product have no single canonical interface, is it image-driven
+     (e.g. physical device, marketplace), or is the archetype `minimal-luxury` and restraint is the move? → commit
+     `product_mock.type: "none"` with explicit reasoning.
+   - If committing a mock: select exactly 2 interactions from the per-type defaults table in the corpus. State
+     whether they are CSS-only or require lightweight JS. State the `prefers-reduced-motion` fallback.
+   - Feeds `product_mock.type`, `product_mock.interactions`, and `product_mock.css_only` in the
+     [DESIGN_SPEC](design-spec-schema.md).
+   - Restraint rule: 2 interactions only. The mock should feel alive, not be a demo. Never animate primary copy.
+7. **The signature move** — The one memorable, non-obvious idea that makes it *this* page and not a template. The "hook."
+7.5. **Scroll narrative planning** — Commit the full-page below-fold narrative before generation. <!-- Added: forge#1046 -->
+   Consult the [below-the-fold narrative vocabulary](reference-corpus.md#below-the-fold-narrative-vocabulary--scroll-driven-full-page-structure)
+   and the per-archetype scroll narrative defaults table.
+   - **Section sequence**: list the committed section order (e.g. `problem-context → solution-showcase → social-proof → deep-features → final-cta`). Deviate from the archetype default with explicit reasoning. Minimum 4 below-fold sections (5 total including hero); `minimal-luxury` archetype may use 3 below-fold sections with explicit restraint rationale.
+   - **Sticky nav decision**: commit `sticky_nav: true` or `false`. True is the default for all archetypes when total sections ≥ 5. False requires explicit rationale. For `minimal-luxury`: omit backdrop-filter blur (glassmorphism contradiction) and use fully-opaque background instead.
+   - **Social proof type**: commit one of `logos | metrics | testimonials | none`. Consult the archetype social proof defaults. `none` requires explicit rationale (e.g., pre-launch product with no social proof yet — acceptable).
+   - **CTA rhythm**: commit ≥ 2 CTA placements — one in hero, one in final-cta. Note any additional mid-page CTA placement and its rationale.
+   - Feeds `scroll_narrative.section_sequence`, `scroll_narrative.sticky_nav`, `scroll_narrative.social_proof_section`, and `scroll_narrative.cta_placements_min` in the [DESIGN_SPEC](design-spec-schema.md).
+8. **What I'm trying this time** — A technique or learning being deliberately applied. Queries
+   [design-memory](design-memory.md) so it builds on, and diverges from, prior work.
+9. **Non-goals** — What this page deliberately will *not* do. Restraint stated as a decision, not an omission.
+
+## FORGE:DESIGN_RATIONALE — annotation format
+
+Posted to the design issue at the architect stage (see the `/design` pipeline, #888):
+
+```markdown
+<!-- FORGE:DESIGN_RATIONALE -->
+## Design Rationale — {product}
+
+**Intent / feeling:** {one message} · {one feeling}
+**Audience / objection:** {who} — must overcome: {objection}
+**Communication hierarchy:** 1) {…} 2) {…} 3) {…}
+**Direction:** {archetype} — because {reasoning}
+  - Considered & rejected: {alt A} (because {…}); {alt B} (because {…})
+**Motion:** Tier {1|2|3} — technique: {hero_technique} — because {reasoning}
+  - `prefers-reduced-motion` fallback: {what degrades gracefully}
+  - Video placeholder: {yes — Tier 3 scaffold generated | no}
+**Product mock:** {type id | none} — because {reasoning}
+  - Interactions: {interaction-id-1}, {interaction-id-2} (or "n/a — type: none")
+  - CSS-only: {yes | no — lightweight JS for {reason}}
+  - `prefers-reduced-motion` fallback: {what degrades gracefully, or "n/a"}
+**Scroll narrative:** {section sequence} — sticky nav: {yes|no} — social proof: {logos|metrics|testimonials|none}
+  - CTA placements: {count} ({hero + final-cta} or note any additional mid-page CTA)
+  - Deviation from archetype default: {reasoning, or "none — follows archetype default"}
+**Signature move:** {the one non-obvious idea}
+**Trying this time:** {technique/learning} (from memory: avoiding {prior move})
+**Non-goals:** {what this won't do}
+
+→ Produces DESIGN_SPEC: {link}
+```
+
+## Why it matters for a non-designer
+
+The rationale is **reviewable without judging pixels.** A non-designer can read the *thinking* and catch when the
+reasoning is thin or generic — "this hook is the same as every other page," "the direction has no justification" —
+**before a single pixel renders.** The harness externalizes the designer's thought process the user may not have.
+This is the review checkpoint that makes the whole pipeline trustworthy.
+
+## Acceptance
+
+- Every generated page is preceded by a DESIGN_RATIONALE covering all 10 elements, with ≥1 explicitly rejected
+  alternative, a committed motion tier + technique, a product mock decision, a scroll narrative plan, and a named signature move.
+- The `**Motion:**` line must be present in every rationale — "no motion" is acceptable only for `bold-brutalist`
+  and `minimal-luxury` archetypes, and must be stated with reasoning, not left absent.
+- The `**Product mock:**` line must be present in every rationale — `type: none` is acceptable when the product
+  has no single canonical interface or when archetype restraint is the deliberate choice, but must be stated with
+  reasoning, not left absent.
+- The `**Scroll narrative:**` line must be present in every rationale — a committed section sequence, sticky nav
+  decision, social proof type, and CTA count are all required. `social_proof_section: none` is acceptable for
+  pre-launch products with no social proof, but must be stated with reasoning, not left absent.
+- On the seed set, rationales for Voltage / Plume / Slipstream show genuinely different intent, hierarchy,
+  motion techniques, product mock decisions, scroll narrative sequences, and signature moves — derived from the
+  briefs alone (no design hints in the brief).

package/docs/design/design-memory.md

@@ -0,0 +1,61 @@
+# Design Memory & Deliberate Divergence
+
+> **Status:** DRAFT for review — foundation spec for issue #887 (milestone #13).
+> Queried by the [design-architect phase](design-architect-rationale.md) (#886) for the "different from my previous
+> work / what new thing am I applying" questions. Enforced by the critique loop (#882).
+
+## The problem it solves
+
+Mode-collapse is not only a *per-page* phenomenon — it is why *all* AI output looks the same *across* pages. Per-page
+taste (the spec, the critique loop) fixes one page. **Design memory fixes the portfolio.** To answer "how is this
+different from before," the harness must *remember before*.
+
+## The store
+
+Local, file-based, on the AGPL CLI side — under `.forgedock/design-memory/` (like per-repo adaptive scripts:
+`.gitignore`d by default, opt-in to commit). One record per shipped design:
+
+```jsonc
+{
+  "product": "…",
+  "shipped_at": "<timestamp>",
+  "corpus_version": "2026.2",          // taste shifts; record what was "current" then
+  "archetype": "technical-dense",
+  "signature_move": "…",               // the hook — the thing to NOT repeat next time
+  "palette_move": "…",                 // the distinctive color decision
+  "type_pairing": "…",
+  "effects_used": ["…"],
+  "rationale_summary": "…",
+  "learnings": ["…"]                   // techniques discovered/applied — grows the vocabulary
+}
+```
+
+## Two mechanisms
+
+### 1. Diverge (anti-sameness)
+The architect phase receives a summary of recent records and is required to **not repeat** the last N designs':
+- signature moves (the hook),
+- archetype (don't ship `technical-dense` three times running for similar briefs),
+- palette/type/effect moves.
+
+The [render → vision-critique loop](render-critique-loop.md) (#882) can enforce a **divergence check**: "is this meaningfully distinct from prior outputs,
+or a reskin?" A reskin fails.
+
+### 2. Evolve (incorporate learnings)
+`learnings` accumulate into a rotating technique/pattern library. The architect's "what I'm trying this time"
+(rationale item 6) draws from it, so the harness deliberately applies and rotates new techniques rather than
+converging on a comfortable default. This is the autopilot / self-improvement angle: **the system gets better the
+more it ships.**
+
+## Open-core boundary
+
+- Memory is **local, AGPL CLI side**. No cross-repo import.
+- It emits nothing the Platform needs to function; if a user opts in, a summary could feed the Platform's
+  observability (per `devdocs/project/architecture.md` boundary rules) — but the CLI never depends on the Platform.
+
+## Acceptance
+
+- Architect phase receives prior signature moves and avoids repeating them.
+- Across N consecutive generations for similar briefs, outputs show measurable variance in concept / hook / palette —
+  not the same page reskinned.
+- `learnings` demonstrably influence later designs ("trying this time" references a prior learning).

package/docs/design/design-spec-schema.md

@@ -0,0 +1,248 @@
+# FORGE:DESIGN_SPEC — Schema
+
+> **Status:** Committed foundation — canonical schema for the UI Taste Harness (milestone #13, issue #881).
+> Output of the [design-architect phase](design-architect-rationale.md) (#886); input to generate + the
+> render-critique loop (#882); enforced by the anti-slop linter (#884); persisted to
+> [design-memory](design-memory.md) (#887) at close. Draws its vocabulary from the
+> [reference corpus](reference-corpus.md) (#880).
+> Extended: `craft` object + `surface_depth` rubric dimension (#1047); `motion.tier`, `motion.hero_technique`,
+> `motion.video_placeholder` fields + `motion` rubric dimension (#1043); `product_mock` field + `product_mock`
+> rubric dimension (#1045); `scroll_narrative` object + `scroll_narrative` rubric dimension (#1046).
+>
+> Registered as a FORGE annotation type in [`../FORGE-PROTOCOL.md`](../FORGE-PROTOCOL.md).
+
+## Purpose
+
+A structured, **machine-checkable** representation of the design language for one page — carried across pipeline
+stages as a `FORGE:DESIGN_SPEC` annotation, exactly like other FORGE annotations carry context. It exists so taste
+decisions **persist** instead of being re-rolled on every generation, and so a deterministic linter and a vision
+critic can both check the output against the *same* committed intent.
+
+Critically: the spec is **produced by the [rationale](design-architect-rationale.md)** (the reasoning), not authored
+from nowhere. Rationale → spec → page.
+
+## Schema
+
+```jsonc
+{
+  "meta": {
+    "product": "Voltage",            // anonymized brief name
+    "archetype": "technical-dense",  // one of the corpus archetypes — committed, not blended
+    "corpus_version": "2026.6",      // which grammar snapshot this was designed against
+    "rationale_ref": "<issue/comment URL of the FORGE:DESIGN_RATIONALE that produced this>"
+  },
+  "typography": {
+    "display_family": "…",           // CONSTRAINT: non-default — never Inter-at-default
+    "body_family": "…",
+    "mono_family": "…",              // optional
+    "scale_ratio": 1.25,             // modular scale; large, confident jumps
+    "base_size_px": 17,
+    "weights": [400, 500, 700],
+    "headline_tracking_em": -0.02
+  },
+  "color": {
+    "mode": "dark",                  // light | dark | auto (dark-first is common)
+    "background": "#…",
+    "foreground": "#…",
+    "accent": "#…",                  // ONE disciplined accent
+    "supporting": ["#…"],
+    "rules": ["no-default-tailwind-palette", "contrast>=4.5"]
+  },
+  "spacing":  { "base_unit_px": 8, "scale": [4,8,12,16,24,32,48,64,96] }, // all spacing on-scale
+  "radius":   { "scale": [4, 8, 16] },   // deliberate system, NOT uniform rounded-everything
+  "shadow":   { "tokens": ["0 1px 2px rgba(0,0,0,.06)", "0 8px 24px rgba(0,0,0,.12)"] }, // soft, low-spread
+  "craft": {                             // see reference-corpus.md#the-craft-vocabulary — #1047
+    "radius_system": {
+      "card_px": 16,                     // CONSTRAINT: distinct_count >= 3 across card/button/badge/input
+      "button_px": 8,
+      "badge_px": 9999,                  // 9999 = pill
+      "input_px": 6
+    },
+    "button": {
+      "depth": "shadow-lift",            // shadow-lift | gradient | flat — flat triggers N14
+      "hover": "shadow+translate",       // how hover is signaled — must not be color-only
+      "active": "press-down",            // translateY(1px) + reduced shadow
+      "focus": "custom-ring"             // custom-ring | none — none triggers N18
+    },
+    "links": {
+      "treatment": "animated-underline", // animated-underline | static-underline | color-only
+      "underline_offset_px": 3,
+      "underline_thickness_px": 1
+    },
+    "icons": {
+      "container": "tinted-square",      // tinted-circle | tinted-square | none
+      "size_context": {                  // different sizes by context — uniform triggers N16
+        "feature_px": 24,
+        "nav_px": 18,
+        "inline_px": 16
+      }
+    },
+    "micro_details": {
+      "custom_selection": true,          // ::selection — false triggers N18
+      "custom_scrollbar": true,          // thin, theme-matched scrollbar
+      "custom_focus_rings": true         // branded focus rings on all interactive elements
+    },
+    "dividers": "spacing-only"           // spacing-only | gradient-fade | hairline | color-shift
+  },
+  "motion": {
+    "tier": 1,                        // 1 = CSS-only | 2 = SVG+JS | 3 = video placeholder — from corpus hero motion vocabulary (#1043)
+    "hero_technique": "text-reveal",  // specific technique id from the corpus tier (e.g. "gradient-shift", "typewriter", "svg-path-draw", "video-scaffold")
+    "video_placeholder": false,       // true = Tier 3 scaffold included — CSS gradient poster generated, drop-in comment in HTML
+    "vocabulary": ["scroll-reveal", "micro-hover"],  // below-fold motion tokens (Tier 1F: scroll-triggered fade-in)
+    "default_ms": 200, "easing": "cubic-bezier(.2,.0,.0,1)",
+    "reduced_motion": "required"      // MUST honor prefers-reduced-motion — @media (prefers-reduced-motion: reduce) on all animated elements
+  },
+  "product_mock": {                  // see reference-corpus.md#interactive-product-mock-vocabulary — #1045
+    "type": "deploy-infra",          // issue-tracker | payment-fintech | deploy-infra | api-developer | email-messaging | none
+    "interactions": [                // select exactly 2 from the per-type list in the corpus
+      "status-building-pulse",       // CSS animation — pulsing dot while deploy is running
+      "deploy-step-progress"         // CSS animation — progress bar filling
+    ],
+    "css_only": true                 // true = CSS-only interactions (preferred) | false = lightweight vanilla JS required (e.g. typing animation, counter)
+  },
+  "scroll_narrative": {              // see reference-corpus.md#below-the-fold-narrative-vocabulary — #1046
+    "section_sequence": [            // committed section order below the fold (derived from rationale step 3 — communication hierarchy)
+      "problem-context",             // section type ids from the corpus scroll narrative vocabulary
+      "solution-showcase",
+      "social-proof",
+      "deep-features",
+      "final-cta"
+    ],
+    "section_count_min": 5,          // total sections including hero — MUST be ≥5 (triggers N25 when < 5)
+    "sticky_nav": true,              // true = nav transforms on scroll (transparent → solid); false = static nav
+    "social_proof_section": "metrics", // logos | metrics | testimonials | none — "none" skips N26 check
+    "cta_placements_min": 2          // minimum CTA count across the full page — must be ≥2 (triggers N27 when < 2)
+  },
+  "layout_grammar": {
+    // ordered sections with purpose + density — MUST NOT be the boilerplate skeleton
+    // (hero → 3 cards → testimonial → CTA). Sections derive from the rationale's communication hierarchy.
+    "sections": [
+      { "id": "hero", "purpose": "…", "density": "low" },
+      { "id": "…",    "purpose": "…", "density": "high" }
+    ],
+    "rhythm": "alternating-density",
+    "intentional_breaks": ["asymmetric hero", "full-bleed product shot"]
+  },
+  "effects_plan": {                  // see effects-appropriateness.md (#885) — reasoned via the effects doctrine, not chosen blindly
+    "per_section": [
+      { "section": "hero", "effect": "subtle-technical-visualization", "intensity": "low",
+        "justification": "product is GPU-compute; one earned hero centerpiece" }
+    ],
+    "budget": { "lcp_ms": 2000, "max_js_kb": 150 },
+    "never": ["3d-on-non-hero", "parallax-on-pricing"]
+  },
+  "negatives": [ /* anti-slop checklist pulled from corpus — linter + critic both check */ ],
+  "acceptance": {
+    "perf_budget": { "lcp_ms": 2000, "cls": 0.1, "inp_ms": 200 },
+    "a11y": { "contrast_min": 4.5, "reduced_motion": true },
+    "divergence_ref": "<design-memory check result — see #887>"
+  }
+}
+```
+
+## How each field defends against slop
+
+| Field | Defends against |
+|---|---|
+| `archetype` (committed) | mode-collapse to the mean (forces a tail direction, not the average) |
+| `typography.display_family` non-default | the Inter-default tell |
+| `color.rules: no-default-tailwind-palette` | slate/indigo "AI gradient" tell |
+| `spacing.scale` (on-scale only) | arbitrary padding / no rhythm |
+| `layout_grammar` (non-boilerplate) | the hero→3-cards→testimonial→CTA skeleton |
+| `effects_plan` (justified + budgeted) — doctrine: [effects-appropriateness](effects-appropriateness.md) (#885) | gratuitous 3D/parallax; perf blowups |
+| `acceptance.perf_budget` | "earned its milliseconds" becomes objective (via Playwright, #875) |
+| `craft.radius_system` (`distinct_count >= 3`) | one-radius-fits-all AI tell (N13) |
+| `craft.button.depth` (not `flat`) | flat Tailwind button with no depth (N14) |
+| `craft.micro_details.custom_selection` + `custom_focus_rings` | missing branded micro-details (N18) |
+| `craft.icons.size_context` (distinct sizes by context) | default uniform icon treatment (N16) |
+| `craft.links.treatment` (not `color-only`) | bare color-only or browser-default link treatment (N17) |
+| `motion.tier` + `motion.hero_technique` (committed) | static hero with no motion — the "poster" tell (N21); jQuery-era effects (N23) |
+| `motion.reduced_motion: "required"` | motion that ignores `prefers-reduced-motion` — accessibility violation |
+| `motion.video_placeholder: true` (when applicable) | video-shaped hero gap: empty space where a demo would go, or placeholder image with no scaffolding |
+| `product_mock.type` (committed, not `none`) | static product screenshot in a browser frame with no interactions — the "screenshot poster" tell (N24) |
+| `product_mock.interactions` (exactly 2 selected) | mock with too many interactions (demo feel) or zero interactions (static poster) |
+| `product_mock.css_only: false` acknowledged explicitly | lightweight JS used without acknowledgement; framework dependency creeping in |
+| `scroll_narrative.section_count_min` (≥5) | hero-only page with no narrative arc — the "above-the-fold only" tell (N25) |
+| `scroll_narrative.social_proof_section` (committed, not `none`) | missing social proof section — page makes claims without third-party validation (N26) |
+| `scroll_narrative.cta_placements_min` (≥2) | single CTA at hero only — convinced visitors at the bottom of the page have nowhere to convert (N27) |
+| `scroll_narrative.sticky_nav` (committed) | nav disappears on scroll — brand and primary CTA lost mid-narrative |
+
+## Benchmark rubric dimensions
+
+The ABC benchmark (#878) evaluates generated pages on a 1–5 rubric. The `craft` field extension (#1047) added
+two dimensions (`surface_depth`, `craft`); the `motion` field extension (#1043) adds a seventh dimension;
+the `scroll_narrative` field extension (#1046) adds a ninth dimension.
+
+| Dimension | What it measures | 1 (worst) | 5 (best) |
+|---|---|---|---|
+| `typography` | Type hierarchy, scale, non-default faces | System font, single weight, no scale | Non-default face, confident scale ratio, tight tracking |
+| `color` | Palette restraint, accent discipline, contrast | Default Tailwind palette, multiple loud accents | Near-monochrome + one disciplined accent, ≥4.5 contrast |
+| `surface_depth` | Shadows, borders, radius system, layering | Flat, no depth cues, uniform radius | Soft multi-token shadows, 3+ distinct radii, clear z-layering |
+| `craft` | Micro-detail quality — buttons, links, icons, forms, micro-details | All framework defaults, no custom states | Custom depth on buttons, animated links, tinted icon containers, branded micro-details |
+| `layout` | Grid, asymmetry, negative space, section rhythm | Centered columns, uniform padding, boilerplate skeleton | Deliberate grid breaks, asymmetry, spacing-as-divider |
+| `effects` | Effect appropriateness and restraint | Gratuitous 3D/parallax on non-visual product | Effects justified by product nature, performance-budgeted |
+| `motion` | Hero vitality — appropriate motion technique committed and executed per archetype | Static hero (poster) — N21 hit; or jQuery-era effects — N23 hit | Archetype-appropriate tier selected, `prefers-reduced-motion` honored, at most 2 simultaneous motion elements |
+| `product_mock` | Product mock interactivity — browser-chrome wrapper with live micro-interactions vs. static screenshot | No mock present, or mock with no interaction — N24 hit | Product type correctly identified, 2 interactions committed from vocabulary, CSS-only preferred, `prefers-reduced-motion` honored |
+| `scroll_narrative` | Full-page narrative completeness — below-fold section depth, social proof presence, CTA rhythm | Hero-only page, no below-fold narrative, single CTA — N25/N26/N27 hit | ≥5 sections committed and generated, social proof section present and animated, ≥2 CTAs placed at narrative milestones |
+
+The `craft` and `surface_depth` dimensions are new in `corpus_version: 2026.3` (#1047). The `motion` dimension
+is new in `corpus_version: 2026.4` (#1043). The `product_mock` dimension is new in `corpus_version: 2026.5`
+(#1045). The `scroll_narrative` dimension is new in `corpus_version: 2026.6` (#1046). Past benchmark runs scored
+under a 4-dimension rubric (no `surface_depth`, `craft`, `motion`, `product_mock`, or `scroll_narrative`).
+Comparison across versions must note the rubric version.
+
+## Section-level surgical re-generation contract
+
+<!-- Added: forge#1044 — user-feedback loop -->
+
+The `layout_grammar.sections` array is the structural hook for **targeted, section-only edits**. Each section carries
+an `id` (e.g. `"hero"`, `"features"`, `"pricing"`), a `purpose`, and a `density`. This structure enables Stage 4.5 of
+the `/design` pipeline (user-feedback loop, #1044) to re-generate a single section without touching the rest of the
+page.
+
+### Rules for surgical re-generation
+
+1. **Section IDs are the targeting key.** When `FORGE:USER_FEEDBACK` names a `section_target`, the re-generation agent
+   receives: the full current HTML + the FORGE:DESIGN_SPEC + the feedback for that section ID only. It produces a
+   replacement for that section's markup and nothing else.
+
+1.5. **`"all"` is the page-wide sentinel.** When `section_target == "all"`, the re-generation agent applies the modification as a global pass — updating CSS custom properties (color palette, typography scale) that span all sections — without replacing any individual section's markup. <!-- Added: forge#1057 -->
+
+2. **Committed archetype and signature move are locked.** User feedback can modify a section's visual execution
+   (motion, layout detail, asset placement, color treatment) but MUST NOT change the committed `meta.archetype` or the
+   signature move recorded in `FORGE:DESIGN_RATIONALE`. Those choices were the architect's and are fixed once the spec
+   is committed. If a user requests a direction change that would require a different archetype, the feedback loop
+   should note the constraint and suggest the closest achievable variation within the committed direction.
+
+3. **The spec is the source of truth for all non-targeted sections.** Sections not named in `section_target` are
+   reproduced from the committed spec unchanged — no style drift, no re-rolling of other sections' taste decisions.
+
+4. **`effects_plan.per_section` updates are allowed.** If feedback changes the hero's visual treatment (e.g., adds a
+   product video, changes the motion vocabulary), the `effects_plan.per_section` entry for that section may be updated
+   in a revised FORGE:DESIGN_SPEC annotation — this is the only part of the spec a feedback iteration may mutate.
+
+5. **Benchmark bypass.** Section-level re-generation is triggered by user presence (Stage 4.5). The ABC benchmark arm A
+   runs non-interactively and bypasses Stage 4.5 entirely — automated runs proceed directly from Stage 4 to Stage 5.
+
+### Asset integration via section targeting
+
+When `FORGE:USER_FEEDBACK` carries an asset, the re-generation agent applies it to the `section_target`:
+
+| Asset type | Section target | Integration |
+|---|---|---|
+| Video URL (mp4/webm) | `hero` | Replace or augment hero visual with `<video autoplay loop muted playsinline>` scaffold; adjust hero layout to accommodate |
+| Video embed URL (YouTube/Vimeo) | `hero` | `<iframe>` with `loading="lazy"`, aspect-ratio container, no autoplay |
+| Logo SVG | `nav` / `hero` | Replace text logo node; adjust `width`/`height` to maintain proportional sizing; verify contrast against background |
+| Brand hex colors | any | Update `color.*` CSS custom properties matching the section; run contrast check (WCAG AA ≥ 4.5:1) before emitting |
+| Product screenshot/image | `hero` / `features` | Replace placeholder with `<img>` or `background-image`; maintain existing sizing/aspect-ratio tokens |
+
+## Lifecycle
+
+1. **architect** (#886) emits this spec from the rationale.
+2. **generate** produces HTML constrained by it.
+3. **linter** ([`design-system-lint.mjs`](design-system-lint.md), #884) checks deterministic fields (palette, spacing, radius, layout skeleton, craft.radius_system, craft.button.depth, craft.micro_details).
+4. **critique loop** (#882) renders + checks `negatives`, `effects_plan` justification, and `acceptance` against the
+   rendered result; iterates until pass.
+4.5. **user-feedback loop** (#1044) prompts for hero-specific user input; applies surgical section-level re-generation
+   using section IDs as targeting keys; bypassed in automated (benchmark) runs.
+5. **close** writes the realized spec + outcome to [design-memory](design-memory.md) (#887).