@bonesofspring/ai-rules 0.2.17 → 0.2.19

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 ## Unreleased
 
+Grouping for the next npm cut: **(A)** post-`0.2.18` delta — MCP merge, spec P0/P1, hook-only lifecycle, and the review follow-up below; **(B)** sections after MCP (UX, mockup reviewer, product-specs, android-kotlin, nuxt/svelte/php-laravel, …) were already Unreleased **on the `v0.2.18` tag** and were never versioned.
+
+### Follow-up: review fixes (lifecycle, MCP merge, docs)
+
+- Hook-only lifecycle sweep: 22 ios-swift agents, 8 next/nuxt/svelte/ios `code-review` skills, 5 Claude `feature-continue` commands, Claude Playwright generators, and backend `code-review` skills upsert `artifact-manifest.json` receipts and must not mutate `status.json`. New hard gate `check:hook-only-lifecycle` (wired into `check:preset-structure`).
+- CLI `init` MCP merge: nested `env` / `headers` on shipped keys are preserved; invalid / JSONC / non-object files get a timestamped `*.bak.<iso>` then preset replace; `mcpServers` as an array is backed up and merged as empty extras. Tests cover those paths.
+- Shipped MCP packages pinned: Context7 `@upstash/context7-mcp@4.0.2`, Playwright `@playwright/mcp@0.0.79`, Chrome DevTools `chrome-devtools-mcp@1.7.0` (no `@latest`).
+- `mcp-usage`: Figma policy is stack-class-specific (UI Stack notes: only `mockup-reviewer` for mockup review). Overlay matching prefers documented aliases / `plugin-*` over substring guessing. Cursor adapters are requestable (no source-tree `globs`); Claude keeps `paths:` so the stem is not a 4th session-start rule.
+- Docs: applyReadiness is YAML on `implementation.md` and a JSON-shaped object on the analyst receipt; Claude rules README twin FAIL list is all 10 stacks; backend AGENTS/CLAUDE inventories list 10 skills including `spec-authoring` / `spec-discovery`. Package README documents JSONC backup and non-sticky shipped-server deletes.
+
+### Follow-up: hook-only lifecycle + stack-neutral discovery examples
+
+- **`debug-investigation`** (next / nuxt / svelte / ios-swift, Cursor + Claude) upserts the owned `artifact-manifest.json` receipt; it must not mutate `status.json`. Cursor **`playwright-test-*`** (planner/generator/healer) and iOS **`xcuitest-test-*`** use the same receipt pattern.
+- **`spec-discovery`** claim-ledger example is stack-neutral (no `app/src/ui/Cart.tsx`). Backend / mobile **`memlog.example.md`** fixtures no longer cite Next `CartEmpty.tsx`.
+- Next **`tests-unit`** Incorrect/Correct pair includes a fenced Correct example (`yarn check:rule-eval`).
+
+### Spec workflow P1 capabilities
+
+- **`specMode`** (`consume` | `generate` | `none`) on `brief.md` / optional `pipeline.json`. Spike/research uses `none` — no dummy INDEX row.
+- **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ state: blocked|ready|all_done, contextFiles[] }` on the analyst receipt (analyst may emit `blocked` before the authoring gate).
+- Requestable skill **`spec-discovery`** (11 methods, mandatory claim ledger). Analyst loads it only for research-before-spec — not default `/task` consume. Cursor + Claude ×10 stacks.
+- **Memlog** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/…`) — append-only agent notes; hook does not parse it.
+- **Code Map** (3–8 annotated paths) + **Suggested Review Order** when a WP spans more than one layer.
+- Skills README catalogs include **`spec-authoring`** (was missing beside `spec-discovery`). Claude nuxt `task-router` writes `.claude/team` (not `.cursor/team`).
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish.
+
+### Spec workflow P0 hygiene
+
+- Router intent **`spec-gen`** now has a default human gate `["after:task-analyst"]` on every stack `task-router` (hook will stop author drafts before `feature-developer`).
+- Orchestrator **Entry points** lists **`/spec-start`** (intent `spec-gen` → analyst author mode → human gate) across Cursor + Claude twins.
+- `feature-delivery` and `debug-investigation` skills, Cursor `playwright-test-*` (planner/generator/healer), and iOS `xcuitest-test-*` no longer tell agents to write `status.json`; the orchestration hook is the single lifecycle writer (receipts stay on `artifact-manifest.json`).
+- Embed drift check includes `architecture/product-specs-authoring.md` (same mode as `product-specs`).
+- npm tarball now ships `scripts/` so consumers can run `check-product-specs.sh` (and the other structure/drift checkers) from the package. The checker is bash INDEX/frontmatter/heading validation — it does **not** evaluate `frontmatter-v1.schema.json`. The schema’s hosted `$id` (404) was removed; `$comment` documents that split.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish to pick up Entry points / router / skill wording.
+
+### MCP usage protocol + `mcp.json` merge
+
+- New requestable shared-core stem **`mcp-usage`** (Cursor + Claude twins ×10 stacks). Runtime catalog is SoT. **Context7** (already shipped): query installed-major docs when lockfile + sibling files are not enough; cap ≤3 queries; degrade to `// VERIFY` if down — do not block.
+- **Chrome DevTools** (already shipped on next/nuxt/svelte): wired for `debugger` / `performance-auditor` against a running app. Playwright MCP stays the e2e path. Not interchangeable.
+- **Local overlay** (not shipped): Storybook (`user-storybook` / `@storybook/addon-mcp`), Sentry/Datadog, Linear/Jira/Notion, optional GitHub MCP. Use only when the server is ready **and** the task fits. Ticket MCP is read-only; task-folder artifacts remain SoT. No new pipeline agents.
+- `anti-sycophancy-discipline` rule 1 and always-on `code-quality` essentials point at Context7 via `mcp-usage`.
+- CLI **`init` merges `mcpServers`**: extra local servers are kept; shipped keys update; nested `env` / `headers` on shipped keys are preserved unless the preset defines them. Invalid / JSONC / non-object JSON is copied to a timestamped `*.bak.<iso>` and replaced with the preset (extras are not merged on that path). Deleting a shipped server is not sticky across re-init. Help + package README updated.
+- Leakage: `storybook-reviewer` forbidden as an agent stem on backend/mobile; Storybook/Chrome DevTools must not be required handoffs there.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish. Overlay servers in project `mcp.json` survive re-init **when the existing file is valid JSON**.
+
+### UX design skill (UI stacks)
+
+- New requestable skill/rule **`ux-design`** on **`next`**, **`nuxt`**, **`svelte`**, **`ios-swift`**, **`android-kotlin`** (Cursor + Claude twins). Shared-core checklist: `presets/_shared/core/review/ux-design.md`. Invoked by **`task-analyst`** — **no** `ux-designer` agent, **no** FAIL-only hook, **no** Figma MCP in the skill/rule.
+- Standalone intent **`ux-design`**: synthesize or review behavioral UX (IA, named flows, empty/error/loading matrix) → profile `light`, steps only `task-analyst`, `humanGates: []`. Classify `mockup-review` before `ux-design` before `review-only`.
+- Embedded: on UI required-signal or advisory AC, analyst loads the skill (no new pipeline step). Required `INCOMPLETE` blocks DoR; advisory notes only. Developer gate: required-signal + no Figma + missing/`INCOMPLETE` UX artifact → `blocked`, hand back to analyst.
+- Backend stacks (`go`, `java`, `mcp-ts`, `php-*`) never ship `skills/ux-design` / `rules/ux-design` or `agents/ux-designer.md`; leakage checker forbids those stems.
+- `/task` examples include standalone UX (no Figma). `artifact-manifest.example.json` analysis paths append `ux-design.md` on web stacks.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <ui-stack>` after publish.
+
+### Mockup reviewer (UI stacks)
+
+- New **`mockup-reviewer`** agent + requestable skill/rule **`mockup-review`** on **`next`**, **`nuxt`**, **`svelte`**, **`ios-swift`**, **`android-kotlin`** (Cursor + Claude twins). Shared-core checklist: `presets/_shared/core/review/mockup-review.md`. Report template fence is a single closed block (no stray fence after AC coverage).
+- Standalone intent **`mockup-review`**: `/task` + Figma URL (e.g. «ревью макета …») → profile `light`, steps only `mockup-reviewer`, report-only exit on FAIL (like `perf-audit`).
+- Embedded: `figma.com` in feature/refactor/spike/spec-gen → reviewer after `task-analyst`, before architect/developer. Embedded **FAIL** → receipt `changes_requested` + FAIL-only hook gate (`awaiting_approval`); resume via `/task-continue` only — no `feature-developer` retry. Orchestrator rule 6 and UI `chain-team-phases.sh` parallel-join now match that exception; ios-swift/android-kotlin `AGENT_HANDOFF` includes `mockup-reviewer`. Never put `mockup-reviewer` in `parallel: true`.
+- Figma MCP-first (read-only subset + node caps); `BLOCKED_MCP` when OAuth/MCP unavailable. Go keeps optional Figma MCP for ad-hoc context — **not** a mockup-review pipeline.
+- Backend stacks (`go`, `java`, `mcp-ts`, `php-*`) never schedule `mockup-reviewer`; leakage checker forbids agent stem on backend.
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <ui-stack>` after publish.
+
 ### Product specs authoring (Phases A–E)
 
 - **Generation modes** (shared-core): **Consume** (default discovery, soft-fail on miss) · **Generate** (explicit intent / AC / `/spec-start` with existing tree) · **Bootstrap** (same triggers when `docs/specs/` absent). Greenfield policy: no INDEX/spec invention without explicit intent; conflict precedence human > brief AC > approved spec > code.

