baldart 5.0.1 → 5.2.0

package/framework/.claude/skills/research/assets/report-deep.template.md

@@ -0,0 +1,61 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: architecture
+tags: []
+profile: deep
+nature: scientific
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title>
+
+<!-- Full §0–§11 contract — VERBATIM in senior-researcher.md § OUTPUT.
+     Every section opens with a 2–5 bullet Key Takeaways block. -->
+
+## §0 Retrieval Index
+<keyword> → §N.M …
+
+## §1 Table of Contents
+
+## §2 Executive Summary
+<!-- 10–20 bullets covering the entire report -->
+
+## §3 Problem Framing and Scope
+
+## §4 Research Landscape / Taxonomy
+<!-- structured by approach, not by time -->
+
+## §5 Comparative Analysis
+<!-- consistent axes: performance, cost, complexity, risk, robustness, maturity, adoption -->
+
+## §6 Key Findings
+<!-- claims + citations + evidence labels -->
+
+## §7 Recommendation
+<!-- one primary path + 1–2 alternatives, rationale, "when not to use" -->
+
+## §8 Risks & Limitations
+<!-- gaps, conflicting evidence, unknowns -->
+
+## §9 Evidence Map
+<!-- claim → sources → section IDs -->
+
+## §10 Annotated Bibliography
+<!-- links/DOIs/arXiv IDs, dated, evidence-labeled -->
+
+## §11 Appendix
+### Search Log
+| query | date/context | rationale | chosen (why) | rejected (why) |
+|---|---|---|---|---|
+### Structured Reading Notes
+### Glossary

package/framework/.claude/skills/research/assets/report-regulatory.template.md

@@ -0,0 +1,44 @@
+---
+id: RES-YYYYMMDD-slug
+title: ""
+category: regulatory
+tags: []
+profile: regulatory
+nature: regulatory
+stack_signature: ""
+date: YYYY-MM-DD
+valid_until: YYYY-MM-DD   # regulatory TTL is SHORT (6 months) — rules move
+status: current
+questions: []
+sources_count: 0
+related: []
+---
+
+RESEARCH_OUTPUT_PATH: <this file's path>
+REUSE: NEW | DELTA -> <prior report path>   <!-- a FULL_REUSE run writes the pointer stub (SECTION=reuse), not this template -->
+
+# <Title>
+
+**Jurisdiction(s):** <named explicitly — a regulatory report without one is invalid>
+
+## Summary & applicability
+
+<does this regime apply to the project at all, and through which activities>
+
+## Obligation checklist
+
+<!-- Obligations cite the PRIMARY legal text; implementation notes may cite secondary. -->
+
+| # | Requirement | Source (primary) | Deadline / threshold | Implementation note |
+|---|---|---|---|---|
+| 1 | | [Reg Art. N] | | |
+
+## Sanctions & risk
+
+## Contradictions & Unknowns
+
+<!-- diverging regulator guidance, pending rulings, transition periods -->
+
+## Sources
+
+- [Source Year] <official title> — <url> (<date>) [STRONG]

package/framework/.claude/skills/research/references/playbook.md

