baldart 3.6.2

package/framework/templates/overlays/copywriting.fidelity-example.md

@@ -0,0 +1,62 @@
+---
+base_skill: copywriting
+base_skill_version: 3.0.0
+mode: extend
+---
+
+# copywriting — fidelity-app overlay (example)
+
+> Captures the project-specific brand voice pillars and segment register that
+> used to live hard-coded in the copywriting skill before v3.0.0. Drop into
+> `.baldart/overlays/copywriting.md` and adapt freely.
+
+## Brand voice pillars (`${paths.ui_guidelines}` § 1.4 — canonical)
+
+The fidelity-app brand voice is built on four pillars. Every UI copy decision MUST align with at least one and contradict none:
+
+1. **Fun & Playful** — light, lively, never sterile.
+2. **Rewarding** — language frames every action as earning something concrete.
+3. **Trustworthy** — operational copy is precise; numbers and dates appear as facts, not promises.
+4. **Energetic** — verbs are active; CTAs use imperatives.
+
+Marketing hyperbole stays in marketing surfaces; transactional/system copy (errors, confirmations) stays direct and trustworthy — even when other pillars apply elsewhere on the page.
+
+## Design philosophy implication (Neo-Brutalism)
+
+Copy is **direct and concrete**: short sentences, concrete nouns, no corporate hedging. Avoid "streamline", "optimize", "innovative", "leverage", "best-in-class". Prefer Italian punchy phrasings ("Risparmia 4 ore a settimana" beats "Optimize your weekly workflow").
+
+## [OVERRIDE] Language rule
+
+All UI copy is **Italian-first** (`identity.language: it`). English appears only in:
+- Brand name / product name fragments that are intentionally untranslated.
+- Technical terms with no idiomatic Italian (e.g. "API", "checkout", "dashboard").
+
+Mixing English marketing phrasing in Italian UI ("Get started ora!") is forbidden — automatic rewrite required.
+
+## Audience register matrix (`identity.audience_segments`)
+
+| Segment | Tone | Hyperbole allowed? | Example CTA |
+|---|---|---|---|
+| `customer` | Playful + rewarding. Emoji sparingly (max 1 per surface). | Yes in marketing, never in transactional. | "Riscatta il premio" |
+| `merchant` | Operational, trust-first, low hyperbole. Numbers up front. | No. | "Apri il pannello vendite" |
+| `merchant-staff` | Operational, brief. No marketing pillars. Direct verbs. | No. | "Conferma incasso" |
+| `super-admin` | Neutral, factual. Like reading a status report. | No. | "Visualizza log" |
+
+When the user requests copy without specifying a segment, default to asking. Never write segment-blind copy in this project.
+
+## Forbidden vocabulary (auto-rewrite)
+
+`streamline`, `seamless`, `unlock`, `empower`, `leverage`, `state-of-the-art`, `cutting-edge`, `revolutionary`, `next-generation`, `world-class`. Italian equivalents to avoid: `ottimizza`, `senza soluzione di continuità`, `sblocca il potenziale`.
+
+## Tone-by-component (consult `${paths.design_system}/INDEX.md` for variants)
+
+- **Empty states (customer surfaces)**: playful + rewarding. End with action verb.
+- **Empty states (merchant surfaces)**: operational. State the missing data, suggest the next concrete step.
+- **Error messages (any segment)**: pillar #3 (Trustworthy) only. Format: "Cosa è successo + Cosa fare adesso". No emoji, no playful tone.
+- **Confirmation dialogs**: pillar #3 only. Past-tense fact + next-step verb.
+
+## Surfaces with unique register (project-specific)
+
+- **Lottery surfaces** (customer): heighten pillar #1 (Fun & Playful) — exclamation tone allowed.
+- **Rewards screens** (customer): heighten pillar #2 (Rewarding) — frame outcomes as earnings.
+- **Gamification surfaces** (customer): pillars #1 + #2 combined; never #3.