package/README.md

@@ -13,7 +13,7 @@ npx @bonesofspring/ai-rules clean cursor
 
 Global: `npm i -g @bonesofspring/ai-rules`, then `ai-rules ...`.
 
-`init` merges into the **current working directory** (or `--cwd <dir>`): dirs are created, matching files are **overwritten**. `--preset` defaults to **`next`**. Supported forms:
+`init` merges into the **current working directory** (or `--cwd <dir>`): dirs are created, matching files are **overwritten**, except **`mcp.json` / `.mcp.json`** where `mcpServers` is **merged** (extra local servers are kept; shipped keys update; nested `env` / `headers` on shipped keys are preserved unless the preset defines them). `--preset` defaults to **`next`**. Supported forms:
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset next
@@ -24,6 +24,8 @@ npx @bonesofspring/ai-rules cursor init --preset next
 
 If `.cursor` does not appear, check the command output for errors and confirm you run init from the **target project root** (where the app lives), not from `node_modules`. Success ends with: `Done. .cursor installed at <absolute-path>`.
 
+**`mcp.json` troubleshooting:** extra overlay servers survive re-init only when the existing file is **valid JSON**. JSONC / trailing commas / a non-object file is copied to a timestamped `mcp.json.bak.<iso>` (or `.mcp.json.bak.<iso>`) and **replaced with the preset** — extras are not merged on that path. Nested `env` / `headers` on shipped server names are kept when the file is valid. Deleting a shipped server (Playwright, Chrome DevTools, Context7, Figma) is **not sticky**: the next `init` restores it.
+
 ### `clean` (breaking vs older wipe behavior)
 
 `clean cursor` / `clean claude` removes **only CLI-managed paths** — not the entire `.cursor/` or `.claude/` tree:
@@ -47,12 +49,12 @@ Where things go on `init`:
 | hooks cookbook | `.cursor/hooks/examples/` (not in default `hooks.json`) | `.claude/hooks/examples/` |
 | skills | `.cursor/skills` | `.claude/skills` |
 | team artifacts template | `.cursor/team` (incl. `conventions.md`) | `.claude/team` |
-| MCP | `mcp.json` → `.cursor/mcp.json`, `MCP.md` → `.cursor/` | `mcp.json` → **`.mcp.json`** (project root), `MCP.md` → `.claude/` |
+| MCP | `mcp.json` → `.cursor/mcp.json` (**merge** `mcpServers`), `MCP.md` → `.cursor/` | `mcp.json` → **`.mcp.json`** (project root, **merge** `mcpServers`), `MCP.md` → `.claude/` |
 | tool map | `AGENTS.md` → `.cursor/AGENTS.md`, `BUGBOT.md` | `CLAUDE.md` → `.claude/CLAUDE.md` |
 | **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
 | **docs/specs seed** | When `<cwd>/docs/specs/` is **absent**, copy INDEX stub + `_templates/*` from `presets/_shared/assets/docs-specs/` (never overwrite existing INDEX) | same |
 
-Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
+Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `mockup-review` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — Figma mockup reviewer via agent `mockup-reviewer`); `ux-design` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — behavioral UX via `task-analyst`, no agent); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
 
 ## Product specs (`docs/specs/`)
 
