baldart 3.30.0 → 3.32.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.32.0] - 2026-05-30
+
+Makes the CLI **agent-native at the output layer**: `npx baldart version --json` and `npx baldart update --json --yes` now emit a single **machine-readable JSON object** on stdout (schemas `baldart.version/1` / `baldart.update/1`), with every human line routed to stderr. This closes the last fragile seam in the autonomous-update path — the `/baldart-update` skill previously had to **regex-scrape human-readable prose** (the v3.26.0 wording change had already forced a dual-format tolerant parser in Step 0). An agent now reads a field instead of matching a sentence. Borrowed from the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) philosophy (`--json` on every command) — but BALDART is already a headless CLI, so this is a thin, hand-rolled output layer, not a generated wrapper. **No new `baldart.config.yml` keys** — `--json` is a CLI flag, not a config key, so the schema-propagation rule does not apply.
+
+### Added — `--json` structured output
+
+- **[src/commands/version.js](src/commands/version.js)**: `--json` emits `{schema:"baldart.version/1", installed, installed_version, remote_version, aligned, offline, fetched, uncommitted_files, commits_ahead/behind, cli_version, cli_latest, cli_update_available, repository, last_update_date, last_pushed_version, last_push_date}` — exactly the facts the human box shows. Framework-not-installed and error paths emit `{installed:false|null, error, …}` so the agent always gets parseable stdout.
+- **[src/commands/update.js](src/commands/update.js)**: `--json` emits a single `{schema:"baldart.update/1", ok, action, …}` result at **every** terminal point through one `emitUpdateJson` chokepoint (all-or-nothing: a missed exit would leave stdout empty). `ok:true` ⟺ the framework is now at the remote version (`action` `updated` / `already-current`); every refusal/failure is `ok:false` with `action` (`divergence-refused`, `divergence-scaffolded`, `aborted`, `failed`, `framework-missing`, `usage-error`), `reason`, and a `next_command` the human can re-run. `--json` **requires `--yes`** (so no prompt can block) and **rejects `--reset`** (the nuclear path stays an interactive human escape hatch).
+- **[src/utils/ui.js](src/utils/ui.js)**: new `UI.setJsonMode(on)` redirects every `console.log` the UI helpers emit to **stderr** (reversible), keeping stdout clean for the JSON. `ora` spinners already write to stderr, so they need no change. The JSON itself is written with `process.stdout.write`, never `console.log`, so it survives the redirect.
+
+### Changed — autonomous `/baldart-update` reads JSON, not prose
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: Step 0 now **prefers** `version --json` (field reads) and **falls back** to the dual-format text parser when the global CLI predates v3.32.0 (`--json` unknown / non-JSON stdout) — the same "new skill + old global CLI" transition window the text parser already guards. Autonomous mode runs `update --json --yes`, parses the single result object (`ok` / `action` / `installed_after` / `backup_tag` / `next_command`), and keeps the **exit code as the safety backstop**. The post-flight assert cross-checks `installed_after` against on-disk `.framework/VERSION` and the Step 0 `remote_version`. `last_verified` v3.31.0 → v3.32.0; added a **JSON-OUTPUT NOTE** recording that `--json` is a flag, not a config key.
+
+### Fixed — self-relaunch flag forwarding
+
+- **[src/commands/update.js](src/commands/update.js)** `maybeRelaunchUnderLatest`: the stale-CLI self-relaunch now forwards `--json` **and** `--on-divergence <strategy>` to the `npx baldart@latest` child. The latter was a pre-existing latent drop (an agent's non-interactive divergence strategy would silently vanish on relaunch); both are fixed together.
+- **[bin/baldart.js](bin/baldart.js)**: the CLI self-update notifier's stdout `announce` is suppressed under `--json` so it cannot pollute the single JSON object.
+
+## [3.31.0] - 2026-05-30
+
+Gives `/baldart-update` an **autonomous mode** so agents and scheduled routines can bring the framework up-to-date with **zero human interaction** — closing the gap that the skill, as shipped, was *purely* human-in-the-loop (it replicated every CLI decision point as a chat confirmation, which an unattended agent cannot answer). The new mode is **auto-detected** from a positive automation signal and keeps every one of the CLI's safety gates: it drives `npx baldart update --yes` and **stops hard** (never forces a merge or reset) the moment the CLI refuses on custom divergence or a conflict — exactly the calls a human should own. **No new `baldart.config.yml` keys** — `BALDART_AUTONOMOUS` is a runtime env var, not a config flag, so the schema-propagation rule does not apply.
+
+### Added — autonomous (unattended) mode for `/baldart-update`
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: new **Mode detection** first step (`printenv | grep -qE '^(BALDART_AUTONOMOUS|CI|GITHUB_ACTIONS)='`) branches the skill into INTERACTIVE (a human is present → existing chat-confirmation flow, unchanged) or AUTONOMOUS (no human → new flow). Detection is **positive-signal-only**: absence of every signal defaults to INTERACTIVE so a human never silently loses control. Documents *why* the TTY test (`[ -t 0 ]`) cannot be used — Claude's Bash tool never has a TTY on stdin, even with a human present, so it can't tell the two situations apart.
+- **`## Autonomous mode`** section: pre-flight (shared Step 0 + CLI version drift gate) → `npx baldart update --yes` (bare, `timeout: 600000`) → exit-code interpretation → shared post-flight assert → structured log-friendly report. **Hard guardrail**: on a non-zero exit (custom-overlay-able / real-custom divergence, subtree-pull conflict, stale-CLI halt) the skill STOPS and reports the exact flag a human would re-run with — it **never** retries with `--on-divergence pull|scaffold-overlays` or `--reset` to force past a refusal. A refusal is a *correct* outcome that needs a human.
+
+### Added — automation marker injected by the routine-adapters
+
+- **[src/utils/routine-adapters/github-actions.js](src/utils/routine-adapters/github-actions.js)**: the generated workflow's run step now sets `BALDART_AUTONOMOUS: '1'` in its `env:` block (alongside `ANTHROPIC_API_KEY`), inherited by the `claude` process and every child Bash it spawns.
+- **[src/utils/routine-adapters/cron.js](src/utils/routine-adapters/cron.js)**: the generated shell wrapper `export`s `BALDART_AUTONOMOUS=1` before invoking `claude`.
+- **[src/utils/routine-adapters/claude-code-cloud.js](src/utils/routine-adapters/claude-code-cloud.js)**: the generated routine config now carries `env: { BALDART_AUTONOMOUS: '1' }` (best-effort — relies on the RemoteTrigger surfacing `env` into the run environment; github-actions / cron inject it directly).
+
+### Changed — drift-check counter + honest framing
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: `last_verified` v3.26.0 → v3.31.0; added an **AUTONOMY NOTE** recording that `BALDART_AUTONOMOUS` is a runtime env var (not a config key) so the schema-propagation rule does not apply. Hard rules gain a rule #0 (run mode detection first; default-on-absence is INTERACTIVE); rule #2 now qualifies the chat-replication mandate as INTERACTIVE-only. The closing "both keep the user in the loop" claim is corrected to reflect that autonomous mode drops confirmations while keeping the safety gates.
+
 ## [3.30.0] - 2026-05-29
 
 Hardens the **overlay** system — the layer that turns generic framework skills into project-specific knowledge. An audit surfaced a structural asymmetry: agent/command overlays are *compile-time merged* (the overlay is materially fused into the generated file → guaranteed delivery), but skill overlays use *runtime concatenation* (a line of prose tells the agent to read `.baldart/overlays/<skill>.md` → best-effort, nothing verifies it loaded). The most important overlays for knowledge transfer had the weakest guarantee. This release ships the high-certainty authoring/DX fixes now and adds **observation-only telemetry** to gather real data on whether skill overlays actually load — before deciding whether a stronger enforcement mechanism is worth building. **No new `baldart.config.yml` keys** — the telemetry hook is always-on (like `framework-edit-gate` / `agent-discovery-gate`), so the schema-propagation rule does not apply.

package/README.md

@@ -456,6 +456,14 @@ Update framework to latest version.
 - Updates via Git subtree
 - Verifies symlinks
 
+**For agents / CI (v3.32.0+):** `npx baldart update --json --yes` emits a single
+machine-readable result object on stdout (`{schema:"baldart.update/1", ok,
+action, installed_after, backup_tag, next_command, …}`) with all human output on
+stderr — no prose to scrape. `ok:true` ⟺ the framework is now at the remote
+version. `--json` requires `--yes` and rejects `--reset`. Pair with
+`--on-divergence pull|scaffold-overlays|abort` for non-interactive divergence
+resolution.
+
 ### `npx baldart` (no args) / `doctor` (v3.2.0+)
 
 Smart diagnostic that detects the install state and proposes the next sensible
@@ -474,7 +482,10 @@ npx baldart doctor     # explicit alias (same behaviour)
 
 Show installed framework version, install date, drift from remote (commits
 ahead/behind), uncommitted-files count in `.framework/`, and last-push info.
-Use `--offline` to skip the upstream fetch when offline.
+Use `--offline` to skip the upstream fetch when offline. Use `--json`
+(v3.32.0+) for a machine-readable object (`schema:"baldart.version/1"`) on
+stdout — agents read `installed_version` / `remote_version` / `aligned`
+instead of scraping the human box.
 
 ### `npx baldart push` / `/baldart-push` (v3.1.0+)
 

package/VERSION

@@ -1 +1 @@
-3.30.0
+3.32.0

package/bin/baldart.js

@@ -43,10 +43,16 @@ const CLI_VERSION = resolveVersion();
 // command on a network call.
 const rawArgsForNotifier = process.argv.slice(2);
 const offlineForNotifier = rawArgsForNotifier.includes('--offline');
-updateNotifier.announceAndRefresh({
-  currentVersion: CLI_VERSION,
-  offline: offlineForNotifier,
-});
+// In --json mode STDOUT must carry exactly one JSON object — the notifier hint
+// would pollute it. Suppress the announce entirely (the refresh is harmless but
+// the announce prints to stdout). (v3.32.0+)
+const jsonForNotifier = rawArgsForNotifier.includes('--json');
+if (!jsonForNotifier) {
+  updateNotifier.announceAndRefresh({
+    currentVersion: CLI_VERSION,
+    offline: offlineForNotifier,
+  });
+}
 
 const program = new Command();
 
@@ -73,6 +79,7 @@ program
   .option('--reset', 'Nuclear option: rm -rf .framework/ + fresh install, preserving baldart.config.yml + .baldart/ + custom .claude/{agents,skills,commands}/. Requires clean working tree.')
   .option('--i-know', 'Acknowledges --reset will wipe untracked/ignored files inside .framework/ (required to use --reset --yes).')
   .option('--on-divergence <strategy>', 'Non-interactive resolution when the consumer has local commits on .framework/ (for agents / CI): "scaffold-overlays" (auto-create overlay skeletons, then stop), "pull" (keep commits + merge — non-destructive), or "abort".')
+  .option('--json', 'Machine-readable output (agents / CI): emit a single JSON result object on stdout, route all human output to stderr. Requires --yes (non-interactive); rejects --reset.')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);
@@ -90,9 +97,10 @@ program
   .command('version')
   .description('Show installed framework version + drift from remote + last-push info')
   .option('--offline', 'Skip the upstream fetch (no remote drift report)')