package/framework/templates/overlays/ui-design.fidelity-example.md

@@ -0,0 +1,75 @@
+---
+base_skill: ui-design
+base_skill_version: 3.0.0
+mode: extend
+---
+
+# ui-design — fidelity-app overlay (example)
+
+> This overlay captures every project-specific opinion that used to live
+> hard-coded in the BALDART `ui-design` skill before v3.0.0. Drop it into
+> your repo at `.baldart/overlays/ui-design.md` to reproduce the legacy
+> behaviour. Adapt freely.
+>
+> Companion `baldart.config.yml` values (set via `npx baldart configure`):
+> ```yaml
+> identity:
+>   brand_name: "Fidelity"
+>   design_philosophy: "Neo-Brutalism"
+>   language: it
+>   audience_segments: ["customer","merchant","merchant-staff","super-admin"]
+> stack:
+>   charting:
+>     canonical: ["recharts", "@nivo/heatmap"]
+>     forbidden: ["chart.js","echarts","victory","visx","d3","observable-plot","tremor"]
+>     wrappers_root: "src/components/charts"
+> features:
+>   has_design_system: true
+>   multi_tenant_theming: true
+> ```
+
+## Audience segments (project-specific)
+
+The Step "Prerequisites" item 7 menu of audience segments is hard-pinned to:
+**Customer, Merchant, Merchant Staff, Super Admin.** Ask the user which one before any design work; refuse to proceed if unstated.
+
+## Tailwind v4 token mechanism (extends "Design System Alignment")
+
+Tailwind CSS v4 is in use (CSS-first, **NO** `tailwind.config.ts`). Token consumption is via CSS custom properties declared in `${paths.global_styles}`. Never hardcode hex colors, shadow pixel tuples, or border-width values — use the CSS variables declared in `${paths.design_system}/tokens-reference.md`.
+
+## Merchant theming pairing rule (multi-tenant)
+
+When rendering any text over a theme-primary background, it MUST pair with the theme-primary-text token:
+```html
+<span class="bg-[var(--theme-primary)] text-[var(--theme-primary-text,#000)]">…</span>
+```
+This is non-negotiable per `${paths.design_system}/patterns/merchant-theming.md`. Evaluation FAILS hard on any violation regardless of other scores.
+
+## [OVERRIDE] Charting stack (Prerequisites item 5)
+
+Replaces the generic "consult `stack.charting`" rule. The project enforces:
+
+- **Canonical**: Recharts v3 (via shadcn primitives in `${paths.components_primitives}/chart.tsx`) + `@nivo/heatmap` only.
+- **Always propose the Neo-Brutalism wrappers** in `${stack.charting.wrappers_root}/` — `BrutalLineChart`, `BrutalBarChart`, `BrutalDonutChart`, `BrutalHeatmapChart`. Never propose raw Recharts/Nivo.
+- **Forbidden** (immediate refusal): chart.js, echarts, victory, visx, d3 standalone, observable-plot, tremor.
+- Read `${paths.design_system}/patterns/charting.md` (BLOCKING) before any chart task.
+- Reference ADR: `${paths.adrs_dir}/ADR-20260516-charting-stack-standardization.md`.
+
+## [OVERRIDE] Browser open command (Step E + generation.md)
+
+Replaces the generic `open <file>` instruction. The project standardizes on Safari:
+```bash
+open -a Safari /tmp/prd-design-<slug>/option-a.html
+```
+
+## Evaluation — additional thresholds
+
+In addition to the base soglie hard:
+
+- **C3 (Design System) >= 4** when `identity.design_philosophy: "Neo-Brutalism"` — anything else means the prototype reads as generic shadcn rather than brutalist.
+- **Themed-surface pairing check**: FAIL on any `bg-[var(--theme-primary)]` without a matching `text-[var(--theme-primary-text,…)]`.
+- **Italian-only**: any English UI text (CTA, button label, empty state) is an automatic FAIL.
+
+## Marker labels
+
+In Step C "Marker": use `NUOVO` for new areas, `MODIFICATO` for changed areas. Bordo tratteggiato attorno agli elementi modificati nel layout esistente.

