baldart 4.81.0 → 4.83.0

package/framework/docs/ROOT-PRIMITIVES.md

@@ -0,0 +1,98 @@
+# Root-file primitives — `AGENTS.md` + `CLAUDE.md`
+
+Since **v4.83.0** BALDART ships **versioned skeletons** for the two most important
+files in any AI-assisted repo and generates concrete, project-specific versions of
+them on every install/update.
+
+- **`AGENTS.md`** — the **cross-tool single source of truth** (read natively by Claude
+  Code, Codex, Cursor, Aider, …). Holds the coordination protocol: MUST rules, git
+  workflow, gates, execution modes, routing.
+- **`CLAUDE.md`** — a **thin Claude-native stub**. Claude Code loads *both* files
+  automatically, so `CLAUDE.md` does **not** import `AGENTS.md` (that would double-load
+  the protocol into context). It carries only the Claude-only mechanics: Plan Mode
+  (`EnterPlanMode`/`ExitPlanMode`), `AskUserQuestion` discipline, the Task-tool subagent
+  roster, output-style, hooks.
+
+Before v4.83.0, `AGENTS.md` was a bulk symlink into the framework payload (not
+customizable without losing auto-update) and `CLAUDE.md` was not shipped at all.
+
+## Three tiers
+
+Each skeleton mixes exactly three kinds of content:
+
+| Tier | What | Who authors it |
+|---|---|---|
+| **STATIC** | universal SOTA prose, identical for every project | the shipped primitive (versioned) |
+| **`{{ slot }}`** | project facts, filled deterministically at write-time | the writer (`src/utils/root-primitives.js`) — pure substitution, never LLM invention |
+| **`[OVERLAY]`** | project opinions / war-stories / KPIs / design rules | the repo owner, in `.baldart/overlays/{AGENTS,CLAUDE}.md` |
+
+This split follows the 2026 research consensus: a shipped skeleton stays **short and
+hand-authored**; project depth lives in the overlay (auto-generating a whole
+`AGENTS.md`/`CLAUDE.md` with an LLM measurably *reduces* agent task success).
+
+## Slot resolution (deterministic)
+
+The writer resolves every slot from `baldart.config.yml` + repo probes — no new config
+key was introduced:
+
+| Slot | Source |
+|---|---|
+| `identity.name` | `identity.brand_name` → `package.json` name → dir basename |
+| `identity.description` | README first paragraph → `package.json` description → visible `<!-- TODO -->` |
+| `stack.summary` | composed from `stack.framework` + `database` + `auth_provider` + `testing.e2e` + `toolchain.installed_tools` |
+| `stack.node` | `package.json` `engines.node` → `.nvmrc` |
+| Commands table | `toolchain.commands.*` → `package.json` scripts (rows with no source are omitted) |
+| Repo map | non-empty `paths.*` + a derived source root |
+| `git.trunk_branch` | `git.trunk_branch` |
+| feature gates | `features.has_backlog` / `has_adrs` / `has_i18n` / `has_design_system` |
+
+## Overlay
+
+`.baldart/overlays/AGENTS.md` (and `…/CLAUDE.md`) use the **same** merge engine as agent
+and command overlays (`overlay-merger.js`):
+
+- `## [OVERRIDE] <section>` — replace a section from the skeleton.
+- `## [APPEND] <section>` — append to a section.
+- `## [PREPEND] <section>` — prepend to a section.
+- a plain `## <heading>` — add a new section at the end.
+
+Author overlays with `/overlay` or by hand. The generated root file carries a
+`baldart-generated` marker and the `framework-edit-gate` hook blocks direct edits to it —
+edit the overlay, not the file.
+
+## Lifecycle
+
+- **`baldart add`** — after `configure` populates `baldart.config.yml`, the writer
+  generates both files with concrete values.
+- **`baldart update`** — regenerates on both the aligned-install and post-pull paths.
+  **Byte-stable**: unchanged inputs produce no diff.
+- **`baldart doctor`** — flags `regenerate-root-primitives` when a file is missing, still
+  a legacy symlink, or drifted (skeleton / overlay / config change), and
+  `adopt-root-primitives` for a handwritten file.
+- **`baldart migrate`** — converts a legacy `AGENTS.md` symlink into the generated file.
+
+## Adoption (existing hand-written files — zero loss)
+
+If a consumer already has a hand-authored `AGENTS.md` or `CLAUDE.md` (no
+`baldart-generated` marker), the writer **adopts** it: the entire file is preserved
+verbatim into `.baldart/overlays/<name>.md`, and the root is regenerated as skeleton +
+overlay (so nothing is lost). You are told to review and re-file — much of a rich
+`CLAUDE.md` typically belongs in the **AGENTS.md** overlay (cross-tool), not CLAUDE.md.
+
+**Adoption is interactive-gated.** In autonomous/CI mode (`CI` / `BALDART_AUTONOMOUS` /
+no TTY) a hand-written file is **never mutated**: the writer emits a blocker and skips it,
+so a routine unattended update never silently transforms your file.
+
+## Versioning
+
+Each skeleton carries a `primitive_version` (SemVer, its own line of evolution,
+independent of the framework `VERSION`) in its banner, plus a sibling
+`framework/templates/primitives/<NAME>.CHANGELOG.md` kept **out** of the generated file
+so version history never costs context. Bump `primitive_version` + add a changelog entry
+whenever a skeleton changes.
+
+## Files
+
+- `framework/templates/primitives/AGENTS.md` · `CLAUDE.md` — the skeletons.
+- `framework/templates/primitives/AGENTS.CHANGELOG.md` · `CLAUDE.CHANGELOG.md` — internal changelogs.
+- `src/utils/root-primitives.js` — the writer (resolve → template → merge → marker → write) + `rootPrimitiveStatus` (doctor).

