baldart 3.6.2

package/framework/routines/code-review.routine.yml

@@ -0,0 +1,46 @@
+name: code-review
+description: Nightly code review on commits from the last 24h — catches regressions and quality drift.
+since_version: 2.1.0
+
+schedule:
+  cron: "0 1 * * *"            # 01:00 UTC daily
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: nightly
+
+agent: code-reviewer
+
+prompt: |
+  Run the nightly code review:
+
+  1. Compute the diff for commits from the last 24h on the main / develop
+     branch.
+  2. Apply the agent's confidence-based filtering (HIGH/MED/LOW) and
+     "Never demote" anti-pattern cluster.
+  3. Spawn specialist auditors in parallel when the diff matches their
+     domain (security-reviewer for auth/secrets, api-perf-cost-auditor for
+     route handlers / DB queries / cron / heavy loops).
+  4. Pool findings using the shared Findings Schema and emit a consolidated
+     report under `docs/reports/{{YYYYMMDD}}-code-review.md`.
+  5. Apply trivial, verified fixes inline (small typos, formatting, missing
+     `.limit()` on bounded queries) and commit with prefix `[CODE-REVIEW]`.
+     Anything HIGH that requires design judgement is left as a finding for
+     the maintainer.
+
+  Scope is changed files only. Pre-existing code is not in scope unless
+  a change introduces a regression there.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-code-review.md
+  commit:
+    enabled: true
+    prefix: "[CODE-REVIEW]"
+    branch: main
+
+required_artifacts:
+  - .claude/agents/code-reviewer.md
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/doc-review.routine.yml

@@ -0,0 +1,45 @@
+name: doc-review
+description: Nightly documentation review — audits recent doc changes, flags SSOT drift, proposes fixes.
+since_version: 2.1.0
+
+schedule:
+  cron: "0 0 * * *"            # 00:00 UTC daily
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: nightly
+
+agent: doc-reviewer
+
+prompt: |
+  Run the nightly documentation review:
+
+  1. Diff the last 24h of commits and identify doc changes (`docs/**`,
+     `AGENTS.md`, `agents/**`, design-system files if present).
+  2. For each changed doc, verify it stays in sync with the code it
+     references. Flag drift as `DOC_DRIFT`.
+  3. For each source file change that landed without a corresponding doc
+     update, flag `DOC_GAP`.
+  4. If the project ships a design-system SSOT, run the standard DS drift
+     checks (INDEX coverage, per-component accuracy, animations
+     reconciliation, tokens reconciliation).
+  5. Emit a consolidated report under `docs/reports/{{YYYYMMDD}}-doc-review.md`
+     with a punch list of needed fixes. Apply trivial fixes inline and
+     commit with prefix `[DOC-REVIEW]`.
+
+  Stay strictly inside `docs/**`. Application code is out of scope.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-doc-review.md
+  commit:
+    enabled: true
+    prefix: "[DOC-REVIEW]"
+    branch: main
+
+required_artifacts:
+  - docs/
+  - .claude/agents/doc-reviewer.md
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/ds-drift.routine.yml

@@ -0,0 +1,52 @@
+name: ds-drift
+description: Weekly design-system drift check — verifies INDEX, per-component docs, animations, tokens.
+since_version: 2.1.0
+
+schedule:
+  cron: "0 3 * * 1"            # Monday 03:00 UTC
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: weekly
+
+agent: doc-reviewer
+
+prompt: |
+  Run the weekly design-system drift check (only if `docs/design-system/`
+  exists in the project — exit cleanly if absent):
+
+  1. **INDEX coverage**: compare `docs/design-system/INDEX.md` component
+     index against the actual shared-component inventory. Flag
+     `DS_INDEX_DRIFT` for any mismatch.
+  2. **Per-component accuracy**: for each `docs/design-system/components/<Name>.md`,
+     verify it lines up with the source file (variants, props, exported
+     constants). Flag `DS_COMPONENT_STALE` for docs not re-verified in >7
+     days where the source has changed in git.
+  3. **Animations reconciliation**: `docs/design-system/patterns/animations.md`
+     must match keyframes in the project's global styles. Flag
+     `DS_ANIMATIONS_DRIFT`.
+  4. **Tokens reconciliation**: when tokens source files changed, verify
+     `docs/design-system/tokens-reference.md` is in sync and the relevant
+     CSS custom properties still exist. Flag `DS_TOKENS_DRIFT`.
+  5. Emit a consolidated report under
+     `docs/reports/{{YYYYMMDD}}-ds-drift.md`.
+
+  Apply trivial fixes inline (e.g. update an INDEX row to match the current
+  source). Anything that requires design judgement is left as a finding.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-ds-drift.md
+  commit:
+    enabled: true
+    prefix: "[DS-DRIFT]"
+    branch: main
+
+required_artifacts:
+  - docs/design-system/
+  - .claude/agents/doc-reviewer.md
+
+optional: true   # routine is silently skipped when artifacts missing
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/full-sweep.routine.yml