+  .option('--json', 'Machine-readable output: emit a single JSON object on stdout, route human output to stderr (for agents / CI).')
   .action(async (options) => {
     const versionCommand = require('../src/commands/version');
-    await versionCommand({ offline: !!options.offline });
+    await versionCommand({ offline: !!options.offline, json: !!options.json });
   });
 
 program

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: baldart-update
-description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. Replicates the native CLI's user-decision points (preview diff, working-tree stash) as chat-side confirmations, lets the CLI auto-resolve mechanical noise (hook backfill, subtree-merge commits, schema migration), and asserts post-flight that .framework/VERSION actually changed. For non-update drift, defers to `npx baldart` (smart doctor)."
+description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. Two modes, auto-detected: INTERACTIVE (a human is present) replicates the native CLI's user-decision points (preview diff, working-tree stash) as chat-side confirmations; AUTONOMOUS (unattended — CI / scheduled routine, signalled by BALDART_AUTONOMOUS / CI / GITHUB_ACTIONS env) runs `npx baldart update --yes` with zero prompts and hard-STOP guardrails (never forces a merge or reset on custom divergence / conflicts). Both let the CLI auto-resolve mechanical noise (hook backfill, subtree-merge commits, schema migration) and assert post-flight that .framework/VERSION actually changed. For non-update drift, defers to `npx baldart` (smart doctor)."
 contamination_scan: skip
 ---
 
