baldart 4.82.0 → 4.84.0

package/framework/templates/primitives/CLAUDE.md

@@ -0,0 +1,41 @@
+<!-- baldart-primitive: name=CLAUDE primitive_version=1.0.0
+     SHIPPED SKELETON. The writer strips this banner, resolves {{ slot }}/{{#flag}} from
+     baldart.config.yml, merges .baldart/overlays/CLAUDE.md, stamps a baldart-generated
+     marker, and writes the result to the repo root.
+     Claude Code loads BOTH CLAUDE.md and AGENTS.md automatically, so this file does NOT
+     import AGENTS.md (that would double-load the protocol). It holds ONLY the Claude-native
+     mechanics that would be noise in the cross-tool AGENTS.md. Edit the OVERLAY, never the
+     generated root CLAUDE.md. -->
+# {{ identity.name }} — Claude Code entry
+
+The full cross-tool coordination protocol (rules, MUST list, git workflow, gates, routing)
+lives in `AGENTS.md`, which Claude Code loads automatically alongside this file — it is the
+SSOT, not restated here. Below are the **Claude-native mechanics only**.
+
+## Plan Mode (Claude-native)
+
+- Enter plan mode (`EnterPlanMode`) for any non-trivial task before writing code.
+  Trivial = single-line fix / typo / obvious bug.
+- Invoke `codebase-architect` before writing the plan — never plan blind.
+- Launch `plan-auditor` + `doc-reviewer` in parallel to review the plan, incorporate their
+  feedback, and state inside the plan that the review gate was honored, BEFORE `ExitPlanMode`.
+- Wait for explicit user approval, then delegate implementation to the `coder` agent (via the
+  Task tool). The `coder` writes code + minimal doc stubs only.
+
+## User Interaction (Claude-native, ABSOLUTE)
+
+- `AskUserQuestion` = STOP and wait. Never answer your own question.
+- It MUST be the only action in that turn. Never proceed without a real user response.
+
+## Subagents & tooling (Claude-native)
+
+- Spawn subagents via the Task tool (`subagent_type: <name>`); the roster + routing is
+  `.claude/agents/REGISTRY.md`.
+{{#output_style}}
+- Output style: `{{ output_style }}` is active (select via `/config` → Output Style).
+{{/output_style}}
+- Hooks (PreToolUse / edit gates) are Claude-only and configured in `.claude/settings.json`.
+
+<!-- OVERLAY: project-specific Claude tweaks live in `.baldart/overlays/CLAUDE.md` and are
+     merged below this line (same OVERRIDE/APPEND/PREPEND model as AGENTS.md). Keep this file
+     thin — cross-tool rules belong in the AGENTS.md overlay, not here. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.82.0",
+  "version": "4.84.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/add.js

@@ -296,6 +296,21 @@ async function add(repo, options) {
       UI.info('Skipped. Run `npx baldart configure` before invoking skills.');
     }
 
+    // Re-write the root primitives (AGENTS.md + CLAUDE.md) now that configure
+    // has populated baldart.config.yml — so the slots resolve to the final
+    // values (name, stack, commands, paths, trunk branch). createAllSymlinks
+    // already wrote them once with whatever config existed; this is idempotent
+    // (byte-stable when nothing changed) and just refreshes the concrete facts.
+    try {
+      const rootPrimitives = require('../utils/root-primitives');
+      const res = rootPrimitives.writeRootPrimitives({ cwd: process.cwd(), tools: enabledTools, autonomous: nonInteractive });
+      if (res.adopted && res.adopted.length) {
+        for (const a of res.adopted) UI.info(`Adopted existing ${a.name}.md → ${a.overlay} (verbatim). Review & re-file when convenient.`);
+      }
+    } catch (err) {
+      UI.warning(`Root primitives step failed: ${err.message}`);
+    }
+
     // Post-flight assert — never declare success with missing hooks.
     // Re-reads .claude/settings.json and confirms every active hook in
     // HOOK_REGISTRY is present. Guards against the silent partial-install

package/src/commands/doctor.js

@@ -343,6 +343,28 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on probe */ }
 
+    // Root primitives (AGENTS.md + CLAUDE.md) integrity (since v4.83.0).
+    // Stale = missing, still a legacy symlink, or drifted vs the current
+    // skeleton / overlay / config. A handwritten file is surfaced separately
+    // (needs interactive adoption) and is NOT auto-regenerated.
+    state.rootPrimitivesStale = [];
+    state.rootPrimitivesAdoptable = [];
+    try {
+      if (state.frameworkPresent) {
+        const rp = require('../utils/root-primitives');
+        for (const name of rp.PRIMITIVES) {
+          if (name === 'CLAUDE') {
+            const toolsEnabled = (config && !config.__malformed && config.tools && Array.isArray(config.tools.enabled))
+              ? config.tools.enabled : ['claude'];
+            if (!toolsEnabled.includes('claude')) continue;
+          }
+          const st = rp.rootPrimitiveStatus({ cwd, name, cfg: config && !config.__malformed ? config : undefined });
+          if (st.state === 'handwritten') state.rootPrimitivesAdoptable.push({ name, reason: st.reason });
+          else if (st.stale) state.rootPrimitivesStale.push({ name, reason: st.reason });
+        }
+      }
+    } catch (_) { /* never block doctor on probe */ }
+
     // `.framework/` is a git subtree — gitignore matching it breaks every
     // future `git add` under that path (the failure mode that hit v3.13.0
     // consumers during push). Detect any gitignore rule that catches the
@@ -861,6 +883,49 @@ function planActions(state) {
     });
   }
 
+  // Root primitives integrity (since v4.83.0). Regenerates AGENTS.md / CLAUDE.md
+  // from the versioned skeleton + config + overlay when missing, still a legacy
+  // symlink, or drifted. Offline + idempotent. A handwritten file is NOT touched
+  // here — it needs interactive adoption (reported below, not auto-run).
+  if (state.rootPrimitivesStale && state.rootPrimitivesStale.length > 0) {
+    const names = state.rootPrimitivesStale.map((r) => `${r.name}.md`).join(', ');
+    actions.push({
+      key: 'regenerate-root-primitives',
+      label: `Regenerate root primitive(s): ${names}`,
+      why: `These root files are out of date vs the shipped skeleton / your overlay / baldart.config.yml (${state.rootPrimitivesStale.map((r) => `${r.name}: ${r.reason}`).join('; ')}). They are BALDART-generated — edit .baldart/overlays/<name>.md, not the file itself.`,
+      autoOk: true,
+      run: async () => {
+        const cfg = loadConfig(process.cwd());
+        const enabledTools = (cfg && !cfg.__malformed
+          && cfg.tools && Array.isArray(cfg.tools.enabled))
+          ? cfg.tools.enabled : ['claude'];
+        const res = require('../utils/root-primitives').writeRootPrimitives({ cwd: process.cwd(), tools: enabledTools });
+        UI.success(`Regenerated root primitives: ${(res.written || []).map((w) => `${w.name}.md`).join(', ') || '(none changed)'}`);
+      },
+    });
+  }
+
+  // Handwritten AGENTS.md/CLAUDE.md that predate BALDART's ownership — offer a
+  // zero-loss adoption (preserve verbatim into an overlay, then generate). Never
+  // auto-run: mutating a hand-authored file must be an explicit choice.
+  if (state.rootPrimitivesAdoptable && state.rootPrimitivesAdoptable.length > 0) {
+    const names = state.rootPrimitivesAdoptable.map((r) => `${r.name}.md`).join(', ');
+    actions.push({
+      key: 'adopt-root-primitives',
+      label: `Adopt handwritten ${names} into overlay(s)`,
+      why: `${names} are hand-authored files with no BALDART marker. Adoption preserves them verbatim into .baldart/overlays/<name>.md (zero loss) and regenerates the root as skeleton + your overlay. Review afterwards — cross-tool rules belong in the AGENTS.md overlay.`,
+      autoOk: false,
+      run: async () => {
+        const cfg = loadConfig(process.cwd());
+        const enabledTools = (cfg && !cfg.__malformed
+          && cfg.tools && Array.isArray(cfg.tools.enabled))
+          ? cfg.tools.enabled : ['claude'];
+        const res = require('../utils/root-primitives').writeRootPrimitives({ cwd: process.cwd(), tools: enabledTools, autonomous: false });
+        for (const a of (res.adopted || [])) UI.success(`Adopted ${a.name}.md → ${a.overlay} (verbatim). Review & re-file when convenient.`);
+      },
+    });
+  }
+
   if (state.lspEnabled && state.lspBroken && state.lspBroken.length > 0) {
     actions.push({
       key: 'lsp-fix',

package/src/commands/migrate.js

@@ -75,6 +75,17 @@ async function migrate() {
     UI.warning(`Found .claude/skills.backup with ${entries.length} entries (from a prior failed update).`);
   }
 
+  // Root primitives (since v4.83.0): AGENTS.md moved from a bulk symlink to a
+  // generated real file, and CLAUDE.md is now shipped. Report a legacy symlink.
+  const agentsMdPath = path.join(cwd, 'AGENTS.md');
+  let agentsMdLegacySymlink = false;
+  try {
+    if (fs.lstatSync(agentsMdPath).isSymbolicLink()) {
+      agentsMdLegacySymlink = true;
+      UI.warning('AGENTS.md is a legacy bulk symlink → will become a generated real file.');
+    }
+  } catch (_) { /* absent or real file — nothing to report here */ }
+
   // --- Plan ---------------------------------------------------------------
 
   const actions = [];
@@ -88,6 +99,11 @@ async function migrate() {
   if (backupPresent) {
     actions.push('Restore user skills from .claude/skills.backup into .claude/skills/ (no overwrites).');
   }
+  if (agentsMdLegacySymlink) {
+    actions.push('Convert legacy AGENTS.md symlink into a generated real file (skeleton + config + overlay).');
+  } else {
+    actions.push('Generate/refresh root primitives AGENTS.md + CLAUDE.md (handwritten files are adopted into overlays, zero-loss).');
+  }
   actions.push('Record any name collisions in .baldart/skill-conflicts.json.');
 
   UI.section('Planned actions');
@@ -133,6 +149,20 @@ async function migrate() {
   symlinks.mergeCommands({ tools: enabledTools });
   UI.info(`Linked ${mergeResult.linked.length} framework skills, kept ${mergeResult.skipped.length} as-is, ${mergeResult.conflicts.length} conflict(s).`);
 
+  // --- Step 2b: root primitives (v4.83.0) --------------------------------
+  // Converts a legacy AGENTS.md symlink → generated real file, ships CLAUDE.md,
+  // and adopts any handwritten root file into an overlay (interactive, zero-loss).
+  UI.section('Step 2b: root primitives (AGENTS.md + CLAUDE.md)');
+  try {
+    const res = require('../utils/root-primitives').writeRootPrimitives({ cwd, tools: enabledTools, autonomous: false });
+    for (const a of (res.adopted || [])) UI.success(`Adopted ${a.name}.md → ${a.overlay} (verbatim, zero-loss). Review & re-file later.`);
+    const wrote = (res.written || []).map((w) => `${w.name}.md (${w.from})`);
+    UI.info(wrote.length ? `Root primitives written: ${wrote.join(', ')}.` : 'Root primitives already up to date.');
+    for (const b of (res.blockers || [])) UI.warning(`Root primitive ${b.name}: ${b.reason}`);
+  } catch (err) {
+    UI.warning(`Root primitives step skipped: ${err.message}`);
+  }
+
   // --- Step 3: restore user skills from .backup --------------------------
 
   if (backupPresent) {

package/src/commands/update.js

@@ -123,6 +123,7 @@ function scaffoldOverlaysForCommits(commits) {
 const BALDART_MANAGED_PATTERNS = [
   /^\.framework(\/|$)/,
   /^AGENTS\.md$/,
+  /^CLAUDE\.md$/,
   /^agents(\.backup)?(\/|$)/,
   /^\.claude\/(agents|commands|skills|workflows|hooks|routines|settings\.json)(\/|$)/,
   /^\.baldart(\/|$)/,
@@ -137,6 +138,28 @@ function isBaldartManagedPath(p) {
   return BALDART_MANAGED_PATTERNS.some((rx) => rx.test(p));
 }
 
+// Re-generate the root primitives (AGENTS.md + CLAUDE.md) from the versioned
+// skeletons + baldart.config.yml + overlays. Idempotent + byte-stable, so it is
+// safe to call on both the aligned-install and post-pull paths. Never throws —
+// a failure here must not abort an otherwise-successful update. Adoption of a
+// handwritten file is interactive-gated inside the writer (a CI/autonomous run
+// surfaces a blocker and leaves the file untouched rather than mutating it).
+function reconcileRootPrimitives(cwd, tools, autonomous) {
+  try {
+    const res = require('../utils/root-primitives').writeRootPrimitives({ cwd, tools, autonomous });
+    for (const a of (res.adopted || [])) {
+      UI.info(`Adopted existing ${a.name}.md → ${a.overlay} (verbatim, zero-loss). Review & re-file when convenient.`);
+    }
+    for (const b of (res.blockers || [])) {
+      UI.warning(`Root primitive ${b.name}: ${b.reason}`);
+    }
+    const wrote = (res.written || []).map((w) => `${w.name}.md`);
+    if (wrote.length) UI.info(`Root primitives updated: ${wrote.join(', ')}.`);
+  } catch (err) {
+    UI.warning(`Root primitives step skipped: ${err.message}`);
+  }
+}
+
 // Real preview (v4.8.0+) — the old `git log HEAD..FETCH_HEAD -- .framework/`
 // is always empty under subtree-squash, so the user never saw what changed.
 // Instead, read the UPSTREAM CHANGELOG and return every entry above the
@@ -912,6 +935,10 @@ async function update(options = {}, unknownArgs = []) {
       if (reconciled > 0) {
         UI.info(`Reconciled ${reconciled} newly-shipped item(s) into per-tool dir(s) — payload drift from a prior CLI-skew update, now healed.`);
       }
+      // Re-generate the root primitives too (AGENTS.md + CLAUDE.md): a primitive
+      // version bump or a slot/overlay change must land even on an aligned install.
+      // --json is programmatic → force autonomous so a handwritten file is never mutated.
+      reconcileRootPrimitives(process.cwd(), alignedTools, options && options.json === true ? true : undefined);
       UI.success(`Already up to date! (v${status.installedVersion})`);
       emitUpdateJson({ ok: true, action: 'already-current',
         installed_before: status.installedVersion,
@@ -1242,6 +1269,10 @@ async function update(options = {}, unknownArgs = []) {
       symlinks.mergeOutputStyles({ tools: enabledTools });
     }
 
+    // Re-generate the root primitives (AGENTS.md + CLAUDE.md) after the pull so
+    // a primitive/slot/overlay change lands. Idempotent + byte-stable.
+    reconcileRootPrimitives(process.cwd(), enabledTools, options && options.json === true ? true : undefined);
+
     // Routines wizard (since v2.1.0) — surfaces routines added in the new framework version
     try {
       const routinesCmd = require('./routines');