forgedock 1.0.16 → 1.0.18

package/docs/articles/selective-spec-loading-token-savings.md

@@ -0,0 +1,140 @@
+---
+title: "Selective Spec Loading: Measured Token Savings From a Self-Map of Command Specs"
+description: "ForgeDock symlinks ~27 command specs (~1.1 MB) into every Claude Code session. We built a queryable graph of the specs and load only the ones a task actually reaches — and measured how many tokens that saves."
+tags: ["ai", "performance", "tokens", "productivity", "opensource"]
+cover_image:
+canonical_url: https://github.com/RapierCraftStudios/ForgeDock
+published: false
+---
+
+<!-- Generated by ForgeDock pipeline — Issue #868 -->
+
+AI coding agents pay for context by the token. ForgeDock's pipeline is driven by
+markdown command specs — `work-on`, `review-pr`, `quality-gate`, and ~40 more —
+that are symlinked into `~/.claude/commands/` and therefore loaded into the model's
+context at session start, whether or not a given run ever touches them. This
+article measures that cost and quantifies how a **self-map of the specs** lets a
+run load only the specs it actually reaches.
+
+---
+
+## The Problem: The Whole Corpus Loads Even Though One Command Runs
+
+A single ForgeDock run invokes exactly one entry command — usually `work-on`.
+That command reaches a small, well-defined set of downstream specs: its own
+sub-phases (`work-on/build/*`, `work-on/review`, `work-on/close`) and the review
+orchestrator it delegates to (`review-pr`). It never reads `pipeline-health.md`,
+`geo-audit.md`, `audit.md`, `incident-response.md`, or the two dozen other
+specs that have nothing to do with the issue at hand.
+
+But all of them are present in context. Measured on the current spec set:
+
+| Metric | Value |
+|--------|-------|
+| Command spec files | 44 |
+| Total bytes | 1,104,004 |
+| Approx. tokens (1 token ≈ 4 chars) | **~276,000** |
+
+That is ~276K tokens of spec text loaded on every session — the overwhelming
+majority of which is dead weight for any single task.
+
+---
+
+## The Mechanism: A Queryable Graph of the Specs
+
+ForgeDock already builds a **spec knowledge graph** — a zero-dependency self-map
+of its own command specs (`scripts/build-spec-graph.mjs`, queried by
+`scripts/graph-query.sh`). The graph records which command *contains* which
+sub-phase, which command *requires* which devdoc, which annotation a command
+*reads* or *writes*, and so on.
+
+The graph already answered "what is the blast radius if I change node X?" via its
+`impact` query (transitive **reverse** reachability). Selective loading needs the
+mirror image: the **forward** transitive reachable set of a command. We added a
+`load-set` subcommand that does exactly that:
+
+```bash
+$ graph-query.sh load-set work-on
+["commands/review-pr.md","commands/work-on.md","commands/work-on/build.md",
+ "commands/work-on/build/architect.md","commands/work-on/build/context.md",
+ "commands/work-on/build/implement.md","commands/work-on/build/validate.md",
+ "commands/work-on/close.md","commands/work-on/decompose.md",
+ "commands/work-on/investigate.md","commands/work-on/review.md"]
+```
+
+`load-set` seeds at the command node and walks `CONTAINS` (sub-phases) and
+`REQUIRES` (devdocs) edges forward to a fixpoint, then maps the reachable nodes to
+their repo-relative file paths. It is read-only, auto-builds the graph if the
+gitignored JSON is absent, and shares the existing `impact` resolver's cycle-safe
+termination. No graph logic was reimplemented — the feature *consumes* the
+builder and query script that were already there.
+
+`work-on` Phase 0 now calls `load-set work-on` and reads **only** the returned
+paths instead of relying on the whole symlinked corpus.
+
+---
+
+## Methodology
+
+- Token counts are estimated at the standard rate of **1 token ≈ 4 characters**.
+- **Baseline (load-all)** = the byte sum of every spec under `commands/`.
+- **Selective (load-set)** = `wc -c` of just the files returned by
+  `graph-query.sh load-set <command>` for the entry command of a session.
+- Measured across **five representative sessions**, each keyed by its entry command.
+
+This mirrors the methodology used in the per-repo adaptive-scripts measurement,
+so the numbers are directly comparable.
+
+---
+
+## Baseline
+
+Every session, with the load-all corpus:
+
+| | Files | Bytes | Approx. tokens |
+|--|------:|------:|---------------:|
+| **Load-all corpus** | 44 | 1,104,004 | ~276,000 |
+
+---
+
+## Target: Per-Session Selective Load
+
+| Session (entry command) | Files | Bytes | Approx. tokens | Tokens saved vs baseline | % saved |
+|-------------------------|------:|------:|---------------:|-------------------------:|--------:|
+| `work-on` (full feature build) | 11 | 296,172 | ~74,000 | ~202,000 | **73%** |
+| `orchestrate` (multi-issue) | 14 | 390,054 | ~98,000 | ~178,000 | **65%** |
+| `review-pr` (PR review) | 1 | 64,395 | ~16,000 | ~260,000 | **94%** |
+| `quality-gate` (pre-commit) | 1 | 47,676 | ~12,000 | ~264,000 | **96%** |
+| `issue` (fast-lane triage) | 1 | 19,945 | ~5,000 | ~271,000 | **98%** |
+
+---
+
+## Savings
+
+Across the five representative sessions, selective loading removes between
+**~178,000 and ~271,000 tokens** of spec text from context — a **65%–98%**
+reduction depending on how much of the pipeline the entry command actually
+reaches. The heaviest run (`orchestrate`, which fans out to many sub-phases)
+still drops nearly two-thirds of the corpus; the lightest (`issue`) drops 98%.
+
+The win scales with breadth: the more specialized commands ForgeDock grows, the
+larger the dead-weight fraction the load-all corpus carries — and the more a run
+saves by loading only what its graph neighborhood reaches. Because the resolution
+is graph-driven and deterministic (the transitive walk lives in `jq`, not in the
+prompt), adding a new command automatically narrows the set for every *other*
+command, with no manual bookkeeping.
+
+---
+
+## How To Reproduce
+
+```bash
+# Baseline: full corpus
+find commands -name '*.md' -type f -exec cat {} + | wc -c
+
+# Selective: minimal set for a given entry command
+graph-query.sh load-set work-on | jq -r '.[]' \
+  | while read -r p; do cat "$p"; done | wc -c
+```
+
+Divide bytes by 4 for the approximate token count.