@@ -101,7 +103,7 @@ Presets are developed in this monorepo under `presets/`. If you add or change ru
 
 - **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging (includes requestable embed stem `architecture/product-specs` for consumer `docs/specs` INDEX discovery)
 - **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (≤3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
-- **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh)
+- **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh). Published npm `files` include `scripts/` so consumers can run `check-product-specs.sh` from the package.
 - **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)
 - **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`
 - **CLI note:** `_shared` is not an installable `--preset`; `init` copies only `presets/cursor/<name>/` or `presets/claude/<name>/`

package/bin/cli.js

@@ -60,7 +60,10 @@ Options:
   --cwd <dir>       Target project directory (default: current working directory)
 
 Notes:
-  init merges into the target directory; same-named files are overwritten.
+  init merges into the target directory; same-named files are overwritten except mcp.json
+  (mcpServers is merged: extra local servers are kept; shipped keys update; nested env/headers
+  on shipped keys are preserved unless the preset defines them. Invalid / non-object JSON is
+  copied to a timestamped *.bak.* then replaced with the preset file. JSONC is not supported).
   Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
   Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
@@ -204,6 +207,112 @@ function assertPresetDirInsideRoot(presetsRoot, presetBase) {
   }
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function ownKeys(object) {
+  return Object.keys(object).filter((key) => Object.hasOwn(object, key));
+}
+
+function backupMcpFile(mcpDestAbs) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const bak = `${mcpDestAbs}.bak.${stamp}`;
+  fs.copyFileSync(mcpDestAbs, bak);
+  return bak;
+}
+
+function replaceMcpWithPreset(mcpFrom, mcpDestAbs, reason) {
+  const bak = backupMcpFile(mcpDestAbs);
+  fs.copyFileSync(mcpFrom, mcpDestAbs);
+  console.warn(`${reason}; backed up to ${bak} and replaced with the preset file.`);
+}
+
+/**
+ * Merge one shipped server object. Preset scalar fields win; nested `env` / `headers`
+ * keep consumer keys unless the preset defines the same nested key.
+ */
+function mergeServerEntry(existingEntry, presetEntry) {
+  if (!isPlainObject(existingEntry) || !isPlainObject(presetEntry)) {
+    return presetEntry;
+  }
+  const merged = { ...existingEntry, ...presetEntry };
+  for (const nested of ['env', 'headers']) {
+    const existingNested = existingEntry[nested];
+    const presetNested = presetEntry[nested];
+    if (isPlainObject(existingNested) && isPlainObject(presetNested)) {
+      merged[nested] = { ...existingNested, ...presetNested };
+    } else if (isPlainObject(existingNested) && presetNested === undefined) {
+      merged[nested] = existingNested;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Extra local `mcpServers` keys are kept. Shipped keys update; nested `env` / `headers`
+ * on overlapping keys are preserved unless the preset defines them.
+ * Other unknown top-level keys on the existing file are preserved.
+ * @returns {{ merged: object, extrasKept: string[], existingServersInvalid: boolean }}
+ */
+function mergeMcpConfig(presetObj, existingObj) {
+  const preset = isPlainObject(presetObj) ? presetObj : {};
+  const existing = isPlainObject(existingObj) ? existingObj : {};
+  const existingServersInvalid =
+    Object.hasOwn(existing, 'mcpServers') && !isPlainObject(existing.mcpServers);
+  const presetServers = isPlainObject(preset.mcpServers) ? preset.mcpServers : {};
+  const existingServers =
+    !existingServersInvalid && isPlainObject(existing.mcpServers) ? existing.mcpServers : {};
+  const extrasKept = ownKeys(existingServers).filter((key) => !Object.hasOwn(presetServers, key));
+  const mergedServers = { ...existingServers };
+  for (const key of ownKeys(presetServers)) {
+    mergedServers[key] = mergeServerEntry(existingServers[key], presetServers[key]);
+  }
+  return {
+    merged: { ...existing, ...preset, mcpServers: mergedServers },
+    extrasKept,
+    existingServersInvalid,
+  };
+}
+
+function installMcpJson(mcpFrom, mcpDestAbs, destLabel) {
+  const presetRaw = fs.readFileSync(mcpFrom, 'utf8');
+  const presetObj = JSON.parse(presetRaw);
+  if (!fs.existsSync(mcpDestAbs)) {
+    fs.mkdirSync(path.dirname(mcpDestAbs), { recursive: true });
+    fs.copyFileSync(mcpFrom, mcpDestAbs);
+    console.log(`Copied ${path.basename(mcpFrom)} → ${destLabel}`);
+    return;
+  }
+  let existingObj;
+  try {
+    existingObj = JSON.parse(fs.readFileSync(mcpDestAbs, 'utf8'));
+  } catch {
+    replaceMcpWithPreset(mcpFrom, mcpDestAbs, `Existing ${destLabel} was not valid JSON`);
+    return;
+  }
+  if (!isPlainObject(existingObj)) {
+    replaceMcpWithPreset(mcpFrom, mcpDestAbs, `Existing ${destLabel} was not a JSON object`);
+    return;
+  }
+  const { merged, extrasKept, existingServersInvalid } = mergeMcpConfig(presetObj, existingObj);
+  if (existingServersInvalid) {
+    const bak = backupMcpFile(mcpDestAbs);
+    console.warn(
+      `Existing ${destLabel} mcpServers was not a JSON object; backed up to ${bak} and merging as empty extras.`,
+    );
+  }
+  fs.mkdirSync(path.dirname(mcpDestAbs), { recursive: true });
+  fs.writeFileSync(mcpDestAbs, `${JSON.stringify(merged, null, 2)}\n`);
+  if (extrasKept.length > 0) {
+    console.log(
+      `Merged ${path.basename(mcpFrom)} → ${destLabel} (kept extra servers: ${extrasKept.join(', ')})`,
+    );
+  } else {
+    console.log(`Merged ${path.basename(mcpFrom)} → ${destLabel}`);
+  }
+}
+
 function copyDir(src, dest) {
   if (!fs.existsSync(src)) {
     throw new Error(`Source not found: ${src}`);
@@ -431,9 +540,7 @@ function cmdInit(tool, preset, cwdOption) {
       const mcpFrom = path.join(base, cfg.mcpJsonSrc);
       if (fs.existsSync(mcpFrom)) {
         const mcpDestAbs = path.join(cwd, cfg.mcpJsonDest);
-        fs.mkdirSync(path.dirname(mcpDestAbs), { recursive: true });
-        fs.copyFileSync(mcpFrom, mcpDestAbs);
-        console.log(`Copied ${cfg.mcpJsonSrc} → ${cfg.mcpJsonDest}`);
+        installMcpJson(mcpFrom, mcpDestAbs, cfg.mcpJsonDest);
         copiedSteps++;
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -22,18 +22,21 @@
     "README.md",
     "CHANGELOG.md",
     "bin",
-    "presets"
+    "presets",
+    "scripts"
   ],
   "scripts": {
     "check:preset-structure": "bash scripts/check-preset-structure.sh",
     "check:preset-twin-map": "bash scripts/check-preset-twin-map.sh",
     "check:preset-token-budget": "bash scripts/check-preset-token-budget.sh",
     "check:preset-leakage": "bash scripts/check-preset-leakage.sh",
+    "check:hook-only-lifecycle": "bash scripts/check-hook-only-lifecycle.sh",
     "check:preset-i18n": "AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0 bash scripts/check-preset-i18n.sh",
     "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh",
     "check:product-specs": "bash scripts/check-product-specs.sh",
     "check:product-specs:dogfood": "bash scripts/check-product-specs.sh ../../dogfood/mcp-ts-sample",
-    "check:rule-eval": "node scripts/check-rule-eval.mjs"
+    "check:rule-eval": "node scripts/check-rule-eval.mjs",
+    "test:cli-mcp-merge": "node scripts/test-cli-mcp-merge.mjs"
   },
   "engines": {
     "node": ">=18"

package/presets/_shared/README.md

@@ -36,10 +36,10 @@ Do **not** expect lineage adapters to byte-match core. Embed adapters should mat
 
 | Dir | Contents |
 |-----|----------|
-| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8) |
+| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8); requestable `mcp-usage` (Context7 + local overlay MCP) |
 | `core/agent-team/` | Orchestrator + intake (pipeline language) |
 | `core/architecture/` | Feature-delivery abstract + reference-features template + product-specs (+ product-specs-authoring) + assets/docs-specs templates |
-| `core/review/` | Code-review MR + technical-retro alias |
+| `core/review/` | Code-review MR + technical-retro alias + mockup-review checklist + ux-design checklist |
 | `core/meta/` | Author-facing preset meta-rules |
 
 ## CLI note

package/presets/_shared/assets/docs-specs/schemas/frontmatter-v1.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://bonesofspring.github.io/ai-rules/schemas/frontmatter-v1.schema.json",
+  "$comment": "Shipped with the npm package as documentation. scripts/check-product-specs.sh validates required keys and headings in bash; it does not load or evaluate this file.",
   "title": "Product spec frontmatter v1",
   "type": "object",
   "required": ["id", "type", "domain", "routes", "ui", "store", "api", "aliases", "e2e"],

package/presets/_shared/core/agent-team/agent-artifact-contracts.md

@@ -103,12 +103,53 @@ A producer finishes its step by upserting only its owned artifact entry and term
 | `security-reviewer` | `security-review` | `security-review.md` |
 | `accessibility-reviewer` | `a11y-review` | `a11y-review.md` |
 | `performance-auditor` | `perf-report` | `perf-report.md` |
+| `mockup-reviewer` | `mockup-review` | `mockup-review.md` |
 | `api-contract-reviewer` | `api-contract-review` | `api-contract-review.md` |
 | `qa-tester` / unit or e2e planners | stack-native test IDs | plan/spec paths named in the agent prompt |
 | `tech-writer` | `documentation` | `documentation.md` |
 
 Use these defaults unless a step's `artifactOutputId` / `artifactOutputIds` assigns a distinct owned ID (parallel reviewers must not share one `id`). `artifactInputIds` defaults to the applicable authoritative entries already present in the manifest.
 
+**v1 UX artifact:** when `task-analyst` produces `ux-design.md`, append it to the **`analysis`** entry `authoritativePaths` and `evidencePaths`. Do **not** add a default producer row for `ux-designer` in v1.
+
+## specMode
+
+Primary location: `brief.md` heading `## Spec mode` with exactly one of `consume` | `generate` | `none` (analyst writes). Optional mirror: top-level `pipeline.json` `specMode` (router echo). Brief wins on conflict.
+
+| Value | When | Behavior |
+|-------|------|----------|
+| `consume` | Default when INDEX exists and there is no generate intent | Discover via INDEX; never invent specs |
+| `generate` | `/spec-start`, router `spec-gen`, or brief AC | Author/bootstrap INDEX + specs |
+| `none` | Spike / research / preset-only; no product-behavior SoT | Skip INDEX row requirement and author mode; do not invent a dummy INDEX |
+
+## applyReadiness
+
+Optional JSON on the producer receipt and, for `feature-developer`, YAML frontmatter on `implementation.md`:
+
+```json
+{
+  "state": "blocked",
+  "contextFiles": ["docs/specs/domains/orders/page-checkout.md"]
+}
+```
+
+| `state` | Meaning | Typical emitter |
+|---------|---------|-----------------|
+| `blocked` | Do not implement; read `contextFiles` | analyst (pre-gate), developer (missing SoT) |
+| `ready` | Safe to implement the current WP | developer |
+| `all_done` | WP complete; mechanical spec sync done | developer terminal receipt |
+
+`contextFiles` are repo-relative paths the next agent must read or that block progress.
+
+## Memlog
+
+Optional append-only file beside slug artifacts:
+
+- Cursor: `.cursor/team/tasks/<slug>/.memlog.md`
+- Claude: `.claude/team/tasks/<slug>/.memlog.md`
+
+Agent-written chronological markdown (`## YYYY-MM-DD` headings). Suggested line tags: `decision`, `assumption`, `override`, `event`, `claim`. Writers: `task-analyst`, `feature-developer`. `/task-continue` may read it. The hook does **not** parse memlog and does **not** treat it as `status.json` / `metrics.json`.
+
 ## Minimal terminal handoff
 
 Report the owned entry ID, outcome, authoritative paths, covered AC/task IDs, and remaining gaps. The hook advances pipeline state from the terminal receipt; the agent receipt is evidence that drives the state transition, not a substitute for writing `status.json`.

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -12,6 +12,7 @@ Work request without `/task` — see **agent-team-intake** (when to suggest the
 | `/task-continue <slug>` | After human gate or pause |
 | `/feature-start <desc>` | Legacy: analyst-only start (no router) |
 | `/feature-continue <slug>` | Alias of task-continue |
+| `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
 | `/technical-retro [slug]` | Retro with agent team block |
 
 ## Roles (shared catalog)
@@ -20,9 +21,9 @@ Roster of specialists is **stack-specific** (agent names and write scopes differ
 
 | Kind | Examples (names vary by stack) |
 |------|--------------------------------|
-| Planning | `task-router`, `task-analyst`, `solution-architect`, `migration-specialist` |
+| Planning | `task-router`, `task-analyst` (plus skill `ux-design` for behavioral UX **where the stack has a UI surface**), `solution-architect`, `migration-specialist` |
 | Implementation | `feature-developer`, `debugger`, `ci-investigator` |
-| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer **only when the stack has a UI surface** |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer and `mockup-reviewer` **only when the stack has a UI surface** |
 | Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
 | Docs | `tech-writer` |
 
@@ -158,8 +159,8 @@ On each `subagentStop`, the hook reconciles `status.state` from the completing p
 2. Read `pipeline.json` before every subagent invocation.
 3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
 4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
-5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
-6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`, `mockup-review.md`, `ux-design.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL (`changes_requested` while the completed/current agent is `mockup-reviewer`) → `awaiting_approval` / `/task-continue` only — do **not** `retryAfterFix` to developer.
 7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
 8. When all steps complete, suggest `/technical-retro <slug>`.
 9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.

package/presets/_shared/core/architecture/feature-delivery-workflow.md

@@ -8,9 +8,9 @@ Typical feature with data and UI. Concrete directories and rule stems — in the
 2. **Transport / DTO** — DTOs and mappers Domain ↔ transport (must not leak into UI).
 3. **Services / Data** — repository / API-service implementations via the stack’s public clients.
 4. **State** — store / ViewModel / use cases; no direct HTTP and no DTOs in UI.
-5. **UI** — thin views/components; data via state; design system.
+5. **UI** — thin views/components; data via state; design system. If the prompt or `brief.md` contains a `figma.com` URL, **mockup review must complete** (or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue`) **before UI work**. When required-signal and **no** `figma.com`, **`ux-design.md` must exist** (not `INCOMPLETE`) before UI work — else blocked, hand back to analyst. Non-UI tasks no-op these gates.
 6. **Tests** — unit for mappers / non-trivial logic; e2e/UI per stack convention.
