agent-templates 0.2.0 → 0.3.0

package/CLAUDE.md

@@ -48,12 +48,13 @@ patterns/three-agent-architect-builder-reviewer/
     ├── INSTALL.md                     # how to drop the scaffold into a target repo
     ├── claude-md-snippet.md           # block to append to the target repo's CLAUDE.md
     └── .claude/
-        ├── settings.json              # PreToolUse write guard wiring
+        ├── settings.json              # PreToolUse write guard + deterministic-script allowlist
         ├── hooks/
         │   └── guard-main-session-writes.mjs
         ├── scripts/
         │   ├── publish-tickets.mjs
-        │   └── milestone-dag.mjs
+        │   ├── milestone-dag.mjs
+        │   └── deliver-ticket.mjs
         ├── workflows/
         │   ├── run-milestone.js
         │   ├── start-all.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-templates",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Catalog of multi-agent development architecture patterns - design write-ups plus drop-in scaffolding (agents, slash commands, workflows, templates).",
   "license": "MIT",
   "author": "Horace Hou",

package/patterns/three-agent-architect-builder-reviewer/README.md

@@ -67,6 +67,8 @@ Figures are transcribed from the team-finalized specification dated 2026-07-17 (
 | **Nightly grinding** — the sweep re-attempts the same unfixable issue night after night, burning tokens | Design risk of the nightly loop (not a measured incident) | Unsolved/failed issues get `nightly:escalated` and are excluded from later sweeps until a human clears the label; `maxIssues` caps each night's spend | 2026-07-17 |
 | **Autonomous misjudgment of "invalid"** — the sweep wrongly declares a real issue invalid and it gets ignored | Design risk | Invalid verdicts only **label** (`triage:invalid`) and comment with evidence — never auto-close; the morning human is the final judge; triage is instructed to prefer `needs-human` when uncertain | 2026-07-17 |
 | **CRLF workflow scripts rejected on Windows** — the Workflow tool's permission layer refuses scripts containing `\r` ("control characters that would be hidden in the approval dialog"), so `/start-milestone` and `/nightly-issues` cannot launch their workflows when git autocrlf has rewritten the installed `.js` files | `[internal]` — **first field observation**: Ruihang2017/Groundwork, Windows 11, Claude Code, 2026-07-18 (catalog issue #21; workaround used: inline `script` param with LF) | Fixed 2026-07-18: catalog ships `.gitattributes` (`* text=auto eol=lf`), `adopt.mjs` normalizes all text installs to LF regardless of source state, and E2E guards assert no `\r` in runtime files (scaffold + installs + catalog self-host) | 2026-07-18 |
+| **CRLF regression on target checkouts** — issue #21's install-time LF normalization does not survive the target repo's own git: a later `checkout`/clone with `core.autocrlf=true` re-CRLFs the installed workflow scripts, and `Workflow({name: …})` (including `start-all`'s name-resolved `run-milestone` child) is rejected again for control characters | `[internal]` — recurrence: Ruihang2017/Groundwork, Windows 11, Claude Code, 2026-07-18 (catalog issue #23; workaround used: inline `script` param with LF) | Fixed 2026-07-18: `adopt.mjs` installs/appends a `.gitattributes` in the **target repo** pinning `.claude/workflows/*.js` and `.claude/scripts/*.mjs` to `text eol=lf` (marker-checked, append-once); E2E asserts fresh install, append-to-existing, and idempotent re-run | 2026-07-18 |
+| **Workflow `args` arrive JSON-stringified** — some harness paths deliver the Workflow tool's `args` as a JSON **string**, so `Object.assign(defaults, args)` merges nothing and launch validation throws in milliseconds (`args.tickets must be a non-empty array`, `args.modules must be a non-empty array`) | `[internal]` — Ruihang2017/Groundwork, Windows 11, Claude Code, 2026-07-18 (catalog issue #23; killed the first `run-milestone` launch in 10ms and would crash `/start-all` identically) | Fixed 2026-07-18: all three workflow scripts (`run-milestone.js`, `start-all.js`, `nightly-issues.js`) parse first — `typeof args === 'string' ? JSON.parse(args) : (args \|\| {})`; E2E runs runner + start-all scenarios with stringified args end-to-end | 2026-07-18 |
 | **Harness-specific timeouts/failures** for these exact model+effort combinations | **None recorded yet** (as of 2026-07-17) | When observed: record here with harness name, conditions, and date | — |
 
 ## 5. Upstream / downstream integration
@@ -150,6 +152,9 @@ Install steps and usage modes: [scaffold/INSTALL.md](scaffold/INSTALL.md). Front
 | 2026-07-17 | Gate 1 made concrete: `/start-milestone` = the human start signal → tickets auto-published as tracker issues (`publish-tickets.mjs`, adapted from fx-eye-tracking `create-issues.mjs`; `[<id>]` title prefix as dedupe key; smoke-tested dry-run/no-CLI/usage paths) → deterministic milestone runner (`run-milestone.js` Workflow script: stage order, reviewer freshness, bounce cap, merge policy in code). Added `templates/ticket.template.md` (adapted from fx ticket discipline). Recorded the Bash guard boundary as a known pitfall. Clarified `ultracode`: a session setting (`xhigh` + automatic workflow orchestration), not a model effort level — role efforts unchanged. | Maintainer direction (Horace Hou), 2026-07-17. fx-eye-tracking conventions read the same day (read-only). Workflow tool, `.claude/workflows/`, and `ultracode` semantics verified against live docs (workflows, claude-directory, model-config — record in `scaffold/INSTALL.md`). | Horace Hou (direction) / Claude Fable 5 (write-up) |
 | 2026-07-18 | **`/start-all` shipped** (catalog issue #20; maintainer-decided semantics: failed module blocks dependents, independent branches continue in `autonomous`, any non-CLEAR stops everything in `supervised`, no cost cap, resume via closed-issue filtering): deterministic DAG script (`milestone-dag.mjs`, ticket `blocked_by` as ground truth, cycles/dangling refs are hard errors) + `start-all` workflow composing `run-milestone` per module + `/start-all` command. 19 new E2E checks (DAG fixtures incl. cycle; module-policy scenarios via stubbed child workflows). Per-ticket stages unchanged. | Maintainer answers on issue #20, 2026-07-18. | Horace Hou (decisions) / Claude Fable 5 (build) |
 | 2026-07-18 | **First field bug fixed** (catalog issue #21, reported from Ruihang2017/Groundwork through the upstream feedback channel): CRLF-rewritten workflow scripts are rejected by the Workflow tool on Windows. Fix: repo-wide `.gitattributes` (`eol=lf`), working tree renormalized (67 files), `adopt.mjs` installs all text as LF, E2E `\r` guards added. Recorded as the pattern's first true `[internal]` pitfall observation. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-19 | **Delivery made deterministic** (catalog issue #26, field report: harness safety classifiers blocked the agent-run deliver stage 3/3 after journaled CLEARs): new `.claude/scripts/deliver-ticket.mjs` — clean-tree guard, `--no-ff` merge (idempotent on re-runs, conflicts abort clean), push, tracker close with post-close verification (`--issue` or `[<id>]` title-prefix lookup), deterministic DoD, `DELIVER-SUMMARY-JSON` contract; run-milestone's deliver agent reduced to executing that one command and relaying its summary; `settings.json` gained explicit allow rules for the three deterministic scripts. E2E: new suite-deliver (12 scenarios on real temp git repos + fake CLIs). The tracker close only happens after merge AND push actually landed — a closed issue is what resume filtering treats as delivered, so closing on a failed delivery would silently drop the ticket. One DoD item relocated: the post-merge test run executes deterministically when `testCmd` is supplied (workflow arg, forwarded as `--test-cmd`; `/start-all` passes it through) and otherwise stays with `/verify-delivery` — builder and reviewer both already ran tests on the branch. Per-ticket stages before deliver, and the model/effort table, unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18; fix direction proposed in the issue itself. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-19 | **Field bug #3 fixed** (catalog issue #27, reported from Ruihang2017/Groundwork2): `/start-all` step 3 never stated that `modules[].tickets` elements must be `{id, path, issue}` objects joined from two sources (DAG plan order + per-module `PUBLISH-SUMMARY-JSON`) — the DAG JSON alone emits bare id strings, which run-milestone's validator rejects. Command doc now names the exact shape and the join; `/start-milestone` already documented it. (The issue's other defect — stringified Workflow `args` — was already fixed under #23 / v0.2.1.) | Field report (Horace Hou via Groundwork2), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
+| 2026-07-18 | **Field bug #2 fixed** (catalog issue #23, same reporter channel): (a) #21's install-time LF fix did not survive target-side git checkouts — `adopt.mjs` now installs/appends a target-repo `.gitattributes` pinning `.claude/workflows/*.js` + `.claude/scripts/*.mjs` to `eol=lf` (marker-checked, append-once); (b) Workflow `args` can arrive JSON-stringified — all three workflow scripts gained the `typeof args === 'string' ? JSON.parse(args) : (args \|\| {})` shim. Both recorded as §4 pitfalls; E2E extended (stringified-args runner + start-all scenarios; `.gitattributes` install/append/idempotency). Per-ticket stages and model/effort table unchanged. | Field report (Horace Hou via Groundwork), 2026-07-18. | Horace Hou (report) / Claude Fable 5 (fix) |
 | 2026-07-17 | **Catalog site**: claymorphic GitHub Pages page generated from pattern data (`scripts/build-site.mjs` — parses pattern README metadata/§1/§3 + package.json; live npm-version fetch with build-time fallback; deployed via `gh-pages` branch). Style spec + generated-not-handwritten rationale in catalog issue #17. | Maintainer direction (Horace Hou) with reference designs, 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (build) |
 | 2026-07-17 | **Released**: catalog published to public npm as `agent-templates` under MIT (maintainer decisions: MIT + personal ownership + publish, 2026-07-17 — catalog issue #15). README carries the scaffold-output attribution carve-out. Adoption command is now `npx agent-templates@latest adopt …`. | Maintainer decision (Horace Hou), 2026-07-17. | Horace Hou (decision) / Claude Fable 5 (release) |
 | 2026-07-17 | **Registry decision — public npm over GitHub Packages** (repo is public; goal is public sharing): GH Packages requires a token even to install public packages (`[official]` GitHub docs, verified live 2026-07-17) and is scope-only; npm allows anonymous installs and the bare name `agent-templates` was unclaimed (registry 404, same day). Publish itself is gated on maintainer decisions — license (repo has none), npm account/name — tracked in catalog issue #13; `package.json` carries the publish-prep (`files`, `repository`) with `private: true` until then. | Maintainer direction (Horace Hou) + live verification, 2026-07-17. | Horace Hou (direction) / Claude Fable 5 (write-up) |

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/start-all.md

@@ -8,8 +8,8 @@ Arguments: `$ARGUMENTS` — optional mode override (else the repo's declared Ope
 Typing this command is the human Gate 1 sign-off **for the whole PRD** — every module, in dependency order. Prefer `/start-milestone` per module when you still want module-boundary checkpoints. Execute in order:
 
 1. **Compute the plan.** Run `node .claude/scripts/milestone-dag.mjs` and show its output (module order, per-module dependencies). STOP on any error — a dangling `blocked_by` or a cycle is a spec defect for the Architect/human, not something to patch here.
-2. **Publish all tickets.** For each module in DAG order: `node .claude/scripts/publish-tickets.mjs docs/prd/<module>` (dry-run, then `--create`; STOP on `error` entries). Then, per module, **filter out tickets whose issues are already closed** (closed = delivered by an earlier run — this makes `/start-all` re-runs resume: fully-closed modules pass an empty ticket list and are marked already-complete).
-3. **Launch the driver.** Call the **Workflow** tool with `name: "start-all"` and `args: { modules: [{name, dependsOn, tickets}] in DAG order, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool. Failure policy is enforced in the workflow: failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`.
+2. **Publish all tickets.** For each module in DAG order: `node .claude/scripts/publish-tickets.mjs docs/prd/<module>` (dry-run, then `--create`; STOP on `error` entries). Keep each module's `PUBLISH-SUMMARY-JSON` line — step 3 needs it. Then, per module, **filter out tickets whose issues are already closed** (closed = delivered by an earlier run — this makes `/start-all` re-runs resume: fully-closed modules pass an empty ticket list and are marked already-complete).
+3. **Launch the driver.** Call the **Workflow** tool with `name: "start-all"` and `args: { modules: [{name, dependsOn, tickets}] in DAG order, mode, defaultBranch, platform }`. Each element of `tickets` MUST be an object `{id, path, issue}` — the exact shape run-milestone validates (issue #27; bare id strings fail). Build it by joining the two step outputs per module: ticket ids and their order come from the DAG plan (step 1), `path` and `issue` come from that module's `PUBLISH-SUMMARY-JSON` (step 2), matched by `id`. Add `testCmd` (the repo's test command, if its CLAUDE.md declares one) so the deterministic deliver script re-runs tests on the merged default branch as part of DoD. This command's instruction is your authorization to use the Workflow tool. Failure policy is enforced in the workflow: failed modules block their dependents; independent branches continue in `autonomous`; anything short of a CLEAR stops everything in `supervised`.
 4. **Relay the final report verbatim** — per module: `completed` / `already-complete` / `paused-for-merge` (supervised: tell the human to merge, then re-run this command) / `failed` (with the failing ticket + stage) / `skipped-dependency` / `not-started`. Escalations inside a module carry through from run-milestone unchanged.
 
 While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/commands/start-milestone.md

@@ -9,7 +9,7 @@ Typing this command **is** the human Gate 1 sign-off: the sub-PRD and tickets ar
 
 1. **Verify Gate 1 inputs.** `MODULE/README.md` (the sub-PRD) exists and `MODULE/tickets/*.md` is non-empty; every ticket has the required frontmatter (see `templates/ticket.template.md`). Anything missing → STOP and list exactly what is missing. Do not fix it yourself — that is Architect-stage work.
 2. **Publish tickets as tracker issues.** Run `node .claude/scripts/publish-tickets.mjs MODULE` (dry-run) and show the mapping. If the summary contains `error` entries → STOP and report them. Otherwise re-run with `--create` (idempotent — the `[<id>]` title prefix dedupes, so re-running is safe), and again STOP on any `error` entries.
-3. **Launch the pipeline.** Parse the final `PUBLISH-SUMMARY-JSON` line into `tickets: [{id, path, issue}]`. **Filter out tickets whose issue is already closed** (check via `gh`/`glab` — closed means delivered by an earlier run; this filter is what makes re-runs after supervised pauses or crashes safe). Determine the Operating mode, then call the **Workflow** tool with `name: "run-milestone"` and `args: { tickets, mode, defaultBranch, platform }`. This command's instruction is your authorization to use the Workflow tool.
+3. **Launch the pipeline.** Parse the final `PUBLISH-SUMMARY-JSON` line into `tickets: [{id, path, issue}]`. **Filter out tickets whose issue is already closed** (check via `gh`/`glab` — closed means delivered by an earlier run; this filter is what makes re-runs after supervised pauses or crashes safe). Determine the Operating mode, then call the **Workflow** tool with `name: "run-milestone"` and `args: { tickets, mode, defaultBranch, platform }` — plus `testCmd` (the repo's test command, if its CLAUDE.md declares one) so the deterministic deliver script re-runs tests on the merged default branch as part of DoD. This command's instruction is your authorization to use the Workflow tool.
 4. **Relay the final report verbatim** — per ticket: `delivered` · `awaiting-human-merge` · `escalated` (stage `review`, `reviewer-failed`, or `bounce-fix-build`) · `failed` · `delivery-incomplete`, plus `notStarted` when the run stopped early. Escalated and failed items go to the human; do not fix them inline (the write guard will hold you to that). In `supervised` mode the run stops after each CLEAR verdict — tell the human to merge, then re-run this command to continue.
 
 While the workflow runs you are an observer. Do not do stage work in parallel, do not "help" a slow stage, do not edit files.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/scripts/deliver-ticket.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// deliver-ticket.mjs — the ONLY sanctioned delivery path for the three-agent
+// pattern (catalog issue #26). Delivery used to be a generic LLM agent prompted
+// to merge + close + verify; harness safety classifiers repeatedly blocked that
+// agent even after a journaled CLEAR (3/3 in one field session), stranding
+// CLEAR-verdict tickets. Like issue creation (publish-tickets.mjs), delivery is
+// now deterministic: the merge policy stays mechanically checkable and the only
+// permission surface is this one command.
+//
+// Usage:
+//   node .claude/scripts/deliver-ticket.mjs --id <ticket-id> --branch <branch>
+//        [--default-branch main] [--issue <n>] [--platform gh|glab]
+//        [--test-cmd "<command>"]
+//
+// Does, in order (every step lands in the summary):
+//   1. refuses to run on a dirty working tree
+//   2. checks out <default-branch>; merges <branch> with --no-ff (an
+//      already-merged branch is recognized and succeeds idempotently);
+//      a conflict aborts the merge and leaves the tree clean
+//   3. pushes <default-branch> to origin (required only when origin exists)
+//   4. closes the tracker issue (--issue <n>, else looked up by the "[<id>]"
+//      title prefix) and VERIFIES it is actually closed afterwards
+//   5. deterministic DoD: plan file exists (docs/plans/<id>.md), merged,
+//      pushed, issue closed, plus --test-cmd green when supplied (post-merge
+//      test runs otherwise stay with /verify-delivery)
+//
+// Last line of stdout is machine-readable for run-milestone:
+//   DELIVER-SUMMARY-JSON: {"id","branch","merged","issueClosed","dodPassed","checks":{...},"notes"}
+// Exit codes: 0 = definitive summary printed (flags may still be false);
+//             1 = bad invocation or unexpected internal error.
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const argv = process.argv.slice(2)
+const opt = (name) => {
+  const i = argv.indexOf('--' + name)
+  if (i === -1) return ''
+  const v = argv[i + 1]
+  return v && !v.startsWith('--') ? v : ''
+}
+
+const ID = opt('id')
+const BRANCH = opt('branch')
+const DEFAULT_BRANCH = opt('default-branch') || 'main'
+const ISSUE_ARG = opt('issue')
+const PLATFORM = opt('platform') || 'gh'
+const TEST_CMD = opt('test-cmd')
+
+if (!ID || !BRANCH) {
+  console.error('usage: node deliver-ticket.mjs --id <ticket-id> --branch <branch> [--default-branch main] [--issue <n>] [--platform gh|glab] [--test-cmd "<command>"]')
+  process.exit(1)
+}
+if (!/^[A-Za-z0-9._-]+$/.test(ID)) {
+  console.error(`invalid --id (allowed: letters, digits, . _ -): ${ID}`)
+  process.exit(1)
+}
+if (!/^[A-Za-z0-9/._-]+$/.test(BRANCH) || !/^[A-Za-z0-9/._-]+$/.test(DEFAULT_BRANCH)) {
+  console.error('invalid --branch / --default-branch (allowed: letters, digits, / . _ -)')
+  process.exit(1)
+}
+if (BRANCH === DEFAULT_BRANCH) {
+  console.error(`--branch must differ from --default-branch (got ${BRANCH} for both) — nothing to deliver`)
+  process.exit(1)
+}
+if (PLATFORM !== 'gh' && PLATFORM !== 'glab') {
+  console.error(`unknown platform: ${PLATFORM} (expected gh or glab)`)
+  process.exit(1)
+}
+
+const run = (bin, args, opts = {}) => execFileSync(bin, args, { encoding: 'utf8', ...opts })
+const git = (args, opts = {}) => run('git', args, opts)
+const errText = (e) => String((e && (e.stderr || e.stdout || e.message)) || e).trim()
+const firstLine = (s) => String(s).trim().split('\n')[0]
+const lastLine = (s) => String(s).trim().split('\n').filter(Boolean).pop() || ''
+const tryGit = (args) => {
+  try { return { ok: true, out: git(args, { stdio: ['ignore', 'pipe', 'pipe'] }) } } catch (e) { return { ok: false, out: errText(e) } }
+}
+
+// GH_BIN / GLAB_BIN env overrides (same mechanism as publish-tickets.mjs) for
+// non-PATH binaries and test doubles, e.g. GH_BIN="node tools/fake-gh.mjs".
+const cli = (args, opts = {}) => {
+  const raw = PLATFORM === 'gh' ? process.env.GH_BIN || 'gh' : process.env.GLAB_BIN || 'glab'
+  const parts = raw.split(' ')
+  return run(parts[0], [...parts.slice(1), ...args], opts)
+}
+
+const checks = { planExists: false, alreadyMerged: false, merged: false, pushRequired: false, pushed: false, issueClosed: false, testsPassed: null }
+const notes = []
+const note = (line) => { notes.push(line); console.log('  (note) ' + line) }
+
+const finish = (code) => {
+  const dodPassed =
+    checks.planExists &&
+    checks.merged &&
+    checks.issueClosed &&
+    (!checks.pushRequired || checks.pushed) &&
+    (TEST_CMD ? checks.testsPassed === true : true)
+  const summary = { id: ID, branch: BRANCH, merged: checks.merged, issueClosed: checks.issueClosed, dodPassed, checks, notes: notes.join('; ') }
+  console.log('DELIVER-SUMMARY-JSON: ' + JSON.stringify(summary))
+  process.exit(code)
+}
+
+try {
+  // 0. operate from the repo root regardless of cwd (plan path + command shape)
+  process.chdir(git(['rev-parse', '--show-toplevel']).trim())
+
+  // 1. clean tree — merging over uncommitted work is never sanctioned
+  if (git(['status', '--porcelain']).trim()) {
+    note('working tree not clean — refusing to merge')
+    finish(0)
+  }
+
+  // 2. refs must exist
+  for (const ref of [BRANCH, DEFAULT_BRANCH]) {
+    if (!tryGit(['rev-parse', '--verify', '--quiet', ref]).ok) {
+      note(`ref not found: ${ref}`)
+      finish(0)
+    }
+  }
+
+  // 3. merge --no-ff into the default branch (idempotent on re-runs)
+  git(['checkout', DEFAULT_BRANCH], { stdio: ['ignore', 'pipe', 'pipe'] })
+  if (tryGit(['merge-base', '--is-ancestor', BRANCH, 'HEAD']).ok) {
+    checks.alreadyMerged = true
+    checks.merged = true
+    console.log(`= merged  ${BRANCH} is already contained in ${DEFAULT_BRANCH}`)
+  } else {
+    const m = tryGit(['merge', '--no-ff', '--no-edit', '-m', `merge: [${ID}] ${BRANCH} -> ${DEFAULT_BRANCH} (pipeline CLEAR)`, BRANCH])
+    if (m.ok) {
+      checks.merged = true
+      console.log(`+ merged  ${BRANCH} -> ${DEFAULT_BRANCH} (--no-ff)`)
+    } else {
+      tryGit(['merge', '--abort'])
+      note(`merge failed (aborted, tree left clean): ${firstLine(m.out)}`)
+    }
+  }
+
+  // 4. push (only meaningful when an origin remote exists)
+  checks.pushRequired = tryGit(['remote', 'get-url', 'origin']).ok
+  if (checks.merged && checks.pushRequired) {
+    const p = tryGit(['push', 'origin', DEFAULT_BRANCH])
+    if (p.ok) {
+      checks.pushed = true
+      console.log(`+ pushed  ${DEFAULT_BRANCH} -> origin`)
+    } else {
+      note(`push failed: ${lastLine(p.out)}`)
+    }
+  }
+
+  // 5. close the tracker issue and verify the transition (never assume auto-close).
+  // ONLY after the work actually landed: a closed issue is what resume filtering
+  // treats as "delivered by an earlier run", so closing on a failed merge/push
+  // would silently drop the ticket from every future run.
+  const landed = checks.merged && (!checks.pushRequired || checks.pushed)
+  let issueNum = ISSUE_ARG ? Number(ISSUE_ARG) : null
+  if (issueNum !== null && (!Number.isInteger(issueNum) || issueNum < 1)) {
+    note(`invalid --issue value: ${ISSUE_ARG}`)
+    issueNum = null
+  }
+  if (!landed) {
+    note('skipping tracker close — merge/push did not complete, ticket is NOT delivered')
+  } else {
+    if (!issueNum) {
+      // fall back to the "[<id>]" title-prefix convention (publish-tickets.mjs key)
+      try {
+        if (PLATFORM === 'gh') {
+          const list = JSON.parse(cli(['issue', 'list', '--state', 'all', '--limit', '1000', '--json', 'number,title']))
+          const hit = list.find((i) => String(i.title).startsWith(`[${ID}]`))
+          if (hit) issueNum = hit.number
+        } else {
+          const text = cli(['issue', 'list', '--all'])
+          const line = text.split('\n').find((l) => l.includes(`[${ID}]`))
+          const m = line && line.match(/#(\d+)\b/)
+          if (m) issueNum = Number(m[1])
+        }
+      } catch (e) {
+        note(`issue lookup failed: ${firstLine(errText(e))}`)
+      }
+    }
+    if (!issueNum) {
+      note(`no tracker issue found for [${ID}]`)
+    } else {
+      try {
+        cli(['issue', 'close', String(issueNum), ...(PLATFORM === 'gh' ? ['--comment', `Delivered: ${BRANCH} merged to ${DEFAULT_BRANCH} (run-milestone, CLEAR verdict).`] : [])])
+      } catch (e) {
+        note(`issue close command failed: ${firstLine(errText(e))}`) // verification below still decides
+      }
+      try {
+        if (PLATFORM === 'gh') {
+          const view = JSON.parse(cli(['issue', 'view', String(issueNum), '--json', 'state']))
+          checks.issueClosed = String(view.state).toUpperCase() === 'CLOSED'
+        } else {
+          // text scrape (older glab has no JSON): only trust a "closed" in the header lines
+          checks.issueClosed = cli(['issue', 'view', String(issueNum)]).split('\n').slice(0, 5).some((l) => /\bclosed\b/i.test(l))
+        }
+        console.log((checks.issueClosed ? '+ closed  ' : '  (note) NOT closed: ') + `issue #${issueNum}`)
+        if (!checks.issueClosed) notes.push(`issue #${issueNum} still open after close attempt`)
+      } catch (e) {
+        note(`issue state verification failed: ${firstLine(errText(e))}`)
+      }
+    }
+  }
+
+  // 6. deterministic DoD inputs
+  checks.planExists = existsSync(join('docs', 'plans', `${ID}.md`))
+  if (!checks.planExists) note(`plan file missing: docs/plans/${ID}.md`)
+  if (TEST_CMD) {
+    const t = spawnSync(TEST_CMD, { shell: true, encoding: 'utf8' })
+    checks.testsPassed = t.status === 0
+    if (!checks.testsPassed) note(`--test-cmd failed (exit ${t.status}): ${String(t.stdout || t.stderr || '').trim().split('\n').slice(-3).join(' | ')}`)
+  }
+
+  finish(0)
+} catch (e) {
+  note(`unexpected error: ${firstLine(errText(e))}`)
+  finish(1)
+}

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/settings.json

@@ -1,4 +1,11 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(node .claude/scripts/milestone-dag.mjs:*)",
+      "Bash(node .claude/scripts/publish-tickets.mjs:*)",
+      "Bash(node .claude/scripts/deliver-ticket.mjs:*)"
+    ]
+  },
   "hooks": {
     "PreToolUse": [
       {

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/nightly-issues.js

@@ -22,7 +22,9 @@ export const meta = {
 // end — comments, labels, and the "Nightly report <date>" issue the human reads
 // over morning email (tracker notifications).
 
-const cfg = Object.assign({ maxIssues: 5, defaultBranch: 'main', platform: 'gh' }, args)
+// args may arrive as a JSON string depending on the harness (catalog issue #23)
+const parsedArgs = typeof args === 'string' ? JSON.parse(args) : (args || {})
+const cfg = Object.assign({ maxIssues: 5, defaultBranch: 'main', platform: 'gh' }, parsedArgs)
 if (!Array.isArray(cfg.issues)) throw new Error('args.issues must be an array (may be empty)')
 if (typeof cfg.reportDate !== 'string' || !cfg.reportDate) throw new Error('args.reportDate is required (the caller stamps the date)')
 if (!Number.isInteger(cfg.maxIssues) || cfg.maxIssues < 1) throw new Error('args.maxIssues must be an integer >= 1')

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/run-milestone.js

@@ -13,7 +13,9 @@ export const meta = {
 //   defaultBranch: 'main',        // optional, default 'main'
 //   maxBounces: 2,                // optional, default 2
 //   continueOnFailure: false,     // optional; default fail-fast (tickets may depend on earlier ones)
-//   platform: 'gh' | 'glab'       // tracker CLI for the deliver step, default 'gh'
+//   platform: 'gh' | 'glab',      // tracker CLI for the deliver step, default 'gh'
+//   testCmd: 'npm test'           // optional; forwarded to deliver-ticket.mjs --test-cmd so the
+//                                 // deterministic DoD re-runs tests on the merged default branch
 // }
 //
 // Guarantees encoded below (each one exists because prose alone failed before):
@@ -23,9 +25,11 @@ export const meta = {
 // - supervised mode STOPS the run after each CLEAR (later tickets may depend on the merge);
 //   re-running /start-milestone continues — already-closed issues are filtered out upstream
 
+// args may arrive as a JSON string depending on the harness (catalog issue #23)
+const parsedArgs = typeof args === 'string' ? JSON.parse(args) : (args || {})
 const cfg = Object.assign(
   { maxBounces: 2, continueOnFailure: false, defaultBranch: 'main', platform: 'gh' },
-  args
+  parsedArgs
 )
 if (!Array.isArray(cfg.tickets) || cfg.tickets.length === 0) {
   throw new Error('args.tickets must be a non-empty array of {id, path, issue}')
@@ -34,10 +38,17 @@ for (const t of cfg.tickets) {
   if (!t || typeof t.id !== 'string' || !t.id || typeof t.path !== 'string' || !t.path) {
     throw new Error('every ticket needs a non-empty string id and path; got: ' + JSON.stringify(t))
   }
+  // the id is composed into branch names and the deliver command — keep it boring
+  if (!/^[A-Za-z0-9._-]+$/.test(t.id)) {
+    throw new Error('ticket id must match [A-Za-z0-9._-]+; got: ' + t.id)
+  }
 }
 if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
   throw new Error("args.mode must be 'supervised' or 'autonomous'")
 }
+if (cfg.testCmd !== undefined && (typeof cfg.testCmd !== 'string' || !cfg.testCmd || cfg.testCmd.includes('"'))) {
+  throw new Error('args.testCmd must be a non-empty string without double quotes when provided')
+}
 if (!Number.isInteger(cfg.maxBounces) || cfg.maxBounces < 0) {
   throw new Error('args.maxBounces must be an integer >= 0')
 }
@@ -192,15 +203,21 @@ for (const t of cfg.tickets) {
     continue
   }
 
-  log('[' + t.id + '] deliver: merge + close issue + DoD')
+  log('[' + t.id + '] deliver: merge + close issue + DoD (deterministic script)')
+  // Delivery is a deterministic script, not agent judgment (catalog issue #26):
+  // harness safety classifiers blocked agent-run merges even after a journaled
+  // CLEAR. The agent below only executes the sanctioned command and relays its
+  // machine-readable summary — same discipline as publish-tickets.mjs for issues.
+  const deliverCmd = 'node .claude/scripts/deliver-ticket.mjs --id ' + t.id + ' --branch ' + branch +
+    ' --default-branch ' + cfg.defaultBranch + ' --platform ' + cfg.platform + (t.issue ? ' --issue ' + t.issue : '') +
+    (cfg.testCmd ? ' --test-cmd "' + cfg.testCmd + '"' : '')
   const delivery = await agent(
     'Delivery step (autonomous mode — pre-authorized by the human Gate 1 start signal). ' +
-    'Merge branch ' + branch + ' into ' + cfg.defaultBranch + ' with --no-ff and push. ' +
-    'Close tracker issue ' + (t.issue ? '#' + t.issue : 'for ticket ' + t.id + ' (find it by its "[' + t.id + ']" title prefix)') +
-    ' via ' + cfg.platform + ' and verify it is ACTUALLY closed afterwards. ' +
-    'Then run the Definition-of-Done checks from .claude/commands/verify-delivery.md for ticket ' + t.id +
-    ' (plan exists; tests green on the merged ' + cfg.defaultBranch + ' — run them yourself; CLEAR verdict recorded; merged to ' + cfg.defaultBranch + '; issue closed; writeback done). ' +
-    'Never report an item you did not check. Return merged, issueClosed, dodPassed, notes.',
+    'Delivery is DETERMINISTIC: from the repo root, run EXACTLY this command and let it do all git and tracker work: ' +
+    deliverCmd + ' — the script is the only sanctioned delivery path; do not merge, push, close issues, or retry pieces yourself. ' +
+    'Parse the DELIVER-SUMMARY-JSON line it prints last and return merged, issueClosed, dodPassed EXACTLY as reported there, ' +
+    'with notes = its notes field plus anything unusual you observed. ' +
+    'If the command cannot run or prints no DELIVER-SUMMARY-JSON, return all three as false with the output tail in notes.',
     { label: 'deliver:' + t.id, phase: P, schema: DELIVERY }
   )
   // Delivered requires ALL THREE flags — a hallucinated dodPassed alone must not count.

package/patterns/three-agent-architect-builder-reviewer/scaffold/.claude/workflows/start-all.js

@@ -13,7 +13,8 @@ export const meta = {
 //     // so an [] tickets list means "module already complete" (resume semantics)
 //   mode: 'supervised' | 'autonomous',
 //   defaultBranch: 'main',      // optional
-//   platform: 'gh' | 'glab'     // optional, default 'gh'
+//   platform: 'gh' | 'glab',    // optional, default 'gh'
+//   testCmd: 'npm test'         // optional; passed through to run-milestone (deliver DoD test run)
 // }
 //
 // Failure policy (maintainer decisions, catalog issue #20, 2026-07-18):
@@ -23,7 +24,9 @@ export const meta = {
 //   issues are filtered upstream, so completed modules arrive as already-complete);
 // - no cost ceiling.
 
-const cfg = Object.assign({ defaultBranch: 'main', platform: 'gh' }, args)
+// args may arrive as a JSON string depending on the harness (catalog issue #23)
+const parsedArgs = typeof args === 'string' ? JSON.parse(args) : (args || {})
+const cfg = Object.assign({ defaultBranch: 'main', platform: 'gh' }, parsedArgs)
 if (!Array.isArray(cfg.modules) || cfg.modules.length === 0) {
   throw new Error('args.modules must be a non-empty array of {name, dependsOn, tickets}')
 }
@@ -36,6 +39,9 @@ if (cfg.mode !== 'supervised' && cfg.mode !== 'autonomous') {
   throw new Error("args.mode must be 'supervised' or 'autonomous'")
 }
 if (cfg.platform !== 'gh' && cfg.platform !== 'glab') throw new Error("args.platform must be 'gh' or 'glab'")
+if (cfg.testCmd !== undefined && (typeof cfg.testCmd !== 'string' || !cfg.testCmd || cfg.testCmd.includes('"'))) {
+  throw new Error('args.testCmd must be a non-empty string without double quotes when provided')
+}
 
 const state = {} // name -> 'completed' | 'failed' | 'skipped' | 'paused'
 const results = []
@@ -73,6 +79,7 @@ for (const m of cfg.modules) {
       mode: cfg.mode,
       defaultBranch: cfg.defaultBranch,
       platform: cfg.platform,
+      ...(cfg.testCmd ? { testCmd: cfg.testCmd } : {}),
     })
   } catch (e) {
     err = e && e.message ? e.message : String(e)

package/patterns/three-agent-architect-builder-reviewer/scaffold/INSTALL.md

@@ -8,10 +8,10 @@ From a checkout of the catalog: `node scripts/adopt.mjs three-agent-architect-bu
 
 ## Steps
 
-1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry instead of overwriting.
+1. Copy `.claude/` from this scaffold into the target repo root. If the target already has `.claude/settings.json`, merge the `hooks.PreToolUse` entry and the `permissions.allow` list instead of overwriting.
 2. Install the catalog's **universal templates** (shared by all patterns — source of truth is the catalog root, not this scaffold): `templates/ticket.template.md` → the target repo's `templates/`; the platform half of `templates/tracker/` → `.github/` (ISSUE_TEMPLATE/ + PULL_REQUEST_TEMPLATE.md) or `.gitlab/` (issue_templates/ + merge_request_templates/). Then fill the PR/MR template's **Constraint check** section with the target repo's CLAUDE.md non-negotiables. Hand-written issues and pipeline PRs now share one format that triage can convert and reviewers can verify.
 3. The write-guard hook needs Node.js ≥ 18 on PATH. It denies main-session Edit/Write with a dispatch instruction; subagent writes pass. Override switch for human-approved out-of-pipeline edits: create `.claude/allow-main-writes`, delete it afterwards — and add that path to `.gitignore`.
-4. The tracker steps (`publish-tickets.mjs`, the deliver stage, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides).
+4. The tracker steps (`publish-tickets.mjs`, `deliver-ticket.mjs`, `/verify-delivery`, the nightly sweep) need the platform CLI installed and authenticated: `gh` (GitHub) or `glab` (GitLab). The publish script autodetects the platform from the origin remote; override with `--platform gh|glab` (test doubles / non-PATH binaries: `GH_BIN` / `GLAB_BIN` env overrides). Delivery (merge `--no-ff` + push + verified issue close + deterministic DoD) is `deliver-ticket.mjs` — never an agent improvising git/tracker writes; `settings.json` carries explicit allow rules for the three deterministic scripts so unattended runs do not stall waiting for interactive approval (catalog issue #26).
 5. Append the content of `claude-md-snippet.md` to the target repo's `CLAUDE.md`, and set the **Operating mode** line (`supervised` for a fresh adoption; `autonomous` is the target).
 6. Ensure the docs layout the pipeline assumes exists: `docs/PRD.md`, `docs/prd/<module>/README.md` (the sub-PRD — `/start-milestone` hard-requires it), `docs/prd/<module>/tickets/` (author tickets from `templates/ticket.template.md`), `docs/adr/`, and an empty `docs/plans/`.
 7. Check the pattern entry's expiry (README metadata table). If expired, re-verify the model/effort table against current official docs before adopting — do not copy an expired recommendation into a new project.

package/scripts/adopt.mjs

@@ -11,6 +11,7 @@
 //   docs/PRD.md              copied from a root PRD.md if present and docs/PRD.md is absent
 //   docs/prd/ docs/adr/ docs/plans/   the docs skeleton the pipeline assumes
 //   CLAUDE.md                created from the snippet, or snippet appended once (marker-checked)
+//   .gitattributes           eol=lf rules for scaffold runtime files, appended once (marker-checked)
 //
 // Idempotent: re-running skips everything that exists (--force overwrites files, never
 // re-appends the snippet). Exit 0 = installed/verified; exit 1 = bad invocation.
@@ -174,6 +175,25 @@ if (!existsSync(claudeMd)) {
   skipped++
 }
 
+// 7. .gitattributes: pin scaffold runtime files to LF. Install-time normalization
+// (above) is not enough on Windows — a later `git checkout` with autocrlf re-CRLFs
+// them and the Workflow tool rejects the script content (catalog issue #23).
+const GA_MARKER = '# agent-templates: Workflow tool rejects CRLF scripts (keep LF)'
+const GA_RULES = `${GA_MARKER}\n.claude/workflows/*.js text eol=lf\n.claude/scripts/*.mjs text eol=lf\n`
+const gaPath = join(target, '.gitattributes')
+if (!existsSync(gaPath)) {
+  writeFileSync(gaPath, GA_RULES)
+  console.log('+ install .gitattributes (eol=lf for scaffold runtime files)')
+  installed++
+} else if (!readFileSync(gaPath, 'utf8').includes(GA_MARKER)) {
+  writeFileSync(gaPath, readFileSync(gaPath, 'utf8').trimEnd() + '\n\n' + GA_RULES)
+  console.log('+ append  .gitattributes (eol=lf rules for scaffold runtime files)')
+  installed++
+} else {
+  console.log('= exists  .gitattributes (eol=lf rules already present)')
+  skipped++
+}
+
 console.log(`\nadopt: ${installed} installed, ${skipped} already present. Pattern: ${pattern}, platform: ${PLATFORM}.`)
 console.log(`
 NEXT STEPS (details: ${join(CATALOG, 'ADOPTING.md')})

package/scripts/build-site.mjs

@@ -6,8 +6,11 @@
 // Usage: node scripts/build-site.mjs [--out <dir>]     (default: site/)
 // Output: <out>/index.html (self-contained) + <out>/.nojekyll
 //
-// Style: claymorphism per catalog issue #17 — cream background, pastel clay palette,
-// puffy cards, soft extruded shadows, rounded chunky type, emoji as clay icons.
+// Style: clay-morphism per the approved hi-fi mock on catalog issue #19 — layered
+// clay shadows (outer drop + inset top highlight + inset bottom ink), Baloo 2 +
+// Nunito, five build-time palettes with mint baked as default, pure-CSS clay icons
+// (no emoji, no icon fonts). The mock is the source of truth for colors/shadows/
+// spacing; the pattern catalog stays the source of truth for all copy.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -58,17 +61,7 @@ function parsePattern(dir) {
     }
   }
 
-  // first three "Use when" bullets from §1
-  const useWhen = []
-  const sec1 = md.split(/\*\*Use when:\*\*/)[1]
-  if (sec1) {
-    for (const l of sec1.split(/\*\*Do not use when:\*\*/)[0].split('\n')) {
-      const m = l.match(/^- (.+)$/)
-      if (m && useWhen.length < 3) useWhen.push(strip(m[1]))
-    }
-  }
-
-  return { dir, title, status, asOf, summary, roles, useWhen }
+  return { dir, title, status, asOf, summary, roles }
 }
 
 const patterns = readdirSync(join(ROOT, 'patterns'), { withFileTypes: true })
@@ -76,45 +69,100 @@ const patterns = readdirSync(join(ROOT, 'patterns'), { withFileTypes: true })
   .map((d) => parsePattern(d.name))
   .filter(Boolean)
 
-const STATUS_STYLE = {
-  proposed: ['var(--blue)', 'var(--blue-d)', '🧪'],
-  trialed: ['var(--butter)', 'var(--butter-d)', '🌱'],
-  adopted: ['var(--sage)', 'var(--sage-d)', '✅'],
-  deprecated: ['var(--pink)', 'var(--pink-d)', '🗄️'],
+// ---------------------------------------------------------------------------
+// Theme palettes, distilled from the approved mock (issue #19). The mock names
+// them cream / mint / lavender / sakura / sky; mint is the approved default.
+// Swapping the palette is a build-time constant change — no runtime switcher.
+// amb/ins/flt are bare R,G,B triplets consumed via rgba(var(--amb), a).
+// ---------------------------------------------------------------------------
+const THEMES = {
+  cream:    { page: '#ffeecb', heroA: '#fbd2b0', heroB: '#f5b98f', heroInk: 'rgba(190,110,60,0.18)', heroAmb: 'rgba(199,141,109,0.32)', heroTitle: '#5a3520', heroBody: '#8a5a3d', card: '#fdf4e6', pill: '#fff7e9', ink: '#4a3020', sub: '#7b5a42', mut: '#a3805f', code: '#7b4a2a', amb: '199,141,109', ins: '214,160,120', flt: '150,90,60' },
+  mint:     { page: '#e0f3e0', heroA: '#c3e6bd', heroB: '#a3d49a', heroInk: 'rgba(40,110,50,0.18)', heroAmb: 'rgba(110,160,120,0.35)', heroTitle: '#2f5a30', heroBody: '#4f7a52', card: '#f0f9ec', pill: '#f8fdf5', ink: '#2f4a28', sub: '#567a50', mut: '#7fa077', code: '#4f6b3a', amb: '110,150,115', ins: '160,195,155', flt: '80,120,85' },
+  lavender: { page: '#f0e7fa', heroA: '#ddcbf3', heroB: '#c4abe8', heroInk: 'rgba(90,50,140,0.16)', heroAmb: 'rgba(140,110,180,0.35)', heroTitle: '#46306b', heroBody: '#6b5490', card: '#f6f1fc', pill: '#fbf9fe', ink: '#3f2f5c', sub: '#6b5a86', mut: '#9284ab', code: '#5f4a8a', amb: '130,110,165', ins: '185,165,215', flt: '100,80,135' },
+  sakura:   { page: '#fde7ee', heroA: '#f9c9d7', heroB: '#f3abc2', heroInk: 'rgba(180,60,100,0.15)', heroAmb: 'rgba(190,120,140,0.35)', heroTitle: '#6b2f45', heroBody: '#96556b', card: '#fcf1f5', pill: '#fef8fa', ink: '#5c2f40', sub: '#86566a', mut: '#ab8494', code: '#8a4a62', amb: '180,120,140', ins: '215,165,185', flt: '150,80,105' },
+  sky:      { page: '#e3eefa', heroA: '#c8ddf4', heroB: '#a8c7ec', heroInk: 'rgba(50,90,150,0.15)', heroAmb: 'rgba(110,140,180,0.35)', heroTitle: '#2c4a6b', heroBody: '#4f6f96', card: '#eff5fc', pill: '#f7fafe', ink: '#2b3f5c', sub: '#52698a', mut: '#8095ad', code: '#3f5a80', amb: '100,130,170', ins: '155,180,215', flt: '70,100,140' },
+}
+const THEME = THEMES.mint
+
+// Status chips: trialed/adopted/proposed use the mock's yellow/green("stable")/
+// pink("experimental") recipes; deprecated (catalog-only status) is a neutral clay.
+const STATUS_CHIP = {
+  trialed:    { chip: 'background:linear-gradient(180deg,#f9d66e,#f0c14a);color:#6b4a15;box-shadow:inset 0 2px 2px rgba(255,255,255,0.6),inset 0 -3px 4px rgba(180,120,20,0.3),0 5px 10px rgba(180,130,60,0.3)', dot: 'inset -1px -1px 2px rgba(180,120,20,0.4)' },
+  proposed:   { chip: 'background:linear-gradient(180deg,#f792ab,#ef6f92);color:#fff;text-shadow:0 1px 2px rgba(170,30,80,0.35);box-shadow:inset 0 2px 2px rgba(255,255,255,0.5),inset 0 -3px 4px rgba(170,30,80,0.3),0 5px 10px rgba(199,100,110,0.3)', dot: 'inset -1px -1px 2px rgba(170,30,80,0.35)' },
+  adopted:    { chip: 'background:linear-gradient(180deg,#b3dcab,#98cb8e);color:#fff;text-shadow:0 1px 2px rgba(30,90,40,0.35);box-shadow:inset 0 2px 2px rgba(255,255,255,0.5),inset 0 -3px 4px rgba(30,100,40,0.28),0 5px 10px rgba(120,150,100,0.3)', dot: 'inset -1px -1px 2px rgba(30,90,40,0.35)' },
+  deprecated: { chip: 'background:linear-gradient(180deg,#cfc4b4,#b8aa96);color:#fff;text-shadow:0 1px 2px rgba(110,90,60,0.35);box-shadow:inset 0 2px 2px rgba(255,255,255,0.5),inset 0 -3px 4px rgba(110,90,60,0.3),0 5px 10px rgba(150,130,100,0.3)', dot: 'inset -1px -1px 2px rgba(110,90,60,0.35)' },
+}
+
+const ROLE_DOT = {
+  Architect: ['#a98fd6', 'rgba(80,40,140,0.3)'],
+  Builder: ['#f28ba3', 'rgba(170,30,80,0.3)'],
+  Reviewer: ['#8fb4e6', 'rgba(40,80,150,0.3)'],
 }
-const ROLE_EMOJI = { Architect: '📐', Builder: '🔨', Reviewer: '🔍' }
-const roleEmoji = (r) => ROLE_EMOJI[Object.keys(ROLE_EMOJI).find((k) => r.startsWith(k))] || '🌙'
+const roleDot = (r) => ROLE_DOT[Object.keys(ROLE_DOT).find((k) => r.startsWith(k))] || ['#f2c44e', 'rgba(180,120,20,0.35)']
 
+// --- pure-CSS clay icons, markup lifted from the approved mock -------------
+const LOGO_ICON = `<span class="gx" style="width:26px;height:26px;filter:drop-shadow(0 2px 3px rgba(var(--flt),0.3))"><span style="position:absolute;left:1px;top:2px;width:15px;height:20px;border-radius:5px;background:#b7a0e2;transform:rotate(-9deg);box-shadow:inset 0 2px 2px rgba(255,255,255,0.5)"></span><span style="position:absolute;left:9px;top:3px;width:15px;height:20px;border-radius:5px;background:var(--pill);transform:rotate(7deg);box-shadow:inset 0 -2px 3px rgba(var(--ins),0.35);display:flex;flex-direction:column;gap:3px;padding:4px 3px;box-sizing:border-box"><span style="height:2.5px;border-radius:2px;background:#f4a0b5"></span><span style="height:2.5px;border-radius:2px;background:#d9c8f0"></span><span style="height:2.5px;border-radius:2px;background:#d9c8f0;width:70%"></span></span></span>`
+const STAR_ICON = `<span style="width:14px;height:14px;background:#f9d66e;clip-path:polygon(50% 0%,61% 35%,98% 35%,68% 57%,79% 91%,50% 70%,21% 91%,32% 57%,2% 35%,39% 35%);display:inline-block"></span>`
+const NPM_ICON = `<span class="gx" style="width:14px;height:14px"><span style="position:absolute;inset:0;border-radius:4px;background:#fff3df;box-shadow:inset 0 -2px 3px rgba(190,110,60,0.4)"></span><span style="position:absolute;left:0;right:0;top:5.5px;height:3px;background:#e8b48c"></span></span>`
+const PATTERNS_ICON = `<span style="display:inline-grid;grid-template-columns:9px 9px;gap:2.5px;filter:drop-shadow(0 2px 3px rgba(var(--flt),0.3))"><span style="width:9px;height:9px;border-radius:3px;background:#9ed095"></span><span style="width:9px;height:9px;border-radius:3px;background:#f6a5bb"></span><span style="width:9px;height:9px;border-radius:3px;background:#f4cd6d"></span><span style="width:9px;height:9px;border-radius:3px;background:#c3abe9"></span></span>`
+const PIPELINE_ICON = `<span class="gx" style="width:22px;height:18px;border-radius:5px;background:#a9c6ec;overflow:hidden;filter:drop-shadow(0 2px 3px rgba(var(--flt),0.3))"><span style="position:absolute;left:3px;top:3px;width:6px;height:6px;border-radius:50%;background:#f9d66e"></span><span style="position:absolute;left:-5px;bottom:-9px;width:17px;height:17px;border-radius:50%;background:#9ed095"></span><span style="position:absolute;right:-4px;bottom:-8px;width:15px;height:15px;border-radius:50%;background:#8fc98b"></span></span>`
+
+// hero side facts: [icon-tile style, glyph markup, copy]
+const FACTS = [
+  ['background:#d9c8f0;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.55),inset -3px -4px 6px rgba(90,50,140,0.18)',
+    `<span class="gx" style="width:15px;height:18px"><span style="position:absolute;inset:0;border-radius:3px;background:#fffaf2;box-shadow:0 2px 4px rgba(90,50,140,0.25)"></span><span style="position:absolute;left:3px;right:3px;top:4px;height:2px;border-radius:2px;background:#c3abe9"></span><span style="position:absolute;left:3px;right:3px;top:8px;height:2px;border-radius:2px;background:#c3abe9"></span><span style="position:absolute;left:3px;right:6px;top:12px;height:2px;border-radius:2px;background:#c3abe9"></span></span>`,
+    'Every model/effort claim carries a source label and an expiry date'],
+  ['background:#b3cdf0;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.55),inset -3px -4px 6px rgba(40,80,150,0.2)',
+    `<span style="width:16px;height:18px;background:#fffaf2;border-radius:5px 5px 50% 50% / 5px 5px 75% 75%;box-shadow:inset 0 -3px 4px rgba(40,80,150,0.25),0 2px 4px rgba(40,80,150,0.3);display:inline-block"></span>`,
+    'Role boundaries enforced by hooks, not prose'],
+  ['background:#f9d66e;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.6),inset -3px -4px 6px rgba(180,120,20,0.25)',
+    `<span class="gx" style="width:17px;height:17px"><span style="position:absolute;inset:0;border-radius:50%;background:#fffaf2;box-shadow:0 2px 4px rgba(160,100,20,0.3)"></span><span style="position:absolute;left:6px;top:-2px;width:14px;height:14px;border-radius:50%;background:#f9d66e"></span></span>`,
+    'Nightly sweep triages and fixes issues while you sleep'],
+]
+
+// pipeline steps: [icon-tile style, glyph markup, title, description]
+const STEPS = [
+  ['background:#9ed095;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.55),inset -3px -4px 6px rgba(30,90,40,0.2),0 6px 10px rgba(var(--amb),0.22)',
+    `<span class="gx" style="width:20px;height:16px"><span style="position:absolute;inset:0;border-radius:4px;background:#fffaf2;box-shadow:inset 0 -2px 3px rgba(30,90,40,0.2),0 3px 5px rgba(30,90,40,0.3)"></span><span style="position:absolute;left:8.5px;top:0;width:3px;height:16px;background:#f4cd6d"></span></span>`,
+    'Adopt', `<code>${esc(QUICKSTART)}</code> — scaffold, templates, docs skeleton, CLAUDE.md, in one idempotent command.`],
+  ['background:#f4cd6d;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.6),inset -3px -4px 6px rgba(180,120,20,0.25),0 6px 10px rgba(var(--amb),0.22)',
+    `<span class="gx" style="width:22px;height:16px"><span style="position:absolute;inset:0;border-radius:3px;background:#fffaf2;box-shadow:0 3px 5px rgba(160,100,20,0.3)"></span><span style="position:absolute;left:6.5px;top:0;width:1.5px;height:16px;background:rgba(var(--flt),0.25)"></span><span style="position:absolute;left:14px;top:0;width:1.5px;height:16px;background:rgba(var(--flt),0.25)"></span><span style="position:absolute;left:9px;top:5px;width:4px;height:4px;border-radius:50%;background:#f2789a"></span></span>`,
+    'Break down', '<code>/breakdown-prd</code> — the Architect turns your PRD into sub-PRDs and cold-startable tickets, then stops.'],
+  ['background:#f3e6d0;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.7),inset -3px -4px 6px rgba(170,120,70,0.2),0 6px 10px rgba(var(--amb),0.22)',
+    `<span style="width:13px;height:28px;border-radius:6.5px;background:#7a6a58;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:2px;box-shadow:inset 0 2px 2px rgba(255,255,255,0.25),0 3px 5px rgba(90,60,30,0.35)"><span style="width:6px;height:6px;border-radius:50%;background:#f28b8b"></span><span style="width:6px;height:6px;border-radius:50%;background:#f9d66e"></span><span style="width:6px;height:6px;border-radius:50%;background:#8fc98b"></span></span>`,
+    'Gate 1 — you decide', 'Review the breakdown, then <code>/start-milestone</code>: tickets become tracker issues and the pipeline starts.'],
+  ['background:#c3abe9;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.55),inset -3px -4px 6px rgba(90,50,140,0.22),0 6px 10px rgba(var(--amb),0.22)',
+    `<span class="gx" style="width:24px;height:24px"><span style="position:absolute;left:11px;top:0;width:2px;height:4px;background:#fffaf2"></span><span style="position:absolute;left:9.5px;top:-3px;width:5px;height:5px;border-radius:50%;background:#f2789a"></span><span style="position:absolute;left:0;top:5px;width:24px;height:18px;border-radius:7px;background:#fffaf2;box-shadow:inset 0 -3px 4px rgba(90,50,140,0.2),0 3px 5px rgba(70,30,120,0.3)"></span><span style="position:absolute;left:5px;top:11px;width:5px;height:5px;border-radius:50%;background:#8f74c4"></span><span style="position:absolute;left:14px;top:11px;width:5px;height:5px;border-radius:50%;background:#8f74c4"></span></span>`,
+    'Autonomous middle', 'Plan → build → fresh-context review (bounce-capped in code) → merge on <code>CLEAR</code> → issue closed → delivery verified.'],
+  ['background:#f6a5bb;box-shadow:inset 2px 3px 4px rgba(255,255,255,0.55),inset -3px -4px 6px rgba(170,30,80,0.2),0 6px 10px rgba(var(--amb),0.22)',
+    `<span class="gx" style="width:22px;height:22px"><span style="position:absolute;left:0;top:0;width:13px;height:13px;border-radius:50%;border:4px solid #fffaf2;box-shadow:0 3px 5px rgba(150,60,90,0.3)"></span><span style="position:absolute;left:16px;top:15px;width:4.5px;height:9px;border-radius:2.5px;background:#fffaf2;transform:rotate(-45deg)"></span></span>`,
+    'Gate 2 — smoke test', 'Agents own unit/integration/E2E all along; you test once, when the PRD is done. A nightly sweep fixes issues while you sleep.'],
+]
+
+// Use-when bullets are intentionally gone (parse + render): the approved mock's
+// pattern card is title + status chip + summary + role chips + links only.
 const patternCards = patterns
   .map((p) => {
-    const [bg, fg, ico] = STATUS_STYLE[p.status] || STATUS_STYLE.proposed
+    const c = STATUS_CHIP[p.status] || STATUS_CHIP.proposed
+    const summary = esc(p.summary).replace(/→/g, '<span class="arr">→</span>')
     return `
-      <article class="card pattern">
+      <article class="panel pattern">
         <div class="pattern-head">
           <h3>${esc(p.title)}</h3>
-          <span class="pill status" style="background:${bg};color:${fg}">${ico} ${esc(p.status)} · as of ${esc(p.asOf)}</span>
+          <span class="chip" style="${c.chip}"><span class="chip-dot" style="box-shadow:${c.dot}"></span>${esc(p.status)} · as of ${esc(p.asOf)}</span>
         </div>
-        <p class="summary">${esc(p.summary)}</p>
+        <p class="summary">${summary}</p>
         <div class="roles">
-          ${p.roles.map((r) => `<span class="pill role">${roleEmoji(r.role)} <b>${esc(r.role)}</b>&nbsp;· ${esc(r.model)} <code>@${esc(r.effort)}</code></span>`).join('\n          ')}
+          ${p.roles.map((r) => { const [dot, dotInk] = roleDot(r.role); return `<span class="role"><span class="dot" style="background:${dot};box-shadow:inset 1px 1.5px 1.5px rgba(255,255,255,0.6),inset -1px -1.5px 2px ${dotInk}"></span><b>${esc(r.role)}</b><span class="sep">·</span><code>${esc(r.model)} <span class="eff">@${esc(r.effort)}</span></code></span>` }).join('\n          ')}
         </div>
-        ${p.useWhen.length ? `<ul class="usewhen">${p.useWhen.map((u) => `<li>${esc(u)}</li>`).join('')}</ul>` : ''}
         <div class="links">
-          <a class="btn small sage" href="${GITHUB}/tree/main/patterns/${esc(p.dir)}">📖 Pattern write-up</a>
-          <a class="btn small lav" href="${GITHUB}/tree/main/patterns/${esc(p.dir)}/scaffold">🧰 Scaffold</a>
+          <a class="btn btn-green" href="${GITHUB}/tree/main/patterns/${esc(p.dir)}">Pattern write-up</a>
+          <a class="btn btn-purple" href="${GITHUB}/tree/main/patterns/${esc(p.dir)}/scaffold">Scaffold</a>
         </div>
       </article>`
   })
   .join('\n')
 
-const STEPS = [
-  ['📦', 'Adopt', `<code>${esc(QUICKSTART)}</code> — scaffold, templates, docs skeleton, CLAUDE.md, in one idempotent command.`],
-  ['🗺️', 'Break down', '<code>/breakdown-prd</code> — the Architect turns your PRD into sub-PRDs and cold-startable tickets, then stops.'],
-  ['🚦', 'Gate 1 — you decide', 'Review the breakdown, then <code>/start-milestone</code>: tickets become tracker issues and the pipeline starts.'],
-  ['🤖', 'Autonomous middle', 'Plan → build → fresh-context review (bounce-capped in code) → merge on CLEAR → issue closed → delivery verified.'],
-  ['🔎', 'Gate 2 — smoke test', 'Agents own unit/integration/E2E all along; you test once, when the PRD is done. A nightly sweep fixes issues while you sleep.'],
-]
-
 const html = `<!doctype html>
 <html lang="en">
 <head>
@@ -124,133 +172,187 @@ const html = `<!doctype html>
 <meta name="description" content="A catalog of multi-agent development architecture patterns: design write-ups plus drop-in scaffolding, E2E-tested, published on npm.">
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&family=Nunito:ital,wght@0,400;0,600;0,700;1,400&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@500;600;700;800&family=Nunito:wght@400;600;700;800;900&display=swap" rel="stylesheet">
 <style>
   :root{
-    --bg:#f7f0e6; --card:#fdf8f2; --ink:#5b4a3f; --muted:#96826f;
-    --sage:#cfe3d0; --sage-d:#5f9c6c; --peach:#f9d3b5; --peach-d:#d97f45;
-    --pink:#f7c6d0; --pink-d:#cf6d87; --butter:#f7e0a8; --butter-d:#a97e1c;
-    --blue:#c5d7ee; --blue-d:#5c82b6; --lav:#d9cdf0; --lav-d:#8266bd;
-    --clay:0 10px 24px rgba(91,74,63,.13), inset 0 3px 8px rgba(255,255,255,.95), inset 0 -4px 8px rgba(91,74,63,.07);
-    --clay-sm:0 6px 14px rgba(91,74,63,.12), inset 0 2px 5px rgba(255,255,255,.9), inset 0 -2px 5px rgba(91,74,63,.06);
+    --page:${THEME.page}; --hero-a:${THEME.heroA}; --hero-b:${THEME.heroB};
+    --hero-ink:${THEME.heroInk}; --hero-amb:${THEME.heroAmb};
+    --hero-title:${THEME.heroTitle}; --hero-body:${THEME.heroBody};
+    --card:${THEME.card}; --pill:${THEME.pill};
+    --ink:${THEME.ink}; --sub:${THEME.sub}; --mut:${THEME.mut}; --code:${THEME.code};
+    --amb:${THEME.amb}; --ins:${THEME.ins}; --flt:${THEME.flt};
+    --mono:ui-monospace,'Cascadia Code',Consolas,Menlo,monospace;
   }
   *{box-sizing:border-box}
-  body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.6 "Nunito",system-ui,sans-serif;
-    background-image:radial-gradient(600px 300px at 85% -50px, rgba(247,198,208,.35), transparent 70%),
-                     radial-gradient(500px 260px at -60px 30%, rgba(207,227,208,.4), transparent 70%),
-                     radial-gradient(520px 300px at 110% 75%, rgba(217,205,240,.32), transparent 70%);}
-  h1,h2,h3{font-family:"Baloo 2","Nunito",sans-serif;line-height:1.15;margin:0}
-  a{color:inherit;text-decoration:none}
-  .wrap{max-width:1060px;margin:0 auto;padding:28px 20px 60px}
-  header.nav{display:flex;align-items:center;gap:14px;flex-wrap:wrap;margin-bottom:26px}
-  .logo{font-family:"Baloo 2",sans-serif;font-weight:800;font-size:1.35rem;background:var(--card);
-    padding:10px 20px;border-radius:999px;box-shadow:var(--clay-sm);border:1.5px solid #fff}
-  .nav .spacer{flex:1}
-  .btn{display:inline-flex;align-items:center;gap:8px;font-weight:700;padding:10px 20px;border-radius:999px;
-    box-shadow:var(--clay-sm);border:1.5px solid #fff;transition:transform .15s ease, box-shadow .15s ease;cursor:pointer}
-  .btn:hover{transform:translateY(-2px)}
-  .btn.small{padding:8px 14px;font-size:.9rem}
-  .btn.sage{background:var(--sage);color:var(--sage-d)} .btn.peach{background:var(--peach);color:var(--peach-d)}
-  .btn.blue{background:var(--blue);color:var(--blue-d)}  .btn.lav{background:var(--lav);color:var(--lav-d)}
-  .card{background:var(--card);border-radius:28px;box-shadow:var(--clay);border:1.5px solid #fff;padding:26px 28px}
-  .hero{display:grid;grid-template-columns:1.5fr 1fr;gap:22px;align-items:stretch;margin-bottom:22px}
-  .hero .main{background:linear-gradient(145deg,#fbe3cd, #f9d3b5);}
-  .hero h1{font-size:clamp(1.9rem,4.5vw,2.9rem);color:#7a4b28;margin-bottom:10px}
-  .hero p.lede{color:#8a5a35;font-size:1.06rem;max-width:34em;margin:0 0 18px}
-  .cta{display:flex;gap:12px;flex-wrap:wrap;margin-bottom:18px}
-  .quick{background:rgba(255,255,255,.75);border-radius:18px;box-shadow:var(--clay-sm);border:1.5px solid #fff;
-    padding:12px 16px;display:flex;gap:10px;align-items:center;flex-wrap:wrap}
-  .quick code{font:600 .85rem/1.4 ui-monospace,Consolas,monospace;color:#7a4b28;word-break:break-all}
-  .hero .side{display:flex;flex-direction:column;gap:14px;justify-content:center}
-  .side .fact{display:flex;gap:12px;align-items:center;background:var(--card);border-radius:20px;
-    box-shadow:var(--clay-sm);border:1.5px solid #fff;padding:12px 16px;font-weight:600}
-  .side .fact .ico{font-size:1.5rem}
-  .chips{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:16px;margin:22px 0}
-  .chip{border-radius:24px;padding:18px 20px;box-shadow:var(--clay);border:1.5px solid #fff}
-  .chip .big{font-family:"Baloo 2",sans-serif;font-weight:800;font-size:1.7rem;display:block}
-  .chip small{font-weight:700;opacity:.75}
-  .chip.c1{background:var(--sage);color:var(--sage-d)} .chip.c2{background:var(--peach);color:var(--peach-d)}
-  .chip.c3{background:var(--butter);color:var(--butter-d)} .chip.c4{background:var(--blue);color:var(--blue-d)}
-  section{margin-top:34px}
-  section > h2{font-size:1.6rem;margin-bottom:14px}
-  .pattern{margin-bottom:18px}
-  .pattern-head{display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap;align-items:center;margin-bottom:8px}
-  .pattern h3{font-size:1.3rem}
-  .pill{display:inline-flex;align-items:center;gap:6px;padding:6px 14px;border-radius:999px;font-weight:700;
-    font-size:.85rem;box-shadow:var(--clay-sm);border:1.5px solid #fff}
-  .summary{color:var(--muted);margin:6px 0 14px;font-weight:600}
-  .roles{display:flex;gap:10px;flex-wrap:wrap;margin-bottom:12px}
-  .pill.role{background:#f3ece1;color:var(--ink)} .pill.role code{color:var(--lav-d)}
-  .usewhen{margin:0 0 14px;padding-left:22px;color:var(--muted)} .usewhen li{margin:4px 0}
-  .links{display:flex;gap:10px;flex-wrap:wrap}
-  .steps{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:16px}
-  .step{border-radius:24px;padding:20px;box-shadow:var(--clay);border:1.5px solid #fff;background:var(--card)}
-  .step .n{display:inline-flex;width:44px;height:44px;align-items:center;justify-content:center;font-size:1.4rem;
-    border-radius:16px;box-shadow:var(--clay-sm);border:1.5px solid #fff;margin-bottom:10px}
-  .step:nth-child(1) .n{background:var(--sage)} .step:nth-child(2) .n{background:var(--butter)}
-  .step:nth-child(3) .n{background:var(--peach)} .step:nth-child(4) .n{background:var(--lav)}
-  .step:nth-child(5) .n{background:var(--pink)}
-  .step h3{font-size:1.05rem;margin-bottom:6px} .step p{margin:0;font-size:.9rem;color:var(--muted)}
-  .step code{font-size:.8rem;color:var(--lav-d);word-break:break-all}
-  footer{margin-top:44px;text-align:center;color:var(--muted);font-weight:600;font-size:.9rem}
-  footer a{color:var(--lav-d)}
-  @media (max-width:760px){.hero{grid-template-columns:1fr}}
+  body{margin:0;background:var(--page);font-family:'Nunito',sans-serif}
+  a{color:#e7548c;text-decoration:none}
+  a:hover{color:#c13a63}
+  .wrap{max-width:880px;margin:0 auto;padding:22px 0 34px}
+  .gx{position:relative;display:inline-block}
+  .arr{color:#e7548c}
+
+  .nav{display:flex;align-items:center;margin-bottom:22px}
+  .logo{display:flex;align-items:center;gap:10px;padding:8px 18px 8px 13px;border-radius:19px;background:var(--pill);
+    box-shadow:inset 0 2px 2px #fff,inset 0 -3px 5px rgba(var(--ins),0.2),0 8px 16px rgba(var(--amb),0.25)}
+  .logo b{font-family:'Baloo 2',cursive;font-weight:800;font-size:19px;color:var(--ink)}
+  .nav-links{margin-left:auto;display:flex;gap:10px}
+
+  .btn{display:inline-flex;align-items:center;gap:8px;padding:9px 18px;border-radius:18px;color:#fff;
+    font-size:12.5px;font-weight:900;transition:transform .15s ease;cursor:pointer}
+  .btn:hover{transform:translateY(-2px);color:#fff}
+  .btn:active{transform:translateY(1px)}
+  .btn-lg{padding:10px 20px;font-size:13px}
+  .btn-green{background:linear-gradient(180deg,#b3dcab,#98cb8e);text-shadow:0 1px 2px rgba(30,90,40,0.35);
+    box-shadow:inset 0 2px 3px rgba(255,255,255,0.5),inset 0 -3px 5px rgba(30,100,40,0.25),0 8px 14px rgba(120,150,100,0.35)}
+  .btn-orange{background:linear-gradient(180deg,#f6c9a2,#efb185);text-shadow:0 1px 2px rgba(160,80,30,0.35);
+    box-shadow:inset 0 2px 3px rgba(255,255,255,0.5),inset 0 -3px 5px rgba(170,90,30,0.25),0 8px 14px rgba(190,130,90,0.35)}
+  .btn-blue{background:linear-gradient(180deg,#b3cdf0,#96b8e5);text-shadow:0 1px 2px rgba(40,80,150,0.4);
+    box-shadow:inset 0 2px 3px rgba(255,255,255,0.55),inset 0 -3px 5px rgba(40,80,150,0.28),0 8px 14px rgba(var(--amb),0.3)}
+  .btn-purple{background:linear-gradient(180deg,#c3abe9,#a78cd8);text-shadow:0 1px 2px rgba(90,50,130,0.4);
+    box-shadow:inset 0 2px 3px rgba(255,255,255,0.55),inset 0 -4px 6px rgba(94,58,140,0.28),0 8px 14px rgba(var(--amb),0.3)}
+
+  .hero{display:grid;grid-template-columns:1fr 300px;gap:16px;align-items:stretch}
+  .hero-main{border-radius:30px;padding:30px 34px 26px;background:linear-gradient(170deg,var(--hero-a),var(--hero-b));
+    box-shadow:inset 0 3px 4px rgba(255,255,255,0.6),inset 0 -6px 10px var(--hero-ink),0 16px 30px var(--hero-amb)}
+  .hero-main h1{margin:0;font-family:'Baloo 2',cursive;font-weight:800;font-size:38px;line-height:1.1;
+    color:var(--hero-title);text-shadow:0 2px 0 rgba(255,255,255,0.4)}
+  .lede{margin:14px 0 0;max-width:410px;font-size:13.5px;line-height:1.6;font-weight:700;color:var(--hero-body)}
+  .cta{display:flex;gap:12px;margin-top:20px}
+  .quick{margin-top:20px;border-radius:16px;background:var(--pill);padding:14px 16px 12px;
+    box-shadow:inset 0 3px 6px rgba(var(--flt),0.2),inset 0 -2px 2px rgba(255,255,255,0.8)}
+  .quick code{display:block;font-family:var(--mono);font-size:12px;font-weight:700;color:var(--code);line-height:1.55;word-break:break-all}
+  .copy{display:inline-flex;margin-top:10px;padding:6px 16px;border-radius:13px;border:0;
+    background:linear-gradient(180deg,#f9d66e,#f0c14a);cursor:pointer;font-family:'Nunito',sans-serif;
+    font-size:12px;font-weight:900;color:#6b4a15;transition:transform .15s ease;
+    box-shadow:inset 0 2px 2px rgba(255,255,255,0.6),inset 0 -3px 4px rgba(180,120,20,0.3),0 5px 10px rgba(180,130,60,0.3)}
+  .copy:hover{transform:translateY(-1.5px)}
+  .copy:active{transform:translateY(1px)}
+  .hero-side{display:flex;flex-direction:column;gap:14px;justify-content:center}
+  .fact{display:flex;align-items:center;gap:12px;padding:13px 16px;border-radius:20px;background:var(--card);
+    box-shadow:inset 0 2px 2px #fff,inset 0 -3px 6px rgba(var(--ins),0.16),0 10px 20px rgba(var(--amb),0.22)}
+  .fact-ico{flex:none;width:38px;height:38px;border-radius:12px;display:grid;place-items:center}
+  .fact p{margin:0;font-size:12.5px;font-weight:800;color:var(--sub);line-height:1.5}
+
+  .stats{display:grid;grid-template-columns:repeat(4,1fr);gap:15px;margin-top:18px}
+  .stat{border-radius:22px;padding:16px 18px 18px}
+  .stat .big{font-family:'Baloo 2',cursive;font-weight:800;font-size:23px}
+  .stat p{margin:3px 0 0;font-size:11.5px;font-weight:800;line-height:1.5}
+  .stat-green{background:linear-gradient(180deg,#b9dfb1,#9bce92);
+    box-shadow:inset 0 3px 4px rgba(255,255,255,0.55),inset 0 -5px 8px rgba(30,90,40,0.2),0 10px 20px rgba(var(--amb),0.25)}
+  .stat-green .big{color:#2f6b35} .stat-green p{color:#3f7a45}
+  .stat-orange{background:linear-gradient(180deg,#f9cba6,#f1af85);
+    box-shadow:inset 0 3px 4px rgba(255,255,255,0.55),inset 0 -5px 8px rgba(170,90,30,0.2),0 10px 20px rgba(var(--amb),0.25)}
+  .stat-orange .big{color:#94481c} .stat-orange p{color:#9c5426}
+  .stat-yellow{background:linear-gradient(180deg,#fae09c,#f3cb6a);
+    box-shadow:inset 0 3px 4px rgba(255,255,255,0.6),inset 0 -5px 8px rgba(180,120,20,0.22),0 10px 20px rgba(var(--amb),0.25)}
+  .stat-yellow .big{color:#7e5a12} .stat-yellow p{color:#8a6218}
+  .stat-blue{background:linear-gradient(180deg,#b7d2f4,#9abfe9);
+    box-shadow:inset 0 3px 4px rgba(255,255,255,0.55),inset 0 -5px 8px rgba(40,80,150,0.22),0 10px 20px rgba(var(--amb),0.25)}
+  .stat-blue .big{color:#2c548c} .stat-blue p{color:#315e9c}
+
+  .sec-head{display:flex;align-items:center;gap:11px;margin:32px 0 14px}
+  .sec-head h2{margin:0;font-family:'Baloo 2',cursive;font-weight:800;font-size:25px;color:var(--ink)}
+
+  .panel{border-radius:24px;background:var(--card);padding:20px 24px 22px;
+    box-shadow:inset 0 2px 2px #fff,inset 0 -4px 8px rgba(var(--ins),0.15),0 14px 26px rgba(var(--amb),0.25)}
+  .pattern + .pattern{margin-top:16px}
+  .pattern-head{display:flex;align-items:center;gap:14px;flex-wrap:wrap}
+  .pattern-head h3{margin:0;font-family:'Baloo 2',cursive;font-weight:700;font-size:20px;color:var(--ink);flex:1}
+  .chip{display:inline-flex;align-items:center;gap:7px;padding:7px 15px;border-radius:15px;font-size:11.5px;font-weight:900}
+  .chip-dot{width:8px;height:8px;border-radius:50%;background:#fffaf2}
+  .summary{margin:12px 0 0;font-size:13px;line-height:1.6;font-weight:700;color:var(--sub);max-width:760px}
+  .roles{display:flex;flex-wrap:wrap;gap:10px;margin-top:15px}
+  .role{display:inline-flex;align-items:center;gap:8px;padding:8px 15px;border-radius:16px;background:var(--pill);
+    box-shadow:inset 0 2px 2px #fff,inset 0 -3px 5px rgba(var(--ins),0.25),0 5px 10px rgba(var(--amb),0.2)}
+  .role .dot{width:9px;height:9px;border-radius:50%}
+  .role b{font-size:12px;font-weight:900;color:var(--ink)}
+  .role .sep{font-size:11px;font-weight:700;color:var(--mut)}
+  .role code{font-family:var(--mono);font-size:11px;font-weight:700;color:#8a5fd0}
+  .role .eff{color:#e7548c}
+  .links{display:flex;gap:12px;margin-top:17px}
+
+  .steps{display:grid;grid-template-columns:repeat(5,1fr);gap:14px}
+  .step{border-radius:20px;background:var(--card);padding:15px 14px 17px;
+    box-shadow:inset 0 2px 2px #fff,inset 0 -3px 6px rgba(var(--ins),0.15),0 10px 20px rgba(var(--amb),0.22)}
+  .step-ico{width:42px;height:42px;border-radius:13px;display:grid;place-items:center}
+  .step h3{margin:11px 0 0;font-size:13px;font-weight:900;color:var(--ink);font-family:'Nunito',sans-serif}
+  .step p{margin:6px 0 0;font-size:11.5px;font-weight:700;color:var(--sub);line-height:1.55}
+  .step code{font-family:var(--mono);font-size:10px;background:rgba(var(--flt),0.12);border-radius:5px;padding:1px 4px;color:var(--code);word-break:break-all}
+
+  footer{margin-top:30px;text-align:center;font-size:12.5px;font-weight:700;color:var(--mut)}
+  footer code{font-family:var(--mono);font-size:11.5px;color:#8a5fd0}
+
+  @media (max-width:912px){.wrap{padding-left:16px;padding-right:16px}}
+  @media (max-width:860px){.hero{grid-template-columns:1fr}.stats{grid-template-columns:repeat(2,1fr)}.steps{grid-template-columns:repeat(2,1fr)}}
+  @media (max-width:540px){.stats,.steps{grid-template-columns:1fr}.pattern-head h3{flex-basis:100%}}
 </style>
 </head>
 <body>
 <div class="wrap">
   <header class="nav">
-    <span class="logo">🏗️ agent-templates</span>
-    <span class="spacer"></span>
-    <a class="btn sage" href="${GITHUB}">⭐ GitHub</a>
-    <a class="btn peach" href="${NPM}">📦 npm <span data-npm-version>v${esc(pkg.version)}</span></a>
+    <span class="logo">${LOGO_ICON}<b>agent-templates</b></span>
+    <span class="nav-links">
+      <a class="btn btn-green" href="${GITHUB}">${STAR_ICON} GitHub</a>
+      <a class="btn btn-orange" href="${NPM}">${NPM_ICON} npm&nbsp;&nbsp;<span data-npm-version>v${esc(pkg.version)}</span></a>
+    </span>
   </header>
 
   <div class="hero">
-    <div class="card main">
+    <div class="hero-main">
       <h1>Multi-agent patterns,<br>ready to drop in.</h1>
-      <p class="lede">Field-proven architectures for AI-agent development — each one a design write-up <b>plus</b> working scaffolding. Humans decide at two gates; the agents do the rest.</p>
+      <p class="lede">Field-proven architectures for AI-agent development — each one a design write-up <em>plus</em> working scaffolding. Humans decide at two gates; the agents do the rest.</p>
       <div class="cta">
-        <a class="btn blue" href="${GITHUB}/blob/main/ADOPTING.md">🚀 Adoption guide</a>
-        <a class="btn lav" href="${GITHUB}/blob/main/CLAUDE.md">📜 Operating manual</a>
+        <a class="btn btn-lg btn-blue" href="${GITHUB}/blob/main/ADOPTING.md">Adoption guide</a>
+        <a class="btn btn-lg btn-purple" href="${GITHUB}/blob/main/CLAUDE.md">Operating manual</a>
+      </div>
+      <div class="quick">
+        <code id="qs">${esc(QUICKSTART)}</code>
+        <button class="copy" id="copy-btn" type="button">Copy</button>
       </div>
-      <div class="quick"><code id="qs">${esc(QUICKSTART)}</code><button class="btn small butter" style="background:var(--butter);color:var(--butter-d)" onclick="navigator.clipboard.writeText(document.getElementById('qs').textContent).then(()=>{this.textContent='Copied ✓'})">Copy</button></div>
     </div>
-    <div class="side">
-      <div class="fact"><span class="ico">🧾</span> Every model/effort claim carries a source label and an expiry date</div>
-      <div class="fact"><span class="ico">🛡️</span> Role boundaries enforced by hooks, not prose</div>
-      <div class="fact"><span class="ico">🌙</span> Nightly sweep triages and fixes issues while you sleep</div>
+    <div class="hero-side">
+      ${FACTS.map(([tile, glyph, copy]) => `<div class="fact"><span class="fact-ico" style="${tile}">${glyph}</span><p>${copy}</p></div>`).join('\n      ')}
     </div>
   </div>
 
-  <div class="chips">
-    <div class="chip c1"><span class="big">${patterns.length}</span><small>pattern${patterns.length === 1 ? '' : 's'} in the catalog</small></div>
-    <div class="chip c2"><span class="big" data-npm-version>v${esc(pkg.version)}</span><small>on npm · MIT</small></div>
-    <div class="chip c3"><span class="big">E2E</span><small>gated merges — deterministic, zero-token tests</small></div>
-    <div class="chip c4"><span class="big">2</span><small>human gates: sign-off &amp; smoke test</small></div>
+  <div class="stats">
+    <div class="stat stat-green"><span class="big">${patterns.length}</span><p>pattern${patterns.length === 1 ? '' : 's'} in the catalog</p></div>
+    <div class="stat stat-orange"><span class="big" data-npm-version>v${esc(pkg.version)}</span><p>on npm · MIT</p></div>
+    <div class="stat stat-yellow"><span class="big">E2E</span><p>gated merges — deterministic, zero-token tests</p></div>
+    <div class="stat stat-blue"><span class="big">2</span><p>human gates: sign-off &amp; smoke test</p></div>
   </div>
 
   <section>
-    <h2>🧩 Patterns</h2>
+    <div class="sec-head">${PATTERNS_ICON}<h2>Patterns</h2></div>
     ${patternCards}
   </section>
 
   <section>
-    <h2>🛤️ From a bare PRD.md to shipped</h2>
+    <div class="sec-head">${PIPELINE_ICON}<h2>From a bare PRD.md to shipped</h2></div>
     <div class="steps">
-      ${STEPS.map(([ico, t, d], i) => `<div class="step"><span class="n">${ico}</span><h3>${i + 1}. ${t}</h3><p>${d}</p></div>`).join('\n      ')}
+      ${STEPS.map(([tile, glyph, t, d], i) => `<div class="step"><span class="step-ico" style="${tile}">${glyph}</span><h3>${i + 1}. ${t}</h3><p>${d}</p></div>`).join('\n      ')}
     </div>
   </section>
 
   <footer>
-    Generated from the pattern catalog by <a href="${GITHUB}/blob/main/scripts/build-site.mjs">scripts/build-site.mjs</a>
+    Generated from the pattern catalog by <a href="${GITHUB}/blob/main/scripts/build-site.mjs"><code>scripts/build-site.mjs</code></a>
     · ${new Date().toISOString().slice(0, 10)} · <a href="${GITHUB}/blob/main/LICENSE">MIT</a>
     · <a href="${GITHUB}/issues/new/choose">Feedback → issues</a>
   </footer>
 </div>
 <script>
-fetch('https://registry.npmjs.org/agent-templates').then(r=>r.json()).then(d=>{
-  var v=d['dist-tags']&&d['dist-tags'].latest;
+(function(){
+  var b=document.getElementById('copy-btn'),q=document.getElementById('qs'),t
+  if(!b||!q)return
+  b.addEventListener('click',function(){
+    try{navigator.clipboard.writeText(q.textContent).catch(function(){})}catch(e){}
+    b.textContent='Copied!'
+    clearTimeout(t)
+    t=setTimeout(function(){b.textContent='Copy'},1400)
+  })
+})()
+fetch('https://registry.npmjs.org/agent-templates').then(function(r){return r.json()}).then(function(d){
+  var v=d['dist-tags']&&d['dist-tags'].latest
   if(v){document.querySelectorAll('[data-npm-version]').forEach(function(e){e.textContent='v'+v})}
 }).catch(function(){})
 </script>