@bonesofspring/ai-rules 0.2.18 → 0.2.20

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 ## Unreleased
 
+### Superpowers B1–B5 (all installable stacks)
+
+- All 10 stacks (Cursor + Claude): **verification-before-completion** lineage snippet on `build-verifier` / `feature-developer` only. `debugger` keeps inline 3-fix + `fixApplied` re-run (skill cross-ref) — not the verification stem. **receiving-code-review** embed on `code-review` skill; implementer one-liner on `feature-developer`, `debugger`, and `ci-investigator` (where those agents exist). Debug skill 4-phase + 3-fix architecture gate; task-analyst/router classify spike / bounded / architectural onto **existing** pipeline profiles.
+- Drift CI: `quality/debug-investigation.md` is **embed** (skill body = core + `## Stack notes`). `verification-before-completion`, `receiving-code-review`, and `task-classification` are **lineage** (section snippets in fat agents — whole-file embed would fail). `mcp-ts` has no `debugger` / `code-reviewer` / `ci-investigator` agents; B1/B2 via skill + `feature-developer` (+ `build-verifier` for B1); B3 via `debug-investigation` skill; B4 on task-analyst/router.
+- Skill-authoring craft (SDO, positive recipes, ~500-line cap) lives in `docs/PRESET-CONTRIBUTION.md` (not installed by `init`).
+- No 4th always-on rule; `anti-sycophancy-discipline` core body unchanged (promote receiving-CR there in a later 10-stack PR).
+- Consumers: re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` after publish.
+
+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: Superpowers B1–B5 review alignment
+
+- CHANGELOG/SoT match PRESET-CONTRIBUTION: verification lineage is `build-verifier` + `feature-developer`; debugger 3-fix stays inline (no verification marker).
+- receiving-CR implementer one-liner extended to `debugger` and `ci-investigator` (9 stacks × 2; mcp-ts has neither).
+- Backend `debugger` agents (`go` / `java` / `php-hexagonal` / `php-laravel`, Cursor + Claude) now load `debug-investigation` at the top, matching UI/mobile.
+
+### 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.

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,7 +49,7 @@ 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 |
@@ -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.18",
+  "version": "0.2.20",
   "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/agent-team/` | Orchestrator + intake (pipeline language) |
+| `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8); requestable `mcp-usage`; embed `debug-investigation`; lineage `verification-before-completion` |
+| `core/agent-team/` | Orchestrator + intake (pipeline language); lineage `task-classification` |
 | `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 + mockup-review checklist + ux-design checklist |