-7. **Completion** — stack post-change gate (lint/build) + package/toolchain rules.
+7. **Completion** — stack post-change gate (lint/build) + package/toolchain rules. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated repo-relative paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
 
 ## Data flow (orientation)
 
@@ -40,6 +40,7 @@ flowchart LR
 - Breaking layer boundaries for brevity.
 - **Ubiquitous language:** Domain/type names and boundaries reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need; presentation must not dictate the model vocabulary.
 - When assessing structure, smells, or pattern choice — load requestable **`design-guidance`** (not always-on); do not copy the catalog into the feature checklist.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
 
 ## Zone → rules matrix
 

package/presets/_shared/core/architecture/product-specs-authoring.md

@@ -2,6 +2,8 @@
 
 Load when **Generate** or **Bootstrap** is requested (`/spec-start`, router `spec-gen`, brief AC, or analyst author mode). Discovery-only work stays on **`product-specs`**.
 
+**Optional prefix:** when the user or AC asks **research-before-spec**, load skill **`spec-discovery`** first (subset of methods; **claim-ledger** mandatory). Not the default `/task` consume path and not a new pipeline step.
+
 ## Modes
 
 1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
@@ -75,7 +77,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 ## Templates & assets
 
-**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; optional `schemas/frontmatter-v1.schema.json`).
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; `schemas/frontmatter-v1.schema.json` is a documentation artifact — the checker does not evaluate it).
 
 **CLI `init`:** when consumer `docs/specs/` is **absent**, copy INDEX stub + `_templates/*` (idempotent; **never overwrite** existing INDEX). When the tree already exists, skip seed entirely.
 
