baldart 3.30.0 → 3.31.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.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/VERSION

@@ -1 +1 @@
-3.30.0
+3.31.0

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,20 @@ 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.31.0
+-->
+
+<!--
+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 +52,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 +98,60 @@ 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:**
+   ```bash
+   npx baldart update --yes
+   ```
+   Use the Bash tool with `timeout: 600000`. `--yes` implies `--auto-stash`,
+   so a dirty tree is handled (stashed + re-applied) without asking.
+   **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.
+3. **Interpret the exit code (the whole point of staying safe):**
+   - **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`.** Report loudly (see below) 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.
+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 +188,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 +245,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)
 
@@ -391,5 +490,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.31.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

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}"