forgedock 1.0.17 → 1.0.19

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.

package/commands/issue.md

@@ -205,10 +205,12 @@ Files that need changes (ordered by dependency — change these in this order):
 
 ## Acceptance Criteria
 
-- [ ] {Specific, testable criterion}
+- [ ] {Specific, testable criterion} [type:api]
 - [ ] {Specific, testable criterion}
 - [ ] {No regressions in {related_feature}}
 
+> **Test-type annotation** (optional): Append `[type:api]`, `[type:unit]`, `[type:e2e]`, or `[type:manual]` to each criterion. The test gate reads this annotation directly and skips regex inference. Omit it to rely on regex classification fallback.
+
 ## Dependencies
 
 {If this issue depends on other issues:}
@@ -281,8 +283,10 @@ Files that need changes (ordered by dependency):
 
 ## Acceptance Criteria
 
+- [ ] {Specific, testable criterion} [type:api]
 - [ ] {Specific, testable criterion}
-- [ ] {Specific, testable criterion}
+
+> **Test-type annotation** (optional): Append `[type:api]`, `[type:unit]`, `[type:e2e]`, or `[type:manual]` to each criterion. The test gate reads this annotation directly and skips regex inference. Omit it to rely on regex classification fallback.
 
 ## Context
 
@@ -307,7 +311,7 @@ Files that need changes (ordered by dependency):
 - Title MUST use conventional commit prefix: `fix:`, `feat:`, `refactor:`, `investigate:`, `docs:`
 - `## Problem` is MANDATORY — every issue must state what's wrong or what's needed
 - `## Affected Files` is MANDATORY — list actual file paths the investigator should read first
-- `## Acceptance Criteria` is MANDATORY — at least one testable `- [ ]` criterion
+- `## Acceptance Criteria` is MANDATORY — at least one testable `- [ ]` criterion; each item MAY carry an optional `[type:api|unit|e2e|manual]` annotation for deterministic test-gate classification (omit to fall back to regex inference)
 - Domain-specific sections (Evidence Trail, Pattern Metadata, Validation Checklist, etc.) SHOULD be preserved — they add pipeline value. Add mandatory sections around them, not instead of them.
 - `## Prior Investigation` is OPTIONAL — include only when parent/sibling investigation Gist URLs are available. Each Gist URL must be wrapped in a `<!-- FORGE:PRIOR_GIST: {url} -->` annotation for machine-readable parsing by downstream agents. <!-- Added: forge#339 -->
 

package/commands/orchestrate.md

@@ -552,6 +552,71 @@ If `UNEXPECTED_GROWTH > 500`, report the alert clearly before launching the next
 
 ---
 