package/framework/templates/primitives/AGENTS.CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog — AGENTS.md primitive
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+Questo è il changelog INTERNO dello skeleton spedito (`primitive_version`), separato dal
+file `AGENTS.md` generato nel consumer e indipendente dal `VERSION` del framework.
+
+## 1.0.0 — 2026-07-01
+
+- Primo skeleton SOTA cross-tool (framework v4.83.0). Sostituisce il bulk symlink di
+  `AGENTS.md` con un real-file **generato**: contenuto STATIC universale + slot `{{ }}`
+  riempiti a write-time da `baldart.config.yml` (identity/stack/paths/commands/git) +
+  hook `[OVERLAY]` per `.baldart/overlays/AGENTS.md`.
+- Struttura: Commands (partial, comandi concreti) · Repo Map (partial) · Non-negotiables
+  (universal + feature-gated) · Git Workflow · Workflow Gates · Execution Modes ·
+  Priority & Conflict · Routing.
+- Le meccaniche solo-Claude (EnterPlanMode/AskUserQuestion/Task) NON stanno qui: vivono
+  nello stub `CLAUDE.md`. La ricchezza project-specific (war-story/KPI/regole design) va
+  in overlay, non nello skeleton (best practice 2026: skeleton corto, no auto-generazione).

package/framework/templates/primitives/AGENTS.md