@@ -12,10 +12,30 @@ pull_request). When any of the numbers below changes against the actual
 sources, a warning is surfaced in the workflow run. The decision whether
 this skill needs an update is left to a human reviewer.
 
-update_js_prompts: 7
+update_js_prompts: 6
 hook_registry_entries: 4
 config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
-last_verified: v3.26.0
+last_verified: v3.32.0
+-->
+
+<!--
+JSON-OUTPUT NOTE (v3.32.0)
+`npx baldart version --json` and `npx baldart update --json --yes` emit a single
+machine-readable object on stdout (schemas `baldart.version/1` /
+`baldart.update/1`), with all human output on stderr. The skill PREFERS these
+over regex-scraping prose, but keeps the text parser as a fallback for the
+"new skill + old global CLI" transition window. `--json` is a CLI FLAG, not a
+baldart.config.yml key — the schema-change propagation rule does NOT apply.
+-->
+
+<!--
+AUTONOMY NOTE (v3.31.0)
+`BALDART_AUTONOMOUS` is a RUNTIME ENV VAR, not a baldart.config.yml key — the
+schema-change propagation rule does NOT apply (no template/configure/update
+detector change). It is injected by the routine-adapters (github-actions: env
+block; cron: `export`; claude-code-cloud: best-effort `env` field in the run
+config) so scheduled routines run unattended. Any orchestrator that wants a
+child agent to update autonomously can set it the same way.
 -->
 
 
@@ -42,7 +62,31 @@ CLI would normally ask in the terminal — so the CLI can be driven with
 ╚══════════════════════════════════════════════════════════════════════╝
 ```
 
-## Execution model — IMPORTANT
+## Mode detection — FIRST STEP, BLOCKING (v3.31.0+)
+
+Before anything else, decide which of two modes you are in. This gates the
+entire rest of the skill.
+
+```bash
+# A single positive signal of automation means "no human is in the loop".
+# Absence of ALL signals means "human present" → stay interactive.
+printenv | grep -qE '^(BALDART_AUTONOMOUS|CI|GITHUB_ACTIONS)=' && echo AUTONOMOUS || echo INTERACTIVE
+```
+
+- **`AUTONOMOUS`** → no human can answer chat prompts (scheduled routine, CI,
+  or an orchestrator that exported the marker). Follow **`## Autonomous mode`**
+  below. Do NOT ask any chat questions — there is no one to read them.
+- **`INTERACTIVE`** → a human is present. Follow the interactive flow
+  (Execution model + Workflow steps), which replicates every CLI decision
+  point as a chat confirmation.
+
+> **Why not `[ -t 0 ]`?** When Claude runs a command via the Bash tool, stdin
+> is never a TTY — not even with a human present. The TTY test cannot tell the
+> two situations apart. Only a *positive* automation signal (env var) is
+> reliable, and we default to INTERACTIVE on its absence so a human never
+> silently loses control.
+
+## Execution model (INTERACTIVE mode) — IMPORTANT
 
 This is an **agent-driven skill with full chat-side replication** of every
 decision point the CLI would pose interactively. The flow is:
@@ -64,6 +108,79 @@ pure-guidance (the user runs the CLI themselves). Here the user has asked
 for an agent that drives the update, so the skill drives it — but it
 replicates every confirmation so nothing is silently auto-accepted.
 
+## Autonomous mode (AUTONOMOUS) — unattended, zero prompts (v3.31.0+)
+
+When mode detection returned `AUTONOMOUS`, there is no human to confirm
+anything. The skill drives the update end-to-end with NO chat questions, and
+leans entirely on the CLI's own safety gates — which already **refuse** to do
+anything destructive under bare `--yes`.
+
+**The contract: autonomy over mechanical work, hard STOP on anything that
+touches the user's custom content.**
+
+### Autonomous workflow
+
+1. **Pre-flight (read-only)** — same as interactive Step 0: run
+   `npx baldart version`, parse the `Installed:` and `Remote:` lines with the
+   tolerant matcher. Apply the same **CLI version drift gate** (a too-old
+   global CLI crossing the v3.27.0 payload boundary → STOP and report; do not
+   launch).
+   - Aligned / already up-to-date → report "already current", exit success.
+2. **Launch directly — no preview/stash confirmation. Prefer `--json`
+   (v3.32.0+) so the result is a parseable object, not prose:**
+   ```bash
+   npx baldart update --json --yes
+   ```
+   Use the Bash tool with `timeout: 600000`. `--yes` implies `--auto-stash`,
+   so a dirty tree is handled (stashed + re-applied) without asking. `--json`
+   requires `--yes` (it refuses interactively) and routes all human output to
+   stderr — **stdout carries exactly one JSON object**.
+   **Do NOT add `--on-divergence pull` or `--reset`.** Bare `--yes` is the
+   safe ceiling: the CLI auto-resolves only mechanical noise and *refuses*
+   (exits non-zero) on real custom divergence.
+
+   **Fallback:** if the CLI predates v3.32.0 it rejects `--json` (unknown
+   option, non-zero exit, empty/garbled stdout). Re-run without it
+   (`npx baldart update --yes`) and fall back to exit-code + stdout-grep
+   interpretation. Never let a missing `--json` block the update.
+3. **Interpret the result — JSON first, exit code as the safety backstop:**
+   - With `--json`, parse the single stdout object. `ok === true` (action
+     `updated` or `already-current`) → success, go to post-flight using
+     `installed_after` / `backup_tag`. `ok === false` → the CLI refused or
+     failed; read `action` (`divergence-refused`, `divergence-scaffolded`,
+     `failed`, `framework-missing`, `usage-error`), `reason`, and
+     `next_command`. Report them verbatim.
+   - The **exit code is still the contract** regardless of `--json`:
+     - **Exit 0** → update applied (or already aligned). Go to post-flight.
+     - **Exit non-zero** → the CLI hit a wall it will not cross unattended:
+       custom-overlay-able / real-custom divergence, a subtree-pull conflict, or
+       a stale-CLI halt. **STOP. Do NOT retry with `--on-divergence` or
+       `--reset`.** Surface the JSON `reason` + `next_command` (or, in fallback
+       mode, the verbatim stderr) so the human who reads the routine log knows
+       exactly what needs a hands-on decision. Forcing a merge or a reset
+       unattended is precisely the silent destruction this mode forbids.
+4. **Post-flight assert (MANDATORY)** — identical to interactive Step 4:
+   `cat .framework/VERSION`, compare to the pre-update version. If the CLI
+   exited 0 but VERSION did not change (and stdout is not "Already up to
+   date"), **FAIL LOUD** — do not report success. With `--json` this is a
+   direct check: the result's `installed_after` MUST equal both
+   `.framework/VERSION` and the Step 0 `remote_version`; any mismatch (e.g.
+   `ok:true` but `installed_after` ≠ on-disk VERSION) is the same FAIL LOUD.
+5. **Report** — emit a structured, log-friendly summary (no questions):
+   version delta, backup tag + rollback command, any agent-layout migration
+   (v3.27.0+), and — on a non-zero exit — the verbatim CLI stderr plus the
+   exact flag a human would re-run with (`--on-divergence pull` /
+   `scaffold-overlays` / `--reset --yes --i-know`). The skill names the
+   options; it never picks one autonomously.
+
+### What autonomous mode must NEVER do
+
+- Ask a chat question (no one is there; a blocked prompt hangs the routine).
+- Pass `--on-divergence pull|scaffold-overlays` or `--reset` to "get past" a
+  refusal. A refusal is a *correct* outcome that needs a human.
+- Report success when the post-flight assert fails.
+- Auto-resolve a stash-pop or merge conflict with `--hard` / `--no-verify`.
+
 ## When to use
 
 - The user invokes `/baldart-update`.
@@ -100,13 +217,20 @@ for the protocol.
 
 ## Hard rules
 
+0. **MUST run mode detection FIRST** (the `printenv | grep` probe above) and
+   branch accordingly. Defaulting to AUTONOMOUS when no signal is present —
+   or to INTERACTIVE when a signal IS present — are both wrong. The default on
+   *absence of signal* is INTERACTIVE (human keeps control).
 1. **MUST NOT re-implement the logic of `update.js`.** Same rule as
    `/baldart-push`: the CLI is the source of truth. The skill only
    replicates prompts and parses output.
-2. **MUST replicate in chat all 5 decision points** before passing `--yes`:
-   preview, working-tree stash, hooks drift, schema config drift,
-   auto-commit of BALDART-managed files. Silencing one is dishonest — the
-   user thinks they confirmed everything, but they didn't see that prompt.
+2. **(INTERACTIVE mode) MUST replicate in chat the 2 remaining decision
+   points** before passing `--yes`: preview and working-tree stash (the other
+   three — hooks drift, schema config drift, BALDART-managed auto-commit — are
+   auto-resolved silently by the CLI since v3.26.0). Silencing a real prompt
+   is dishonest — the user thinks they confirmed everything, but they didn't
+   see that prompt. **(AUTONOMOUS mode) MUST NOT ask any chat question** — see
+   `## Autonomous mode`; a blocked prompt hangs the routine.
 3. **MUST pass `timeout: 600000` (10 minutes)** to the `Bash` call running
    `npx baldart update --yes`. The default 120s is not enough for subtree
    pull + symlink reconcile + post-update wizard + hooks register +
@@ -150,7 +274,11 @@ post-flight assert:
 > preview. The repo URL is exposed by `npx baldart version` in the
 > `Repository:` line.
 
-## Workflow
+## Workflow (INTERACTIVE mode)
+
+> In AUTONOMOUS mode follow `## Autonomous mode` instead. Step 0 (pre-flight
+> probe + CLI version drift gate) and Step 4 (post-flight assert) are shared
+> by both modes; Steps 1–3 (chat confirmations) are interactive-only.
 
 ### Step 0 — Pre-flight (read-only)
 
@@ -161,7 +289,36 @@ post-flight assert:
 npx baldart version
 ```
 
-**Parser tollerante** — the output format changed in v3.26.0 (version-compare
+#### Preferred: structured `--json` (v3.32.0+) — NO regex
+
+As of v3.32.0 the CLI emits a machine-readable object — read fields instead
+of scraping prose:
+
+```bash
+npx baldart version --json 2>/dev/null
+# → {"schema":"baldart.version/1","installed":true,"installed_version":"3.32.0",
+#    "remote_version":"3.33.0","aligned":false,"offline":false,"fetched":true,
+#    "uncommitted_files":0,"cli_version":"3.32.0","cli_latest":null,
+#    "cli_update_available":false,"repository":"https://github.com/antbald/BALDART",...}
+```
+
+Decision logic on the JSON:
+- `installed === false` → framework not installed → STOP, instruct `npx baldart add`.
+- `aligned === true` → already up-to-date (`installed_version`). STOP.
+- `aligned === false` AND `remote_version !== "unknown"` → continue (save
+  `installed_version` for the post-flight assert, `remote_version` as target).
+- `offline === true` / `fetched === false` → ask the user how to proceed.
+- Still apply the **CLI version drift gate** below using `cli_version` /
+  `cli_latest` (same semver logic).
+
+**Fallback (BLOCKING for the transition window):** if `version --json` errors
+(non-zero exit, unknown-option message, or stdout that is NOT valid JSON), the
+global CLI predates v3.32.0. Do **not** abort — fall back to the **Parser
+tollerante** below, which scrapes the human-readable output. This is the same
+"new skill + old global CLI" case the dual-format text parser already exists
+for. Never remove the text parser.
+
+**Parser tollerante (fallback)** — the output format changed in v3.26.0 (version-compare
 authority instead of subtree-merge commit count). The skill must accept BOTH
 the new and legacy formats so it works during the transition window where
 the consumer has the new skill but an older global CLI.
@@ -391,5 +548,9 @@ spine of BALDART maintenance:
 - `/baldart-update` — pull from upstream.
 - `/baldart-push` — push to upstream.
 
-Both wrap the CLI without re-implementing it; both keep the user in the
-loop. The CLI remains the source of truth.
+Both wrap the CLI without re-implementing it; the CLI remains the source of
+truth. `/baldart-push` always keeps the user in the loop. `/baldart-update`
+does too **when a human is present** (interactive mode); when run unattended
+(autonomous mode — CI / scheduled routine) it drops the confirmations but
+keeps the CLI's safety gates, stopping hard rather than forcing any
+destructive resolution a human would otherwise own.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.30.0",
+  "version": "3.32.0",
   "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

@@ -28,6 +28,20 @@ function readEnabledTools(cwd = process.cwd()) {
 // agent-overlay feedback that prompted this).
 const DIVERGENCE_STRATEGIES = ['abort', 'pull', 'scaffold-overlays'];
 
+// Machine-readable result channel (v3.32.0+). When --json is active, STDOUT
+// must carry exactly ONE JSON object and nothing else — UI.setJsonMode() has
+// already redirected every human line to STDERR. Every terminal point in the
+// standard flow routes through `emitUpdateJson` so the contract holds: one
+// object, then exit. `ok: true` means "framework is now at the remote version"
+// (action `updated` or `already-current`); everything else is `ok: false`.
+let JSON_MODE = false;
+function emitUpdateJson(obj, exitCode) {
+  if (JSON_MODE) {
+    process.stdout.write(JSON.stringify({ schema: 'baldart.update/1', ...obj }) + '\n');
+  }
+  process.exit(exitCode);
+}
+
 // Map a touched framework path to an `overlay scaffold` target string.
 //   .framework/framework/.claude/agents/coder.md     → 'agents/coder'
 //   .framework/framework/.claude/commands/check.md    → 'commands/check'
@@ -394,6 +408,10 @@ async function maybeRelaunchUnderLatest(options) {
   if (options.commit === false) flags.push('--no-commit');
   if (options.reset === true) flags.push('--reset');
   if (options.iKnow === true) flags.push('--i-know');
+  // Forward the non-interactive resolution + machine-readable flags too, else
+  // a stale-CLI self-relaunch would silently drop them (v3.32.0+).
+  if (options.onDivergence) flags.push('--on-divergence', options.onDivergence);
+  if (options.json === true) flags.push('--json');
 
   const spawn = require('child_process').spawnSync;
   UI.info(`Auto-relaunching via npx baldart@${info.latest}…`);
@@ -421,10 +439,31 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Machine-readable mode (v3.32.0+). Must be fully non-interactive: --json
+  // requires --yes (so no UI.select/confirm can block) and rejects --reset
+  // (the nuclear path is a deliberate destructive human escape hatch, not an
+  // agent flow — see the autonomous /baldart-update skill, which never resets).
+  JSON_MODE = options.json === true;
+  if (JSON_MODE) {
+    UI.setJsonMode(true);
+    if (options.reset === true) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: '--json does not support --reset. Reset is an interactive destructive escape hatch; run it manually.' }, 2);
+    }
+    if (!autoYes) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: '--json requires --yes (non-interactive). Re-run: npx baldart update --json --yes [--on-divergence pull|scaffold-overlays]' }, 2);
+    }
+  }
+
   // Non-interactive divergence strategy (since v3.29.0). Validated up-front so
   // a typo fails fast instead of mid-flow after the network fetch.
   const divStrategy = options.onDivergence;
   if (divStrategy !== undefined && !DIVERGENCE_STRATEGIES.includes(divStrategy)) {
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: `Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.` }, 1);
+    }
     UI.error(`Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
     process.exit(1);
   }