+### Step 4A.pre.0: Pre-create milestone branches for the wave (MANDATORY before classify-lane) <!-- Added: forge#901 -->
+
+**WHY THIS EXISTS**: Feature-lane milestone branches were created lazily — by whichever feature-lane agent reached its build phase first. When a wave launches N feature-lane agents in parallel, they each run the lane check at roughly the same time. Every agent that runs before the branch is first pushed observes "branch absent" and is misrouted (hard-fail / `needs-human`, or fallback to staging in older code paths). The result is a single milestone's PRs scattered across the milestone branch and staging — a branch-routing nondeterminism that recurs under parallelism.
+
+The fix is deterministic: create every milestone branch the wave will target **once, up front, before any agent runs `classify-lane.sh`**. After this step, every agent's lane check sees the branch and routes consistently.
+
+**When to run**: Before the classify-lane loop in Step 4A.pre, for every wave. The step is a no-op for pure fast-lane waves (no issue in the wave has a milestone).
+
+**Requires bash 4+**: This snippet uses an associative array (`declare -A SEEN_MILESTONE_SLUG`) to de-dupe milestone slugs, so it must run under bash 4 or newer. Under a non-bash POSIX shell (`sh`/dash), `declare -A` fails and the de-dupe silently no-ops. This degrades gracefully — branch creation stays correct because the `git ls-remote --exit-code` exists-check below still skips any milestone branch that already exists; the only effect is redundant, idempotent `ls-remote`/`push` attempts for milestones referenced by more than one issue in the wave. Run this command's blocks under bash 4+. <!-- Added: forge#901 -->
+
+```bash
+# Pre-create the origin milestone branch for every distinct milestone referenced by the wave.
+# Slugification MUST byte-match scripts/classify-lane.sh — otherwise a branch is created that
+# the classifier will not select. Keep these two slug pipelines identical.
+git fetch origin
+
+# Collect distinct milestone titles among the wave's issues
+declare -A SEEN_MILESTONE_SLUG
+for NUM in {wave_issue_numbers}; do
+  MILESTONE_TITLE=$(gh issue view "$NUM" -R {GH_REPO} --json milestone --jq '.milestone.title // empty' 2>/dev/null || echo "")
+  [ -z "$MILESTONE_TITLE" ] && continue  # fast-lane issue — no milestone branch needed
+
+  # Slugify — IDENTICAL to classify-lane.sh: lowercase → spaces-to-hyphens →
+  # strip non-[a-z0-9-] → collapse hyphens → strip leading/trailing hyphens.
+  SLUG=$(echo "$MILESTONE_TITLE" \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr ' ' '-' \
+    | tr -cd 'a-z0-9-' \
+    | sed 's/--*/-/g' \
+    | sed 's/^-//;s/-$//')
+
+  # Empty-slug guard (matches classify-lane.sh): a title with no ASCII letters/digits/hyphens
+  # would produce "milestone/", an invalid ref. Skip and let classify-lane surface the error.
+  if [ -z "$SLUG" ]; then
+    echo "WARN: milestone title '$MILESTONE_TITLE' (issue #$NUM) produced an empty slug — skipping pre-creation; classify-lane will hard-fail." >&2
+    continue
+  fi
+
+  # De-dupe: only attempt creation once per milestone
+  [ -n "${SEEN_MILESTONE_SLUG[$SLUG]:-}" ] && continue
+  SEEN_MILESTONE_SLUG[$SLUG]=1
+
+  LANE="milestone/$SLUG"
+  if git ls-remote --exit-code origin "$LANE" >/dev/null 2>&1; then
+    echo "Milestone branch '$LANE' already exists on origin — no action."
+    continue
+  fi
+
+  # Create-if-absent from the default branch (matches /milestone create).
+  # $DEFAULT_BRANCH is resolved from forge.yaml at the top of this command.
+  echo "Pre-creating milestone branch '$LANE' from origin/$DEFAULT_BRANCH …"
+  if git push origin "origin/$DEFAULT_BRANCH:refs/heads/$LANE" 2>/dev/null; then
+    echo "Created milestone branch '$LANE'."
+  elif git ls-remote --exit-code origin "$LANE" >/dev/null 2>&1; then
+    # A concurrent orchestrator (or an agent) created it first — harmless. Never force-push.
+    echo "Milestone branch '$LANE' was created concurrently — proceeding with the existing branch."
+  else
+    echo "ERROR: failed to pre-create milestone branch '$LANE' from origin/$DEFAULT_BRANCH." >&2
+    echo "       classify-lane.sh will hard-fail for issues in this milestone until the branch exists." >&2
+  fi
+done
+```
+
+This step is the deterministic counterpart to fix #2 (atomic create-if-absent in the classifier): by guaranteeing the branch exists before the wave's lane checks run, no agent can observe a missing branch. `classify-lane.sh`'s hard-fail is intentionally preserved as the phantom-slug gate for any path that bypasses this step.
+
 ### Step 4A.pre: Classify lane for each issue (MANDATORY before spawning agents)
 
 Before building agent prompts, run `classify-lane.sh` for every issue in the current wave to compute `{LANE}` and `{PR_BASE}` deterministically. The script output is authoritative — the LLM MUST NOT override or reason around it.
@@ -932,6 +997,62 @@ They remain open in GitHub — they will be picked up by future `/orchestrate` o
 
 **If no review-finding issues were spawned:** Continue to next wave normally.
 