@@ -85,7 +87,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 | Role | Responsibility |
 |------|----------------|
-| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring`; optional skill `spec-discovery` when research-before-spec |
 | **tech-writer** | Post-delivery sync where present; never invent product behavior without AC/code source |
 | **feature-developer** | Consumes approved specs as SoT; mechanical INDEX/frontmatter fixes only on renames |
 | **mcp-ts** | No tech-writer — author + post-sync via **task-analyst** only |
@@ -104,4 +106,5 @@ Block handoff via `open_questions` until fixed:
 
 - `product-specs` — discovery / consume
 - Skill `spec-authoring` — procedural checklist
-- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)
+- Skill `spec-discovery` — opt-in research-before-spec (not default)
+- Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`

package/presets/_shared/core/architecture/product-specs.md

@@ -4,6 +4,8 @@ Product page/feature **behavior** specs live under the consumer repo `docs/specs
 
 **Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
 
+**Pipeline `specMode`:** `consume` (this stem) · `generate` (authoring stem) · `none` (spike/research — skip INDEX row requirement; do not invent a dummy INDEX). Primary field: `brief.md` `## Spec mode`; optional `pipeline.json` `specMode`.
+
 ## Modes (summary)
 
 | Mode | When | Behavior |
@@ -11,19 +13,21 @@ Product page/feature **behavior** specs live under the consumer repo `docs/specs
 | **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
 | **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
 | **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+| **None** (`specMode: none`) | Spike / research / preset-only | Skip INDEX requirement and author mode; no dummy INDEX row |
 
 Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
 
 ## Presence policy
 
+- If `specMode` is **`none`** → do **not** require an INDEX row; continue from brief/AC. Do not invent INDEX.
 - If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
-- If INDEX **exists** → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+- If INDEX **exists** and `specMode` is not `none` → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
 
 ## Discovery algorithm
 
-1. Always start at `docs/specs/INDEX.md` when present.
+1. Always start at `docs/specs/INDEX.md` when present (skip when `specMode: none`).
 2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
-3. Read the linked page spec (and optional domain `feature.md` when the INDEX or page Related links it).
+3. Read the **linked page** spec and, when INDEX or page Related links it, the optional domain `feature.md`. Do **not** dump the whole `docs/specs/**` tree into the prompt — locator = those linked files.
 
 ## Miss policy (INDEX present, row or file missing)
 
@@ -45,5 +49,6 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 ## Related
 
 - `product-specs-authoring` — generation modes, contracts, self-check.
+- Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
 - `reference-features` — code structure mirror (how to layout files), not product behavior.
 - Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.

package/presets/_shared/core/meta/preset-no-cross-stack-leakage.md

@@ -12,6 +12,7 @@ Ban leakage of stack-specific names, paths, and handoff stems across presets.
 - `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Android instrumentation agents, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
 - `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+- Storybook / Chrome DevTools MCP must **not** be required handoffs or agent stems (`storybook-reviewer`) on backend or mobile stacks. Frontend overlay mentions in `MCP.md` / `mcp-usage` Stack notes are OK.
 
 ## Forbidden in ios-swift hooks/agents (FAIL)
 
@@ -59,7 +60,8 @@ Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
 - `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css`
 - `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
-- Agent file `accessibility-reviewer` (no UI surface)
+- Agent files `accessibility-reviewer`, `mockup-reviewer`, `ux-designer` (no UI surface)
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
 
 Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
 
@@ -71,7 +73,8 @@ Same UI/mobile bans as backend stacks, plus:
 - Positive yarn recipes `lint:js` / `lint:css` as required gates
 - `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Go tool commands as required MCP delivery gates: `go test`, `go vet`, `golangci-lint`
-- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`
+- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`, `mockup-reviewer`, `ux-designer`
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
 
 Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`, `post-change-test`); Phase 1 gates `build-verifier` + `security-reviewer`.
 

package/presets/_shared/core/quality/anti-sycophancy-discipline.md

@@ -2,7 +2,7 @@
 
 Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
 
-1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If that is not enough and Context7 MCP is available, load **`mcp-usage`** and query docs for the **installed major**. If you still cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
 2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
 3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
 4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.

package/presets/_shared/core/quality/code-quality-and-refactoring.md

@@ -26,7 +26,7 @@
 
 Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
 
-- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Unverifiable third-party API → if Context7 is up, load **`mcp-usage`** and query the installed major; else mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
 - Before "is this correct?" — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
 - Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
 - Comments = WHY only when non-obvious; ban self-referential "added for issue Y".