@@ -443,7 +482,9 @@ async function update(options = {}) {
         'Solution:',
         '  Install first: npx baldart add'
       ]);
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'framework-missing',
+        reason: 'Framework directory .framework/ not found.',
+        next_command: 'npx baldart add' }, 1);
     }
 
     // v3.26.0+ NUCLEAR OPTION: --reset rips out .framework/ and reinstalls
@@ -480,7 +521,8 @@ async function update(options = {}) {
           UI.error('.framework/ is STILL ignored after auto-heal — likely a parent-dir .gitignore outside this repo.');
           UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
           UI.info('Resolve by removing that rule, then re-run `baldart update`.');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'failed',
+            reason: `.framework/ is still ignored after auto-heal (${heal.recheck.source}:${heal.recheck.line}). Remove that .gitignore rule and re-run.` }, 1);
         }
       }
     } catch (err) {
@@ -512,19 +554,24 @@ async function update(options = {}) {
         '  • Check internet connection',
         '  • Try again later'
       ]);
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'connect-failed',
+        reason: 'Cannot connect to repository (network / access).' }, 1);
     }
 
     if (!status.fetched || !status.hasFetchHead) {
       UI.error('Could not fetch upstream — try again with network access.');
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'fetch-failed',
+        reason: 'Could not fetch upstream — try again with network access.' }, 1);
     }
 
     // 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) {
       UI.success(`Already up to date! (v${status.installedVersion})`);
