forgedock 1.0.16 → 1.0.18

package/docs/BRAND.md

@@ -0,0 +1,51 @@
+# ForgeDock Brand Handles
+
+Status of reserved and blocked brand handles across platforms.
+
+## Domain
+
+| Domain | Status |
+|--------|--------|
+| `forgedock.dev` | **Owned** — canonical marketing and App URL |
+
+## npm
+
+| Package | Status |
+|---------|--------|
+| `forgedock` | **Owned** — published AGPL CLI at https://www.npmjs.com/package/forgedock |
+
+No action needed. The package name was claimed on first publish.
+
+## GitHub Organization
+
+| Slug | Status |
+|------|--------|
+| `forgedock` | **Blocked** — parked org created 2024-05-23, not administered by RapierCraft Studios |
+
+The bare `forgedock` org slug cannot be used for the ForgeDock GitHub App name — GitHub
+slugifies App display names and rejects collisions with existing user/org accounts.
+
+**Recommended App slug**: `forgedock-ai` (or `forgedock-app`). The App ID in use during
+development is **3978349** (registered under RapierCraftStudios with `public: false`).
+Update the display name and slug when the L2 central public App launches.
+
+## Social Handles
+
+| Platform | Handle | Status |
+|----------|--------|--------|
+| X / Twitter | `@forgedock` | Check and reserve if available |
+| Bluesky | `forgedock.bsky.social` | Check and reserve if available |
+| LinkedIn | `forgedock` company page | Check and reserve if available |
+| Product Hunt | `forgedock` | Reserve at launch |
+
+Social handle registration is an operational task. Reserve handles before public launch
+(L1 milestone) to prevent squatting. The public App launch (L2) is gated on L1 completion.
+
+## Summary
+
+| Platform | Action |
+|----------|--------|
+| Domain | Done |
+| npm | Done |
+| GitHub org slug | Blocked — use variant for App slug |
+| Social handles | Reserve before L1 public launch |

package/docs/CI.md