@@ -0,0 +1,111 @@
+<!-- baldart-primitive: name=AGENTS primitive_version=1.0.0
+     This is the SHIPPED SKELETON. The writer (src/utils/root-primitives.js) strips
+     this banner, resolves every {{ slot }} / {{> partial }} / {{#flag}} from
+     baldart.config.yml (+ package.json/README), merges .baldart/overlays/AGENTS.md,
+     stamps a baldart-generated marker, and writes the result to the repo root.
+     Tiers: STATIC (verbatim) · {{slot}} (config fill) · [OVERLAY] (project opinions).
+     Edit the OVERLAY, never the generated root AGENTS.md. -->
+# {{ identity.name }} — Agent Protocol (AGENTS.md)
+
+{{ identity.description }}
+Stack: {{ stack.summary }}.{{ stack.node_suffix }}
+
+Mandatory coordination rules for all agents (Claude / Codex / humans). Read by every
+AI tool that supports AGENTS.md. If context is limited, follow **MUST** rules and
+**Routing** first. Claude Code additionally loads `CLAUDE.md`, which adds Claude-native
+mechanics — this file remains the single source of truth for the protocol.
+
+{{> commands_section }}
+## Repo Map
+
+{{> repo_map }}
+
+## Non-negotiables (MUST)
+
+**Universal (every project):**
+- MUST treat `AGENTS.md` as authoritative for agent rules.
+- MUST understand the codebase before planning/implementing — invoke `codebase-architect`
+  (Claude Code: Task tool `subagent_type: codebase-architect`; Codex: the custom agent by
+  name at `.codex/agents/codebase-architect.toml`). Only if NEITHER mechanism exists,
+  degrade explicitly to inline retrieval (code-graph → LSP → Grep) and SAY SO.
+- MUST NOT silently substitute a different agent when an invocation returns empty / times
+  out / is denied — STOP, report verbatim, and wait. Never auto-route to a generic agent.
+- MUST NOT work on files another agent has claimed; parallel work only on independent areas.
+- MUST do a clarity analysis before fixing anything labeled `bug` — no blind guessing.
+- MUST mark missing info UNKNOWN and ask; if blocked, set `BLOCKED` with the blocker.
+- MUST NOT make forbidden assumptions: provider/auth swap, DB-schema change without a
+  data-model update, new external dependency without docs, API-contract change without an
+  API-reference update.
+- MUST keep docs and code in sync — a code change without the matching doc update is invalid.
+- MUST use commit format `{{ git.commit_format }}`; small, traceable commits.
+- MUST NOT commit with failing lint/type checks. Full build only before opening a PR.
+- MUST pre-sync (`git fetch`, clean status, confirm branch, `--ff-only`) and NEVER push
+  directly to `{{ git.trunk_branch }}` — all changes reach it via PR.
+- MUST get owner approval before force-push/reset or deleting an UNMERGED branch (create a
+  `backup/<YYYYMMDD>-<reason>` tag first). Deleting an already-merged branch is routine.
+- MUST run the testing gates before DONE (see § Workflow Gates).
+
+**Feature-gated (active only when the flag is `true` in `baldart.config.yml`):**
+{{#has_backlog}}
+- Backlog: pick one card (TODO/READY), set `IN_PROGRESS`, assign yourself, branch-per-card
+  (`{{ git.feature_prefix }}/<CARD-ID>-slug`), keep status current, document before merge.
+{{/has_backlog}}
+{{#has_adrs}}
+- ADRs: write complete records (Context / Decision / Rationale / Alternatives / Consequences,
+  no TODO placeholders) for architectural decisions.
+{{/has_adrs}}
+{{#has_i18n}}
+- i18n: NO hardcoded user-facing strings; every label via `t()` + a key in
+  `{{ i18n.registry }}`. Enforced by the anti-hardcoded lint gate.
+{{/has_i18n}}
+{{#has_design_system}}
+- Design system: the BLOCKING read cascade applies before any UI work — read the registry
+  `INDEX.md` → the per-component spec → the token SSOT (see § Routing).
+{{/has_design_system}}
+{{#has_project_status}}
+- Status doc: update its Active Code Context before work; keep it < 200 lines; archive
+  entries older than 7 days to `work-history.md`.
+{{/has_project_status}}
+
+## Git Workflow
+
+Branch naming: `{{ git.feature_prefix }}/<CARD-ID>-slug` (local), `codex/…` or `claude/…`
+(cloud agents), `hotfix/<ID>-slug` (production fixes). Branches are created by the
+orchestrator (`/nw`, `/new`) or the user — **never by the `coder` agent** (it implements on
+the branch it was spawned on). Stage explicit filenames only; never bundle unrelated changes.
+
+## Workflow Gates
+
+**Pre-commit (fast, every commit):** lint · type check{{#has_i18n}} · the i18n anti-hardcoded
+gate{{/has_i18n}} · markdown-lint on changed `.md`. Fix all errors before `git add`. Do NOT
+run a full build every commit.
+
+**Pre-PR (once, before opening a PR):** full build (must pass) · unit tests (if they exist) ·
+E2E for critical-flow changes.
+
+## Execution Modes
+
+| Mode | Branch | Validation |
+|---|---|---|
+| `local` | `{{ git.feature_prefix }}/<CARD-ID>-slug` → PR to `{{ git.trunk_branch }}` | manual run mandatory |
+| `cloud` | `codex/…` or `claude/…` → PR to `{{ git.trunk_branch }}` | CI-first; local advisory |
+| `hotfix` | `hotfix/<BUG-ID>-slug` | owner approval |
+
+## Priority & Conflict
+
+Priority: `AGENTS.md` → `agents/index.md` → domain references → ADRs → `archive/`.
+On conflict: stop → read both → decide which is newer → update the other → record the
+decision in an ADR + the backlog card.
+
+## Routing
+
+- Docs routing (touch X → read/update Y): `agents/index.md`.
+- Agent invocation routing: `.claude/agents/REGISTRY.md` (SSOT). Update it when adding agents.
+- Domain protocols load on demand from `agents/*.md` (architecture, testing, security,
+  design-system-protocol, i18n-protocol, …) — never load them all at once.
+
+<!-- OVERLAY: project-specific rules live in `.baldart/overlays/AGENTS.md` and are merged
+     below this line. Use `## [APPEND] <section>` to extend a section above, `## [OVERRIDE]
+     <section>` to replace one, or a plain `## <heading>` to add a new section. Typical
+     content: design-system rules · DB/migration discipline · NFR/KPI targets · security
+     specifics · project war-stories & ADR pointers · custom commands. -->

package/framework/templates/primitives/CLAUDE.CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — CLAUDE.md primitive
+
+Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
+Changelog INTERNO dello stub spedito (`primitive_version`), separato dal `CLAUDE.md`
+generato nel consumer e indipendente dal `VERSION` del framework.
+
+## 1.0.0 — 2026-07-01
+
+- Primo stub Claude-native (framework v4.83.0). BALDART inizia a spedire `CLAUDE.md`.
+- Deliberatamente **non** importa `AGENTS.md` (Claude Code carica entrambi i file
+  nativamente → un `@AGENTS.md` raddoppierebbe il protocollo in contesto). Contiene solo:
+  Plan Mode (EnterPlanMode/plan-auditor/doc-reviewer/ExitPlanMode), User Interaction
+  (AskUserQuestion = stop-and-wait), Subagents & tooling (Task tool, output-style, hooks).
+- Hook `[OVERLAY]` per `.baldart/overlays/CLAUDE.md`; le regole cross-tool vanno
+  nell'overlay di AGENTS.md, non qui.

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.81.0",
+  "version": "4.83.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');