-      process.exit(0);
+      emitUpdateJson({ ok: true, action: 'already-current',
+        installed_before: status.installedVersion,
+        installed_after: status.installedVersion,
+        remote_version: status.remoteVersion }, 0);
     }
 
     UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);
@@ -556,9 +603,18 @@ async function update(options = {}) {
             'Then complete the update with `npx baldart update --reset --yes --i-know` — this discards the now-redundant `.framework/` edits and reinstalls clean; your `.baldart/overlays/` are preserved and re-applied.',
             'Alternatively, push the edits upstream with `/baldart-push` if they are generic improvements.',
           ], 'cyan');
-          process.exit(0);
+          emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Scaffolded overlay skeleton(s); fill them in, then re-run.',
+            next_command: 'npx baldart update --reset --yes --i-know' }, 0);
+        }
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort).');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass,
+            reason: 'Update cancelled (--on-divergence abort).' }, 0);
         }
-        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
         if (divStrategy === 'pull') {
           UI.info('Keeping the custom commits (--on-divergence pull). The subtree pull will attempt a merge.');
           // fall through
@@ -572,7 +628,11 @@ async function update(options = {}) {
             '--on-divergence pull               → keep the commits and merge the update (non-destructive)',
             '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
           ], 'cyan');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'divergence-refused',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Custom edits present — refusing to resolve them unattended under --yes.',