@@ -0,0 +1,51 @@
+name: full-sweep
+description: Weekly full SSOT sweep — runs the project's audit suite and writes a consolidated drift report.
+since_version: 2.1.0
+
+schedule:
+  cron: "0 3 * * 0"            # Sunday 03:00 UTC
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: weekly
+
+agent: doc-reviewer
+
+prompt: |
+  Run the weekly full SSOT sweep:
+
+  1. Run the project's audit suite if it exists (typically
+     `npm run audit:full-sweep`, `npm run validate:frontmatter`,
+     `npm run validate:errors`, `npm run validate:perms`,
+     `npm run validate:env`, `npm run validate:imports`). Capture stdout/stderr
+     and exit codes for each.
+  2. Parse the validator outputs and group findings by category
+     (FRONTMATTER_DRIFT, ERRORS_DRIFT, PERMS_DRIFT, ENV_DRIFT, IMPORTS_DRIFT,
+     etc.).
+  3. For each finding, propose a fix and apply trivial ones inline. Anything
+     requiring design judgement is left as an item in the report's
+     "Manual review needed" section.
+  4. Emit a consolidated report under
+     `docs/reports/{{YYYYMMDD}}-full-sweep.md` with one section per
+     validator and a top-line PASS/FAIL summary.
+  5. Commit applied fixes with prefix `[FULL-SWEEP]`.
+
+  If no audit scripts are configured in the project's `package.json`, log
+  the missing scripts as informational notes and exit cleanly.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-full-sweep.md
+  commit:
+    enabled: true
+    prefix: "[FULL-SWEEP]"
+    branch: main
+
+required_artifacts:
+  - package.json
+  - .claude/agents/doc-reviewer.md
+
+optional: true   # only runs when audit scripts are present
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/index.yml

@@ -0,0 +1,70 @@
+# BALDART Routines Catalog
+#
+# Each routine is a declarative spec for a scheduled run of one of the
+# framework's agents. The actual scheduling backend (Claude Code Cloud
+# RemoteTrigger, GitHub Actions, cron, …) is chosen at install time via
+# `npx baldart routines install <name>`.
+#
+# Routines are designed to make the framework's auto-learning and drift-
+# detection loops actually run. Without these schedules, agents like
+# wiki-curator or skill-improver are dormant.
+#
+# Add a new routine by dropping `<name>.routine.yml` in this directory and
+# listing it under `routines:` below. The CLI reads this catalog as the
+# source of truth.
+
+version: 1
+routines:
+  # Nightly cadence ---------------------------------------------------------
+  - name: doc-review
+    file: doc-review.routine.yml
+    cadence: nightly
+    since_version: 2.1.0
+    summary: |
+      Nightly documentation review — runs doc-reviewer to audit recent
+      doc changes, flag SSOT drift, and propose fixes.
+
+  - name: code-review
+    file: code-review.routine.yml
+    cadence: nightly
+    since_version: 2.1.0
+    summary: |
+      Nightly code review — runs code-reviewer on commits from the last
+      24h to catch regressions early.
+
+  - name: wiki-review
+    file: wiki-review.routine.yml
+    cadence: nightly
+    since_version: 2.1.0
+    summary: |
+      Nightly wiki review — drives the LLM-wiki auto-learning loop.
+      Surfaces synthesis candidates and validates anchors. Required for
+      the LLM Wiki Overlay methodology to actually run.
+
+  # Weekly cadence ----------------------------------------------------------
+  - name: skill-improve
+    file: skill-improve.routine.yml
+    cadence: weekly
+    since_version: 2.1.0
+    summary: |
+      Weekly skill / agent improvement — analyses accumulated review
+      findings and proposes refinements to .claude/skills/, .claude/agents/,
+      and AGENTS.md.
+
+  - name: ds-drift
+    file: ds-drift.routine.yml
+    cadence: weekly
+    since_version: 2.1.0
+    summary: |
+      Weekly design-system drift check — verifies INDEX, per-component
+      docs, animations, and tokens against the source. Optional (only
+      useful if the project ships a design-system SSOT).
+
+  - name: full-sweep
+    file: full-sweep.routine.yml
+    cadence: weekly
+    since_version: 2.1.0
+    summary: |
+      Weekly full SSOT sweep — runs the project's full audit suite
+      (frontmatter, errors, perms, env, imports, etc.) and writes a
+      consolidated drift report.