@@ -0,0 +1,112 @@
+# Research playbook — step-by-step detail
+
+Companion to `SKILL.md`. Rules live in `agents/research-protocol.md` (cited by
+SECTION); this playbook covers execution mechanics only.
+
+## 1. Scoping
+
+Goal: a research brief precise enough that the worker never has to guess.
+Skip entirely when the request already pins topic + purpose + constraints.
+
+Ask AT MOST 3 of these (AskUserQuestion, one round):
+
+- **Purpose** — "Decidere tra opzioni? Survey completa? Confronto puntuale?
+  Vincolo normativo?" → maps 1:1 to `PROFILE=` (decision/deep/compare/regulatory).
+- **Nature** — scientific / dev / regulatory / ux / market → picks the source
+  policy row. Infer it when obvious ("paper su CRDT" = scientific;
+  "best practice Next.js" = dev) — ask only when ambiguous.
+- **Constraints** — jurisdiction (regulatory), budget/timeline (market),
+  must-include candidates (compare).
+
+Then assemble the brief: 1–3 research questions, stack signature
+(`{{stack.framework}} + {{stack.database}} + {{stack.auth_provider}}`, empty
+segments omitted), known internal context worth passing.
+
+## 2. Routing
+
+One line to the user before launching, e.g.:
+`Routing: PROFILE=compare, nature=dev (fonti: official docs → GitHub issues → engineering blogs). Library: 1 possibile riuso.`
+
+Heuristics:
+
+| Signal in the request | Profile |
+|---|---|
+| "quale scegliere", "ci serve per decidere", feeds a plan/PRD | `decision` |
+| "survey", "stato dell'arte", "letteratura", open-ended learning | `deep` |
+| exactly 2+ named candidates ("X vs Y") | `compare` |
+| law/standard/compliance named or implied | `regulatory` |
+
+`DEPTH=` (deep only): default 1. Suggest 2 when the topic is broad AND the
+user asked for thoroughness; 3 only on explicit request (each level multiplies
+cost).
+
+## 3. Reuse check
+
+Per `SECTION=reuse` — the skill runs the lookup itself (INDEX.md only, never
+walk the report dirs) so the user decides BEFORE a worker is paid for:
+
+- Hit + fresh + same stack → propose **FULL_REUSE**: show the report path +
+  its Executive Summary/Recommendation; done if accepted.
+- Hit but stale/stack-drifted → propose **DELTA**: the spawn prompt names the
+  prior report path and instructs "update only what expired; `related:` link".
+- No hit → **NEW**.
+
+The worker re-runs its own pre-flight anyway (BINDING in the agent) — the two
+never conflict because both apply the same SECTION=reuse rules; the skill's
+pass just moves the decision to the human.
+
+## 4. Launch
+
+Spawn prompt skeleton (one per sub-question):
+
+```
+PROFILE=<x> [DEPTH=<n>]
+FILING=orchestrator — do not append INDEX rows; the skill files reports.
+Research brief: <question(s)>
+Stack signature: <sig>
+Internal context: <paths / findings worth reading first>
+Reuse decision from library lookup: NEW | DELTA (prior: <path>)
+OUTPUT CONTRACT (mandatory):
+Write the full report to: <pre-allocated path per SECTION=library>
+First line: RESEARCH_OUTPUT_PATH: <that path>
+Return COMPACT per your Return Contract.
+```
+
+- Pre-allocate ids `RES-<YYYYMMDD>-<slug>`; two sub-questions same day → make
+  slugs distinct (never rely on a suffix race).
+- Parallel fan-out (Claude): all spawns in ONE message. Codex: sequential
+  by-name spawns (`agents/runtime-portability-protocol.md`), same prompts.
+- Foreground when the user is waiting; background (`run_in_background: true` +
+  `BACKGROUND_RUN=true` first line) only when the user asked to keep working.
+
+## 5. Filing
+
+For each spawn: file exists at the pre-allocated path → frontmatter parses and
+carries `id/category/tags/valid_until` → append its INDEX row (this skill is
+the ONLY INDEX writer during the run). Failures:
+
+- Missing file → re-read the worker's return; if it died, offer one relaunch
+  of THAT sub-question (never the whole batch).
+- Frontmatter invalid → fix mechanically from the report content (id/path are
+  known; category from the pre-allocation; tags from the questions).
+- INDEX drift (row exists, file moved, duplicate id) → run
+  `scripts/rebuild-research-index.mjs <research_dir>` and report what changed.
+
+## 6. Matrix loop
+
+On `## SOURCE_MATRIX_CANDIDATE` in any report, per `SECTION=sources`:
+
+1. Show the candidate (nature, change, source, tier, evidence).
+2. Offer BOTH, independently: (a) apply now to `SOURCES.md` under
+   `## Local additions` (append a row — never touch the default matrix
+   section); (b) print the report's ready-to-paste BALDART prompt for the
+   maintainer session.
+3. Never apply silently; never emit candidates the report didn't contain.
+
+## Recovery
+
+- Session died mid-run → `/research status` surfaces reports on disk that lack
+  INDEX rows (rebuild script reconciles) and pre-allocated paths never written
+  (relaunch those sub-questions only).
+- Library missing entirely → `npx baldart doctor` (`create-research-dir`),
+  then resume.