+            next_command: 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 1);
         } else {
           const choice = await UI.select('How would you like to proceed?', [
             { name: 'Scaffold overlay skeleton(s) now (recommended — then fill them in & re-run)', value: 'overlay' },
@@ -605,16 +665,29 @@ async function update(options = {}) {
           if (overlayCommits.length === 0) {
             UI.error('No overlay-able commits to scaffold — every custom commit touches non-overlayable paths (src/, CHANGELOG, …).');
             UI.info('Use `/baldart-push` to contribute them upstream, or `--on-divergence pull` to merge.');
-            process.exit(1);
+            emitUpdateJson({ ok: false, action: 'divergence-refused',
+              divergence_class: status.divergenceClass,
+              installed_before: status.installedVersion, remote_version: status.remoteVersion,
+              reason: 'No overlay-able commits to scaffold — every custom commit touches non-overlayable paths.',
+              next_command: 'npx baldart update --json --yes --on-divergence pull' }, 1);
           }
           UI.newline();
           scaffoldOverlaysForCommits(overlayCommits);
           UI.newline();
           UI.warning('Scaffolded overlays for the overlay-able commits, but custom-other commit(s) remain — NOT pulling (would be destructive to those edits).');
           UI.info('Resolve the remaining commits (push upstream with `/baldart-push`, or revert), then re-run `npx baldart update`.');
-          process.exit(0);
+          emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Scaffolded overlay-able subset; custom-other commit(s) still need handling before pulling.',
+            next_command: 'npx baldart update --json --yes' }, 0);
+        }
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort).');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass,
+            reason: 'Update cancelled (--on-divergence abort).' }, 0);
         }
-        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
         if (divStrategy === 'pull') {
           UI.info('Pulling over the custom commits (--on-divergence pull). A merge commit will be created — resolve any conflicts that surface.');
           // fall through
@@ -627,7 +700,11 @@ async function update(options = {}) {
             '--on-divergence abort              → do nothing',
           ], 'cyan');
           UI.info('Best practice: contribute generic improvements upstream first with `/baldart-push`.');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'divergence-refused',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Custom commits present — refusing to pull over them unattended under --yes.',