@@ -0,0 +1,177 @@
+# CI Integration — ForgeDock PR Review in GitHub Actions
+
+This guide explains how to integrate ForgeDock's `/review-pr` pipeline into GitHub Actions so every PR gets automatic multi-domain AI review without requiring a manual Claude Code session.
+
+<!-- publish trigger: bot-token merges do not fire path-filtered workflows -->
+
+---
+
+## What This Does
+
+The `forgedock-review.yml` workflow template triggers on every pull request (opened, synchronized, or reopened) and runs ForgeDock's full review pipeline:
+
+- Security, auth, billing, database, concurrency, frontend, API, performance, and infrastructure agents all review the PR diff
+- Review findings are posted as comments on the PR
+- Each finding becomes a tracked GitHub issue in your repository
+- No human needs to remember to run `/review-pr` — it happens automatically
+
+---
+
+## Prerequisites
+
+1. **Anthropic API key** — Claude Code runs against the Anthropic API. Get one at [console.anthropic.com](https://console.anthropic.com).
+2. **ForgeDock installed** — The workflow installs ForgeDock automatically via `npx forgedock install`.
+3. **GitHub Actions enabled** — Standard for all public repos; enabled by default for private repos.
+
+---
+
+## Setup
+
+### 1. Add the API key as a repository secret
+
+In your repository: **Settings → Secrets and variables → Actions → New repository secret**
+
+| Name | Value |
+|------|-------|
+| `ANTHROPIC_API_KEY` | Your Anthropic API key (`sk-ant-...`) |
+
+Never commit the API key to your repository. GitHub Actions masks secrets in logs, but only secrets stored via Settings are protected.
+
+### 2. Copy the workflow template
+
+Copy `templates/workflows/forgedock-review.yml` from your ForgeDock installation to your repository:
+
+```bash
+# From your repository root
+mkdir -p .github/workflows
+cp "$(npx forgedock which-dir)/templates/workflows/forgedock-review.yml" .github/workflows/forgedock-review.yml
+```
+
+Or copy it manually — the file is in `~/.claude/commands/../templates/workflows/forgedock-review.yml` after running `npx forgedock install`.
+
+### 3. Commit and push
+
+```bash
+git add .github/workflows/forgedock-review.yml
+git commit -m "feat(ci): add ForgeDock automated PR review workflow"
+git push
+```
+
+The workflow activates immediately. Open or synchronize any PR to trigger the first review.
+
+---
+
+## Security Model
+
+### API key handling
+
+The `ANTHROPIC_API_KEY` is passed exclusively via the `env:` block in the workflow YAML. It is never:
+- Echoed to logs with `echo` or `printf`
+- Passed as a CLI argument (visible in process lists)
+- Written to disk during the workflow run
+
+GitHub Actions masks the secret value in all log output automatically.
+
+### GITHUB_TOKEN scope
+
+The workflow uses the built-in `GITHUB_TOKEN`, which is:
+- Automatically provided by GitHub Actions for every workflow run
+- Scoped to the repository
+- Revoked after the workflow run completes
+- Constrained to `contents: read` and `pull-requests: write` by the `permissions:` block
+
+No additional tokens or personal access tokens are required.
+
+### Runner isolation
+
+Each workflow run uses a fresh ephemeral GitHub-hosted runner (`ubuntu-latest`). The `--dangerously-skip-permissions` flag passed to Claude Code is safe in this context because:
+- The runner is discarded after the job completes
+- No persistent state is left behind
+- The workflow's `permissions:` block constrains what the `GITHUB_TOKEN` can do
+
+---
+
+## Fork PR Limitation
+
+**Pull requests from forks do not have access to repository secrets.**
+
+This is a GitHub security restriction: a forked repository's PR cannot read secrets from the upstream repository's Settings. The `pull_request` event that triggers this workflow will have `ANTHROPIC_API_KEY` as an empty string for fork PRs, and the Claude Code step will fail silently or error.
+
+### Option 1: Accept the limitation (recommended for open-source repos)
+
+Leave the workflow as-is. Team members' PRs get reviewed automatically. External contributor PRs are reviewed manually when a maintainer runs `/review-pr` in Claude Code.
+
+### Option 2: Use `pull_request_target` (advanced — security implications)
+
+`pull_request_target` runs in the context of the base repository (not the fork), so secrets are available. However, it also runs untrusted code from the fork in a privileged context, which is a security risk if the workflow checks out and runs code from the fork.
+
+If you use `pull_request_target`, you MUST:
+1. Never check out the fork's code and run it
+2. Scope what Claude Code can access carefully
+3. Review the [GitHub security hardening guide for `pull_request_target`](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/)
+
+This is not recommended without understanding the security implications.
+
+---
+
+## Customization
+
+### Skip review for certain PRs
+
+Add conditions to the `if:` field on the job:
+
+```yaml
+# Skip bot PRs and draft PRs
+if: |
+  github.actor != 'dependabot[bot]' &&
+  github.actor != 'github-actions[bot]' &&
+  github.event.pull_request.draft == false
+```
+
+### Target only certain branches
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches:
+      - main
+      - staging
+      - 'milestone/**'
+```
+
+### Pass additional flags to /review-pr
+
+The `claude --print` invocation accepts `/review-pr` arguments. For example, to skip auto-merge (default) or pass a custom flag:
+
+```yaml
+run: |
+  claude --print "/review-pr $PR_NUMBER --model opus" \
+    --dangerously-skip-permissions
+```
+
+### Enable commit status badge
+
+Uncomment the `Set Commit Status` step in the workflow template to add a pass/fail badge to PRs. This uses the GitHub API via `actions/github-script` to post a commit status after the review completes.
+
+---
+
+## Troubleshooting
+
+**Review job fails immediately with `ANTHROPIC_API_KEY not set`**
+→ The secret is not configured. Go to Settings → Secrets and variables → Actions and add `ANTHROPIC_API_KEY`.
+
+**Review passes but no comments appear on the PR**
+→ Check that `permissions: pull-requests: write` is present in the workflow. Without it, the `gh` CLI calls from `/review-pr` will receive 403 errors.
+
+**Fork PRs show empty `ANTHROPIC_API_KEY`**
+→ Expected behavior. See the Fork PR Limitation section above.
+
+**`claude: command not found`**
+→ The `npm install -g @anthropic-ai/claude-code` step failed. Check the job logs. The `ubuntu-latest` runner includes Node.js but the global npm install may fail if the runner's Node version is too old. Ensure the `Set up Node.js` step runs first and targets Node.js 18+.
+
+**`npx forgedock install` reports `command not found: forgedock`**
+→ `npx forgedock install` runs the installer from npm. If it fails, verify the ForgeDock package name is correct: `npm show forgedock version` should return a version number.
+
+**`claude: unknown flag --output-format` or similar unrecognized flag error**
+→ Your local Claude Code installation is outdated. The `--output-format` flag is available in all recent versions of Claude Code. Run `npm update -g @anthropic-ai/claude-code` to update to the latest version. Note: the workflow template itself no longer passes `--output-format` (the flag was redundant — `--print` defaults to text output). If you copied the template before this fix, remove the `--output-format text` line from your workflow file.

package/docs/CONFIG.md

@@ -41,6 +41,7 @@ The default (`npx forgedock init` with no flags) remains the zero-question autop
 | [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
 | [`verification`](#verification-optional) | No | Health-check patterns |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
+| [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
 
 ---
 
@@ -330,14 +331,38 @@ Run `npx forgedock docs init` to scaffold the tree from ForgeDock's seed templat
 ```yaml
 devdocs:
   path: "devdocs"
+  # index_path: "devdocs/index.yaml"   # optional; defaults to {path}/index.yaml
 ```
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `path` | string (relative path) | No | Path to the devdocs tree, relative to project root. Default: `devdocs`. |
+| `index_path` | string (relative or absolute path) | No | Path to the selective loading index file. Default: `{path}/index.yaml`. When the index file exists at this path, agents read it first (~400 tokens) and load only docs whose domain matches the current issue's labels. When absent, agents fall back to loading all docs with `applies_to: work-on` (backward compatible). Scaffold the index with `npx forgedock docs init`. |
 
 **Commands that use this section**: `docs init`, `work-on/build/context` (Phase C-1), `work-on/build/architect` (Phase A0)
 
+### Selective Loading (index.yaml)
+
+When `devdocs/index.yaml` exists, agents use **domain-filtered selective loading** instead of reading all applicable devdocs:
+
+1. Read `index.yaml` (~400 tokens)
+2. Extract issue labels (e.g. `billing`, `infra`, `auth`)
+3. Load only docs in matching domains + all `always_load` entries
+4. When no labels match any domain key: load only `always_load` entries
+
+**Domain matching**: GitHub issue labels map directly to domain keys in `index.yaml`. For example, a label `billing` matches `domains.billing`. Prefixes like `workflow:`, `priority:`, and `review-finding` are stripped before matching.
+
+**`always_load` entries** are loaded for every task regardless of domain. Use for `project/custom-instructions.md` and other files every agent must read.
+
+**Token savings**: A typical task loads 1-3 docs (~1,500-3,000 tokens) instead of all docs (~8,000-12,000 tokens). The index itself costs ~400 tokens — break-even at 1 file avoided.
+
+**Backward compatibility**: If `index.yaml` is absent, behavior is unchanged — all docs with `applies_to: work-on` are loaded. No migration required for existing devdocs trees.
+
+Scaffold the index with:
+```bash
+npx forgedock docs init
+```
+
 ### Migration from `review.context`
 
 If you previously stored project context in `forge.yaml → review.context`, move that content into the appropriate devdocs file after running `npx forgedock docs init`:
@@ -431,6 +456,75 @@ billing:
 
 ---
 
+## `adaptive_scripts` (OPTIONAL)
+
+Per-repo script override configuration. Controls whether ForgeDock looks for project-specific scripts in `.forgedock/scripts/` before falling back to universal scripts.
+
+```yaml
+adaptive_scripts:
+  enabled: true
+  directory: ".forgedock/scripts"
+  commit: false
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | boolean | No | `true` | When `true`, pipeline agents check `.forgedock/scripts/` for a per-repo script before using the universal one. Set to `false` to disable per-repo overrides entirely and always use universal scripts. |
+| `directory` | string (relative path) | No | `".forgedock/scripts"` | Directory where per-repo adaptive scripts live, relative to the project root. Scaffolded by `npx forgedock init`. |
+| `commit` | boolean | No | `false` | When `false`, `.forgedock/scripts/` is `.gitignore`d — scripts are local-only and not shared with the team. Set to `true` (and remove the `.gitignore` entry) to commit per-repo scripts to version control. |
+
+**Commands that use this section**: `work-on` (Phase 0B script resolution), any pipeline command that calls a deterministic script
+
+### Script Precedence
+
+ForgeDock resolves which script handles each operation using a strict 4-level hierarchy (highest to lowest authority):
+
+```
+1. forge.yaml → learned: (machine-captured corrections)        ← highest
+2. .forgedock/scripts/{operation}.sh  (per-repo adaptive)
+3. scripts/{operation}.sh             (universal, ships with npm)
+4. Prose instructions in command specs (fallback)              ← lowest
+```
+
+### Override Semantics
+
+- **Per-repo scripts completely replace** the universal script for that operation — there is no partial inheritance or merging.
+- **Per-repo scripts may call universal scripts** via the `$FORGEDOCK_SCRIPTS/{operation}.sh` path. Every universal script exports `FORGEDOCK_SCRIPTS` (absolute path to the universal scripts directory) and `FORGEDOCK_HOME` (absolute path to the ForgeDock installation root) so that per-repo scripts can delegate back to them.
+- **No circular dependencies**: per-repo scripts may call universal scripts but must NOT call other per-repo scripts. One level of delegation only.
+- **`forge.yaml → learned:`** overrides take precedence over everything. They represent explicit user corrections captured by the pipeline.
+
+### Example: per-repo script that delegates to universal
+
+```bash
+#!/usr/bin/env bash
+# .forgedock/scripts/classify-lane.sh
+# Override: this repo uses 'develop' instead of 'staging' for the fast lane.
+
+set -euo pipefail
+
+# Delegate to universal classify-lane.sh to get the standard result
+UNIVERSAL_RESULT=$(bash "$FORGEDOCK_SCRIPTS/classify-lane.sh" "$@")
+
+# Override only the fast-lane output for this project
+if [ "$UNIVERSAL_RESULT" = "staging" ]; then
+  echo "develop"
+else
+  echo "$UNIVERSAL_RESULT"
+fi
+```
+
+### Logging
+
+When a pipeline agent resolves a script tier, it logs the result in the FORGE annotation:
+
+```
+Script tier: adaptive (.forgedock/scripts/classify-lane.sh)
+Script tier: universal (scripts/classify-lane.sh)
+Script tier: prose (no script found — using spec instructions)
+```
+
+---
+
 ## Label Bootstrap
 
 ForgeDock manages a canonical set of GitHub labels for use across all pipeline commands. Labels cover workflow state, priority, review findings, audit findings, and category classification.

package/docs/FORGE-PROTOCOL.md

@@ -398,6 +398,330 @@ gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
 
 ---
 
+### Design Pipeline Annotations
+
+These annotations drive the UI Taste Harness — the design-generation pipeline that produces a landing page from a design-blind product brief. They carry design intent across the architect → generate → critique → close stages, exactly as the issue-pipeline annotations carry code-context across investigate → build → review.
+
+---
+
+#### `FORGE:DESIGN_CONTEXT`
+
+**Phase**: Design — Investigate (`/design` stage 1, #888) — the first `FORGE:DESIGN_*` annotation in the chain
+**Written by**: `/design` design-investigate stage
+**Read by**: Design-architect stage (grounds the rationale), Close phase (audit trail)
+**Location**: Issue comment
+
+The design analog of `FORGE:CONTEXT`: the parsed brief (message / audience / single objection), the grammar pulled
+from the [reference corpus](design/reference-corpus.md) (#880), and the recent signature moves / archetypes / palettes
+pulled from [design-memory](design/design-memory.md) (#887) that this design must **diverge** from. Opens the
+`FORGE:DESIGN_*` chain that `FORGE:DESIGN_RATIONALE` → `FORGE:DESIGN_CANDIDATES` → `FORGE:DESIGN_SPEC` → `FORGE:CRITIQUE`
+→ `FORGE:DESIGN_SHIPPED` continues. See [`commands/design.md`](../commands/design.md).
+
+**Schema**:
+
+```markdown
+<!-- FORGE:DESIGN_CONTEXT -->
+## Design Context — {product}
+
+**Message:** {one thing the page must say}
+**Audience / objection:** {who} — must overcome: {objection}
+**Corpus grammar:** {relevant traits / archetype priors from #880}
+**Diverge from (memory):** {recent signature moves / archetypes / palettes to avoid — #887}
+<!-- FORGE:DESIGN_CONTEXT:COMPLETE -->
+```
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:DESIGN_CONTEXT")) | .body'
+```
+
+---
+
+#### `FORGE:DESIGN_RATIONALE`
+
+**Phase**: Design — Architecture (design-architect, #886) — emitted *before* `FORGE:DESIGN_SPEC`
+**Written by**: Design-architect agent
+**Read by**: Generate agent (the spec it produces), render → vision-critique loop (#882), and a non-designer reviewer (the reasoning is reviewable without judging pixels)
+**Location**: Issue comment
+
+The designer's diary — the reasoning-before-generation step. Captures the seven-element chain of thought (intent/feeling, audience/objection, communication hierarchy, direction + rejected alternatives, signature move, what's being tried this time, non-goals) and **produces** the `FORGE:DESIGN_SPEC` rather than letting the spec appear from nowhere. The format is the structured contract: it MUST carry at least one explicitly **rejected alternative**, a named **signature move**, and a **produces-DESIGN_SPEC link**. See [`docs/design/design-architect-rationale.md`](design/design-architect-rationale.md) for the full doctrine.
+
+**Schema**:
+
+```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 {…})
+**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}
+```
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:DESIGN_RATIONALE")) | .body'
+```
+
+---
+
+#### `FORGE:DESIGN_CANDIDATES`
+
+**Phase**: Design — Divergent generation (#883) — emitted *after* `FORGE:DESIGN_RATIONALE`, *before* `FORGE:DESIGN_SPEC`
+**Written by**: Generate agent (divergent-generation step)
+**Read by**: Taste-judge (selects the winner), Close phase (audit trail), design-memory (#887, to diverge from past winners)
+**Location**: Issue comment
+
+The variance lever's audit record: the one **committed archetype** (one of the five corpus ids — #880, never blended),
+the **N distinct directions** generated within it, and the **independent taste-judge's** scores + selection. The
+winner hands off into `FORGE:DESIGN_SPEC`. The selection judge is deliberately distinct from the critique loop (#882)
+and the benchmark judge (#878) — anti-Goodhart. See [`docs/design/divergent-generation.md`](design/divergent-generation.md).
+
+**Schema**:
+
+```markdown
+<!-- FORGE:DESIGN_CANDIDATES -->
+## Design Candidates — {product}
+
+**Archetype (committed):** {one of the 5 corpus ids}
+**Directions:**
+1. {concept} — signature: {move} — {distinguishing grammar/tokens}
+2. {concept} — signature: {move} — {…}
+**Judge scores:** 1) {score} 2) {score} …
+**Selected:** #{n} — because {reason}
+
+→ Winner produces DESIGN_SPEC: {link}
+```
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:DESIGN_CANDIDATES")) | .body'
+```
+
+---
+
+#### `FORGE:DESIGN_SPEC`
+
+**Phase**: Design — Architecture (design-architect, #886)
+**Written by**: Design-architect agent
+**Read by**: Generate agent (constrains output), deterministic anti-slop linter (#884), render → vision-critique loop (#882), Close phase agent (persists realized spec to design-memory, #887)
+
+A structured, **machine-checkable** representation of one page's design language. Carried across design-pipeline stages as a `FORGE:DESIGN_SPEC` annotation so taste decisions **persist** instead of being re-rolled per generation, and so a deterministic linter and a vision critic both check the rendered output against the *same* committed intent.
+
+Critically, the spec is **produced by** a `FORGE:DESIGN_RATIONALE` (the reasoning) — not authored from nowhere. The flow is rationale → spec → page.
+
+The full field-by-field schema (JSON shape, the per-field slop-tell defense table, and the lifecycle) lives in [`design/design-spec-schema.md`](design/design-spec-schema.md). The annotation body embeds that schema as a fenced `jsonc` block.
+
+**Schema** (annotation envelope):
+
+````
+<!-- FORGE:DESIGN_SPEC -->
+## Design Spec — {product}
+
+```jsonc
+{
+  "meta":          { "product": "…", "archetype": "…", "corpus_version": "…", "rationale_ref": "…" },
+  "typography":    { "display_family": "…", "body_family": "…", "scale_ratio": …, "weights": […] },
+  "color":         { "mode": "…", "background": "#…", "foreground": "#…", "accent": "#…",
+                     "rules": ["no-default-tailwind-palette", "contrast>=4.5"] },
+  "spacing":       { "base_unit_px": …, "scale": […] },
+  "radius":        { "scale": […] },
+  "shadow":        { "tokens": […] },
+  "motion":        { "vocabulary": […], "reduced_motion": "required" },
+  "layout_grammar":{ "sections": [ { "id": "…", "purpose": "…", "density": "…" } ], "rhythm": "…" },
+  "effects_plan":  { "per_section": [ … ], "budget": { … }, "never": [ … ] }, // doctrine: docs/design/effects-appropriateness.md (#885)
+  "negatives":     [ … ],
+  "acceptance":    { "perf_budget": { … }, "a11y": { … }, "divergence_ref": "…" }
+}
+```
+
+→ Produced by FORGE:DESIGN_RATIONALE: {link}
+````
+
+**Field reference**: see [`design/design-spec-schema.md`](design/design-spec-schema.md) for the complete schema, the "How each field defends against slop" table, and the lifecycle.
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:DESIGN_SPEC")) | .body'
+```
+
+---
+
+#### `FORGE:CRITIQUE`
+
+**Phase**: Design — Render → vision-critique loop (`/design-render-critique-loop`, #882) — after `FORGE:DESIGN_SPEC`
+**Written by**: Vision-critique loop (one per iteration)
+**Read by**: The iterate step (consumes its own findings), Close phase (improvement trajectory audit), `/design` (#888)
+**Location**: Issue comment
+
+One annotation per render→critique iteration — the page's improvement trajectory as an auditable trail. Records the
+deterministic lint floor result (#884), the desktop+mobile render, the perceptual findings (N3, N8–N12 — the negatives
+the linter declares out of scope), and the verdict (`PASS` | `ITERATE` | `BUDGET-EXHAUSTED`). The critic is strictly
+independent from the ABC benchmark judge (#878) — anti-Goodhart. See
+[`docs/design/render-critique-loop.md`](design/render-critique-loop.md).
+
+**Schema**:
+
+```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 -->
+```
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CRITIQUE")) | .body'
+```
+
+---
+
+#### `FORGE:USER_FEEDBACK`
+
+<!-- Added: forge#1044 — user-feedback loop -->
+
+**Phase**: Design — User-feedback loop (`/design` stage 4.5, #1044) — after `FORGE:CRITIQUE`, before `FORGE:DESIGN_SHIPPED`
+**Written by**: `/design` user-feedback stage (Stage 4.5) — records structured user input after the automated critique loop
+**Read by**: Surgical re-generation step (same stage 4.5, consumes `section_target` + `modification`), Close phase (audit trail of user-driven changes)
+**Location**: Issue comment
+
+The structured record of one user-feedback round in Stage 4.5 of the `/design` pipeline. Posted once per feedback
+exchange — there may be multiple `FORGE:USER_FEEDBACK` annotations on a single issue if the user iterates several
+times. Each annotation carries a `section_target` (the section ID from `layout_grammar.sections` to re-generate), the
+`feedback_type` (asset / emotion / direction / freeform), any asset URL, the structured modification derived from the
+feedback, and a `satisfied` flag indicating whether the user is done iterating.
+
+The annotation is **not produced** in automated (benchmark) runs — Stage 4.5 is bypassed when no user is present.
+See [`docs/design/design-spec-schema.md`](design/design-spec-schema.md) for the section modularity contract that
+governs surgical re-generation. See [`commands/design.md`](../commands/design.md) for the full Stage 4.5 procedure.
+
+**Constraint**: `FORGE:USER_FEEDBACK` may modify a section's visual execution but MUST NOT change the committed
+`meta.archetype` or the signature move from `FORGE:DESIGN_RATIONALE` — those choices are locked once the spec is
+committed in Stage 2.
+
+**Schema**:
+
+````markdown
+<!-- FORGE:USER_FEEDBACK -->
+## User Feedback — {product} · round {n}
+
+**Section target:** {section ID from layout_grammar.sections, e.g. "hero" | "all" for page-wide feedback}
+**Feedback type:** {asset | emotion | direction | freeform}
+**Asset URL:** {URL or "none"}
+**Modification:** {structured description of what to change — derived from user's natural-language input}
+**Emotion target:** {trust | speed | power | craft | play | unchanged} — maps to motion vocabulary
+**Satisfied:** {yes | no — "no" loops back to 4.5 after re-generation}
+**Freeform notes:** {verbatim user input not captured in the structured fields above}
+<!-- FORGE:USER_FEEDBACK:COMPLETE -->
+````
+
+**Field notes**:
+- `section_target`: must match an `id` in the committed `FORGE:DESIGN_SPEC → layout_grammar.sections`. Use `"all"` only for page-wide color/typography changes that cannot be scoped to one section.
+- `feedback_type`: `asset` = user provided a URL (video/logo/image/colors); `emotion` = user described a feeling to change; `direction` = user described a layout or composition change; `freeform` = catch-all for input that doesn't fit the above.
+- `modification`: the parsed, actionable version of the user's words — e.g., user says "make the hero feel more urgent" → modification: `"increase motion intensity in hero scroll-reveal; tighten headline tracking"`.
+- `satisfied: yes` means no further feedback iteration — proceed to Stage 5 (design-close).
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:USER_FEEDBACK"))] | last | .body'
+```
+
+---
+
+#### `FORGE:BENCH_SCORECARD`
+
+**Phase**: Design — Benchmark (`/design-bench`, #878)
+**Written by**: Benchmark rig (`/design-bench` command)
+**Read by**: Harness developers (the fitness signal — "did arm A's win-rate vs C go up?"), milestone tracker, pipeline-health
+
+The result of one ABC benchmark run. Arm A is the ForgeDock harness output, arm B is a raw one-shot model, and arm C is the real reference page (gold standard). The annotation carries the **win-rate of each arm against C**, the **A-vs-B harness delta**, rubric **distributions** (mean + stdev) across n runs, mean slop counts, and the **judge-calibration check** (C must beat A and B; otherwise the judge is miscalibrated and the result is suspect).
+
+The scorecard is the fitness function for the UI Taste Harness milestone — it is built before the harness so each lever the harness adds is a measurable hypothesis. The methodology (three arms, same-model rule, three-layer judging, n>=3) lives in [`design/abc-benchmark.md`](design/abc-benchmark.md); the deterministic aggregator is [`../scripts/bench-scorecard.mjs`](../scripts/bench-scorecard.mjs).
+
+Two invariants this annotation encodes: **n>=3** (taste output is high-variance — distributions, never a single number) and **judge independence** from the harness critique loop (#882) (anti-Goodhart).
+
+**Schema** (annotation envelope):
+
+````
+<!-- FORGE:BENCH_SCORECARD -->
+## ABC Benchmark Scorecard
+
+**Corpus version**: {ver} · **Generation model (A & B)**: {model} · **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 from bench-scorecard.mjs}
+```
+
+<!-- FORGE:BENCH_SCORECARD:COMPLETE -->
+````
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:BENCH_SCORECARD")) | .body'
+```
+
+---
+
+#### `FORGE:DESIGN_SHIPPED`
+
+**Phase**: Design — Close (`/design` stage 5, #888) — the terminal `FORGE:DESIGN_*` annotation
+**Written by**: `/design` design-close stage
+**Read by**: [design-memory](design/design-memory.md) (#887, persists the realized outcome), milestone tracker, pipeline-health
+**Location**: Issue comment
+
+Closes the design pipeline. Posted only when the design passes the full definition of done — critique-rubric threshold,
+perf budget (#875), a11y check, and the divergence check (#887). Records the final scorecard and the realized outcome
+(archetype, signature move, palette/type/effects, learnings) that is written to design-memory so the *next* design can
+diverge from it. The design analog of closing a code issue at `workflow:merged`; its label is `design:shipped` (the
+rejected counterpart is `design:rejected`, set without this annotation). See [`commands/design.md`](../commands/design.md).
+
+**Schema**:
+
+```markdown
+<!-- FORGE:DESIGN_SHIPPED -->
+## Design Shipped — {product}
+
+**Archetype:** {committed id} · **Signature move:** {the hook}
+**Gates:** rubric {pass} · perf {pass} · a11y {pass} · divergence {distinct from prior — #887}
+**Critique iterations:** {n}
+**Written to memory:** {palette/type/effects/learnings summary}
+<!-- FORGE:DESIGN_SHIPPED:COMPLETE -->
+```
+
+**Detection query**:
+```bash
+gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:DESIGN_SHIPPED")) | .body'
+```
+
+---
+
 ### Orchestration / Milestone Annotations
 
 These annotations transfer investigation context across issue boundaries in decomposed or multi-issue milestone workflows.