baldart 5.0.1 → 5.2.0

package/framework/.claude/skills/ui-design/scripts/craft-check.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * craft-check.mjs — deterministic anti-slop / craft gate for ui-design mockups.
+ *
+ * Scans self-contained mockup HTML for the mechanically-checkable subset of
+ * references/anti-slop.md + references/craft-standards.md. Runs identically on
+ * Claude Code and Codex (zero deps, Node >= 18) — it is Gate 0 of Step D.
+ *
+ * Usage:
+ *   node craft-check.mjs <file.html> [more.html ...] [--json] [--strict-palette]
+ *
+ *   --strict-palette  escalate palette-reflex findings (AI-indigo, beige
+ *                     battery, trust gradient) from warn to block. Use in
+ *                     exploration regime; leave off in-context (the project's
+ *                     own brand may legitimately use these families).
+ *
+ * Exit codes: 0 = PASS (no blockers), 1 = FAIL (>=1 blocker), 2 = usage error.
+ *
+ * Rule provenance: distilled from impeccable (Apache-2.0, © Paul Bakaus),
+ * taste-skill (MIT, © Leonxlnx), open-design (Apache-2.0, nexu-io).
+ * Heuristics are conservative: binary rules block, judgment-adjacent rules warn.
+ */
+
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+const strictPalette = args.includes('--strict-palette');
+const files = args.filter((a) => !a.startsWith('--'));
+
+if (files.length === 0) {
+  console.error('usage: node craft-check.mjs <file.html> [...] [--json] [--strict-palette]');
+  process.exit(2);
+}
+
+const INDIGO_HEXES = ['#6366f1', '#4f46e5', '#4338ca', '#3730a3', '#8b5cf6', '#7c3aed', '#a855f7'];
+const BEIGE_BG_HEXES = ['#f5f1ea', '#f7f5f1', '#fbf8f1', '#efeae0', '#ece6db', '#faf7f1', '#e8dfcb'];
+const BEIGE_ACCENT_HEXES = ['#b08947', '#b6553a', '#9a2436', '#9c6e2a', '#bc7c3a', '#7d5621'];
+const EMOJI_RE = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}]/u;
+
+function lineOf(src, index) {
+  return src.slice(0, index).split('\n').length;
+}
+
+function excerptAt(src, index, len = 80) {
+  const start = Math.max(0, src.lastIndexOf('\n', index) + 1);
+  const end = src.indexOf('\n', index);
+  return src.slice(start, end === -1 ? start + len : Math.min(end, start + len)).trim();
+}
+
+/** Collect matches of a regex as {line, excerpt} evidence (capped). */
+function findAll(src, re, cap = 5) {
+  const out = [];
+  let m;
+  const rex = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g');
+  while ((m = rex.exec(src)) !== null && out.length < cap) {
+    out.push({ line: lineOf(src, m.index), excerpt: excerptAt(src, m.index) });
+    if (m.index === rex.lastIndex) rex.lastIndex++;
+  }
+  return out;
+}
+
+/** Strip script/style/comments, then tags → visible text (index-preserving via spaces). */
+function visibleText(src) {
+  const blank = (s) => s.replace(/[^\n]/g, ' ');
+  return src
+    .replace(/<script[\s\S]*?<\/script>/gi, blank)
+    .replace(/<style[\s\S]*?<\/style>/gi, blank)
+    .replace(/<!--[\s\S]*?-->/g, blank)
+    .replace(/<[^>]+>/g, blank);
+}
+
+function checkFile(path) {
+  const src = readFileSync(path, 'utf8');
+  const text = visibleText(src);
+  const findings = [];
+  const add = (rule, severity, message, evidence) => {
+    if (evidence.length > 0) findings.push({ rule, severity, message, count: evidence.length, evidence });
+  };
+  const palSev = strictPalette ? 'block' : 'warn';
+
+  // ---- Absolute bans (binary) ------------------------------------------
+  add('em-dash', 'block',
+    'Em-dash (or en-dash separator) in visible copy — zero tolerance (anti-slop.md).',
+    findAll(text, /—|\s–\s/));
+
+  add('filler-copy', 'block',
+    'Filler copy (lorem ipsum / "Feature One") — an empty section is a composition problem.',
+    findAll(text, /lorem ipsum|\bfeature (one|two|three)\b/i));
+
+  add('gradient-text', 'block',
+    'Gradient text (background-clip: text) — decorative, never meaningful.',
+    findAll(src, /background-clip:\s*text|bg-clip-text/i));
+
+  add('scroll-cue', 'block',
+    '"Scroll to explore" cue — they know what scroll is.',
+    findAll(text, /scroll (down )?to (explore|discover|see)/i));
+
+  add('scroll-listener', 'block',
+    'window scroll listener in script — use IntersectionObserver / animation-library scroll values.',
+    findAll(src, /addEventListener\(\s*['"]scroll['"]/));
+
+  if (!/<meta[^>]+name=["']viewport["']/i.test(src)) {
+    findings.push({ rule: 'missing-viewport', severity: 'block', message: 'Missing <meta name="viewport"> — the mockup cannot be judged responsively.', count: 1, evidence: [{ line: 1, excerpt: '<head>' }] });
+  }
+  if (!/<html[^>]+lang=/i.test(src)) {
+    findings.push({ rule: 'missing-lang', severity: 'block', message: 'Missing lang attribute on <html> (identity.language).', count: 1, evidence: [{ line: 1, excerpt: '<html>' }] });
+  }
+
+  // Emoji as icons inside headings/buttons
+  {
+    const ev = [];
+    const rex = /<(h[1-6]|button)\b[^>]*>([\s\S]*?)<\/\1>/gi;
+    let m;
+    while ((m = rex.exec(src)) !== null && ev.length < 5) {
+      const inner = m[2].replace(/<[^>]+>/g, '');
+      if (EMOJI_RE.test(inner)) ev.push({ line: lineOf(src, m.index), excerpt: excerptAt(src, m.index) });
+    }
+    add('emoji-icons', 'block',
+      'Emoji as feature icons in headings/buttons — use monoline SVG with currentColor.', ev);
+  }
+
+  // ---- Rationed patterns (count-bounded) --------------------------------
+  {
+    const sections = (src.match(/<section\b/gi) || []).length || 1;
+    const eyebrows = findAll(src, /class=["'][^"']*\buppercase\b[^"']*\btracking-/g, 50);
+    const cap = Math.ceil(sections / 3);
+    if (eyebrows.length > cap) {
+      findings.push({
+        rule: 'eyebrow-overuse', severity: 'block',
+        message: `Eyebrow kickers: ${eyebrows.length} for ${sections} section(s) — cap is ceil(sections/3) = ${cap}. Drop them; the headline alone is enough.`,
+        count: eyebrows.length, evidence: eyebrows.slice(0, 5),
+      });
+    }
+  }
+
+  add('numbered-markers', 'warn',
+    'Numbered section markers (01 / 02 · Label) — the eyebrow trope one tier deeper.',
+    findAll(text, /\b0\d\s*[\/·]\s*\S/));
+
+  add('status-dots', 'warn',
+    'Pulsing decorative status dots — zero by default.',
+    findAll(src, /class=["'][^"']*animate-pulse[^"']*["']/));
+
+  add('marquee-overuse', 'warn',
+    'More than one marquee/auto-scroll strip per page.',
+    findAll(src, /marquee|animate-\[?scroll/gi).slice(1));
+
+  // ---- Palette reflexes (warn; block with --strict-palette) -------------
+  add('ai-indigo', palSev,
+    'Default-Tailwind indigo/violet accent — the textbook AI tell (LILA rule).',
+    findAll(src, new RegExp(INDIGO_HEXES.join('|'), 'i')));
+
+  add('beige-battery', palSev,
+    'Premium-consumer beige/brass battery — banned as a default; rotate palette families (design-directions.md).',
+    findAll(src, new RegExp([...BEIGE_BG_HEXES, ...BEIGE_ACCENT_HEXES].join('|'), 'i')));
+
+  add('trust-gradient', palSev,
+    'Two-stop purple→blue/cyan/pink "trust" gradient — a flat surface + intentional type beats it.',
+    findAll(src, /from-(purple|indigo|violet)-\d+[^"']*to-(blue|cyan|pink|fuchsia)-\d+/i));
+
+  // ---- Craft warnings ----------------------------------------------------
+  add('side-stripe', 'warn',
+    'Colored side-stripe accent (border-left/right > 1px) — the canonical AI dashboard tile.',
+    findAll(src, /border-l-[2-8]\b|border-r-[2-8]\b|border-left:\s*[2-9]px\s+solid\s+(?!transparent)/i));
+
+  add('h-screen', 'warn',
+    'h-screen used — prefer min-h-[100dvh] (iOS Safari).',
+    findAll(src, /\bh-screen\b/));
+
+  add('transition-all', 'warn',
+    '`transition: all` — animate transform/opacity explicitly.',
+    findAll(src, /transition:\s*all|\btransition-all\b/i));
+
+  add('br-in-heading', 'warn',
+    '<br> inside a heading — plan font scale with the copy instead of breaking lines manually.',
+    findAll(src, /<h[1-3][^>]*>(?:(?!<\/h[1-3]>)[\s\S])*?<br\s*\/?>/gi));
+
+  add('caps-no-tracking', 'warn',
+    'ALL-CAPS element without letter-spacing — uppercase requires +0.06–0.1em tracking.',
+    findAll(src, /class=["'](?![^"']*tracking-)[^"']*\buppercase\b[^"']*["']/g));
+
+  add('justify-text', 'warn',
+    'Justified text — never text-align: justify in UI.',
+    findAll(src, /text-align:\s*justify|\btext-justify\b/i));
+
+  add('fake-metrics', 'warn',
+    'Fake-perfect metric (99.9%, 10×) — real source, labelled mock, or absent (Jane Doe rule).',
+    findAll(text, /\b99\.9+\s*%|\b10×|\b100\s*%\s+(faster|better)/i));
+
+  // First <img> lazy / dimensionless images (CLS)
+  {
+    const imgs = [...src.matchAll(/<img\b[^>]*>/gi)];
+    if (imgs.length > 0 && /loading=["']lazy["']/i.test(imgs[0][0])) {
+      findings.push({ rule: 'lcp-lazy', severity: 'warn', message: 'First image is loading="lazy" — never lazy-load the LCP candidate.', count: 1, evidence: [{ line: lineOf(src, imgs[0].index), excerpt: excerptAt(src, imgs[0].index) }] });
+    }
+    const dimless = imgs.filter((m) => !/\bwidth=|\baspect-ratio|aspect-\[/i.test(m[0]));
+    add('img-no-dimensions', 'warn',
+      '<img> without width/height or aspect-ratio — reserves no space (CLS).',
+      dimless.slice(0, 5).map((m) => ({ line: lineOf(src, m.index), excerpt: excerptAt(src, m.index) })));
+  }
+
+  // Token discipline: distinct raw hexes + off-scale arbitrary values
+  {
+    const hexes = new Set((src.match(/#[0-9a-fA-F]{6}\b/g) || []).map((h) => h.toLowerCase()));
+    if (hexes.size > 12) {
+      findings.push({ rule: 'hex-sprawl', severity: 'warn', message: `${hexes.size} distinct raw hex colors — an incomplete palette; consolidate to CSS custom properties.`, count: hexes.size, evidence: [] });
+    }
+    const offScale = [...src.matchAll(/\b(?:[mp][trblxy]?|gap|space-[xy])-\[(\d+)px\]/g)]
+      .filter((m) => Number(m[1]) % 4 !== 0);
+    add('off-scale-spacing', 'warn',
+      'Arbitrary spacing off the base-4 scale (e.g. p-[13px]) — token violation.',
+      offScale.slice(0, 5).map((m) => ({ line: lineOf(src, m.index), excerpt: m[0] })));
+    const sizes = new Set([
+      ...[...src.matchAll(/text-\[(\d+)px\]/g)].map((m) => m[1]),
+      ...[...src.matchAll(/font-size:\s*(\d+)px/gi)].map((m) => m[1]),
+    ]);
+    if (sizes.size > 9) {
+      findings.push({ rule: 'type-scale-sprawl', severity: 'warn', message: `${sizes.size} distinct px font sizes — one scale, 6–9 deliberate steps.`, count: sizes.size, evidence: [] });
+    }
+  }
+
+  const blockers = findings.filter((f) => f.severity === 'block');
+  return { file: path, verdict: blockers.length === 0 ? 'PASS' : 'FAIL', blockers: blockers.length, warnings: findings.length - blockers.length, findings };
+}
+
+const results = files.map((f) => {
+  try {
+    return checkFile(f);
+  } catch (e) {
+    return { file: f, verdict: 'ERROR', error: e.message, findings: [] };
+  }
+});
+
+if (asJson) {
+  console.log(JSON.stringify({ strictPalette, results }, null, 2));
+} else {
+  for (const r of results) {
+    console.log(`\n${r.verdict === 'PASS' ? '✓' : '✗'} ${r.file} — ${r.verdict}` + (r.error ? ` (${r.error})` : ''));
+    for (const f of r.findings || []) {
+      console.log(`  [${f.severity.toUpperCase()}] ${f.rule} ×${f.count}: ${f.message}`);
+      for (const ev of f.evidence.slice(0, 3)) console.log(`      L${ev.line}: ${ev.excerpt}`);
+    }
+  }
+  console.log('');
+}
+
+process.exit(results.some((r) => r.verdict === 'FAIL' || r.verdict === 'ERROR') ? 1 : 0);

package/framework/agents/component-manifest-schema.md

@@ -220,7 +220,7 @@ This keeps consumers that have not yet upgraded (and non-TS stacks) from becomin
 - **Single-element edit**: `/ds-edit` (update one existing component/token —
   resync / extend / breaking / re-govern; regenerates the HEAD from the new source
   via the same scripts, **preserving non-empty agentic fields + prose**).
-- **Per-task write**: `ui-expert` / `ui-design` / `frontend-design` in the
+- **Per-task write**: `ui-expert` / `ui-design` / `ui-implement` in the
   Post-Intervention Coherence Check — a new/modified primitive regenerates its
   HEAD in the same change.
 - **Curation owner**: `doc-reviewer` (agentic fields).

package/framework/agents/design-system-protocol.md

@@ -12,7 +12,7 @@ twofold:
    implementation, so existing primitives are reused instead of duplicated.
 
 This is the textual SSOT for the registry-first protocol. Skills (`ui-design`,
-`frontend-design`, `design-system-init`), agents (`ui-expert`, `code-reviewer`),
+`ui-implement`, `design-system-init`), agents (`ui-expert`, `code-reviewer`),
 and the `/design-review` command all reference this module instead of
 duplicating the BLOCKING-read cascade.
 
@@ -468,7 +468,7 @@ its own — it **proposes, a human confirms**:
 ## Functional Traceability Gate (BLOCKING — unconditional)
 
 A mockup is a fidelity target, **not** a requirements oracle. Design tools
-(Claude Design, Figma, the `ui-design`/`frontend-design` generators) routinely
+(Claude Design, Figma, the `ui-design` generator) routinely
 add interactive-looking chrome — buttons, icons, menu entries, toggles, badges —
 that no requirement asked for. Implementing a mockup **1:1 for fidelity**
 materialises that chrome into real markup + dead handlers + unused icon imports,
@@ -524,7 +524,7 @@ For every **orphan**, never decide silently (consistent with the framework's
 
 ### Where it runs
 
-1. **Design / generation time** (`ui-design`, `frontend-design`, `ui-expert`
+1. **Design / generation time** (`ui-design`, `ui-expert`
    designing) — when producing a mockup, do not invent interactive chrome with
    no backing requirement; mark genuinely decorative elements as such in the
    inventory so the downstream gate is deterministic, not a guess.
@@ -698,7 +698,7 @@ complete** when `features.has_design_system: true` until the registry has
 been verified against the change that was just made.
 
 The check runs at end-of-task by the agent that performed the work (`ui-expert`,
-`ui-design`, `frontend-design`, `code-reviewer`). It is **not** delegated to
+`ui-design`, `code-reviewer`). It is **not** delegated to
 the weekly `ds-drift` routine — that routine is a safety net, not the primary
 mechanism. Drift introduced today must be reconciled today, not next Monday.
 
@@ -820,9 +820,9 @@ The following files reference this module instead of duplicating its rules:
 - `framework/.claude/agents/ui-expert.md`
 - `framework/.claude/agents/code-reviewer.md`
 - `framework/.claude/agents/ui-quality-critic.md` (Design Quality Rubric — the
-  intrinsic-quality critic consumed by `/e2e-review` Phase 4b)
+  intrinsic-quality critic consumed by `/e2e-review` Phase 4b and `/ui-design`
+  Step D)
 - `framework/.claude/skills/ui-design/SKILL.md`
-- `framework/.claude/skills/frontend-design/SKILL.md`
 - `framework/.claude/skills/design-system-init/SKILL.md` (bulk registry bootstrap/upgrade)
 - `framework/.claude/skills/ds-new/SKILL.md` (single-element guided creation)
 - `framework/.claude/skills/ds-edit/SKILL.md` (single-element guided edit — resync / extend / breaking / re-govern)

package/framework/agents/index.md

@@ -20,6 +20,7 @@ Route agents to the right module with minimal reading.
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
 - If touching ANY visual surface (component, page, mockup, design review) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` and treat the BLOCKING cascade (`${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md`) as mandatory pre-work. When the flag is `false`, recommend `/design-system-init` to scaffold a registry.
+- If the task is a DESIGN DECISION (new page/screen/component to design, redesign/restyle, design options to explore, a local prototype/mockup) -> route to the `/ui-design` skill (the local design studio: Design Read & direction lock, deterministic craft gate, dual-lens evaluation). An ALREADY-APPROVED mockup to implement routes to `/ui-implement`; a direct in-code UI change with no design decision delegates to the `ui-expert` agent (`AGENTS.md` § delegation). NEVER route design work to `frontend-design` (a router since v5.2.0) or `ui-ux-pro-max` (superseded by `ui-design/references/`).
 - If a UI change might INTRODUCE a component (designing from a mockup, building a new primitive) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` § "Closed-Set Selection Policy": query the registry by ROLE (`INDEX.md` § Selection Policy), reuse the canonical member of any `closed` family, honor the card's `component_bindings`, and run `baldart ds-gate` (a `DS_CLOSED_SET_VIOLATION` — a new canonical in a closed family, the "third header" failure mode — BLOCKS). A new member of a closed family is a governance decision (`/prd` reconciliation + ADR), never an implementation act.
 - If creating ONE new canonical design-system element on-the-fly (a component or a token) and `features.has_design_system: true` -> use the `/ds-new` skill (reuse-first → optional scaffold via `ui-expert` → document + register + govern + verify); it produces the standardized spec by filling `framework/templates/component-spec.template.md` via the serializer, never hand-writing a HEAD. The bulk analogue (whole registry) is `/design-system-init`.
 - If EDITING one existing design-system element (add a variant/prop, breaking change, re-govern, or resync the spec) and `features.has_design_system: true` -> use the `/ds-edit` skill (classify the change → apply source via `ui-expert` → regenerate the spec via the serializer, PRESERVING agentic fields + prose, same canonical template as `/ds-new` → verify). The pure mechanical doc-resync after a code change is already automatic (serializer + `DS_COMPONENT_STALE` gate); `/ds-edit` is for the deliberate change.
@@ -43,6 +44,7 @@ Route agents to the right module with minimal reading.
 - If authoring/auditing a subagent whose return would flood the orchestrator context (free-form analysis/audit/research) -> read `agents/return-contract-protocol.md` and bound its final message: COMPACT headline + `path:line` findings + disk pointer, persist the long form. The input-side twin of the effort protocol.
 - If authoring/editing an agent definition -> the shared operating procedures (injection guard, retrieval, memory, tool budget) live in `agents/agent-operating-protocol.md` and the reviewer verification passes (challenge/simulation/CoVe/risk) in `agents/review-protocol.md` — cite their sections, never re-inline them; keep only the 1-line binding versions in the agent body.
 - If a skill performs runtime-mechanical operations (spawn an agent, gate on the user, track state, accelerate a fan-out, run an adversarial review) and must work on BOTH Claude Code and Codex -> read `agents/runtime-portability-protocol.md`: bind each abstract operation to the runtime (Claude `Task`/`Workflow`/`AskUserQuestion`/task-spine ↔ Codex named-agent spawn / inline / plain prompt / file-backed queue), detect the runtime once at kickoff, never probe Claude-only primitives on Codex. Shared policy (delegation, no-silent-fallback, worktree isolation) stays in `AGENTS.md` — cited, not restated.
+- If conducting research (technology evaluation, best practices, compliance survey), spawning `senior-researcher`, or managing the research library (`${paths.research_dir}/`) -> read `agents/research-protocol.md` (the matching `SECTION=` only): pass a `PROFILE=<decision|deep|compare|regulatory>` token, run the library reuse pre-flight BEFORE searching, and route sources by nature via the source matrix. Interactive channel: the `/research` skill.
 - If building or maintaining a derived LLM wiki overlay (`${paths.wiki_dir}/`) -> read `agents/llm-wiki-methodology.md` and invoke `wiki-curator` / `/capture`.
 - For day-to-day status -> read and update `${paths.references_dir}/project-status.md`.
 - For legacy context -> read `archive/project_full_legacy.md` if it exists.
@@ -85,6 +87,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/agent-operating-protocol.md` — Shared operating procedures for the core agents (injection guard, doc-retrieval consumption, persistent-memory hygiene, tool-budget discipline), `SECTION=` dispatch, read only the matching section; agents keep 1-line binding versions inline (since v5.0.0)
 - `agents/review-protocol.md` — The shared verification engine for reviewers: Challenge + Actionability, Simulation (diff-walk / plan-walk), Chain-of-Verification, quantified risk scoring + absolute severity calibration, specialist-spawn discipline incl. orchestrated-mode `specialist_dispatch` suppression; `SECTION=` dispatch (since v5.0.0)
 - `agents/doc-audit-protocol.md` — doc-reviewer's audit-mode procedures (drift validator suite, topological generation, epistemic metadata, SCIP anchors, schema/registry drift, coverage gauges); read ONLY when invoked without card context; `SECTION=` dispatch (since v5.0.0)
+- `agents/research-protocol.md` — Research discipline: `PROFILE=<decision|deep|compare|regulatory>` output contracts (+ `DEPTH=` iterative loop), the research library (`paths.research_dir` — layout, report frontmatter, INDEX, archive-not-delete), the reuse pre-flight (`FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs), and the versioned source matrix with its growth loop (`SOURCE_MATRIX_CANDIDATE`); `SECTION=` dispatch. The research-side sibling of `analysis-profiles.md` (since v5.1.0)
 
 ## Where to Document (Decision Tree)
 

package/framework/agents/research-protocol.md

@@ -0,0 +1,228 @@
+# Research Protocol — profiles, library, reuse, and the source matrix
+
+**Purpose**: the single SSOT for how BALDART conducts research. Consumed by the
+`senior-researcher` agent (worker) and the `/research` skill (interactive
+orchestrator); `/prd` Step 2.5 spawns the worker directly with the tokens
+defined here. One research contract used to fit every request — a
+publication-grade literature review — which conflicted with what orchestrators
+actually need (fast, stack-aware, decision-ready answers) and buried finished
+research where it was never reused. This module fixes both: **profiles** shape
+the output to the purpose, the **library** makes every report a reusable,
+indexed asset, and the **source matrix** routes each research nature to the
+right sources and grows over time.
+
+This is the research-side sibling of `analysis-profiles.md` (same mechanism:
+one agent + a `PROFILE=` prompt token + one SSOT module — never a twin agent).
+Prompt-level, zero new config keys beyond `paths.research_dir`, zero runtime
+dependency.
+
+## Contract
+
+- **Dispatch**: consumers cite a section as
+  `agents/research-protocol.md SECTION=<profiles|library|reuse|sources>`.
+  When you (an agent or skill) need the full procedure, Grep this file for the
+  heading `### SECTION: <name>` and Read ONLY that section — never this module
+  end-to-end.
+- **Degrade-safe**: everything here degrades, never aborts. No
+  `paths.research_dir` → deliver to the prompt-supplied path (or
+  `${paths.docs_dir}/` as last resort) and skip the library steps. No
+  `SOURCES.md` → fall back to the framework default matrix. No matrix at all →
+  proceed with judgment and say so in the report.
+- The agent body keeps 1-line BINDING versions of these rules inline; if the
+  inline line and this module diverge, **this module wins** — fix the agent.
+
+---
+
+### SECTION: profiles
+
+The `PROFILE=<decision|deep|compare|regulatory>` token in the spawn prompt
+selects the research contract. **Token absent → `deep`** (preserves the legacy
+full-report semantics for direct invocation and for existing spawners that
+pass no token).
+
+| Profile | Typical consumer | Output contract | Depth |
+|---|---|---|---|
+| `decision` | `/prd` Step 2.5, orchestrators mid-pipeline | Per-topic blocks, **recommendation first**: Recommendation (for THIS stack) → Best practices → Gotchas / anti-patterns → **Contradictions & Unknowns (mandatory section)** → Sources. Matches the `/prd` "Processing Findings" shape byte-for-byte. | Time-boxed; 1–3 questions; no ceremony sections |
+| `deep` | direct user invocation, `/research` | The full §0–§11 report (Retrieval Index, TOC, Executive Summary, Taxonomy, Comparative Analysis, Key Findings, Recommendation, Risks, Evidence Map, Annotated Bibliography, Appendix with Search Log) | Full survey; see the DEPTH token below |
+| `compare` | technology / vendor evaluations | Comparison matrix on fixed axes — performance, cost, complexity, risk, maturity, adoption — then Recommendation + explicit "when NOT to use" per option | Medium; one matrix, no unbounded exploration |
+| `regulatory` | `/prd` S2 signal, compliance questions | Obligation checklist (requirement → source → deadline/threshold → implementation note), jurisdiction-aware; normative sources only for the obligations themselves | High rigor, tightly scoped to the named jurisdiction(s) |
+
+Rules that apply to EVERY profile:
+
+- **AI-readable minimum**: every report — not just `deep` — is consumed by an
+  AI reader with limited context: short paragraphs, dense factual bullets,
+  modular self-contained sections, consistent terminology. The full ceremony
+  (Retrieval Index, Evidence Map, Search Log) belongs to `deep` only; the
+  lighter profiles carry traceability through their per-topic **Sources**
+  lists (dated + evidence-labeled).
+- **Recommendation is stack-bound**: evaluate against the stack signature and
+  the internal-repo findings supplied in the prompt — "best for THIS project",
+  never "best in the abstract".
+- **Recency bias**: for fast-moving topics (frameworks, APIs, tooling) prefer
+  sources < 18 months old; date-stamp every source in the bibliography.
+- **Contradictions surface early**: when evidence is split or absent, say so
+  near the top (in `decision` it is a mandatory section) — a hidden
+  disagreement is the failure mode that sends a project in the wrong
+  direction.
+
+**`DEPTH=<1..3>` (deep profile only, default 1)** — the iterative
+breadth/depth loop, opt-in so legacy spawns cost what they cost today:
+
+- `DEPTH=1` (default): single research pass — today's behavior.
+- `DEPTH=2..3`: before searching, generate 3–5 expert *perspectives* on the
+  topic (architect, operator, security, cost-owner, end-user — pick what fits)
+  and derive each perspective's questions. Then per round: search → extract
+  *learnings* + *follow-up directions* → recurse into the most promising
+  directions until DEPTH is exhausted. Each round is bounded by the tool
+  budget (`agents/agent-operating-protocol.md SECTION=tool-budget`).
+- At `DEPTH>=2`, before finalizing run a citation spot-check (CoVe-lite):
+  WebFetch the sources behind the decision-driving claims and verify they
+  actually support them; demote or drop any that don't.
+
+### SECTION: library
+
+The research library lives at `${paths.research_dir}` (key in
+`baldart.config.yml`; seeded by the BALDART CLI):
+
+```
+${paths.research_dir}/
+  INDEX.md          <- THE map. Agents do lookup HERE first, never by walking dirs.
+  SOURCES.md        <- live source matrix (consumer-owned; see SECTION: sources)
+  architecture/  integrations/  regulatory/  ux-patterns/  algorithms/  tooling/
+  _archive/         <- superseded reports: banner added, row removed from INDEX
+```
+
+- **Category**: pick the closest of the six; a report that genuinely fits none
+  goes in the closest match with a distinguishing tag (do NOT invent new
+  top-level directories — the closed set keeps lookup deterministic).
+- **Report frontmatter** (every report, mandatory — this is the source of
+  truth; INDEX.md is a regenerable view over it):
+
+  ```yaml
+  ---
+  id: RES-<YYYYMMDD>-<slug>        # date + slug, NEVER max+1 (see Concurrency)
+  title: <one line>
+  category: architecture|integrations|regulatory|ux-patterns|algorithms|tooling
+  tags: [<free-form, lowercase, for findability — be generous>]
+  profile: decision|deep|compare|regulatory
+  nature: scientific|dev|regulatory|ux|market
+  stack_signature: "<framework + database + auth, from baldart.config.yml>"
+  date: <YYYY-MM-DD>
+  valid_until: <YYYY-MM-DD>        # date + category TTL (see SECTION: reuse)
+  status: current                   # current | superseded
+  questions:
+    - <the research questions answered>
+  sources_count: <n>
+  related: []                       # ids of related reports
+  ---
+  ```
+
+- **INDEX.md row format** (append-only; one row per report):
+
+  ```
+  | <id> | <title> | <category> | <profile> | <tags csv> | <date> | <valid_until> | <path> |
+  ```
+
+- **Archive, never delete**: a superseded report moves to `_archive/`, gets a
+  first-line banner `> [!SUPERSEDED] Replaced by <id>. Non-authoritative.`,
+  `status: superseded` in frontmatter, and its INDEX row is removed (out of
+  the index = invisible to lookup, history preserved in git).
+- **Concurrency**: IDs are `RES-<YYYYMMDD>-<slug>` (add a short unique suffix
+  only on a real collision) — never "max existing + 1", which races under
+  parallel spawns. When an orchestrator (the `/research` skill, `/prd`) runs
+  the show, **the orchestrator pre-allocates id + full path in each spawn
+  prompt and serializes the INDEX appends itself** in its filing step; a
+  worker spawned solo appends its own row. Reconciliation is deterministic:
+  `rebuild-research-index.mjs` (shipped with the `/research` skill)
+  regenerates INDEX.md from report frontmatter.
+- **Delivery-path resolution** (total, in order — never undefined, never
+  abort): (1) an explicit output path in the spawn prompt is AUTHORITATIVE;
+  (2) else `${paths.research_dir}/<category>/<id>-<slug>.md`;
+  (3) else (no path, no key) `${paths.docs_dir}/`.
+
+### SECTION: reuse
+
+Research repeats across features and projects. Before ANY new research, run
+this pre-flight (skip it only when `paths.research_dir` is missing/empty —
+then use the prompt-supplied path and proceed as a plain one-shot run):
+
+1. **Lookup**: Read `INDEX.md` (only the index — not the reports). Match the
+   topic against `title`, `tags`, `category`.
+2. **On hit, judge fitness**:
+   - **Freshness**: compare today against `valid_until`. Category TTLs (used
+     to SET `valid_until` at write time): `regulatory` 6 months ·
+     `integrations`/`tooling` 6–12 · `ux-patterns` 12 ·
+     `architecture`/`algorithms` 24.
+   - **Stack match**: compare the report's `stack_signature` with the current
+     one.
+3. **Decide and DECLARE the decision in your report/return** (`REUSE:` line):
+   - `FULL_REUSE` — fresh + same stack + questions covered → return the
+     existing report; do not search again.
+   - `DELTA` — partially stale, stack drifted, or questions partially covered
+     → update ONLY what expired, publish as a new report that `related:`-links
+     the old one; the old report is archived per SECTION: library.
+   - `NEW` — no usable hit.
+   - **Anti-false-reuse guard**: doubtful staleness or a different stack →
+     `DELTA`, never `FULL_REUSE`. Reuse must never silently serve a stale
+     answer to a decision-making consumer.
+4. **Orchestrator polling contract**: when the spawn prompt pre-allocates an
+   output path, ALWAYS write a file there — the new report (`NEW`/`DELTA`), or
+   a stub for `FULL_REUSE`:
+
+   ```
+   RESEARCH_OUTPUT_PATH: <this file's own path>
+   REUSE: FULL_REUSE -> <path of the existing report>
+   ```
+
+   so a file-exists poll never times out and never matches a stale artifact.
+
+### SECTION: sources
+
+The source matrix routes each research **nature** to the right sources. Schema
+(rows = natures; the columns are fixed):
+
+| Column | Meaning |
+|---|---|
+| `nature` | scientific · dev · regulatory · ux · market |
+| `primary` | search these first; sufficient alone for [STRONG]/[MODERATE] claims |
+| `secondary` | corroboration and leads; never sole support for a decision-driving claim |
+| `avoid` | known-poor signal for this nature (content farms, marketing, SEO spam) |
+| `notes` | nature-specific heuristics (recency windows, venue quality cues) |
+
+**Resolution order** (no dual-SSOT — the default matrix lives in ONE file):
+
+1. `${paths.research_dir}/SOURCES.md` — the live, consumer-owned matrix
+   (framework defaults + the project's `## Local additions`).
+2. `.framework/framework/templates/research-sources.template.md` — the
+   framework default matrix (readable inside every consumer install).
+3. Neither readable → proceed with judgment and state in the report that no
+   source matrix was available.
+
+**Growth loop** (how the matrix improves project after project): when a run
+hits a matrix gap — an unmapped nature, a newly discovered source that proved
+high-quality in THIS run, or a mapped source that proved poor — append to the
+END of the report:
+
+```markdown
+## SOURCE_MATRIX_CANDIDATE
+
+- nature: <matrix row>
+  change: add-source | demote-source | new-nature
+  source: <name + URL>
+  tier: primary | secondary | avoid
+  evidence: <what happened in this run that proves it, 1-3 lines>
+
+### Prompt for BALDART (copy-paste)
+
+Aggiorna la matrice fonti in `framework/templates/research-sources.template.md`:
+<change> per nature `<nature>`: `<source>` come `<tier>` — evidenza: <evidence>.
+Bump `matrix_version` (minor per add, patch per demote/note) e aggiungi la voce
+a `framework/templates/research-sources.CHANGELOG.md`.
+```
+
+(the research twin of skill-improver's `## Upstream Candidates`). Also mention
+the candidate in your COMPACT return so the orchestrator can act on it. The
+`/research` skill then offers two applications: (a) immediately to the local
+`SOURCES.md` `## Local additions`, and/or (b) the copy-paste prompt upstream to
+the BALDART maintainer session. Emit a candidate ONLY with run-local evidence —
+never from general knowledge.