+            next_command: 'npx baldart update --json --yes --on-divergence pull' }, 1);
         } else {
           const choice = await UI.select('How would you like to proceed?', [
             { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
@@ -669,6 +746,7 @@ async function update(options = {}) {
     // "fatal: working tree has modifications. Cannot add." Offer to stash
     // and re-apply after the update, so the user doesn't have to abort mid-flow.
     let stashRef = null;
+    let stashConflict = false; // surfaced in the --json result (v3.32.0+)
     const isClean = await git.hasCleanWorkingTree();
     if (!isClean) {
       UI.newline();
@@ -703,7 +781,8 @@ async function update(options = {}) {
         UI.success(`Stashed working tree as "${stashRef}".`);
       } catch (err) {
         UI.error(`Could not stash: ${err.message}`);
-        process.exit(1);
+        emitUpdateJson({ ok: false, action: 'failed',
+          reason: `Could not stash working tree before update: ${err.message}` }, 1);
       }
     }
 
@@ -756,6 +835,7 @@ async function update(options = {}) {
           await git.git.stash(['pop']);
           UI.success(`Re-applied pre-update stash "${stashRef}".`);
         } catch (err) {
+          stashConflict = true;
           UI.newline();
           UI.warning(`Could not auto-re-apply stash "${stashRef}" — conflicts with the framework update.`);
           UI.box('STASH CONFLICT', [
@@ -1006,7 +1086,15 @@ async function update(options = {}) {
     UI.newline();
     UI.success('Framework updated successfully!');
 
+    emitUpdateJson({ ok: true, action: 'updated',
+      installed_before: currentVersion, installed_after: newVersion,
+      remote_version: status.remoteVersion, backup_tag: backupTag,
+      stash_conflict: stashConflict }, 0);
+
   } catch (error) {
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'failed', reason: error.message }, 1);
+    }
     UI.error(`Update failed: ${error.message}`);
     process.exit(1);
   }

package/src/commands/version.js

@@ -30,12 +30,25 @@ async function describeDrift(git, status) {
   };
 }
 
+// Emit a structured JSON object on stdout (v3.32.0+). Used by agents / CI to
+// avoid scraping the human-readable box with fragile regex. Schema is
+// versioned (`baldart.version/1`) so consumers can detect breaking changes.
+function emitVersionJson(obj) {
+  process.stdout.write(JSON.stringify({ schema: 'baldart.version/1', ...obj }) + '\n');
+}
+
 async function version(opts = {}) {
   const git = new GitUtils();
+  const jsonMode = opts.json === true;
+  if (jsonMode) UI.setJsonMode(true);
 
   try {
     const exists = await git.frameworkExists();
     if (!exists) {
+      if (jsonMode) {
+        emitVersionJson({ installed: false, error: 'framework_not_installed' });
+        process.exit(0);
+      }
       UI.warning('Framework not installed');
       UI.info('Install with: npx baldart add');
       process.exit(0);
@@ -63,6 +76,31 @@ async function version(opts = {}) {
     }
     const drift = await describeDrift(git, status);
 
+    // Machine-readable path (v3.32.0+) — emit the structured object and stop.
+    // Mirrors exactly the facts the human box shows below, so the autonomous
+    // /baldart-update skill can read fields instead of regex-scraping prose.
+    if (jsonMode) {
+      emitVersionJson({
+        installed: true,
+        installed_version: frameworkVersion,
+        remote_version: drift.remoteVersion, // string version, or 'unknown'
+        aligned: drift.isAligned,
+        offline: opts.offline === true || !drift.hasFetchHead,
+        fetched: drift.hasFetchHead,
+        uncommitted_files: drift.uncommittedFiles,
+        commits_ahead: drift.ahead,
+        commits_behind: drift.behind,
+        cli_version: cliVersion,
+        cli_latest: cliUpdate ? cliUpdate.latest : null,
+        cli_update_available: !!cliUpdate,
+        repository: `https://github.com/${repo}`,
+        last_update_date: state.last_update_date || null,
+        last_pushed_version: state.last_pushed_version || null,
+        last_push_date: state.last_push_date || null,
+      });
+      return;
+    }
+
     // Messaging based on `isAligned` (not commit count, which is subtree noise).
     let remoteLine;
     if (!drift.hasFetchHead) {
@@ -103,6 +141,10 @@ async function version(opts = {}) {
     UI.box('BALDART VERSION', lines.filter((l) => l !== ''));
     UI.newline();
   } catch (error) {
+    if (jsonMode) {
+      emitVersionJson({ installed: null, error: 'version_failed', reason: error.message });
+      process.exit(1);
+    }
     UI.error(`Failed to get version: ${error.message}`);
     process.exit(1);
   }

package/src/utils/routine-adapters/claude-code-cloud.js

@@ -43,6 +43,13 @@ class ClaudeCodeCloudAdapter {
       prompt: spec.prompt,
       output: spec.output,
       backend: this.name,
+      // Marks this as an unattended (no-human) run. Autonomy-aware skills
+      // (e.g. /baldart-update) auto-detect this and drop their chat
+      // confirmations, with safe guardrails (STOP on custom divergence /
+      // conflicts, never forces a destructive merge). Best-effort for this
+      // backend: RemoteTrigger must surface `env` into the run environment for
+      // the runtime probe to see it; github-actions / cron inject it directly.
+      env: { BALDART_AUTONOMOUS: '1' },
       installed_at: new Date().toISOString()
     };
     fs.writeFileSync(this.configPath(spec.name), JSON.stringify(config, null, 2) + '\n');

package/src/utils/routine-adapters/cron.js

@@ -101,6 +101,13 @@ if ! command -v claude >/dev/null 2>&1; then
 fi
 : "\${ANTHROPIC_API_KEY:?ANTHROPIC_API_KEY must be set (export it from the cron env or your shell profile)}"
 
+# Marks this as an unattended (no-human) run. The /baldart-update skill (and
+# any other autonomy-aware skill) auto-detects this and switches to
+# non-interactive mode — no chat confirmations, safe guardrails (STOP on
+# custom divergence / conflicts, never forces a destructive merge). Exported
+# so the \`claude\` process and every child Bash it spawns inherit it.
+export BALDART_AUTONOMOUS=1
+
 DATE=$(date -u +%Y%m%d)
 OUT_PATH="${outputPath}"
 OUT_PATH="\${OUT_PATH//\\{\\{YYYYMMDD\\}\\}/$DATE}"

package/src/utils/routine-adapters/github-actions.js

@@ -105,6 +105,13 @@ jobs:
       - name: Run ${spec.name}
         env:
           ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+          # Marks this as an unattended (no-human) run. The /baldart-update
+          # skill (and any other autonomy-aware skill) auto-detects this and
+          # switches to non-interactive mode — no chat confirmations, safe
+          # guardrails (STOP on custom divergence / conflicts, never forces a
+          # destructive merge). Inherited by the \`claude\` process and every
+          # child Bash it spawns.
+          BALDART_AUTONOMOUS: '1'
         run: |
           DATE=$(date -u +%Y%m%d)
           OUT_PATH="${outputPath}"

package/src/utils/ui.js

@@ -3,6 +3,22 @@ const ora = require('ora');
 const inquirer = require('inquirer');
 
 class UI {
+  // Machine-readable mode (v3.32.0+). When on, every human-facing line that
+  // these helpers emit via `console.log` is redirected to STDERR, leaving
+  // STDOUT free for a single JSON object the caller (agent / CI) can parse.
+  // The JSON itself MUST be written with `process.stdout.write` directly —
+  // never through `console.log` — so it survives this redirect. Reversible;
+  // `ora` spinners already write to stderr, so they need no special handling.
+  static setJsonMode(on) {
+    if (on && !UI._origLog) {
+      UI._origLog = console.log;
+      console.log = (...args) => process.stderr.write(args.join(' ') + '\n');
+    } else if (!on && UI._origLog) {
+      console.log = UI._origLog;
+      UI._origLog = null;
+    }
+  }
+
   static header(text) {
     console.log('');
     console.log(chalk.cyan('━'.repeat(60)));