package/framework/routines/skill-improve.routine.yml

@@ -0,0 +1,50 @@
+name: skill-improve
+description: Weekly skill / agent improvement — analyses accumulated review findings and proposes refinements.
+since_version: 2.1.0
+
+schedule:
+  cron: "0 2 * * 0"            # Sunday 02:00 UTC
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: weekly
+
+agent: skill-improver
+
+prompt: |
+  Run the weekly skill / agent improvement pass:
+
+  1. Read the last 7 days of `docs/reports/*-code-review.md` and
+     `docs/reports/*-doc-review.md` (plus any `docs/reports/*-qa.md` if
+     present). Identify recurring patterns in findings.
+  2. For each recurring pattern, propose a targeted improvement to:
+     - the relevant `.claude/skills/<name>/SKILL.md` (rule clarification,
+       new MUST/SHOULD, anti-pattern entry)
+     - the relevant `.claude/agents/<name>.md` (prompt tightening,
+       checklist update)
+     - `AGENTS.md` (new project-wide rule) or
+       `agents/coding-standards.md` (terminology, naming)
+  3. Apply changes inline and commit with prefix `[SKILL-IMPROVE]`. NEVER
+     modify application code in this routine — only `.claude/`, `agents/`,
+     `AGENTS.md`, `docs/`.
+  4. Emit a consolidated report under
+     `docs/reports/{{YYYYMMDD}}-skill-improve.md` listing every change with
+     evidence (which findings drove it) and a confidence score.
+
+  If no recurring pattern is found, write a short "no changes needed" report
+  and exit cleanly.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-skill-improve.md
+  commit:
+    enabled: true
+    prefix: "[SKILL-IMPROVE]"
+    branch: main
+
+required_artifacts:
+  - docs/reports/
+  - .claude/agents/skill-improver.md
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/wiki-review.routine.yml

@@ -0,0 +1,45 @@
+name: wiki-review
+description: Nightly review of the derived LLM wiki overlay (docs/wiki/) — synthesis candidates, anchor validation, drift detection.
+since_version: 2.1.0
+
+schedule:
+  cron: "0 2 * * *"            # 02:00 UTC daily
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: nightly
+
+agent: wiki-curator
+
+prompt: |
+  Run the nightly wiki-review pass:
+
+  1. Scan ADRs and PRDs from the last 14 days. For each architectural pivot
+     (provider swap, schema change, auth change, API contract, multi-card
+     epic) propose a synthesis page candidate and append it to
+     `docs/wiki/log.md` with `entry_type: synthesis_candidate`.
+  2. Read `docs/wiki/log.md` for RAG queries with verdict=weak|empty
+     repeated ≥3 times. These are documentation gaps — propose a synthesis.
+  3. Validate anchor slugs across all wiki pages (internal and cross-file).
+     Flag `WIKI_ANCHOR_BROKEN` and fix in-place when possible.
+  4. Verify frontmatter discipline on every wiki page. Run the project's
+     frontmatter validator if it exists.
+  5. Emit a consolidated report under `docs/reports/{{YYYYMMDD}}-wiki-review.md`.
+
+  Do NOT create canonical truth in the wiki layer. SSOT always wins.
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-wiki-review.md
+  commit:
+    enabled: true
+    prefix: "[WIKI-REVIEW]"
+    branch: main
+
+required_artifacts:
+  # Routine is silently skipped if these are missing.
+  - docs/wiki/
+  - .claude/agents/wiki-curator.md
+
+backend_hints:
+  - claude-code-cloud      # primary — uses Claude Code Cloud RemoteTrigger
+  - github-actions         # alternative — workflow_dispatch + schedule
+  - cron                   # local — shell wrapper around `claude` CLI

package/framework/templates/baldart.config.template.yml