+### Step 4C.5: Milestone lane-consistency check (run after each wave) <!-- Added: forge#901 -->
+
+**WHY THIS EXISTS**: A milestone's feature-lane PRs must all target the same milestone branch. If a branch-routing race ever scatters them — some on the milestone branch, some on staging — the milestone branch becomes incomplete relative to staging, and the split is otherwise invisible until the milestone tries to ship. Step 4A.pre.0 prevents the split deterministically; this check detects any residual split so it surfaces immediately instead of at ship time.
+
+**When to run**: After each wave completes, for any batch where at least one issue has a milestone. Skip for pure fast-lane batches. This check is **non-blocking** — it alerts; it does not auto-resolve or stop the pipeline.
+
+```bash
+# For each distinct milestone in the batch, assert all of its feature-lane PRs share one base.
+for NUM in {all_batch_issue_numbers}; do
+  MILESTONE_TITLE=$(gh issue view "$NUM" -R {GH_REPO} --json milestone --jq '.milestone.title // empty' 2>/dev/null || echo "")
+  [ -z "$MILESTONE_TITLE" ] && continue
+
+  SLUG=$(echo "$MILESTONE_TITLE" \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr ' ' '-' \
+    | tr -cd 'a-z0-9-' \
+    | sed 's/--*/-/g' \
+    | sed 's/^-//;s/-$//')
+  [ -z "$SLUG" ] && continue
+  EXPECTED_BASE="milestone/$SLUG"
+
+  # Collect the base branch of every PR that closes an issue in this milestone.
+  # Iterate the milestone's issues and read each one's linked PR base.
+  # Exclude CLOSED-unmerged PRs: a closed-but-not-merged PR is a superseded/abandoned
+  # routing attempt and does NOT reflect the live lane. Keep only OPEN (in-flight) and
+  # MERGED (landed) PRs. `gh pr list --state` cannot combine open+merged, so query all
+  # and drop CLOSED in jq.
+  BASES=$(gh pr list -R {GH_REPO} --state all --search "milestone:\"$MILESTONE_TITLE\"" \
+    --json baseRefName,state --jq '.[] | select(.state != "CLOSED") | .baseRefName' 2>/dev/null | sort -u)
+  # Fallback: if PR search by milestone is unavailable, derive from the issues' linked PRs.
+  if [ -z "$BASES" ]; then
+    BASES=$(for IN in {all_batch_issue_numbers}; do
+      IM=$(gh issue view "$IN" -R {GH_REPO} --json milestone --jq '.milestone.title // empty' 2>/dev/null)
+      [ "$IM" = "$MILESTONE_TITLE" ] || continue
+      gh pr list -R {GH_REPO} --state all --search "$IN in:body" \
+        --json baseRefName,state --jq '.[] | select(.state != "CLOSED") | .baseRefName' 2>/dev/null
+    done | sort -u)
+  fi
+
+  STRAY_BASES=$(echo "$BASES" | grep -v "^${EXPECTED_BASE}\$" | grep -v '^$' || true)
+  if [ -n "$STRAY_BASES" ]; then
+    echo "ALERT: milestone '$MILESTONE_TITLE' has feature-lane PRs split across multiple base branches." >&2
+    echo "       Expected base: $EXPECTED_BASE" >&2
+    echo "       Found bases:" >&2
+    echo "$BASES" | sed 's/^/         - /' >&2
+    echo "       This indicates a branch-routing split — reconcile the stray PRs onto $EXPECTED_BASE" >&2
+    echo "       (rebase/cherry-pick the stray branch onto the milestone branch) before the milestone ships." >&2
+    # Do NOT auto-stop or auto-resolve — surface the alert and let the user decide.
+  else
+    echo "Lane-consistency OK: all '$MILESTONE_TITLE' PRs target $EXPECTED_BASE."
+  fi
+done
+```
+
+Report any `ALERT` lines prominently before advancing to the next wave. Reconciliation of an existing split is a manual/`/milestone`-assisted step — this check only ensures the split is never silent.
+
 ### Step 4D: Milestone integration build gate (MANDATORY between waves)
 
 **WHY THIS EXISTS**: Session Intelligence milestone shipped 116 PRs across multiple waves with zero integration testing. Each PR built in isolation — type errors from cross-PR interactions (wrong prop types, missing components, incompatible interfaces) were invisible until the milestone→staging merge broke the build with 4 distinct errors. This gate catches those failures early.

package/commands/{resume.md → pipeline-resume.md}

@@ -3,7 +3,7 @@ description: Recover full pipeline context after compaction — find the last ac
 argument-hint: [issue number (optional — auto-detects if omitted)]
 ---
 
-# /resume — Context Recovery After Compaction
+# /pipeline-resume — Context Recovery After Compaction
 
 **Input**: $ARGUMENTS
 
@@ -110,7 +110,7 @@ for NUMBER in $(echo "$RECENT_ISSUES" | jq -r '.number'); do
 done
 ```
 
-If still no candidate: display `No recent active issues found. To resume work on a specific issue, run: /resume {issue-number}` and STOP.
+If still no candidate: display `No recent active issues found. To resume work on a specific issue, run: /pipeline-resume {issue-number}` and STOP.
 
 ---
 
@@ -247,7 +247,7 @@ Invoke `/work-on` to re-enter the pipeline. Work-on reads GitHub state independe
 Skill("work-on", args="{TARGET_NUMBER}")
 ```
 