package/framework/templates/skill-project-context.snippet.md

@@ -0,0 +1,19 @@
+<!--
+  PROJECT CONTEXT HEADER — paste this at the top of any BALDART skill that
+  depends on project-specific paths, identity, stack choices, or feature
+  toggles. Customize the bracketed values for your skill.
+
+  Full protocol: framework/agents/project-context.md
+  Schema:        framework/templates/baldart.config.template.yml
+  Docs:          framework/docs/PROJECT-CONFIGURATION.md
+
+  Keep this header DENSE (3-6 lines). Do not re-explain the protocol —
+  cite framework/agents/project-context.md instead.
+-->
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.<key>`, `identity.<key>`, `stack.<group>.<key>`.
+**Gated by features:** `features.has_<flag>` (BLOCKING when `true`), `features.has_<other>` (skips step N when `false`).
+**Overlay:** loads `.baldart/overlays/<this-skill>.md` if present — extends base by default; sections marked `## [OVERRIDE] <topic>` replace base sections.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

package/framework/templates/spec.template.md

@@ -0,0 +1,208 @@
+# [Feature Name] - Specification
+
+**Feature ID**: FEAT-XXX
+**Status**: DRAFT | APPROVED | IMPLEMENTED
+**Owner**: [Agent/Person]
+**Created**: YYYY-MM-DD
+**Updated**: YYYY-MM-DD
+
+---
+
+## Summary
+
+[1-3 paragraphs describing what this feature does, why it exists, and what problem it solves]
+
+**Target Users**: [CUSTOMER | MERCHANT | ADMIN]
+**Priority**: [LOW | MEDIUM | HIGH | CRITICAL]
+**Effort Estimate**: [S | M | L | XL]
+
+---
+
+## User Stories
+
+**As a [user type]**, I want to [action] so that [benefit].
+
+### Primary Stories
+- **US-1**: As a [user], I want to [action] so that [benefit]
+- **US-2**: As a [user], I want to [action] so that [benefit]
+
+### Secondary Stories
+- **US-3**: As a [user], I want to [action] so that [benefit]
+
+---
+
+## Scope
+
+### In Scope
+- [What this feature WILL include]
+- [Specific functionality to be implemented]
+
+### Out of Scope (Non-Goals)
+- [What this feature will NOT include]
+- [Features explicitly excluded]
+- [Future enhancements to consider later]
+
+---
+
+## UX Notes
+
+### User Flow
+1. User navigates to [page/component]
+2. User performs [action]
+3. System responds with [result]
+4. User sees [feedback]
+
+### UI Components
+- **[Component Name]**: Description and purpose
+- **[Component Name]**: Description and purpose
+
+### Mobile Considerations
+- [Mobile-specific UX notes]
+- [Responsive behavior]
+- [Touch interactions]
+
+### Error States
+- [Error condition]: [Error message shown to user]
+- [Error condition]: [Error message shown to user]
+
+### Loading States
+- [When loading]: [What user sees]
+
+---
+
+## API Changes
+
+### New Endpoints
+```typescript
+// POST /api/[endpoint]
+// Description: [What this endpoint does]
+Request: {
+  field: type  // Description
+}
+Response: {
+  field: type  // Description
+}
+Errors:
+  - 400: [Error condition]
+  - 404: [Error condition]
+  - 500: [Error condition]
+```
+
+### Modified Endpoints
+```typescript
+// [METHOD] /api/[endpoint]
+// Changes: [What's being modified]
+```
+
+### Deprecated Endpoints
+- `/api/[old-endpoint]` - Replaced by `/api/[new-endpoint]`
+
+---
+
+## Data Model Changes
+
+### New Collections
+```typescript
+// Collection: [collectionName]
+{
+  id: string              // Description
+  field: type             // Description
+  createdAt: Date
+  updatedAt: Date
+}
+```
+**Indexes Required**: [List indexes]
+
+### Schema Changes to Existing Collections
+```typescript
+// Collection: [collectionName]
+// Added fields:
+{
+  newField: type          // Description
+}
+```
+
+### Data Migration Required
+- [Y/N] If yes, describe migration strategy
+
+---
+
+## Edge Cases
+
+### Validation
+- **[Case]**: System validates [condition] and rejects if [rule]
+- **[Case]**: System validates [condition] and rejects if [rule]
+
+### Error Handling
+- **[Scenario]**: [How system handles it]
+- **[Scenario]**: [How system handles it]
+
+### Performance
+- **[Concern]**: [Mitigation strategy]
+
+### Security
+- **[Concern]**: [Mitigation strategy]
+
+---
+
+## Test Plan
+
+### Manual Test Cases
+1. **[Test Case]**: [Steps to reproduce] → Expected: [result]
+2. **[Test Case]**: [Steps to reproduce] → Expected: [result]
+
+### Validation Checklist
+- [ ] Happy path: User completes flow successfully
+- [ ] Error path: Invalid input rejected with clear message
+- [ ] Empty state: UI handles no data gracefully
+- [ ] Loading state: UI shows loading indicator
+- [ ] Mobile: Feature works on mobile viewport
+- [ ] Authentication: Unauthorized access blocked
+
+### Build Verification
+- [ ] `npm run build` passes with no TypeScript errors
+- [ ] No console errors in browser
+- [ ] All links/navigation work correctly
+
+---
+
+## Rollout Notes
+
+### Prerequisites
+- [Dependency or requirement needed before this can ship]
+
+### Deployment Steps
+1. [Step to deploy]
+2. [Step to deploy]
+
+### Seed Data Updates
+- [Y/N] If yes, describe changes to seed script
+
+### Breaking Changes
+- [List any breaking changes and migration path]
+
+### Rollback Plan
+- [How to rollback if issues found]
+
+---
+
+## Open Questions
+
+- **[Q-1]**: [Question that needs answering before implementation]
+- **[Q-2]**: [Question that needs answering before implementation]
+
+---
+
+## Related
+
+- **Feature Card**: `/backlog/[feature-name].yml`
+- **Related Specs**: [Links to other specs]
+- **Docs References**: [Which docs/references files this impacts]
+
+---
+
+## Changelog
+
+| Date | Change | Author |
+|------|--------|--------|
+| YYYY-MM-DD | Initial draft | [Agent] |

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "baldart",
+  "version": "3.6.2",
+  "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
+  "bin": {
+    "baldart": "./bin/baldart.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0",
+    "sync-version": "node -e \"const fs=require('fs'),p=require('./package.json');p.version=fs.readFileSync('VERSION','utf8').trim();fs.writeFileSync('./package.json',JSON.stringify(p,null,2)+'\\n')\"",
+    "prepublishOnly": "npm run sync-version"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "agents",
+    "framework",
+    "coordination",
+    "development",
+    "workflow"
+  ],
+  "author": "Antonio Baldassarre <antonio@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/antbald/BALDART.git"
+  },
+  "bugs": {
+    "url": "https://github.com/antbald/BALDART/issues"
+  },
+  "homepage": "https://github.com/antbald/BALDART#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "inquirer": "^8.2.5",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1",
+    "simple-git": "^3.22.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "framework",
+    "VERSION",
+    "CHANGELOG.md",
+    "README.md"
+  ]
+}