@@ -0,0 +1,113 @@
+# BALDART Project Configuration
+# ------------------------------
+# This file is consumed by BALDART skills/agents instead of hard-coded paths.
+# It is a CUSTOMIZABLE COPY: BALDART never overwrites it on `npx baldart update`.
+#
+# To (re)generate / merge: `npx baldart configure`
+# Schema reference:        framework/docs/PROJECT-CONFIGURATION.md
+# Always commit this file. Skills will ask the user when keys are missing.
+
+# Schema version. Do not edit manually. `baldart configure` migrates this.
+version: 1
+
+# ─── PATHS ───────────────────────────────────────────────────────────────
+# Absolute repo paths to the project's canonical documents and source roots.
+# Leave a key empty ("") or omit it if the concept does not exist in your
+# project — skills gated by the corresponding `features.*` flag will skip
+# the related BLOCKING read.
+paths:
+  # Design-system entry point (e.g. docs/design-system/INDEX.md).
+  # Set features.has_design_system: true if this exists.
+  design_system: ""
+
+  # Canonical brand / UI guidelines doc (typography, colors, voice principles).
+  ui_guidelines: ""
+
+  # API reference index (set features.has_api_docs: true to enable).
+  api_index: ""
+
+  # Canonical schema and error-code references (used by doc-writing-for-rag).
+  api_schemas: ""
+  api_errors: ""
+
+  # Source roots — skills use these to discover/place components.
+  components_primitives: ""   # e.g. src/components/ui
+  components_root: ""         # e.g. src/components
+  global_styles: ""           # e.g. src/app/globals.css
+
+  # Workflow infrastructure (set the matching `features.*` flag).
+  backlog_dir: ""             # e.g. backlog
+  adrs_dir: ""                # e.g. docs/decisions
+  prd_dir: ""                 # e.g. docs/prd
+  references_dir: ""          # e.g. docs/references
+  wiki_dir: ""                # e.g. docs/wiki   (LLM-wiki overlay)
+
+  # Test infrastructure.
+  e2e_tests_dir: ""           # e.g. tests/e2e
+
+# ─── IDENTITY ────────────────────────────────────────────────────────────
+# Brand and audience facts skills use when generating UI, copy, or motion.
+identity:
+  # Public-facing product name.
+  brand_name: ""
+
+  # Visual/conceptual design direction (free-form, single line).
+  # Examples: "Neo-Brutalism", "Glassmorphism", "Minimalist", "Skeuomorphic",
+  # "Material 3", "" (no opinion — skills default to neutral choices).
+  design_philosophy: ""
+
+  # Primary UI language (BCP-47 tag). Drives copywriting register.
+  language: en
+
+  # Domain segments your product addresses (free-form labels).
+  # Examples: ["merchant","customer"], ["b2b","b2c"], ["internal","external"], [].
+  # Empty list = no segmentation; copy/design skills won't split tone by audience.
+  audience_segments: []
+
+# ─── STACK ───────────────────────────────────────────────────────────────
+# Technology choices that skills must respect when generating code.
+stack:
+  charting:
+    # Libraries to use by default (in order of preference).
+    canonical: []             # e.g. ["recharts", "@nivo/heatmap"]
+    # Libraries skills must refuse to propose.
+    forbidden: []             # e.g. ["chart.js", "echarts", "victory"]
+    # Optional: path to project-specific chart wrappers
+    # (skills will propose these over raw library usage).
+    wrappers_root: ""         # e.g. src/components/charts
+
+  animation:
+    # Libraries to use for motion (in order of preference).
+    canonical: []             # e.g. ["framer-motion", "lottie-react"]
+    forbidden: []
+
+  testing:
+    # E2E framework — drives playwright-skill behaviour.
+    e2e: ""                   # e.g. "playwright" | "cypress" | ""
+
+# ─── FEATURES ────────────────────────────────────────────────────────────
+# Explicit booleans. ALL keys must be present (true | false) once `baldart
+# configure` has run. An absent flag means the user hasn't been asked yet —
+# skills will prompt and persist the answer. Never assume `false` from absence.
+features:
+  # The project has a documented design system rooted at paths.design_system.
+  # Skills like ui-design treat its INDEX/tokens as BLOCKING when true.
+  has_design_system: false
+
+  # Multi-tenant theming (e.g. per-merchant accent overrides).
+  multi_tenant_theming: false
+
+  # Canonical API docs at paths.api_index — gates doc-writing-for-rag flows.
+  has_api_docs: false
+
+  # Backlog-card driven workflow (paths.backlog_dir + AGENTS.md card protocol).
+  has_backlog: false
+
+  # ADR workflow (paths.adrs_dir + ADR-YYYYMMDD-* convention).
+  has_adrs: false
+
+  # PRD workflow (paths.prd_dir + /prd skill produces specs here).
+  has_prd_workflow: false
+
+  # LLM-wiki overlay (paths.wiki_dir + capture/wiki-curator loop).
+  has_wiki_overlay: false