+| `core/review/` | Code-review MR + technical-retro alias + mockup-review checklist + ux-design checklist; lineage `receiving-code-review` |
 | `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

@@ -112,6 +112,44 @@ Use these defaults unless a step's `artifactOutputId` / `artifactOutputIds` assi
 
 **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)

package/presets/_shared/core/agent-team/task-classification.md

@@ -0,0 +1,21 @@
+# Task classification (spike / bounded / architectural)
+
+Stack-agnostic. Classify **before** decomposing work or expanding a pipeline. This maps onto existing `pipeline.json` **profiles** (`light` / `standard` / `full`) and intents — do **not** invent a second orchestrator.
+
+## Classes
+
+| Class | Signals | Pipeline posture |
+|-------|---------|------------------|
+| **Spike** | Research, estimate, "can we", no ship | Existing `spike` intent: analyst → architect (or analyst-only). No `feature-developer` until a later task. |
+| **Bounded** | One layer or file, explicit AC, typo / small fix | Existing `light` (or skip analyst fan-out). Do **not** invent a full types/api/store/ui task table. |
+| **Architectural** | New subsystem, public contract, cross-layer | Existing `full`. Add `solution-architect` when boundaries are unclear. |
+
+Ratchet **up** if bounded work reveals architectural scope. Do not ratchet **down** to skip a needed verification gate (`build-verifier` after code changes still applies).
+
+## Clarification
+
+Prefer **one** unblocking question per message when a single decision unblocks DoR. Never more than **3** questions per iteration (existing analyst cap).
+
+## Router
+
+`task-router` already chooses profiles from complexity signals. Use this table to **name** the class in `routingReasons` / brief assumptions — do not add parallel step lists that contradict the intent table.

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

@@ -10,7 +10,7 @@ Typical feature with data and UI. Concrete directories and rule stems — in the
 4. **State** — store / ViewModel / use cases; no direct HTTP and no DTOs in UI.
 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)
 

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

package/presets/_shared/core/quality/debug-investigation.md

@@ -0,0 +1,24 @@
+# Debug investigation
+
+Stack-agnostic root-cause loop. Consumed by skill `debug-investigation` and agent `debugger`. Platform paths, MCP, and stack commands belong in adapter **Stack notes**.
+
+## When
+
+Any bug, test failure, build failure, or unexpected behavior — **before** proposing a fix.
+
+## Phases (in order)
+
+1. **Evidence** — reproduce, or collect the closest evidence (error output, failing test, logs, user steps).
+2. **Isolate** — expected vs actual in one sentence; smallest relevant slice of the codebase.
+3. **Root cause** — name the cause before editing. One hypothesis at a time; do not stack speculative fixes.
+4. **Minimal fix + verify** — smallest change that preserves architecture and public contracts. Add a regression test when the behavior is user-facing or likely to recur. Re-run the **failing** check first, then the relevant lint/type/test slice.
+
+## 3-fix architecture gate
+
+If **three** fix attempts fail, or the same symptom returns after two supposed fixes: **STOP**. Do not attempt fix #4. Escalate — the design is likely wrong (human partner or `solution-architect`). Chasing symptoms is the failure mode.
+
+## Do not
+
+- Broad refactor during a bugfix.
+- Fix only where the error surfaces if invalid data originates elsewhere.
+- Claim `fixApplied: true` without re-running the failing check (see `quality/verification-before-completion.md`).

package/presets/_shared/core/quality/mcp-usage.md

@@ -0,0 +1,84 @@
+# MCP usage
+
+Requestable protocol for **shipped** and **local-overlay** MCP servers. Agents load this stem via one-liner wiring — do not copy tool schemas into prompts; discover them at runtime.
+
+Does not replace Figma mockup-review (that checklist stays on `mockup-review`). Does not add pipeline agents or required handoff stems.
+
+## Presence (runtime catalog is SoT)
+
+1. Inspect the **session MCP catalog** (server names + `serverStatus`). Project `mcp.json` / `.mcp.json` is a hint, not proof the server is up (user-level and plugin servers never appear there).
+2. Treat `error`, `needsAuth`, and `loading` as **unavailable**. Authenticate only when this task needs that server.
+3. **Discover tool schemas before calling.** Never invent tool names or arguments from memory.
+4. Match overlay servers by **documented aliases** or exact catalog ids. Prefer a ready `plugin-*` id over an unknown similarly named server; if several match, ask rather than guessing.
+5. If two servers expose the same product (plugin + project entry), use the **ready** one; do not call both.
+
+## Classes
+
+| Class | Who adds it | Policy |
+|-------|-------------|--------|
+| **Shipped** | Preset `mcp.json` | Assume it should be there; call when the task fits; degrade if down (do not block unless noted below) |
+| **Local overlay** | Consumer project or user MCP | Use only when present **and** the task fits. Never a required pipeline step |
+
+Shipped in every preset: **Context7** (library docs). Other shipped servers are stack-specific — see adapter **Stack notes**.
+
+## Context7 (shipped)
+
+**When to call** (after lockfile / manifest + sibling files still do not confirm the symbol):
+
+- Third-party API that would otherwise get `// VERIFY: lib.symbol @ version`
+- Version-sensitive framework or SDK APIs
+- Migrations / major upgrades
+- Library is in the lockfile but the signature is unclear
+
+**When not to call:** repo public API; a sibling file already imports the symbol; a trivial call already in this module.
+
+**Flow:**
+
+1. Discover server `context7`.
+2. Resolve a library id, then query docs (read the live schema; typical names `resolve-library-id` then `query-docs`).
+3. Put the **installed major** from the project manifest into the query.
+4. Cap: **≤3 doc queries per question**.
+5. Source priority: lockfile / sibling code **>** Context7 **>** training data. If docs disagree with the installed major, keep the installed API.
+6. If Context7 is down: `// VERIFY` (or stack equivalent) and say MCP was unavailable. **Do not block** the task.
+
+## Local overlay protocol
+
+If a matching server is ready and a **task signal** fires → discover and use. Otherwise continue from files / native tools (`gh`, repo docs, source).
+
+Absence of an overlay is **not** `BLOCKED` unless the user required that MCP as source of truth.
+
+### Observability (Sentry, Datadog, similar)
+
+**Signal:** production error, event/trace id, APM / latency, pasted dashboard or issue URL.
+
+Use the **first ready** observability MCP. Do not invent metrics or stack traces. Do not require two observability servers.
+
+### Tickets (Linear, Jira, Notion, similar)
+
+**Signal:** ticket/page URL in the prompt or brief, or an explicit “pull from \<tracker\>”.
+
+Read-only by default. Task-folder artifacts (`brief.md`, `decomposition.md`) remain SoT — do not replace them with a tracker page. Write back to the tracker **only** if the user asked.
+
+### Component-library overlay
+
+**Signal:** UI component public API, stories, controls, or explicit component-docs MCP.
+
+If such a server is ready, use it for documented props/variants instead of inventing them. If it is down, read story/source files. **Block** only when the user required that MCP as SoT.
+
+Usual aliases and runtime needs live in frontend **Stack notes**. Do not ship this server in preset `mcp.json`.
+
+### GitHub MCP
+
+Native `gh` / git remain SoT for PRs and checks. A GitHub MCP may be used when present; do not require it.
+
+## Figma
+
+Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plugin** and a project `figma` server are both present, use the ready one and do not duplicate calls.
+
+## Forbidden
+
+- Secrets in `mcp.json` / `.mcp.json`
+- New pipeline agents or required handoffs for overlay MCP
+- Treating overlay absence as blocked (except user-required SoT)
+- Tracker/admin write tools without an explicit ask
+- Calling overlay MCP “just in case” on unrelated tasks