package/framework/.claude/skills/research/scripts/rebuild-research-index.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * rebuild-research-index.mjs — deterministic INDEX.md reconciliation.
+ *
+ * Report frontmatter is the source of truth; INDEX.md is a regenerable view
+ * (research-protocol.md SECTION=library). Walks the category subdirectories
+ * (never _archive/), parses each report's frontmatter, and rewrites the INDEX
+ * table — preserving the header block above the table. Zero dependencies.
+ *
+ * Usage: node rebuild-research-index.mjs <research_dir> [--check]
+ *   --check  exit 1 (printing the diff summary) instead of writing.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CATEGORY_DIRS = ['architecture', 'integrations', 'regulatory', 'ux-patterns', 'algorithms', 'tooling'];
+
+const dir = process.argv[2];
+const checkOnly = process.argv.includes('--check');
+if (!dir || !fs.existsSync(dir)) {
+  console.error('Usage: node rebuild-research-index.mjs <research_dir> [--check]');
+  process.exit(2);
+}
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w+):\s*(.*)$/);
+    if (!kv) continue;
+    let v = kv[2].trim().replace(/^["']|["']$/g, '');
+    if (v.startsWith('[') && v.endsWith(']')) {
+      v = v.slice(1, -1).split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean).join(', ');
+    }
+    out[kv[1]] = v;
+  }
+  return out;
+}
+
+const rows = [];
+const problems = [];
+for (const cat of CATEGORY_DIRS) {
+  const catAbs = path.join(dir, cat);
+  if (!fs.existsSync(catAbs)) continue;
+  for (const f of fs.readdirSync(catAbs).filter((f) => f.endsWith('.md')).sort()) {
+    const rel = path.join(cat, f);
+    let fm;
+    try { fm = parseFrontmatter(fs.readFileSync(path.join(catAbs, f), 'utf8')); }
+    catch { problems.push(`${rel}: unreadable`); continue; }
+    if (!fm || !fm.id) { problems.push(`${rel}: missing frontmatter/id`); continue; }
+    if (fm.status === 'superseded') { problems.push(`${rel}: status superseded but not in _archive/`); continue; }
+    rows.push(`| ${fm.id} | ${fm.title || ''} | ${fm.category || cat} | ${fm.profile || ''} | ${fm.tags || ''} | ${fm.date || ''} | ${fm.valid_until || ''} | ${rel} |`);
+  }
+}
+rows.sort();
+
+const indexPath = path.join(dir, 'INDEX.md');
+const existing = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf8') : '';
+const tableStart = existing.search(/^\| id \|/m);
+const header = tableStart >= 0
+  ? existing.slice(0, tableStart)
+  : '# Research Library — INDEX\n\n';
+const headerRow = '| id | title | category | profile | tags | date | valid_until | path |\n|----|-------|----------|---------|------|------|-------------|------|\n';
+const next = header + headerRow + rows.join('\n') + (rows.length ? '\n' : '');
+
+if (next === existing) {
+  console.log(`INDEX.md in sync (${rows.length} report(s)).`);
+} else if (checkOnly) {
+  console.error(`INDEX.md out of sync: ${rows.length} report(s) on disk.`);
+  process.exit(1);
+} else {
+  fs.writeFileSync(indexPath, next, 'utf8');
+  console.log(`INDEX.md rebuilt: ${rows.length} report(s).`);
+}
+for (const p of problems) console.warn(`WARN ${p}`);

package/framework/.claude/skills/ui-design/CHANGELOG.md

