forgedock 1.0.16 → 1.0.18

package/commands/deploy-info.md

@@ -36,12 +36,13 @@ TARGET=${TARGET_BRANCH:-main}
 
 # Step 1: Find all PR numbers in the bundle (same logic as review-pr-staging Phase 0A)
 BUNDLE_PRS=$(git log origin/$TARGET..origin/$SOURCE --oneline \
-  | grep -oP '#\d+' \
+  | grep -oE '#[0-9]+' \
   | sort -u \
   | tr -d '#')
 
 MERGE_PRS=$(git log origin/$TARGET..origin/$SOURCE --merges --oneline \
-  | grep -oP '(?<=pull request #)\d+' \
+  | grep -oE 'pull request #[0-9]+' \
+  | grep -oE '[0-9]+' \
   | sort -u)
 
 ALL_PR_NUMBERS=$(echo "$BUNDLE_PRS $MERGE_PRS" | tr ' ' '\n' | sort -u | grep -E '^[0-9]+$')
@@ -127,7 +128,7 @@ git log --oneline origin/$TARGET..origin/$SOURCE --format="%h %s" | head -50
 
 ```bash
 # Extract PR numbers from merge commits
-PR_NUMBERS=$(git log origin/$TARGET..origin/$SOURCE --merges --format="%s" | grep -oP '#\d+' | sort -u)
+PR_NUMBERS=$(git log origin/$TARGET..origin/$SOURCE --merges --format="%s" | grep -oE '#[0-9]+' | sort -u)
 
 # Get PR details
 for PR in $PR_NUMBERS; do
@@ -142,7 +143,7 @@ done
 # Extract issue references from PR bodies
 for PR in $PR_NUMBERS; do
   NUM=${PR#\#}
-  CLOSES=$(gh pr view $NUM --json body --jq '.body' 2>/dev/null | grep -oP 'Closes #\K\d+')
+  CLOSES=$(gh pr view $NUM --json body --jq '.body' 2>/dev/null | grep -oE 'Closes #[0-9]+' | grep -oE '[0-9]+')
   for ISSUE in $CLOSES; do
     gh issue view $ISSUE --json number,title,labels --jq '"\(.number) | \(.title) | \([.labels[].name] | join(","))"' 2>/dev/null
   done
@@ -225,7 +226,7 @@ if [ -n "$NEW_ENV" ]; then
   # Cross-check with SOPS chain (only when deploy.secrets_backend == "sops")
   # If your project uses a different backend, skip this block and verify manually.
   if [ "{DEPLOY_SECRETS_BACKEND}" = "sops" ]; then
-    for var in $(echo "$NEW_ENV" | grep -oP '^\+\K[A-Z_]+'); do
+    for var in $(echo "$NEW_ENV" | grep -oE '^\+[A-Z_]+' | sed 's/^\+//'); do
       if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
         echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
       fi

package/commands/design-bench.md

@@ -0,0 +1,176 @@
+---
+description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
+argument-hint: [<brief-name>|all] [--n <runs>] [--corpus-version <ver>]
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /design-bench — The ABC Benchmark Rig
+
+**Input**: $ARGUMENTS — a seed brief name (`cadence` | `tender` | `slipstream` | `voltage` | `plume`) or `all`, with optional `--n <runs>` (default 3, min 3) and `--corpus-version <ver>`.
+
+This is the **fitness function** for the UI Taste Harness (milestone #13, issue #878). It is built *before*
+the harness and is the only thing that tells us whether each lever the harness adds actually moves design
+quality. Running this command answers one question: **did arm A (the harness) score higher against the real
+reference (arm C) than it did last time?**
+
+Read [`docs/design/abc-benchmark.md`](../docs/design/abc-benchmark.md) (methodology) before running. The three
+arms, the same-model rule, the C-as-calibration check, the three-layer judging protocol, and the n>=3 rule all
+live there — this command is the executable workflow over that methodology.
+
+**No application runtime.** ForgeDock is a set of command specs. This command is a step-by-step procedure an
+agent executes; the only executable helper is the deterministic aggregator `scripts/bench-scorecard.mjs`.
+
+---
+
+## The three arms (one variable)
+
+| Arm | What it is | How this command produces it |
+|-----|------------|------------------------------|
+| **A** | ForgeDock harness output | Run the brief through `/design` (#888). **Pluggable** — see [Arm A is pluggable](#arm-a-is-pluggable). |
+| **B** | Raw frontier model, one shot | Hand the brief to the model once, no tools, no iteration. |
+| **C** | The real reference page | Capture the brief's real reference URL through the same render pipeline. |
+
+**Hard rule — same generation model for A and B.** The harness is the ONLY difference between A and B; that is
+what makes the A-vs-B delta attributable to the harness. Different models benchmark models, not the harness.
+
+**Validated generation model: `claude-opus-4-6`.** Benchmark results (#878) show a tier-level quality difference: 90% A-vs-B pairwise win-rate with Opus vs 54% with Sonnet, rubric mean 4.11 vs 3.40, slop 1.2 vs 1.8. The canonical baseline going forward is the Opus run. Raw data: `docs/design/fixtures/runs/full-abc-opus/`. Use Opus for both arm A and arm B unless explicitly testing a different model.
+
+---
+
+## Phase 0: Resolve inputs
+
+1. Parse `$ARGUMENTS`: the brief name(s) and `--n` (default 3; **reject n<3** — n=1 is a lie). `all` = every
+   brief under `docs/design/fixtures/briefs/` (excluding `README.md`).
+2. For each brief, load `docs/design/fixtures/briefs/<name>.md`. This is the design-blind input handed to arms
+   A and B.
+3. Load the brief→reference(C) mapping from `docs/design/fixtures/briefs/README.md`. **The mapping is for the
+   judge/calibration record only — it is NEVER shown to the generating arms.** A real brand name leaking into a
+   brief measures recall, not taste, and inflates arm B.
+
+---
+
+## Phase 1: Brief (reference URL → design-blind brief)
+
+The seed briefs are pre-stripped fixtures, so for the seed set this phase is a load, not a derivation.
+
+**To add a new reference URL** (outside the seed set): fetch the page, strip every visual cue (color, type,
+layout, "make it like X"), keep only what the product *does* / who it's for / what the page must communicate,
+and assign an **anonymized** product name. Save as a new fixture and add its mapping row. Follow
+`docs/design/fixtures/briefs/README.md`.
+
+---
+
+## Phase 2: Render arms (kill confounds)
+
+Render **all three arms through the identical pipeline** so the judge compares design, not rendering artifacts.
+
+For each of the `--n` runs per brief:
+
+1. **Arm A** — run the brief through `/design` (#888) → self-contained HTML.
+2. **Arm B** — one-shot the SAME model with the brief → self-contained HTML. No tools, no iteration.
+3. **Arm C** — the real reference URL.
+
+Render every arm with **Playwright** (milestone render dependency) at:
+
+- **1440px** desktop and **390px** mobile,
+- `networkidle` + fonts loaded before capture,
+- **full-page** screenshot.
+
+For arm C, trim cookie banners / hero video and **record any trim applied** in the run record (reproducibility).
+
+> **Arm A is pluggable.** Until `/design` (#888) lands, arm A is produced by a clearly-labeled manual hook:
+> generate arm A by hand using the harness method-of-the-day and drop its HTML into the run record marked
+> `arm_a_source: manual`. The rig — brief loading, render protocol, judging, scorecard — is fully operational
+> without #888. When #888 lands, replace the manual hook with the `/design` invocation; nothing else changes.
+> **Do NOT block the benchmark on #888.**
+
+---
+
+## Phase 3: Judge (three layers)
+
+The judge is a **named, independent stage**. See [Anti-Goodhart](#anti-goodhart) — it MUST NOT be the harness's
+own critique loop (#882).
+
+For each run, produce judge output in the [runs-file schema](../docs/design/abc-benchmark.md#scorecard-schema):
+
+### Layer 1 — Blind randomized pairwise (primary)
+Show the judge two **anonymized** screenshots in **shuffled** order and ask: *"Which reads more like a
+professionally designed, well-funded SaaS landing page?"* Run **A-vs-C, B-vs-C, A-vs-B**. Record the winner
+(`"A" | "B" | "C" | "tie"`) per comparison. Screenshots carry no arm labels.
+
+### Layer 2 — Rubric (1–5 per arm)
+Score each arm on: hierarchy, typography, color discipline, whitespace rhythm, originality-vs-slop, mobile.
+
+### Layer 3 — Slop detector (binary)
+Run the anti-slop negatives checklist (corpus #880) over each arm; record the count of negatives present
+(lower is better).
+
+Append each run to the brief's `runs[]` array in the runs file.
+
+---
+
+## Phase 4: Scorecard
+
+Aggregate deterministically:
+
+```bash
+node scripts/bench-scorecard.mjs runs.json > scorecard.json
+```
+
+The aggregator (see `scripts/bench-scorecard.mjs`):
+- **rejects any product with n<3 runs** (exit 1) — enforces the no-point-estimate rule,
+- emits **win-rate vs C** per arm (overall + per-product), the **A-vs-B harness delta**, **rubric mean+stdev**
+  per arm/dimension, **mean slop** per arm,
+- runs the **judge-calibration check**: C must beat A and B in the pairwise; any run where C loses is listed in
+  `judge_calibration.miscalibrated_runs` and the command exits 2 with a warning. A real reference losing to a
+  generated arm is a judge defect, not a harness win — treat those runs as suspect.
+
+Post the result as a `FORGE:BENCH_SCORECARD` annotation (registered in
+[`docs/FORGE-PROTOCOL.md`](../docs/FORGE-PROTOCOL.md)) on the tracking issue:
+
+```bash
+gh issue comment <ISSUE> --body "<!-- FORGE:BENCH_SCORECARD -->
+## ABC Benchmark Scorecard
+
+**Corpus version**: <ver> · **Generation model (A & B)**: <model> (canonical: claude-opus-4-6) · **Judge model**: <independent judge>
+**Products**: <n_products> · **Runs/product**: <n>
+
+| Arm | Win-rate vs C | A-vs-B | Mean slop |
+|-----|---------------|--------|-----------|
+| A   | <wr>          | <a_vs_b> | <slop_A> |
+| B   | <wr>          | —        | <slop_B> |
+
+**Judge calibration**: <ok | MISCALIBRATED — N runs where C lost (suspect)>
+
+\`\`\`json
+<scorecard.json>
+\`\`\`
+
+<!-- FORGE:BENCH_SCORECARD:COMPLETE -->"
+```
+
+---
+
+## Two non-negotiable rules
+
+### n=1 is a lie
+Taste output is high-variance. Run **3–5 generations per arm across 3–5 products** and report **distributions**.
+The aggregator hard-fails on n<3.
+
+### Anti-Goodhart
+The benchmark judge **MUST be independent from the harness's own critique loop (#882)**. Optimizing against the
+same judge that scores the benchmark is training to the test — the number rises while real quality does not. The
+benchmark judge uses its own prompt and is a distinct stage; it does not reuse the #882 critique judge.
+
+---
+
+## Acceptance (issue #878)
+
+- [x] Reproducible command/workflow: reference URL → brief → render arms → judge → scorecard.
+- [x] Arms A/B/C defined; same generation model for A and B; C = gold standard + judge calibration.
+- [x] Three judging layers: blind randomized pairwise, 1–5 rubric, binary slop detector.
+- [x] n=3–5 across 3–5 products; distributions reported; n=1 rejected by the aggregator.
+- [x] Benchmark judge independent from the #882 critique loop (anti-Goodhart).
+- [x] Five seed briefs as fixtures (Cadence/Tender/Slipstream/Voltage/Plume), anonymized + mapped to C.
+- [x] Arm A pluggable — rig runs now, plugs into `/design` (#888) when it lands.

package/commands/design-render-critique-loop.md

@@ -0,0 +1,103 @@
+---
+description: Render a design from its FORGE:DESIGN_SPEC, critique the rendered pixels against the perceptual negatives, and iterate until it passes or the budget is spent — the missing reward signal.
+argument-hint: [<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /design-render-critique-loop — render → vision-critique → iterate
+
+**Input**: $ARGUMENTS — the design issue number (reads its `FORGE:DESIGN_SPEC`) or a path to a spec, with optional
+`--max-iters <n>` (default 3) and `--viewports` (default `desktop,mobile`).
+
+This is the **missing reward signal** for the UI Taste Harness (milestone #13, issue #882). Every other lever in the
+harness can still raw-dog the output — write a page and defend it blind. This loop is the only stage that *looks at the
+rendered pixels* and feeds a correction back in. Without it the harness has no feedback loop; with it, a page measurably
+improves across iterations.
+
+Read [`docs/design/render-critique-loop.md`](../docs/design/render-critique-loop.md) (methodology) before running —
+the thesis, the iteration protocol, the deterministic-floor-first ordering, the anti-Goodhart independence rule, and the
+pass/budget criteria all live there. This command is the executable procedure over that methodology.
+
+**No application runtime.** ForgeDock is a set of command specs. The only executable helper is the deterministic
+linter `scripts/design-system-lint.mjs` (#884); the render + critique steps are agent-driven via the Playwright MCP.
+
+---
+
+## Inputs (read before iterating)
+
+| Input | Source | Role |
+|-------|--------|------|
+| `FORGE:DESIGN_SPEC` | the design issue (#881) | the committed intent the render must satisfy |
+| `scripts/design-system-lint.mjs` | #884 | deterministic floor — cheap, runs first |
+| Perceptual negatives N3, N8–N12 | [`reference-corpus.md`](../docs/design/reference-corpus.md) (#880) | what the vision critic judges (the linter declares these out of scope) |
+| Render protocol | the #878 / #875 Playwright protocol | desktop + mobile capture, same viewports as the benchmark |
+
+## The loop
+
+```
+iteration = 0
+while iteration < max_iters:
+    iteration += 1
+
+    # 1. Deterministic floor FIRST (cheap — never spend a render on a page that fails the linter)
+    Run: node scripts/design-system-lint.mjs --spec <spec> --html <generated> [--strict]
+    if HARD findings: fix against the spec, continue   # do not render a lint-failing page
+
+    # 2. Render (Playwright MCP) — desktop + mobile, same protocol as #878
+    Capture the page at each viewport.
+
+    # 3. Vision critique — judge the RENDERED pixels against the perceptual negatives ONLY
+    For N3 (centered/no asymmetry), N8 (stock/generic 3D), N9 (glassmorphism overuse),
+    N10 (no visual hierarchy), N11 (abstract copy / no product shown), N12 (decorative effects
+    that serve nothing): is the negative present in the render? Each hit is a finding.
+    Also check the render against the spec's own acceptance + effects_plan justification (#885).
+
+    # 4. Emit the per-iteration trail
+    Post a FORGE:CRITIQUE annotation (schema below) with findings + verdict.
+
+    if no perceptual findings AND lint clean: PASS — break
+    else: translate each finding into a concrete spec/markup correction and iterate.
+
+if iteration == max_iters and not PASS:
+    Post the final FORGE:CRITIQUE with verdict BUDGET-EXHAUSTED and the residual findings.
+```
+
+## Ordering rule (cheap gate first)
+
+The deterministic linter (#884) runs **before** every render. A page that fails a hard lint rule is fixed before a
+render is ever captured — rendering and vision-critiquing a page the linter already rejects wastes the expensive step.
+The critic owns **only** the perceptual negatives the linter declares out of scope (N3, N8–N12); it never re-checks a
+deterministic rule. No duplication.
+
+## Anti-Goodhart independence (non-negotiable)
+
+The critic in this loop is **strictly independent** from the ABC benchmark judge (#878). The benchmark judge is the
+*evaluator* — it scores finished arms blind against arm C to tell us whether the harness improved. If the loop
+optimized against that same judge, the harness would be training on its own test set (Goodhart). The loop's critic
+judges *one page against its own committed spec + the perceptual negatives*; the benchmark judge judges *arms against a
+real reference*. They must never be the same judge. This is also distinct from the divergent-generation taste-judge
+(#883), which scores pre-render candidate directions.
+
+## `FORGE:CRITIQUE` annotation
+
+Registered in [FORGE-PROTOCOL](../docs/FORGE-PROTOCOL.md). One per iteration, so the improvement trajectory is an
+auditable artifact:
+
+```markdown
+<!-- FORGE:CRITIQUE -->
+## Critique — {product} · iteration {i}/{max}
+
+**Lint floor:** {PASS | fixed N hard findings}
+**Render:** desktop + mobile captured
+**Perceptual findings:**
+- N{n}: {what was observed in the render} → {correction}
+**Verdict:** {PASS | ITERATE | BUDGET-EXHAUSTED}
+<!-- FORGE:CRITIQUE:COMPLETE -->
+```
+
+## Success measure
+
+The loop works when a page **improves across iterations** and when, on the seed set, *A-with-loop* scores higher than
+*A-without-loop* and higher than *raw B*, measured against the #879 baseline via the ABC benchmark (#878). The loop is
+the reward signal; the benchmark is the independent scoreboard that confirms it moved.

package/commands/design.md

@@ -0,0 +1,259 @@
+---
+description: Route a design GitHub issue through the UI Taste Harness — investigate → architect → implement → critique loop → user-feedback loop → close — accumulating FORGE:DESIGN_* annotations and driving the design:* label state machine to design:shipped.
+argument-hint: <issue-number> | <brief-name>
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /design — the design pipeline (the `/work-on` analog for design)
+
+**Input**: $ARGUMENTS — a design issue number, or a seed brief name (`cadence` | `tender` | `slipstream` | `voltage` | `plume`) which is opened as a design issue first.
+
+This is the **spine of the UI Taste Harness** (milestone #13, issue #888). Just as a code task is a GitHub issue
+routed `investigate → build → review → close` by [`/work-on`](work-on.md) — accumulating `FORGE:*` annotations, closed
+at the end — a **design task is a GitHub issue routed through this design pipeline**, accumulating `FORGE:DESIGN_*`
+annotations and closed when the design ships and passes its gates. It is a parallel track on the same "GitHub as a
+knowledge graph" model, not a new paradigm.
+
+**It IS arm A of the ABC benchmark (#878).** Running a brief through `/design` produces the arm-A output; the benchmark
+rig (`/design-bench`) feeds briefs in and screenshots the result, so this command is what makes the benchmark runnable
+end to end.
+
+**Agent model policy**: `model: "claude-opus-4-6"` — Opus is the validated generation model. Benchmark #878 (90% A-vs-B pairwise win-rate with Opus vs 54% with Sonnet) confirms a tier-level quality difference. Both arm A and arm B MUST use the same model to keep the benchmark valid (see [design-bench](design-bench.md)).
+
+**No application runtime.** ForgeDock is a set of command specs. `/design` *sequences* the already-built stage specs —
+it does not reimplement them. The only executable helper in the chain is the deterministic linter
+`scripts/design-system-lint.mjs` (#884).
+
+---
+
+## Universal Stage Dispatcher
+
+<!-- This is the single source of truth for design:* transitions, mirroring /work-on's Universal Phase Dispatcher. -->
+
+| Stage | design:* label | Terminal? | Reads | Produces | Spec it sequences |
+|-------|----------------|-----------|-------|----------|-------------------|
+| 1. design-investigate | `design:investigating` | No | the brief | `FORGE:DESIGN_CONTEXT` | corpus #880 (grammar) + memory #887 (what to diverge from) |
+| 2. design-architect | `design:architecting` | No | `FORGE:DESIGN_CONTEXT` | `FORGE:DESIGN_RATIONALE` → `FORGE:DESIGN_CANDIDATES` → `FORGE:DESIGN_SPEC` | rationale #886, divergent generation #883, effects #885, schema #881 |
+| 3. design-implement | `design:generating` | No | `FORGE:DESIGN_SPEC` | the generated page (artifact) | — (generate from the committed spec) |
+| 4. design-critique | `design:critiquing` | No | the render + `FORGE:DESIGN_SPEC` | `FORGE:CRITIQUE` (per pass) | render→critique loop #882 (lint #884 floor + perf #875 + a11y) |
+| 4.5. user-feedback | `design:awaiting-feedback` | No | `FORGE:CRITIQUE` + user input | `FORGE:USER_FEEDBACK` (per round) | this spec (#1044); bypassed in automated/benchmark runs |
+| 5. design-close | `design:shipped` / `design:rejected` | **Yes** | `FORGE:USER_FEEDBACK` (latest) or `FORGE:CRITIQUE` | `FORGE:DESIGN_SHIPPED` | scorecard + write outcome to memory #887 |
+
+**Continuation rule** (mirrors `/work-on`): after any stage completes, if the issue is not at a terminal label
+(`design:shipped` or `design:rejected`), proceed to the next stage immediately. No intermediate stage is terminal.
+`design:awaiting-feedback` is **non-terminal** — it resolves to Stage 5 when `FORGE:USER_FEEDBACK.satisfied == "yes"`
+or when no user is present (automated runs bypass Stage 4.5 entirely).
+
+---
+
+## Stage 1 — design-investigate (`design:investigating`)
+
+Parse the brief into message / audience / single objection. Pull the relevant grammar from the
+[reference corpus](../docs/design/reference-corpus.md) (#880) and query [design-memory](../docs/design/design-memory.md)
+(#887) for the recent signature moves / archetypes / palettes to **diverge** from. Post `FORGE:DESIGN_CONTEXT`.
+
+## Stage 2 — design-architect (`design:architecting`)
+
+Run the [design-architect rationale](../docs/design/design-architect-rationale.md) (#886): the 7-element diary →
+`FORGE:DESIGN_RATIONALE`. Then [divergent generation](../docs/design/divergent-generation.md) (#883): commit one
+archetype, diverge into N directions, independent taste-judge selects → `FORGE:DESIGN_CANDIDATES`. The winning
+direction + the [effects-appropriateness](../docs/design/effects-appropriateness.md) (#885) `effects_plan` are
+committed into `FORGE:DESIGN_SPEC` ([schema](../docs/design/design-spec-schema.md), #881).
+
+## Stage 3 — design-implement (`design:generating`)
+
+Generate the page from the committed `FORGE:DESIGN_SPEC`. The spec is the contract — no taste decisions are re-rolled
+here; generation realizes the committed intent.
+
+### Foundation CSS injection <!-- Added: forge#1048 -->
+
+Before generating the page, inject the archetype's pre-built CSS foundation as the starting stylesheet. Foundation files live in `docs/design/foundations/` and are keyed by `meta.archetype` from `FORGE:DESIGN_SPEC`:
+
+| `meta.archetype` | Foundation file |
+|---|---|
+| `editorial-typographic` | `docs/design/foundations/editorial.css` |
+| `technical-dense` | `docs/design/foundations/technical.css` |
+| `minimal-luxury` | `docs/design/foundations/minimal-luxury.css` |
+| `bold-brutalist` | `docs/design/foundations/brutalist.css` |
+| `warm-photographic` | `docs/design/foundations/warm-photo.css` |
+
+**Injection pattern**: read the foundation file content and include it in the generation prompt as the starting `<style>` block. Instruct the generator to:
+1. Use the foundation's component classes (`.btn`, `.card`, `.badge`, `.input`, `.reveal`) where applicable — do NOT replace them with generic Tailwind equivalents.
+2. Override `--color-accent` and `--color-bg` custom properties with the spec's `color.accent` and `color.background` values to apply the committed palette to the foundation.
+3. Extend, don't replace — additional styles may be added on top of the foundation, but the foundation's radius system, component state management (hover/active/focus), and micro-detail rules (::selection, scrollbar, focus rings) must be preserved.
+
+The foundation is the professional baseline. The generator adds layout and content on top.
+
+## Stage 4 — design-critique (`design:critiquing`)
+
+Run [`/design-render-critique-loop`](design-render-critique-loop.md) (#882): deterministic lint floor (#884) → Playwright
+render (desktop + mobile, #875/#878) → vision critique of the perceptual negatives → iterate. Each pass posts a
+`FORGE:CRITIQUE`. The loop continues until PASS or budget.
+
+## Stage 4.5 — user-feedback loop (`design:awaiting-feedback`) <!-- Added: forge#1044 -->
+
+**Entry condition**: Stage 4 (design-critique) has completed — `FORGE:CRITIQUE` posted with verdict `PASS` or
+`BUDGET-EXHAUSTED`. **Automated/benchmark bypass**: if no user is present (e.g., running as part of the ABC benchmark
+arm A), skip this stage entirely and proceed to Stage 5.
+
+**Purpose**: The automated critique loop (#882) closes the perceptual-quality loop. This stage closes the **brand
+fit** loop — the part only the user can judge. Brand assets are user-supplied, emotional register is subjective, and
+the best heroes are refined, not generated once. Stage 4.5 collects that input in a structured way and routes it to
+surgical section-level re-generation rather than full-page regeneration.
+
+### Step 1 — Set label
+
+```bash
+gh issue edit {NUMBER} {GH_FLAG} --add-label "design:awaiting-feedback" \
+  --remove-label "design:critiquing" 2>/dev/null || true
+```
+
+### Step 2 — Prompt the user with structured hero-specific questions
+
+After Stage 4 completes, post a comment on the design issue asking the user the following questions. Present them
+clearly — the user's answer drives the `FORGE:USER_FEEDBACK` structured fields.
+
+```
+## Hero feedback — your turn
+
+The automated critique is complete. Now it's yours to shape.
+
+Please answer any or all of the following:
+
+1. **Demo video or animation** — Do you have a product demo video or animation to feature in the hero?
+   (paste a URL, or say "none")
+
+2. **Primary emotion** — What's the primary feeling you want the hero to evoke?
+   Options: trust / speed / power / craft / play — or describe in your own words.
+
+3. **Brand assets** — Any assets to integrate?
+   - Logo SVG (paste URL or say "none")
+   - Brand hex colors (e.g. "#1a1a2e, #e94560" or "none")
+   - Product screenshots (paste URLs or say "none")
+
+4. **Anything that feels off?** — Any section, element, or overall impression that feels wrong or
+   off-brand? Describe it.
+
+If you're happy with the design as-is, reply: **"looks good, ship it"** (or any affirmative) — that
+sets `satisfied: yes` and moves to Stage 5 without re-generation.
+```
+
+### Step 3 — Parse the user's response into `FORGE:USER_FEEDBACK`
+
+Read the user's reply and produce a structured `FORGE:USER_FEEDBACK` annotation. Map natural-language input to
+the structured fields:
+
+| User says | Maps to |
+|---|---|
+| Pastes a video URL | `feedback_type: asset`, `asset_url: <url>`, `section_target: "hero"` |
+| "make it feel faster / more urgent" | `feedback_type: emotion`, `emotion_target: speed`, `modification: "increase motion intensity; tighten headline tracking"` |
+| "add our logo" + SVG URL | `feedback_type: asset`, `asset_url: <url>`, `section_target: "nav"`, `modification: "replace text logo with SVG; adjust sizing"` |
+| Provides brand hex colors (e.g. "#1a1a2e") | `feedback_type: asset`, `asset_url: none`, `section_target: "all"`, `modification: "update CSS custom properties: --color-accent: #… --color-bg: #…"` |
+| Describes a layout change | `feedback_type: direction`, `modification: <parsed description>` |
+| Freeform complaint | `feedback_type: freeform`, `freeform_notes: <verbatim>`, `modification: <best-effort parse>` |
+| "looks good" / "ship it" / affirmative | `satisfied: yes` → proceed to Stage 5 without re-generation |
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:USER_FEEDBACK -->
+## User Feedback — {product} · round {n}
+
+**Section target:** {section_target}
+**Feedback type:** {asset | emotion | direction | freeform}
+**Asset URL:** {URL or "none"}
+**Modification:** {structured description of what to change}
+**Emotion target:** {trust | speed | power | craft | play | unchanged}
+**Satisfied:** {yes | no}
+**Freeform notes:** {verbatim user input not captured above}
+<!-- FORGE:USER_FEEDBACK:COMPLETE -->"
+```
+
+### Step 4 — Route on `satisfied`
+
+**If `satisfied: yes`** (user approved, or no feedback given): proceed immediately to Stage 5 (design-close).
+No re-generation needed.
+
+**If `satisfied: no`** (feedback given): proceed to Step 5 (surgical re-generation), then loop back to Step 2
+for another feedback round.
+
+### Step 5 — Surgical re-generation (only when `satisfied: no`)
+
+Use the `section_target` from `FORGE:USER_FEEDBACK` and the section IDs in `FORGE:DESIGN_SPEC →
+layout_grammar.sections` to re-generate only the targeted section. See
+[`docs/design/design-spec-schema.md`](../docs/design/design-spec-schema.md) for the full surgical re-generation
+contract.
+
+**Inputs for the re-generation agent**:
+1. The full current HTML page
+2. `FORGE:DESIGN_SPEC` (the committed spec — defines what all non-targeted sections must look like)
+3. `FORGE:USER_FEEDBACK` (the modification + asset URL for the targeted section)
+
+**Re-generation rules**:
+- Modify **only** the targeted section's markup and styles
+- Do NOT change any other section's content, layout, or CSS
+- Do NOT re-roll the committed `meta.archetype` or the signature move from `FORGE:DESIGN_RATIONALE`
+- If the feedback requires an archetype change, note the constraint and propose the closest variant within the committed direction
+- After re-generation, run the deterministic linter on the modified section to catch any regressions (#884)
+
+**Asset integration**:
+
+| Asset | Integration procedure |
+|---|---|
+| Video URL (mp4/webm) | Add `<video autoplay loop muted playsinline>` scaffold in the hero visual area; adjust hero layout CSS to accommodate; keep LCP budget ≤ 2000ms |
+| Video embed URL (YouTube/Vimeo) | `<iframe>` with `loading="lazy"` and aspect-ratio container (`padding-top: 56.25%`); no autoplay |
+| Logo SVG | Fetch the SVG; inline or `<img>` it at the nav/hero logo node; remove the text logo; set `width`/`height` to maintain proportional sizing; verify contrast against background (WCAG AA ≥ 4.5:1) |
+| Brand hex colors | Update the relevant CSS custom properties (`--color-accent`, `--color-bg`, etc.); run contrast check on all text/background pairs; record the update in `effects_plan.per_section` if it affects a hero effect |
+| Product screenshot/image | Replace the placeholder with `<img loading="lazy" decoding="async">` or a `background-image`; maintain existing aspect-ratio and sizing tokens from the spec |
+
+**After re-generation**: loop back to Step 2 — prompt the user again for the next round.
+
+### Budget
+
+Maximum **3 user-feedback rounds** per design issue (configurable). If the budget is exhausted with `satisfied: no`,
+post a summary of the rounds and proceed to Stage 5 with the best version. The design was not fully approved by the
+user — note this in the `FORGE:DESIGN_SHIPPED` annotation.
+
+---
+
+## Stage 5 — design-close (`design:shipped` | `design:rejected`)
+
+Apply the **definition of done**: critique-rubric threshold met **and** perf budget (#875) **and** a11y check **and**
+the divergence check vs memory (#887) — not a reskin of a prior design. If all pass → write the realized outcome
+(archetype, signature move, palette/type/effects, learnings) to [design-memory](../docs/design/design-memory.md) (#887),
+post `FORGE:DESIGN_SHIPPED`, set `design:shipped`, close the issue. Otherwise loop (back to Stage 4) or, if the budget is
+exhausted with residual findings, set `design:rejected` with the reasons on the issue.
+
+---
+
+## Label state machine
+
+```
+design:investigating → design:architecting → design:generating → design:critiquing → design:awaiting-feedback → design:shipped
+                                                                                              │                       ↑
+                                                                                              └──── (loop ≤ 3) ───────┘
+                                                                                  (automated bypass: skip awaiting-feedback)
+                                                                          └──────────────────────────────────────────→ design:rejected
+```
+
+Terminal labels: `design:shipped`, `design:rejected`. These mirror `workflow:merged` / `workflow:invalid` on the code
+track. `design:awaiting-feedback` is **non-terminal** — it resolves to `design:shipped` (via Stage 5) when the user
+approves or the feedback budget is exhausted.
+
+## Definition of done
+
+A design ships only when it passes **all** of: the critique rubric threshold, the perf budget (#875), the a11y check,
+and the divergence check (#887). Anything short loops or is rejected with reasons recorded on the issue — so every
+outcome, pass or fail, is auditable on the GitHub issue.
+
+## Why it matters
+
+1. **Traceability** — every design's thinking (`FORGE:DESIGN_RATIONALE`), the candidate set and the choice
+   (`FORGE:DESIGN_CANDIDATES`), each critique iteration (`FORGE:CRITIQUE`), each user-feedback round
+   (`FORGE:USER_FEEDBACK`), and the final outcome (`FORGE:DESIGN_SHIPPED`) live on the issue. You can read *why* a
+   page looks the way it does — the designer's diary, made auditable, reviewable by a non-designer.
+2. **It is arm A.** Driving the seed briefs (Cadence / Tender / Slipstream / Voltage / Plume) through `/design`
+   produces the arm-A outputs the benchmark (#878) scores against the real references — so building this makes the ABC
+   benchmark runnable end to end.
+3. **Brand fit.** The automated critique loop (#882) closes the perceptual-quality loop. Stage 4.5 closes the brand-fit
+   loop — the part only the user can judge. Brand assets are user-supplied, emotional register is subjective, and the
+   best heroes are refined through iteration. The feedback annotations make that iteration traceable and repeatable.