-**Why delegation works**: `/work-on` Phase 0B already implements "Determine resume point" — it reads issue labels and FORGE annotations to route to the correct phase. `/resume` provides the human-readable context summary, then hands off to `/work-on` for execution.
+**Why delegation works**: `/work-on` Phase 0B already implements "Determine resume point" — it reads issue labels and FORGE annotations to route to the correct phase. `/pipeline-resume` provides the human-readable context summary, then hands off to `/work-on` for execution.
 
 **Do NOT re-implement pipeline logic here.** The context summary above is for the agent's working memory only — the actual phase routing and execution is owned by `/work-on`.
 
@@ -258,7 +258,7 @@ Skill("work-on", args="{TARGET_NUMBER}")
 | Condition | Response |
 |-----------|----------|
 | `forge.yaml` missing | Stop: "Run \`npx forgedock init\` to generate forge.yaml" |
-| No active issues + no FORGE annotations found | Stop: "No recent active issues found. Run \`/resume {number}\` with an explicit issue number, or \`/work-on next\` to start a new issue." |
+| No active issues + no FORGE annotations found | Stop: "No recent active issues found. Run \`/pipeline-resume {number}\` with an explicit issue number, or \`/work-on next\` to start a new issue." |
 | Issue is closed with `workflow:merged` | Stop: "Issue #{number} is already merged. Nothing to resume." |
 | Issue is closed with `workflow:invalid` | Stop: "Issue #{number} was closed as invalid. Nothing to resume." |
 | Issue has `needs-human` label | Stop: "Issue #{number} is blocked (needs-human). Review the blocking comment and resolve it manually before resuming." |

package/commands/{status.md → pipeline-status.md}

@@ -3,7 +3,7 @@ description: Pipeline-wide situational awareness — groups open issues by workf
 argument-hint: [--repo <owner/repo> | --stale-days <N>]
 ---
 
-# /status — Pipeline Status
+# /pipeline-status — Pipeline Status
 
 **Input**: $ARGUMENTS (optional: `--repo <owner/repo>`, `--stale-days <N>`)
 

package/commands/qa-sweep.md

@@ -16,9 +16,26 @@ You are the QA orchestrator. Auto-discover every page across the platform (dashb
 
 ---
 
+## Playwright MCP Prerequisite (MANDATORY — check before proceeding)
+
+Playwright MCP is a **guaranteed ForgeDock dependency** for all browser automation commands. Before running any qa-sweep phase, verify it is available:
+
+**Check**: Confirm `mcp__playwright__*` tools are available in your tool context (e.g., `mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`).
+
+**If Playwright MCP tools are NOT available**: STOP immediately. Do not attempt to run qa-sweep — all browser automation steps will fail silently.
+
+**Fix**:
+1. Register Playwright MCP: `claude mcp add playwright npx @playwright/mcp@latest`
+2. Restart Claude Code to reload MCP servers
+3. Verify with: `npx forgedock doctor` (Check 9 confirms registration)
+
+See README.md Requirements section for full setup instructions.
+
+---
+
 ## Browser Tool Reference
 
-All browser automation uses Playwright MCP tools (`mcp__playwright__*`).
+All browser automation uses Playwright MCP tools (`mcp__playwright__*`). Playwright MCP is a guaranteed ForgeDock dependency — see the Playwright MCP Prerequisite section above.
 
 | Action | Tool | Key param |
 |--------|------|-----------|
@@ -97,7 +114,25 @@ Depth-first, workflow-driven:
 
 ## Phase 0: Setup & Auth
 
-**Load config from forge.yaml** before running any checks:
+**Playwright MCP prerequisite guard** — run BEFORE loading forge.yaml config:
+
+Confirm `mcp__playwright__browser_navigate` (or any `mcp__playwright__*` tool) is available in your tool context. If Playwright MCP tools are absent:
+
+```
+STOP. Playwright MCP is not registered in this Claude Code session.
+
+Register it with:  claude mcp add playwright npx @playwright/mcp@latest
+Then restart Claude Code and run /qa-sweep again.
+
+Verify installation with: npx forgedock doctor (Check 9 confirms Playwright MCP status)
+See: README.md Requirements section for full setup instructions.
+```
+
+Do not proceed past this guard if Playwright MCP tools are unavailable — all browser automation steps will fail silently without clear error messages.
+
+---
+
+**Load config from forge.yaml** after confirming Playwright MCP is available:
 
 ```bash
 QA_CONFIG=$(python3 - <<'PYEOF'