@@ -2,9 +2,68 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.0.0 — 2026-07-03
+
+**The local design studio.** Root-level refactor (framework v5.2.0): the
+skill absorbs top-of-the-line design intelligence distilled from
+[impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0),
+[taste-skill](https://github.com/Leonxlnx/taste-skill) (MIT) and
+[open-design](https://github.com/nexu-io/open-design) (Apache-2.0), and stops
+depending on superseded external skills. Public step contract A–H is
+UNCHANGED (the `/prd` 3a–3e mapping still holds).
+
+- **BREAKING — external-skill dependencies removed**: `ui-ux-pro-max`
+  (Prerequisite 6, dropped — replaced by the internal references),
+  `huashu-design` (optional prototype engine, dropped — the engine rules now
+  live in `references/generation.md`), `frontend-design` (linked skill,
+  retired to a router at framework level).
+- **NEW Step C.0 — Design Read & Direction Lock** (`references/design-brief.md`):
+  register (brand/product), regime (in-context/exploration), the three dials
+  (VARIANCE/MOTION/DENSITY), two-altitude slop test, scene sentence,
+  color-commitment axis, anti-references, ONE-question ambiguity rule,
+  rotation check. Persisted in the state file.
+- **NEW `references/design-directions.md`**: 12-direction aesthetic menu,
+  color commitment axis, reflex-reject lists (LILA rule, premium-consumer
+  beige ban, cream/sand band, serif discipline, font reflex pool + rotation).
+- **NEW `references/craft-standards.md`**: always-on craft rules (tracking
+  table, three-weight system, color proportions + accent rationing ≤2/screen,
+  layout-family diversity, 8-state taxonomy + loading thresholds, Laws-of-UX
+  numbers, 100/300/500 motion rule, curve-vs-spring) — numeric ranges cite
+  `design-system-protocol.md` § Reference Tables. **Canonical new home of the
+  Performance Gates (CWV 2026), Modern CSS and Form-quality sections**
+  migrated from the retired `frontend-design` generator.
+- **NEW `references/anti-slop.md`**: the Tells catalog — absolute bans,
+  rationed patterns (eyebrow ≤ ceil(sections/3), etc.), layout/copy tells,
+  every ban with a declared-override path.
+- **NEW `scripts/craft-check.mjs`**: deterministic anti-slop/craft gate
+  (~22 rules, zero deps, `--json`, `--strict-palette`), run by the generator
+  as self-check and by Step D as Gate 0. Identical on Claude and Codex.
+- **Step D rewritten** (`references/evaluation.md`): Gate 0 (craft-check,
+  fail-fast, output hidden from lenses) + **Lens A = `ui-quality-critic`**
+  (true evaluator diversity — a different agent definition, rubric SSOT in
+  `design-system-protocol.md` § Design Quality Rubric) + **Lens B = fresh
+  `ui-expert`** (brief/context conformance B1–B5, evidence-cited scoring,
+  worst-sustained-band). Honest **degraded mode** on non-multimodal runtimes
+  (mandatory `⚠️ DEGRADED` banner). Max 5 iterations unchanged.
+- **Generation rewritten** (`references/generation.md`): token-first scaffold
+  (project tokens embedded in `:root` — the mockup speaks the project token
+  language, mirroring the Claude Design channel), `data-region` annotations
+  (surgical iteration + deterministic inventory join), real-content
+  discipline (image source ladder, copy self-audit, states-as-content),
+  responsive-by-construction (375px is evaluated), generator craft self-check.
+- **Routing fix**: frontmatter `description` rewritten to win skill routing
+  for design/prototype/restyle work (explicit supersession of
+  `frontend-design`/`ui-ux-pro-max`; IT+EN triggers; explicit NOT-list →
+  `/ui-implement`, `ui-expert`, `/motion-design`).
+- **Runtime portability**: new § citing
+  `agents/runtime-portability-protocol.md` (spawn/decision-gate bindings);
+  Codex degradation documented instead of silent.
+- Codex parity: **portable** (same SKILL.md bundle; zero-dep script; visual
+  lenses degrade honestly with banner).
+
 ## 1.1.0 — 2026-07-02
 
-- **Analysis-profile contract (framework v4.94.0)**: Step B adjacent-UI analysis passes `PROFILE=ui OUTPUT=terse` to `codebase-architect` (registry-cascade-first per `framework/agents/analysis-profiles.md`).
+- **Analysis-profile contract (framework v4.94.0)**: Step B adjacent-UI analysis passes `PROFILE=ui OUTPUT=terse` a `codebase-architect` (registry-cascade-first per `framework/agents/analysis-profiles.md`).
 
 ## 1.0.0 — 2026-07-01