package/src/commands/add.js

@@ -0,0 +1,229 @@
+const GitUtils = require('../utils/git');
+const SymlinkUtils = require('../utils/symlinks');
+const UI = require('../utils/ui');
+const State = require('../utils/state');
+const Hooks = require('../utils/hooks');
+
+async function add(repo, options) {
+  const git = new GitUtils();
+  const symlinks = new SymlinkUtils();
+
+  try {
+    // Step 1: Verify environment
+    UI.header('STEP 1/5: Verify Environment');
+
+    const spinner = UI.spinner('Checking Git repository...').start();
+
+    const isRepo = await git.isGitRepo();
+    if (!isRepo) {
+      spinner.fail();
+      UI.error('Not a Git repository!');
+      UI.newline();
+      UI.box('ERROR', [
+        'BALDART requires your project to be a Git repository.',
+        '',
+        'Solution:',
+        '  1. Initialize Git: git init',
+        '  2. Or navigate to your project directory'
+      ]);
+      process.exit(1);
+    }
+
+    spinner.succeed('Git repository verified');
+
+    // Step 2: Check for existing framework
+    UI.header('STEP 2/5: Check Existing Installation');
+
+    const exists = await git.frameworkExists();
+    if (exists) {
+      UI.warning('Framework already installed!');
+      const shouldReinstall = await UI.confirm(
+        'Remove and reinstall? (You will lose customizations)',
+        false
+      );
+
+      if (!shouldReinstall) {
+        UI.info('Installation cancelled. Use "baldart update" to update.');
+        process.exit(0);
+      }
+
+      UI.warning('Removing existing framework...');
+      const fs = require('fs');
+      fs.rmSync('.framework', { recursive: true, force: true });
+    }
+
+    UI.success('Ready for installation');
+
+    // Step 3: Explain what will be installed
+    UI.header('STEP 3/5: Installation Overview');
+
+    UI.box('WHAT WILL BE INSTALLED', [
+      '• Core Protocol: AGENTS.md (coordination rules)',
+      '• 17 Agent Modules: architecture, workflows, testing...',
+      '• 9 AI Agents: coder, code-reviewer, doc-reviewer...',
+      '• 3 Commands: /new, /design-review, /issue-review',
+      '• Templates: backlog cards, specs, UI guidelines',
+      '• Pre-commit hooks (customizable)',
+      '',
+      'Framework will be installed in .framework/ directory',
+      'Symlinks created for auto-updateable files',
+      'Templates copied for customization'
+    ]);
+
+    const proceed = await UI.confirm('Install framework?', true);
+    if (!proceed) {
+      UI.info('Installation cancelled');
+      process.exit(0);
+    }
+
+    // Step 4: Download framework
+    UI.header('STEP 4/5: Download Framework');
+
+    const downloadSpinner = UI.spinner(`Downloading from ${repo}...`).start();
+
+    try {
+      await git.addSubtree(repo, options.branch);
+      downloadSpinner.succeed('Framework downloaded');
+
+      const version = await git.getFrameworkVersion();
+      UI.success(`Version installed: ${version}`);
+      try { State.recordInstall({ version, repo }); } catch (_) { /* non-fatal */ }
+    } catch (error) {
+      downloadSpinner.fail();
+      UI.error('Failed to download framework!');
+      UI.newline();
+      UI.box('ERROR', [
+        'Possible causes:',
+        '  • No internet connection',
+        '  • Repository not accessible',
+        `  • Invalid repository: ${repo}`,
+        '',
+        'Solution:',
+        '  • Check your internet connection',
+        '  • Verify repository exists',
+        '  • Try again later'
+      ]);
+      throw error;
+    }
+
+    // Step 5: Setup structure
+    UI.header('STEP 5/5: Setup Project Structure');
+
+    UI.info('Creating directories...');
+    symlinks.ensureDirectory('.claude');
+    symlinks.ensureDirectory('docs/references');
+    symlinks.ensureDirectory('templates');
+    symlinks.ensureDirectory('backlog');
+    UI.success('Directories created');
+
+    UI.newline();
+    // First-time install: 'safe' mode preserves any pre-existing user
+    // customisations without prompting (no destructive backups on fresh
+    // install paths). Per-skill merge always runs.
+    await symlinks.createAllSymlinks({ mode: 'safe' });
+
+    UI.newline();
+    symlinks.copyCustomizableFiles();
+
+    // Configure Git aliases
+    UI.section('Configuring Git Aliases');
+
+    const configureAliases = await UI.confirm('Configure git aliases (fw-version, fw-update, fw-push)?', true);
+
+    if (configureAliases) {
+      await git.git.addConfig('alias.fw-version', '!cat .framework/VERSION');
+      await git.git.addConfig('alias.fw-update', '!npx github:antbald/BALDART update');
+      await git.git.addConfig('alias.fw-push', '!npx github:antbald/BALDART push');
+      UI.success('Git aliases configured');
+    }
+
+    // Framework-edit-gate hook (since v3.3.0)
+    // Auto-register the PreToolUse hook that prevents project-specific
+    // tokens from being written into .framework/ skills accidentally.
+    try {
+      const res = Hooks.register();
+      if (res.status === 'created') {
+        UI.success('Registered framework-edit-gate hook in .claude/settings.json');
+      } else if (res.status === 'updated') {
+        UI.success('Added framework-edit-gate hook to existing .claude/settings.json');
+      } else if (res.status === 'already') {
+        UI.info('framework-edit-gate hook already registered.');
+      } else if (res.status === 'malformed') {
+        UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
+      }
+    } catch (err) {
+      UI.warning(`Hook registration skipped: ${err.message}`);
+    }
+
+    // Routines wizard (since v2.1.0)
+    try {
+      const routinesCmd = require('./routines');
+      await routinesCmd.postUpdateWizard();
+    } catch (err) {
+      UI.warning(`Routines wizard skipped: ${err.message}`);
+    }
+
+    // Project configuration (since v3.0.0)
+    // Skills now resolve project-specific facts from baldart.config.yml
+    // instead of hard-coding paths. Configure prompts for these on install.
+    UI.newline();
+    const runConfigure = await UI.confirm(
+      'Configure project context now (paths, identity, stack, feature flags)?',
+      true
+    );
+    if (runConfigure) {
+      try {
+        const configureCmd = require('./configure');
+        await configureCmd();
+      } catch (err) {
+        UI.warning(`Configure step failed: ${err.message}`);
+        UI.info('Run `npx baldart configure` later to complete setup.');
+      }
+    } else {
+      UI.info('Skipped. Run `npx baldart configure` before invoking skills.');
+    }
+
+    // Success summary
+    UI.header('✓ INSTALLATION COMPLETE');
+
+    UI.box('NEXT STEPS', [
+      '1. Customize pre-commit hook:',
+      '   • Edit .claude/hooks/lint-before-commit.sh.template',
+      '   • Rename to lint-before-commit.sh',
+      '   • Make executable: chmod +x .claude/hooks/lint-before-commit.sh',
+      '',
+      '2. Customize UI guidelines:',
+      '   • Edit docs/references/ui-guidelines.template.md',
+      '   • Define colors, typography, spacing',
+      '',
+      '3. Create backlog cards:',
+      '   • Copy templates/feature-card.template.yml',
+      '   • Use /new command to implement',
+      '',
+      '4. Review scheduled routines:',
+      '   • npx baldart routines list',
+      '   • Install missing ones to drive auto-learning loops',
+      '',
+      '5. Read documentation:',
+      '   • cat AGENTS.md'
+    ]);
+
+    UI.newline();
+    UI.section('Available Commands');
+    UI.list([
+      'baldart version  - Show framework version',
+      'baldart update   - Update framework',
+      'baldart push     - Contribute improvements',
+      'baldart status   - Check installation status'
+    ], 'cyan');
+
+    UI.newline();
+    UI.success('Framework ready to use!');
+
+  } catch (error) {
+    UI.error(`Installation failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = add;