package/docs/claude-breakpoints.json

@@ -0,0 +1,47 @@
+{
+  "_comment": "claude-breakpoints.json — structured registry of known Claude Code version breakpoints. Each entry documents a version where Claude Code changed behavior that ForgeDock depends on, introduced a feature ForgeDock leverages, or broke a capability ForgeDock uses. Format is append-only and human-editable. Consumers: detectClaudeVersion() (issue #680), /compat-audit (issue #686), forgedock doctor (issue #682).",
+  "schema": {
+    "version": "Claude Code version string where the breakpoint was introduced (e.g. '2.1.157')",
+    "type": "Category of change: 'feature' | 'behavior_change' | 'compatibility' | 'deprecation'",
+    "description": "Human-readable description of what changed in Claude Code at this version",
+    "forgedock_impact": "How this change affects ForgeDock — what commands, scripts, or behaviors are affected",
+    "severity": "Impact level if a user is on this version or older: 'high' | 'medium' | 'low' | 'info'"
+  },
+  "breakpoints": [
+    {
+      "version": "2.1.157",
+      "type": "behavior_change",
+      "description": "EnterWorktree now unlocks worktrees automatically when the agent session finishes",
+      "forgedock_impact": "ForgeDock no longer needs --force on worktree cleanup commands. The cleanup phase in work-on.md can use standard git worktree remove without the force flag.",
+      "severity": "low"
+    },
+    {
+      "version": "2.1.157",
+      "type": "feature",
+      "description": "Plugins in .claude/skills are auto-loaded without requiring marketplace installation",
+      "forgedock_impact": "Symlink-based install (the original forgedock install method) remains valid but is no longer required for skill discovery. The stub file install pattern introduced in #619 is the preferred approach and works the same way.",
+      "severity": "info"
+    },
+    {
+      "version": "2.1.163",
+      "type": "compatibility",
+      "description": "requiredMinimumVersion and requiredMaximumVersion managed settings added for enterprise deployments",
+      "forgedock_impact": "ForgeDock's own version check (forgedock doctor, #682) is the OSS equivalent of this enterprise feature. No conflict — enterprise users with managed settings may have stricter version constraints than ForgeDock requires.",
+      "severity": "info"
+    },
+    {
+      "version": "2.1.172",
+      "type": "feature",
+      "description": "Sub-agents can spawn sub-agents up to 5 levels deep (increased nesting depth)",
+      "forgedock_impact": "ForgeDock's orchestrate.md uses multi-agent orchestration. The 5-level nesting limit is compatible with ForgeDock's orchestration patterns. No changes needed.",
+      "severity": "info"
+    },
+    {
+      "version": "2.1.154",
+      "type": "compatibility",
+      "description": "Native /workflows dynamic workflows introduced as a built-in Claude Code feature",
+      "forgedock_impact": "Parallel to ForgeDock's orchestrate.md. ForgeDock's approach adds GitHub persistence (FORGE: annotations, label-state machine, compaction resilience) that native /workflows lacks. Both can coexist — ForgeDock is the orchestration layer with state, not a replacement for native workflows.",
+      "severity": "info"
+    }
+  ]
+}

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).