baldart 4.80.0 → 4.80.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [4.80.1] - 2026-06-29
+
+**Self-heal payload drift on an already-current install + a Codex-correct "agent not found" message.** Shipping v4.80.0 surfaced two gaps in the field, both from the same incident: a consumer's Codex session emitted the AGENTS.md STOP message for `codebase-architect`, yet the framework was already at v4.80.0. Two root causes:
+
+1. **CLI↔framework skew left the consumer stuck even after the framework reached 4.80.0.** The consumer's subtree was pulled to v4.80.0, but the `update` that pulled it ran with an **older global CLI** (4.76.x) whose `codex.agentsDir()` was still `null` — so the new Codex-agent payload was silently skipped, and `.codex/agents/` was never created. Worse, *re-running* `update` after aligning the CLI hit the **`Already up to date!` early-exit** (line ~893), which returned BEFORE the symlink/merge reconciliation block — so the version-aligned install never self-healed the missing payload (recoverable only via `baldart doctor`). Fix: the `isAligned` branch now runs the idempotent, additive per-item merges (skills/agents/commands/workflows/output-styles) **before** declaring "up to date". They stay silent when nothing is missing and emit a one-line "Reconciled N newly-shipped item(s)" when they heal real drift — so a CLI-skew victim self-heals on the next `update`, not only via `doctor`. This generalises: ANY future payload-kind addition (a new `MERGE_KINDS` entry) is now reconciled on version-aligned installs too.
+2. **The "agent not found" STOP message told a Codex user to "riavvia Claude Code".** The v4.80.0 AGENTS.md edit gave the Codex branch the Claude verbatim message. Fix: a **Codex-specific** message — *"Agent `<name>` non trovato tra i custom agent di Codex (`.codex/agents/<name>.toml`) — allinea la CLI (`npm i -g baldart@latest`), esegui `npx baldart update` (o `npx baldart doctor`), assicurati che il progetto sia trusted in Codex, poi riavvia la sessione Codex"* — encoding the exact remediation (CLI align → update → trust → restart; Codex loads `.codex/agents/` only in **trusted** projects, and discovers agents at session start).
+
+**PATCH** — script bugfix (update self-heals payload drift) + AGENTS.md message correction; no behaviour change on the happy path, no new config key. Existing v4.80.0 consumers should `npm i -g baldart@latest` (kill the skew at the source) then `npx baldart update`; the Codex session must be restarted to discover the newly-installed agents.
+
+### Changed
+
+- **`src/commands/update.js`** — the `Already up to date!` (`status.isAligned`) branch now runs the per-item merges before the early exit (self-heal of payload drift from a prior CLI-skew update), reports the healed count, and adds `reconciled_items` to the `already-current` JSON event.
+- **`framework/AGENTS.md`** — the no-silent-substitution rule's Codex branch now carries its own verbatim "agent not found" remediation message (was reusing the Claude "riavvia Claude Code" text).
+
 ## [4.80.0] - 2026-06-29
 
 **Codex-native subagents — the 32 BALDART agents are now installed for Codex, not just Claude.** A portability bug surfaced in the field: a skill running on Codex delegated to `codebase-architect` (*"invoke the codebase-architect agent"*), but the agent did not exist in the Codex tree and there was no obvious mechanism to spawn it, so the model **improvised** a generic explorer sub-agent. Root cause (confirmed against the OpenAI Codex docs, June 2026): the framework treated subagents as Claude-only — the Codex tool adapter declared `supportsSubagents() === false` / `agentsDir() === null`, so the agent definitions under `framework/.claude/agents/` were **never installed into a Codex tree**. But **Codex now has custom agents** (subagents) — they were simply in a different shape than Claude's, and BALDART had not yet mapped them. This release closes that gap.

package/VERSION

@@ -1 +1 @@
-4.80.0
+4.80.1

package/framework/AGENTS.md

