baldart 3.6.2

package/CHANGELOG.md

@@ -0,0 +1,599 @@
+# Changelog
+
+All notable changes to BALDART will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.6.2] - 2026-05-22
+
+BALDART is now published to npm as [`baldart`](https://www.npmjs.com/package/baldart) on every `v*.*.*` tag. End-users can run `npx baldart <cmd>` (without the `-y github:antbald/BALDART` prefix), which resolves through the npm registry and avoids the stale-tarball cache that plagued the GitHub-source installation.
+
+### Added
+
+- **`.github/workflows/publish-npm.yml`** — triggers on `v*.*.*` tag push (and `workflow_dispatch`). Steps: checkout the tagged ref, setup Node 20 with npm registry auth, sync `package.json` version to the `VERSION` file, verify tag matches VERSION (hard fail otherwise), `npm ci`, `npm publish --access public --provenance`. Requires `NPM_TOKEN` repo secret.
+- **`package.json` scripts** — `sync-version` reads `VERSION` and writes it into `package.json`. `prepublishOnly` runs it so manual `npm publish` is also safe.
+- **`package.json` files** — added `VERSION` and `CHANGELOG.md` to the published tarball; removed dangling `LICENSE` reference; removed unused `main` field (this is a CLI package, `bin` is what matters).
+
+### Changed
+
+- **README.md** — primary install/usage examples now use `npx baldart <cmd>` (npm form). The legacy `npx -y github:antbald/BALDART <cmd>` is mentioned as the fallback for unreleased commits on `main`.
+- **CLAUDE.md** — documented the dual distribution model (npm registry + Git subtree for the framework payload) and the workflow's tag-vs-VERSION gate.
+- **MAINTAINING.md** — release checklist now mentions the npm publish trigger and the `npm view baldart version` verification step.
+
+### Why it matters
+
+Before this, `npx -y github:antbald/BALDART` was the only install path, and npx's GitHub-tarball cache regularly served stale CLI code even after `update` to a newer framework version — producing confusing errors like *"Template not found at .framework/templates/baldart.config.template.yml"* that referenced bugs already fixed on `main`. Publishing to the npm registry sidesteps that entire caching layer.
+
+### Operational note
+
+The first tag push to v3.6.2 will fail if `NPM_TOKEN` is not yet configured as a GitHub Actions secret. Generate an **Automation token** on npmjs.com (Settings → Access Tokens → Generate New Token → Automation) and add it as `NPM_TOKEN` under repo Settings → Secrets and variables → Actions.
+
+## [3.6.1] - 2026-05-22
+
+Fix a long-standing path bug: the bulk symlinks (`AGENTS.md`, `agents/`, `.claude/agents/`, `.claude/commands/`), the customizable-template copies (hooks, ui-guidelines, brand-guidelines, backlog templates), and the `baldart.config.template.yml` lookup all referenced `.framework/<sub>` (single `framework/` segment). The Git subtree pull nests the entire BALDART repo under `.framework/`, and the repo itself nests its shippable content under a top-level `framework/` directory — so the real path is `.framework/framework/<sub>`. The bulk symlinks were therefore being created broken (pointed nowhere) and `configure` couldn't find its template, surfacing the misleading *"Run `npx baldart add` first"* error during `update`.
+
+### Fixed
+
+- **`src/utils/symlinks.js`** — introduced `FRAMEWORK_PAYLOAD = .framework/framework` constant. All bulk symlinks (`AGENTS.md`, `agents`, `.claude/agents`, `.claude/commands`), the `copyCustomizableFiles()` source paths (hooks, docs/references, templates copy loop), and the relative-mode symlink callsites now resolve through it. The relative symlink callers no longer mis-prepend `..` (which previously combined with `path.join(cwd, target)` to navigate ABOVE the consumer repo).
+- **`src/commands/configure.js`** — `TEMPLATE_PATH` corrected to `.framework/framework/templates/baldart.config.template.yml`.
+- **`src/commands/update.js`** — schema-drift template lookup corrected to the same path.
+- **`src/commands/doctor.js`** — `loadConfigTemplate()` corrected to the same path.
+
+### Why it matters
+
+Until now, every consumer had **broken** `AGENTS.md`/`agents/`/`.claude/agents/`/`.claude/commands/` symlinks (pointing at paths that don't exist) — Claude Code silently saw "no shared agents/commands" and used only what the user had authored locally. Same story for `configure`: it could never find its template, so it bailed and the user's `baldart.config.yml` was never generated automatically during `update`. After v3.6.1, on the next `npx baldart update` the symlinks get re-created with the correct `.framework/framework/` target and `configure` runs end-to-end.
+
+## [3.6.0] - 2026-05-22
+
+`npx baldart update` now handles a dirty consumer worktree gracefully instead of crashing with `fatal: working tree has modifications. Cannot add.` from `git subtree pull`. Before the subtree pull runs, the CLI detects uncommitted changes, lists them, and offers to auto-stash + re-apply automatically after the update.
+
+### Added
+
+- **`src/commands/update.js` pre-flight check** — after the user confirms "Proceed with update?", if the working tree is dirty: the CLI lists the dirty paths and asks "Auto-stash now and re-apply after the update (recommended) / Abort". Stash is labelled `baldart-pre-update-<ISO timestamp>` for traceability.
+- **Auto-pop after success** — on a successful subtree pull the stash is popped. If the pop conflicts with the framework update, the stash is left intact and the user gets a `STASH CONFLICT` box with recovery commands (`git stash list`, `git stash pop`).
+- **Auto-restore on failure** — if the subtree pull itself fails after stashing, the stash is restored automatically so the user's pre-update changes never appear lost.
+
+### Why it matters
+
+Combined with the v3.5.0 post-update auto-commit, the full update flow now keeps the worktree clean on entry AND on exit, without ever silently dropping the user's work-in-progress.
+
+## [3.5.1] - 2026-05-22
+
+Fix `npx baldart update` crashing with `EEXIST: file already exists, symlink …` when the bulk symlinks (`AGENTS.md`, `agents`, `.claude/agents`, `.claude/commands`) were broken (target sparito dopo un cleanup o move). `fs.existsSync` segue il symlink e tornava `false` per i broken link → il ramo di cleanup veniva saltato → `fs.symlinkSync` falliva creando il nuovo link sopra quello rotto.
+
+### Fixed
+
+- **`src/utils/symlinks.js` `createSymlink()`** — switched from `fs.existsSync` to `fs.lstatSync` (with try/catch) to detect broken symlinks and treat them as "existing symlink to wrong target" → unlink + recreate.
+- **`src/utils/symlinks.js` `verifySymlinks()`** — same fix on the diagnostic path, so broken bulk symlinks are now reported as `Broken symlink: <link> → <target>` instead of being misclassified as `Missing`.
+
+## [3.5.0] - 2026-05-22
+
+`npx baldart update` now offers to commit the post-update reconcile (symlinks, hook registration, state.json, routine adapters, etc.) in a single dedicated commit, so the consumer's worktree stays clean and there is a clear revert point per upgrade.
+
+### Added
+
+- **`src/commands/update.js` `postUpdateAutoCommit()`** — runs after all post-update reconcile steps. Scans `git status`, filters to a BALDART-managed allowlist (`.framework/`, `AGENTS.md`, `agents`, `.claude/{agents,commands,skills,hooks,routines,settings.json}`, `.baldart/`, `baldart.config.yml`, `docs/references/{ui-guidelines.template,brand-guidelines}.md`, `templates/`, `.github/workflows/baldart-*`, `scripts/routines/`), shows a preview and asks before committing as `chore(baldart): post-update reconcile to vX.Y.Z`. User-owned dirty paths are never staged.
+- **`bin/baldart.js` `--no-commit` flag on `update`** — skips the prompt entirely for CI/scripted runs.
+
+### Why it matters
+
+Before v3.5.0 every `update` left a dirty worktree (the subtree-pull commit only covers `.framework/`; symlink reconcile + hook + state writes happen outside it). Consumers either had to `git status` and craft a commit by hand or live with a noisy `git status`. The new flow keeps the post-update side effects bundled in one self-describing commit you can `git revert` if anything goes wrong.
+
+## [3.4.1] - 2026-05-22
+
+Fix `npx baldart update` crashing with `ReferenceError: newVersion is not defined` after a successful framework update. The update completed correctly but the final "WHAT CHANGED" summary referenced an out-of-scope `const`, surfacing the error through the outer catch and exiting non-zero — confusing the user and breaking CI signal.
+
+### Fixed
+
+- **`src/commands/update.js`** — hoisted `newVersion` declaration above the inner try/catch (`let newVersion;`) so the "WHAT CHANGED" box can read it. The `const` lived inside the inner try block (lines 105–138) and was unreachable from the success summary below it.
+
+## [3.4.0] - 2026-05-22
+
+Worktree manager now respects terminal isolation. The `/mw` skill no longer runs `git checkout develop` on the main repo (which is a shared resource across parallel terminals in worktree-driven projects). Same for `/nw` pre-flight. Reported from a production failure in the `mayo` consumer where CLAUDE.md declares terminal-isolation as an absolute rule and Claude Code's classifier preemptively blocked the checkout.
+
+### Changed
+
+- **`framework/.claude/skills/worktree-manager/SKILL.md` `/mw` step 4c** — replaced local-checkout merge (`git checkout develop && git pull --ff-only && git merge && git push`) with remote merge via GitHub PR (`gh pr create` + `gh pr merge --merge --delete-branch`). The main repo's `HEAD` is never touched. Local `develop` is synced via `git -C <main> pull --ff-only` ONLY when the main repo HEAD is already `develop`; otherwise we just fetch and leave the user's working state alone.
+- **`/mw` step 4c fallback** — if `gh pr merge` CLI fails (typically on the local-branch cleanup when `develop` is checked out in another worktree), fall back to the REST API (`gh api -X PUT repos/:owner/:repo/pulls/:n/merge`). Hard-fails (no local-checkout fallback) — the user installs `gh` and re-runs.
+- **`/nw` pre-flight (step 1) + step 3** — no longer runs `git checkout develop` on the main repo. Pre-flight is now `git fetch origin develop` (read-only); worktrees branch from `origin/develop` directly.
+- **`/mw` Programmatic API output** — now returns `prNumber` alongside `mergeCommit`.
+- **Safety Rules** in worktree-manager SKILL.md — added explicit `NEVER git checkout/switch/branch on main repo` rule with rationale (terminal isolation, classifier pre-blocking).
+- **`framework/.claude/skills/new/SKILL.md` Phase 6 description + Fail-safe rules** — aligned to the new flow.
+
+### Why it matters
+
+Many consumer projects declare a "shared main repo" / terminal-isolation rule in their CLAUDE.md. The classifier in Claude Code pattern-matches the rule text (not the runtime state) and preemptively denies `git checkout develop` on the main repo. The legacy flow therefore failed silently in those projects, and the `/new` orchestrator could not close the merge loop — the user had to merge by hand. With v3.4.0 the merge happens entirely server-side via the GitHub API and the main repo is never touched.
+
+### Note for consumers
+
+`gh` CLI must be installed and authenticated (`gh auth login`). If it isn't, `/mw` STOPs and asks the user to install it — it does NOT fall back to the legacy local-checkout flow.
+
+## [3.3.0] - 2026-05-21
+
+Real-time contamination gate. A Claude Code `PreToolUse` hook now intercepts every `Edit`/`Write`/`MultiEdit` whose target resolves (via symlink) to a path inside `.framework/`, runs the contamination scanner on the new content, and blocks the call with an informative reason if project-specific tokens are detected. Auto-registered in every consumer at install time.
+
+### Added
+
+- **`framework/.claude/hooks/framework-edit-gate.js`** — Claude Code `PreToolUse` hook (Node, cross-platform, fail-safe). Reads tool input from stdin, resolves the real path with `fs.realpathSync` (follows symlinks), and checks if it lands inside `.framework/`. If so, scans the new content via the existing contamination utility and returns `permissionDecision: "deny"` with a structured reason walking the user through three resolution paths: (A) reformulate generically using `${paths.X}`/`identity.X`/`stack.X`, (B) move to `.baldart/overlays/<skill>.md`, (C) declare the file opt-out with the contamination-scan marker.
+- **`src/utils/hooks.js`** — registration utility. `register()` / `unregister()` / `isRegistered()` operate on `.claude/settings.json` with idempotent JSON merge (preserves user-authored hooks). The registered entry carries a stable `id: "baldart-framework-edit-gate"` for future detection.
+- **Auto-registration**:
+  - `baldart add` registers the hook after symlinks are created (creates `.claude/settings.json` if absent, merges otherwise).
+  - `baldart update` re-registers (idempotent) — backfills consumers installed before v3.3.0.
+  - `baldart doctor` detects missing registration and proposes "Register framework-edit-gate hook" as a remediation action.
+- **`baldart doctor` status line**: new "Edit gate" row in the diagnostic table showing registered vs not-registered.
+
+### How it works
+
+A typical flow now looks like this. Claude is editing a skill in fidelity-app:
+
+```
+Claude → Edit .claude/skills/ui-design/SKILL.md (new_string contains "Neo-Brutalism")
+       ↓
+       framework-edit-gate.js fires (PreToolUse)
+       ↓
+       Resolves symlink → /…/.framework/framework/.claude/skills/ui-design/SKILL.md
+       ↓
+       Detects ".framework/" segment → triggers
+       ↓
+       Runs contamination.scan() on new_string → finds "Neo-Brutalism"
+       ↓
+       Returns permissionDecision: "deny" with structured reason
+       ↓
+Claude reads the reason, moves the rule to .baldart/overlays/ui-design.md instead.
+```
+
+The hook is fail-safe: any internal error (missing scanner, parse error, IO error) exits 0 and lets the tool call through. The scanner is a safety net, not a tribunal.
+
+### Disabling
+
+If the gate gets in the way for a specific session, remove the entry from `.claude/settings.json` under `hooks.PreToolUse[]` (look for `id: "baldart-framework-edit-gate"`). `baldart doctor` will detect the absence and offer to re-register on next run.
+
+For per-file legitimate exceptions (docs that legitimately quote canonical paths as illustrative examples), add the existing opt-out marker:
+
+```markdown
+<!-- contamination-scan: skip -->
+```
+
+or in YAML frontmatter:
+
+```yaml
+contamination_scan: skip
+```
+
+## [3.2.0] - 2026-05-21
+
+Single smart entry point. `npx baldart` with no arguments now runs a doctor that diagnoses the install and proposes the next sensible action.
+
+### Added
+
+- **`baldart doctor` command** + **no-argument shortcut**. Detects (in priority order): not-a-git-repo, framework absent, legacy v2.0.x bulk-skills layout, malformed config, missing config, config schema drift, remote ahead, local framework changes, overlay version drift. Renders a status table, then proposes the matching action(s) and runs each with confirmation. Acts as the new informational default — `npx baldart` no longer prints commander help, it prints a diagnostic.
+- **`--auto` flag**: skips yes/no confirmations for CI; errors out with exit 2 if multiple actions are proposed (avoids guessing in ambiguous states). Pairs cleanly with `--offline` for fully sandboxed runs.
+- **`--offline` flag**: skips the upstream fetch (no remote drift detection).
+- Both flags work without typing `doctor`: `npx baldart --auto --offline` is equivalent to `npx baldart doctor --auto --offline`.
+
+### Changed
+
+- `npx baldart` with no arguments previously dumped the commander help. It now runs the doctor flow instead. The help is still accessible via `npx baldart --help` or `npx baldart <subcommand> --help`.
+
+## [3.1.0] - 2026-05-21
+
+Contribution flow upgrade. Centralized framework versioning via `.baldart/state.json`. New `/baldart-push` skill orchestrates safe upstream contributions with automatic contamination autofix, version bump, CHANGELOG generation, and tag push.
+
+### Added
+
+- **`/baldart-push` skill** (`framework/.claude/skills/baldart-push/`) + slash command (`framework/.claude/commands/baldart-push.md`). Conversational orchestration of the contribution flow with hard rules: no secrets, no overlay/config push, always show current version first.
+- **`src/utils/contamination.js`** — scanner + autofix library. Catalogues every fidelity-app-specific token pattern that v3.0.0 cleaned up. Three severities: `autofixable` (safe substitutions like `docs/design-system/` → `${paths.design_system}/`), `requires-decision` (identity/stack tokens — user reviews per file), `block` (secrets — hard fail).
+- **`src/utils/state.js`** — `.baldart/state.json` read/write. Centralized versioning state: installed_version, install_date, last_update_date, last_pushed_version, last_push_date, rolling history of the last 20 events. Updated automatically by `add`/`update`/`push`.
+- **`baldart version`** command rewritten — now shows installed version + install date, remote drift (ahead/behind), local uncommitted-files count, last-push info, CLI version. New `--offline` flag to skip the upstream fetch.
+- **`baldart push`** command rewritten — auto-pull when behind, file triage, new-skill discovery, contamination scan with per-file decisions, auto VERSION bump, auto-generated CHANGELOG entry (Added/Changed/Removed grouped from diff), annotated tag push, state.json update. Replaces the previous "next steps required" manual workflow.
+- **Triage rules**: hooks customizations (`.claude/hooks/*.sh` non-template) are blocked from push automatically; overlay starter examples (`framework/templates/overlays/*`) are exempted from contamination scan.
+
+### Changed
+
+- `src/commands/add.js`, `src/commands/update.js` now record events into `.baldart/state.json` after successful operations.
+- The push flow now exits with `Description is required.` when the user provides empty description (was previously a silent failure mode).
+- `AGENTS.md` `§ 4 Non-negotiables (MUST)` split into **4.a Universal MUST** (apply everywhere) and **4.b Workflow MUST** (gated by `features.has_backlog` / `features.has_adrs` / existence of `project-status.md` / overlay-declared conventions). Pre-v3 absolute MUST rules around backlog / ADRs / GitHub issue labels / `git_strategy` are now correctly feature-gated. Duplicate ADR completeness MUST removed.
+- `framework/agents/project-context.md` § 6 autodetection table rewritten as the source of truth, listing all 20 probes that `configure.js detect()` actually runs.
+- README "Migrating an Existing Install" rewritten as `v1.x / v2.x → v3.x` (was v2.1.1 framing), with explicit `npx baldart configure` step and links to `PROJECT-CONFIGURATION.md` § 9.
+- README duplicate `push` command section removed; Quick Start now lists `configure`.
+- `MAINTAINING.md` prefaced with v3.1.0+ automated flow TL;DR (the CLI now does steps that used to be manual: VERSION bump, CHANGELOG entry, tag).
+
+### Fixed
+
+- `src/commands/push.js` "skip file" branch now distinguishes status `A` (newly added — `git rm -f`) from `M`/`R`/`D` (existing upstream — `git checkout origin/main`). Previously the `checkout` failed silently on newly-added files and they were pushed despite the user's skip decision.
+- `src/commands/push.js` autofix commit now stages only the files autofix actually modified (was sweeping all pushable files, capturing unrelated edits).
+- `src/commands/push.js` partial failure surfaces a rollback SHA snapshot (`git reset --hard <preFlightSHA>`) so the user can undo chore commits cleanly.
+- `src/commands/push.js` path comparisons normalized to forward slashes — fixes Windows where `simple-git` returns `/` but `path.join` produces `\`, so `CHANGELOG.md` and `VERSION` previously fell into the `pushable` bucket and were double-committed.
+- `src/commands/push.js` `buildChangelogEntry` strips the `.framework/` mount-point prefix from path entries (was `.framework/framework/.claude/skills/foo/SKILL.md`; now `framework/.claude/skills/foo/SKILL.md`).
+- `src/commands/configure.js` `mergePreserving` preserves deliberate empty-string user values (was overwriting them with detected defaults).
+- `src/utils/contamination.js` `stack-recharts` rule case-insensitive (was missing lowercase `import 'recharts'`).
+- `src/utils/contamination.js` `secret-api-key` rule catches unquoted assignments (`API_KEY=abc123...` in `.env` files).
+- `src/utils/contamination.js` added secret patterns: GitHub PATs (`ghp_`/`ghs_`/`ghu_`/`gho_`), Slack tokens (`xox[baprs]-`), JWTs.
+
+## [3.0.0] - 2026-05-21
+
+This is a MAJOR release. Skills no longer hard-code paths, brand identity, or technology stack choices — they read them from `baldart.config.yml` and project-specific overlays. The same skills now work across projects with different design systems, audiences, and stacks.
+
+### Added
+
+- **Project context system** (3 layers):
+  - `baldart.config.yml` at repo root — schema versioned, populated by the new `npx baldart configure` command. Defines `paths.*`, `identity.*`, `stack.*`, `features.*` for the project.
+  - `.baldart/overlays/<skill>.md` — consumer-authored per-skill extensions with `base_skill_version` frontmatter for drift detection. Sections marked `## [OVERRIDE] <topic>` replace base skill sections.
+  - `framework/agents/project-context.md` — protocol module loaded as MANDATORY pre-read for any skill that touches project-specific facts.
+- **`npx baldart configure` command** — interactive prompts + filesystem autodetection (probes for design-system index, components dirs, backlog, ADRs, wiki overlay, package.json dependencies for charting/animation/E2E framework). Idempotent: re-running merges without clobbering user values. Available as `--non-interactive` for CI.
+- **Project context header convention** — every refactored skill now declares its config dependencies in a dense 4-line header citing `framework/agents/project-context.md` for the protocol.
+- **Overlay starter templates** under `framework/templates/overlays/`:
+  - `ui-design.fidelity-example.md` — Neo-Brutalism, Recharts/nivo stack, merchant theming, Safari open command, evaluation thresholds.
+  - `copywriting.fidelity-example.md` — 4-pillar brand voice, Italian-only rule, audience register matrix, forbidden vocabulary.
+- **`framework/docs/PROJECT-CONFIGURATION.md`** — comprehensive guide for consumers: schema reference, overlay system, per-skill behaviour when keys are missing, ground-up examples, v2→v3 migration cheat sheet, FAQ.
+- **Status command extensions** — reports `baldart.config.yml` presence + schema version, lists authored overlays with version-drift warnings.
+- **Update command extensions** — never overwrites `baldart.config.yml`; warns when new framework version adds config keys not yet in the consumer's file (suggests re-running configure).
+
+### Changed (BREAKING)
+
+- **Skills no longer assume the fidelity-app shape**. Sixteen skills with significant hard-coded paths or identity tokens were refactored to resolve them from `baldart.config.yml`; the remaining skills (`api-design-principles`, `remotion-best-practices`, `seo-audit`, `skill-creator`, `worktree-manager`, `find-skills`) had no significant project-leaks and were left untouched. The refactored skills:
+  - `ui-design`, `ui-design/references/*` — design-system reads, charting stack, identity-driven aesthetic
+  - `copywriting` — brand voice pillars now overlay-driven
+  - `prd`, `prd-add`, `prd/references/*`, `prd/assets/*` — backlog/PRD/references paths, design-system gating
+  - `new` — backlog and references paths, validation tooling generalized
+  - `bug`, `bug/references/logging-patterns.md` — project-specific debug entry points moved to overlay
+  - `kie-ai` — design-system reads gated by `features.has_design_system`
+  - `motion-design` — illustration-motion path resolved from config
+  - `capture` — wiki overlay path from `paths.wiki_dir`, domain vocabulary from overlay
+  - `context-primer` — backlog/references/wiki paths from config; feature-gated probing
+  - `playwright-skill`, `webapp-testing` — design-system reads gated, theming pairing from overlay
+  - `gamification-design` — design system + audience segment from config, customer surface guidance overlay-driven
+  - `doc-writing-for-rag` — schemas/errors paths from config, examples marked as illustrative
+  - `frontend-design`, `simplify` — design-system reads gated by `features.has_design_system`
+- **Skills refuse to run when their gating feature is `false`**. E.g. `/new` requires `features.has_backlog: true`, `/prd` requires `features.has_prd_workflow: true`, `/capture` requires `features.has_wiki_overlay: true`. This replaces silent degradation with explicit refusal + suggestion to enable the feature in config.
+- **Always-ask on missing keys**. When a skill encounters a required path that is `""`, or a `features.*` flag absent from the YAML, it prompts the user and suggests persisting the answer via `npx baldart configure`. Never defaults to `false` from absence.
+- **`templates/` install excludes framework-internal templates**. `baldart.config.template.yml`, `skill-project-context.snippet.md`, and the `overlays/` example directory live in `.framework/templates/` only — they are consumed by CLI commands and references, not copied to the user's `templates/`.
+
+### Migration from 2.x
+
+`npx baldart update` warns if `baldart.config.yml` is missing and offers to run configure. Existing v2.x installs need:
+
+1. `npx baldart update` (pulls v3.0.0).
+2. `npx baldart configure` (interactive — autodetects ~80% of values from typical fidelity-app layouts).
+3. For projects that relied on the pre-v3 hard-coded opinions (Neo-Brutalism, merchant/customer, Recharts-only): copy the matching `*.fidelity-example.md` from `.framework/templates/overlays/` into `.baldart/overlays/` and adapt.
+4. `npx baldart status` — verify config + overlays.
+5. Commit `baldart.config.yml` and `.baldart/overlays/`.
+
+Full migration guide: `.framework/docs/PROJECT-CONFIGURATION.md` § 9.
+
+## [1.0.0] - 2026-02-13
+
+### Added
+- Complete npm package implementation with CLI
+- 5 commands: add, update, push, version, status
+- Interactive prompts with colored terminal output
+- Git subtree bidirectional sync (pull updates + push improvements)
+- Professional utility classes (git, ui, symlinks)
+- Comprehensive README with npm/npx usage
+- 9 generic AI agents (codebase-architect, coder, code-reviewer, doc-reviewer, prd, plan-auditor, senior-researcher, api-perf-cost-auditor)
+- 17 domain modules (architecture, workflows, testing, security, etc.)
+- 3 commands (/new, /design-review, /issue-review)
+- Templates (feature-card, spec, breaking-change-checklist, ui-guidelines, brand-guidelines)
+- Symlink-based auto-update mechanism
+- Customizable files (hooks, UI guidelines, templates)
+
+### Changed
+- **BREAKING**: Replaced bash scripts with npm package
+- **BREAKING**: Installation now via `npx baldart add` instead of bash script
+- **BREAKING**: All commands now use `npx baldart <command>` syntax
+- **BREAKING**: Framework files moved to `framework/` subdirectory
+
+### Removed
+- install-framework.sh (replaced by src/commands/add.js)
+- update-framework.sh (replaced by src/commands/update.js)
+- push-improvements.sh (replaced by src/commands/push.js)
+
+## [1.1.0] - 2026-02-27
+
+### Added
+- 12 new specialized agents: hybrid-ml-architect, hyper-gamification-designer, legal-counsel-gdpr, marketing-conversion-strategist, motion-expert, onboarding-architect-lead, qa-sentinel, remotion-animator-orchestrator, seo-analytics-strategist, ui-expert, visual-designer, website-orchestrator
+- `/qa` command: Standardized QA workflow with 3 profiles (Light, Balanced, Deep)
+- `/check` command: Pre-development parallel quality audits on backlog cards using agent teams
+- QA Protocol in REGISTRY.md with profile selection guide and self-healing loop
+- Batch tracking protocol in `/new` command for parallel session safety
+- Context recovery protocol in `/new` for resilience after context compaction
+- Phase 3.5 (QA Validation) in `/new` pipeline with automatic profile selection
+- Phase 7 (Production Readiness Checklist) in `/new` pipeline
+- Branching Strategy section in AGENTS.md (Simplified Git Flow with develop branch)
+- Execution Modes section in AGENTS.md (local/cloud/hotfix)
+- Pre-commit vs Pre-PR build check separation in AGENTS.md
+- Macro Feature Identification Protocol in doc-reviewer
+- Single Source of Truth (SSOT) Protocol in doc-reviewer
+- Post-Development Doc Debt tracking in doc-reviewer
+- Multi-phase review with risk matrix in plan-auditor
+- PRD Review & Confirmation phase (Phase 2.1) with [TO CONFIRM] markers in prd
+- API Performance & Cost Audit phase (Phase 2.5) in prd
+- Autonomous technical decisions (Phase 1A) in prd — agent decides tech, asks user only product questions
+- Parent/child card structure with epic support in prd
+- Bug card template with mandatory clarity analysis in prd
+
+### Changed
+- **REGISTRY.md**: Expanded from 9 to 21 agents with compact table format, decision tree, and QA Protocol section
+- **doc-reviewer**: Major rewrite — now fully responsible for documentation (audit + write), with SSOT sync and doc debt tracking
+- **plan-auditor**: Enhanced with 4 expert personas (Staff Engineer, Tech Lead, Security Engineer, SRE), anti-patterns checklist, and pre-mortem scenario
+- **prd**: Major expansion — one-question-at-a-time discovery, gamification validation for B2C, performance audit integration, detailed card templates
+- **senior-researcher**: Improved with AI-readable output format (retrieval index, evidence map, structured reading notes)
+- **code-reviewer**: Added structured output format (Critical/Major/Minor/Recommendations), review checklist, and Linked Skills pattern
+- **coder**: Added explicit build/test/lint gates, task scoping guidelines, and Linked Skills pattern
+- **api-perf-cost-auditor**: Added project context integration section and Linked Skills pattern
+- **new.md**: Added worktree grouping, QA validation phase, production readiness checklist, and context recovery
+- **AGENTS.md**: Added branching strategy, execution modes, testing gates separation, commit hygiene rules
+
+## [2.1.1] - 2026-05-18
+
+Critical migration-safety fix. v2.0.0 / v2.1.0 introduced a bulk symlink for
+`.claude/skills/` that — on existing installations — silently renamed the
+user's personal skills directory to `.claude/skills.backup` and replaced it
+with the framework symlink. This release fixes the merge strategy and ships
+a migration command for repos already affected.
+
+### Added
+
+- **`npx baldart migrate` command** — idempotent recovery for repos that ran
+  v2.0.0 / v2.1.0 update with the old bulk-symlink strategy:
+  - Detects legacy `.claude/skills` bulk symlink and converts it to a real
+    directory.
+  - Re-merges framework skills as per-item symlinks alongside user skills.
+  - Restores `.claude/skills.backup/*` user skills into `.claude/skills/`
+    (skipping name collisions, which stay in `.backup/` for manual review).
+  - Removes empty `.backup/` directory at the end.
+  - Records remaining collisions in `.baldart/skill-conflicts.json`.
+- **Per-skill merge strategy** in `symlinks.js`:
+  - `.claude/skills/` is now a **real directory the user owns**.
+  - Each framework skill is symlinked individually:
+    `.claude/skills/<name> → ../../.framework/framework/.claude/skills/<name>`.
+  - User-authored skills coexist in the same directory and are NEVER
+    overwritten or backed up by the framework.
+  - Name collisions are logged to `.baldart/skill-conflicts.json` with
+    enough context for the user to resolve them.
+- **`createSymlink` modes** in `symlinks.js`:
+  - `safe`: refuses to overwrite a user-customised file/dir (used on fresh
+    installs).
+  - `prompt` (default): asks before backing up a customised file/dir.
+  - `force`: legacy v2.0.x behaviour (no longer used by default).
+
+### Changed
+
+- `npx baldart add` now runs symlink creation in `safe` mode — first-time
+  installs never silently rename user customisations.
+- `npx baldart update` no longer issues a generic "Recreate broken symlinks?"
+  prompt that triggered the destructive path. Instead it explains exactly
+  what will happen (per-item merge, no overwrites without confirmation) and
+  prompts in `prompt` mode.
+- `verifySymlinks()` now spot-checks `.claude/skills/` for the per-item
+  layout and reports a clear actionable warning when the legacy bulk
+  symlink is detected (`Run npx baldart update or npx baldart migrate`).
+- `createAllSymlinks(opts)` is now `async` because some bulk-symlink
+  reconciliations may ask the user for confirmation. All callers updated.
+
+### Fixed
+
+- **Destructive update path on existing repos**: v2.0.0 / v2.1.0
+  `npx baldart update` could rename `.claude/skills/` to `.claude/skills.backup`
+  on existing installs without explicit user consent. The new merge strategy
+  never touches user-owned content under `.claude/skills/`.
+
+### Migration (v1.x / v2.0.x / v2.1.0 → v2.1.1)
+
+After updating BALDART:
+
+```bash
+npx baldart update     # pulls v2.1.1 framework
+npx baldart migrate    # one-shot: converts skills layout, restores .backup
+npx baldart status     # confirm
+```
+
+`migrate` is idempotent — safe to re-run.
+
+---
+
+## [2.1.0] - 2026-05-18
+
+Minor release that closes the gap left by v2.0.0: the framework now ships the
+**scheduled routines** that make agents like `wiki-curator` and `skill-improver`
+actually run on a cadence. Without these schedules the auto-learning loops are
+dormant, so every BALDART install is now prompted to configure them.
+
+### Added
+
+- **`framework/routines/` directory** with 6 declarative routine specs:
+  - `wiki-review` — nightly @ 02:00 UTC — drives the LLM-wiki auto-learning loop
+  - `doc-review` — nightly @ 00:00 UTC — audits doc changes, flags SSOT drift
+  - `code-review` — nightly @ 01:00 UTC — reviews last-24h commits
+  - `skill-improve` — weekly Sunday @ 02:00 UTC — refines skills/agents
+  - `ds-drift` — weekly Monday @ 03:00 UTC — design-system drift check (optional)
+  - `full-sweep` — weekly Sunday @ 03:00 UTC — full SSOT audit (optional)
+- **3 backend adapters** (`src/utils/routine-adapters/`):
+  - `claude-code-cloud` — generates `.claude/routines/<name>.json` for RemoteTrigger
+  - `github-actions` — generates `.github/workflows/baldart-<name>.yml`
+  - `cron` — generates `scripts/routines/<name>.sh` + prints crontab line
+- **`npx baldart routines` command** with 4 subcommands:
+  - `list` — shows status for every routine (installed / available / blocked /
+    skipped / disabled / unavailable)
+  - `install <name>` — interactive install with backend picker
+  - `disable <name>` — removes the schedule artifact and updates the lock
+  - `doctor` — verifies installed routines still have their artifacts present
+- **Post-install / post-update wizard** — `npx baldart add` and
+  `npx baldart update` now surface newly-available routines and offer to
+  configure them right after a successful install/update. Skipped routines
+  are remembered in `.baldart/routines.lock.json` and not re-prompted.
+- **`.baldart/routines.lock.json`** — durable record of which routines are
+  installed, their backend, since-version, and per-routine status.
+
+### Changed
+
+- `npx baldart add` next-steps box now includes a "Review scheduled routines"
+  step pointing to `npx baldart routines list`.
+- `npx baldart update` "what changed" box now includes a routines review
+  pointer.
+- Added `js-yaml@^4.1.0` as a runtime dependency for parsing routine specs.
+
+### Notes
+
+- Routines are **opt-in per backend**: BALDART never installs schedules
+  silently. The user picks the backend and reviews the generated artifact
+  before committing.
+- The wizard skips routines whose `required_artifacts` are missing (e.g.
+  `wiki-review` is blocked until `docs/wiki/` exists). Run `npx baldart
+  routines install <name>` later once the artifact lands.
+- The CLI is non-interactive when stdin is not a TTY — safe to run in CI
+  contexts (the wizard simply exits).
+
+---
+
+## [2.0.0] - 2026-05-18
+
+Major release distilled from ~3 months of intensive use of v1.1.0 inside a real
+multi-merchant fidelity/loyalty platform. Introduces the **Skills** category, a
+new **LLM Wiki Overlay methodology**, the `/codexreview` deep multi-agent code
+review command, and a substantial rewrite of every core agent.
+
+### Added
+
+- **Skills category (new)**: `framework/.claude/skills/` directory with 22
+  generic, portable skills shipped out-of-the-box:
+  - Workflow skills: `new`, `prd`, `prd-add`, `bug`, `simplify`,
+    `worktree-manager`, `issue-review`, `context-primer`
+  - Code-quality skills: `skill-creator`, `find-skills`,
+    `webapp-testing`, `playwright-skill`
+  - Design skills: `frontend-design`, `ui-design`, `motion-design`,
+    `gamification-design`
+  - Product skills: `seo-audit`, `copywriting`, `api-design-principles`
+  - Knowledge skills: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
+  - Integration: `kie-ai`, `remotion-best-practices`
+- **5 new agents**:
+  - `security-reviewer` — dedicated AppSec auditor for auth/secrets/multi-tenant/infra
+  - `deep-human-insight` — psychological / sociological analysis for B2C UX
+  - `email-deliverability-architect` — transactional email design + deliverability
+  - `skill-improver` — weekly auto-improvement of skills/agents based on review/QA findings
+  - `prd-card-writer` — atomic backlog-card generation from approved PRDs
+  - `wiki-curator` — derived LLM wiki overlay maintenance (re-introduced and generalized)
+- **`/codexreview` command** — deep multi-agent code review with mandatory
+  false-positive validation. Pools findings from `code-reviewer`,
+  `security-reviewer`, `api-perf-cost-auditor`, `doc-reviewer`, and
+  `plan-auditor` into a single ranked report with dedup and risk weighting.
+- **`agents/llm-wiki-methodology.md`** — full methodology for building a
+  derived LLM wiki overlay: layered knowledge stack, page types, frontmatter
+  discipline, auto-learning loop (RAG telemetry → synthesis candidates →
+  `/capture` skill → new wiki pages), adoption checklist.
+- **Post-Approval Complexity Gate** (in `coder.md`) — explicit isolation-mode
+  decision (heavy/light worktree) made by the orchestrator before spawning
+  the coder, eliminating ambiguity about who owns branch creation.
+- **High-Risk Path Code Review trigger table** (in `plan-auditor.md`) — five
+  generic triggers that force a per-card `/codexreview` BEFORE merge.
+- **Specialist Auto-Spawn matrix** (in `plan-auditor.md`) — auto-routes plans
+  to specialist auditors (security, api-perf, ui, ml, docs) based on domain
+  signals.
+- **NFR enforcement framework** in `code-reviewer.md` and `new` skill —
+  generic performance / security / accessibility MUST rules with a project-
+  adaptable anti-pattern list (the "Never demote" cluster).
+- **Findings Schema** — single YAML emit shape across all reviewing agents so
+  `/codexreview` can pool and rank findings.
+- **YOLO MODE protocol** — explicit instruction that all Task-spawned
+  subagents must use `mode: "bypassPermissions"`.
+
+### Changed
+
+- **All 9 core agents heavily rewritten** based on 3 months of production use
+  in a real project:
+  - `plan-auditor.md` (+22 KB): 4 expert personas (Staff Eng / Tech Lead /
+    Security / SRE), High-Risk Path triggers, Specialist Auto-Spawn matrix,
+    multi-phase review with risk matrix, anti-patterns checklist, pre-mortem.
+  - `coder.md` (+17.6 KB): explicit build/test/lint gates, design-system
+    SSOT read protocol, conditional binary-outcome items, reuse analysis,
+    branch/worktree safety check, completion-report schema, Linked Skills.
+  - `codebase-architect.md` (+15.3 KB): Linking Protocol v1 for canonical-
+    source resolution, design-system resolution path, agent memory, retrieval
+    protocol consumption.
+  - `code-reviewer.md` (+14.3 KB): confidence-based filtering (HIGH/MED/LOW),
+    "Never demote" anti-pattern cluster, Findings Schema emission, design-
+    system compliance section, scope boundary discipline.
+  - `doc-reviewer.md` (+10.6 KB): design-system scope (when project has one),
+    SCIP-symbol code refs, drift validator suite integration.
+  - `api-perf-cost-auditor.md` (+9.2 KB): project context integration, agent
+    memory, Findings Schema, retrieval protocol consumption.
+  - `qa-sentinel.md` (+6.5 KB): clear gate-runner mandate (no AC checks, no
+    code analysis), command output management, operating modes
+    (Quick / Full / Deep), documentation coverage check.
+  - `senior-researcher.md` (+2.7 KB): retrieval-optimized report format,
+    structured reading notes, agent memory.
+  - `REGISTRY.md` (+5.4 KB): expanded to 24 agents, Model Selection Matrix,
+    QA Protocol, Domain Ownership map, doc-writing responsibility split.
+- **REGISTRY.md** is the **single source of truth** for agent invocation
+  routing. `agents/index.md` defers to it.
+- **`coder` vs `doc-reviewer` responsibility split** — `coder` writes only
+  minimal invariant doc stubs (API index, UI route, collection entry, env
+  var, dependency, SSOT registry); `doc-reviewer` owns full doc writing,
+  SSOT sync, and drift resolution.
+- **Pre-commit vs Pre-PR build separation** (clarified in AGENTS.md): lint +
+  typecheck + markdownlint at every commit; full `npm run build` and test
+  suite only before opening a PR. This matches multi-hour build realities
+  in larger projects.
+
+### Removed
+
+- **`obsidian-sync` agent** removed from the core framework. Mirroring docs to
+  an external corpus (Obsidian / Notion / Confluence) is **project-specific**
+  and should ship as a project-local agent. The `wiki-curator` agent still
+  mentions external-vault sync as an optional coordination step.
+- **Standalone `/qa` command file**. QA functionality remains available via
+  the `qa-sentinel` agent and the `/new` skill's Phase 3.5; invocation
+  patterns documented in REGISTRY.md § QA Protocol.
+
+### Migration Guide (v1.1.0 → v2.0.0)
+
+- Run `npx baldart update` from your project root. The framework files in
+  `.framework/` are auto-updated via git subtree.
+- The new `.claude/skills/` directory will land in your project after the
+  update. Existing skills you authored locally are not touched.
+- If you relied on the old `obsidian-sync` agent, move it to your project's
+  `.claude/agents/` (it's a project-specific concern). Update any references
+  in `AGENTS.md` to make the dependency explicit.
+- The new `wiki-curator` agent expects a `docs/wiki/` directory and a
+  frontmatter validator. See `framework/agents/llm-wiki-methodology.md` for
+  the adoption checklist; the agent degrades gracefully if you don't ship a
+  RAG layer.
+- Calls to `Task tool` spawning subagents must now pass
+  `mode: "bypassPermissions"` (the YOLO MODE protocol). Without this flag the
+  subagent will pause for permission prompts and break the orchestration.
+
+---
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+---
+
+## Version Format
+
+**MAJOR.MINOR.PATCH**
+
+- **MAJOR**: Breaking changes (incompatible API updates, directory structure changes, removed features)
+- **MINOR**: New features (backwards compatible additions)
+- **PATCH**: Bug fixes (backwards compatible fixes)
+
+## Change Categories
+
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Security fixes