@@ -104,7 +104,7 @@ Conflict steps (must follow in order):
 
 - MUST treat `AGENTS.md` as authoritative for agent rules.
 - MUST invoke the `codebase-architect` agent whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect. **The agent exists on both tools** — Claude Code spawns it via the Task/Agent tool with `subagent_type: "codebase-architect"`; Codex spawns the `codebase-architect` custom agent **by name** (BALDART installs it at `.codex/agents/codebase-architect.toml`, transpiled from the same `.md` source). Only if your environment genuinely exposes NEITHER subagent mechanism (a stripped tool host) do you degrade — explicitly — to inline structural retrieval (code-graph → LSP → Grep → direct file reads per `agents/code-search-protocol.md`), and SAY SO; never silently skip the understanding step.
-- MUST NOT silently substitute a *different* agent when an agent invocation returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. On **Claude Code** this pattern indicates a sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook): STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.** On **Codex** the named-agent spawn is the equivalent; the same no-silent-substitution rule holds (the #56869 specifics are Claude-only, the principle is universal).
+- MUST NOT silently substitute a *different* agent when an agent invocation returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. On **Claude Code** this pattern indicates a sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook): STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.** On **Codex** the equivalent is spawning the custom agent by name; the same no-silent-substitution rule holds — but the remediation differs, so STOP and report the **Codex-specific** message verbatim: "Agent `<name>` non trovato tra i custom agent di Codex (`.codex/agents/<name>.toml`) — allinea la CLI (`npm i -g baldart@latest`), esegui `npx baldart update` (o `npx baldart doctor`), assicurati che il progetto sia *trusted* in Codex, poi riavvia la sessione Codex", and wait for direction. (The #56869 specifics are Claude-only; the no-silent-substitution principle is universal.)
 - MUST NOT work on files/components already claimed by another agent; multiple agents allowed if working on independent areas.
 - MUST perform a mandatory clarity analysis before fixing any issue labeled `bug`; confirm that the issue description, proposed correct behavior, and edge cases are unambiguous, document any resolved doubts, and only start fix work once every zone of uncertainty is covered.
 - MUST mark missing info as UNKNOWN and ask the user; if blocked, set `BLOCKED` with a blocker.

package/package.json

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

package/src/commands/update.js

@@ -891,11 +891,33 @@ async function update(options = {}, unknownArgs = []) {
     // VERSION-compare authority. Subtree-merge commit count is noise; never
     // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
     if (status.isAligned) {
+      // Even when the VERSION is aligned, the per-item PAYLOAD may be stale.
+      // The failure class: a consumer updates with an OLDER CLI (CLI↔framework
+      // skew) → gets the new framework content but the old reconciliation logic,
+      // so a newly-added payload kind (e.g. Codex agents in v4.80.0, where
+      // `codex.agentsDir()` flipped from null to `.codex/agents`) is silently
+      // skipped. Later aligning the CLI and re-running `update` hit this early
+      // "already current" exit and NEVER reconciled — leaving the consumer
+      // stuck (recoverable only via `doctor`). The per-item merges are
+      // idempotent + additive and stay SILENT when nothing is missing, so run
+      // them here: an up-to-date install now self-heals payload drift too.
+      const alignedTools = readEnabledTools();
+      const reconciled = [
+        symlinks.mergeSkills({ tools: alignedTools }),
+        symlinks.mergeAgents({ tools: alignedTools }),
+        symlinks.mergeCommands({ tools: alignedTools }),
+        symlinks.mergeWorkflows({ tools: alignedTools }),
+        symlinks.mergeOutputStyles({ tools: alignedTools })
+      ].reduce((n, r) => n + ((r.linked && r.linked.length) || 0) + ((r.generated && r.generated.length) || 0), 0);
+      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.`);
+      }
       UI.success(`Already up to date! (v${status.installedVersion})`);
       emitUpdateJson({ ok: true, action: 'already-current',
         installed_before: status.installedVersion,
         installed_after: status.installedVersion,
-        remote_version: status.remoteVersion }, 0);
+        remote_version: status.remoteVersion,
+        reconciled_items: reconciled }, 0);
     }
 
     UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);