baldart 4.7.0 → 4.8.0

package/CHANGELOG.md

@@ -5,7 +5,24 @@ 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.7.0] - 2026-06-03
+## [4.8.0] - 2026-06-03
+
+**`baldart update` diventa seamless: un solo comando, zero iterazioni — aggiorna e preserva gli overlay.** Un transcript reale (`v4.2.1 → v4.3.0`) ha richiesto **3 invocazioni fallite + git surgery manuale** per un'operazione il cui lavoro è sempre lo stesso. Le cause erano bug di design del CLI, ora rimossi: (1) **asimmetria stash** — `--yes` auto-stasciava il tree sporco ma il path `--reset` lo *rifiutava*, buttando via l'autorizzazione dell'utente e costringendo a stash/drop/mv-a-/tmp/pop a mano; (2) **hard-stop su divergenza già sicura** — il CLI calcolava `overlayCoversTouched` (sa che gli edit sono già negli overlay, lo scrive: "--reset is safe") ma sotto `--yes` *rifiutava* invece di procedere; (3) **flag-maze** — per sbloccarsi serviva `--reset --yes --i-know`, combo da indovinare; (4) **finalizer assente sul path reset** — i generated-agents + `state.json` restavano uncommitted; (5) **preview morta** — `git log HEAD..FETCH_HEAD -- .framework/` è sempre vuoto col subtree-squash. Ora `npx baldart update --yes` fa tutto in un colpo: auto-stash (motore unico, `git stash push -u` senza pathspec → niente più fallimenti su dir `.gitignore`d), auto-risoluzione della divergenza (overlay-covered → reinstall pulito che riapplica gli overlay; **uncovered → auto-cattura in overlay popolati dal diff + VERIFICA che il merge riproduca l'edit** prima del reinstall), riconcilia + committa gli artefatti BALDART-managed (finalizer anche sul path reset), e ripristina lo stash. **MINOR** (capability aggiunta, comandi invariati e retrocompatibili; nessuna chiave `baldart.config.yml`).
+
+> **Why.** L'intent dell'utente è vincolante: *"voglio che tutto il processo sia seamless, niente iterazioni — le cose da fare sono sempre le stesse: aggiornare e preservare gli overlay"* (coerente col principio "rispetta l'intent esplicito vs advisor"). L'unica collisione possibile tra "seamless" e "non perdere dati" è un edit a un file framework **non** coperto da overlay: la scelta dell'utente è **auto-cattura + verifica** — il CLI genera l'overlay dal diff (modello section-marker di `overlay-merger.js`) e ri-merge contro il base upstream fresco; se il risultato riproduce l'edit a livello di sezioni+preamble procede muto, altrimenti **si ferma una sola volta** (`divergence-capture-incomplete`) elencando i blocker (section deletion, cambio frontmatter/preamble, file `src/`) — mai un'azione distruttiva silenziosa. La verifica è la rete di sicurezza che rende la cattura sicura a prescindere dalla fedeltà dell'algoritmo. Gli escape hatch espliciti (`--on-divergence pull|scaffold-overlays|abort`, `--reset --yes --i-know`) restano per CI/power-user, ma non sono più il path che l'utente deve scoprire: il default È quello seamless.
+
+### Added
+
+- **`src/utils/overlay-capture.js`** — nuovo modulo `captureAndVerify`: verifica che OGNI edit overlay-able divergente sia preservato da un overlay, esistente o catturato. Per agents/commands è **verificabile** — ri-merge l'overlay (esistente o generato dal diff via `[OVERRIDE]`/H2 plain) contro il base upstream fresco (`FETCH_HEAD`) e confronta sezioni ordinate + preamble; un overlay **esistente ma stale** (non riproduce l'edit `.framework` corrente) diventa un **blocker**, non una perdita silenziosa al reset. Per le skill (runtime-concat, non mergiabili dal CLI) un overlay esistente è fidato, l'assenza è un blocker. Path non mappabili → blocker. Il chiamante passa l'INTERO set di file toccati (mai un sottoinsieme pre-filtrato): un pre-filtro lascerebbe il reset cancellare un edit senza overlay che lo preservi. Esporta helper unit-testabili (12+ test).
+
+### Changed
+
+- **`src/commands/update.js`** — (a) **motore di stash unico** `autoStashNonFramework` (blanket `git stash push -u`, niente pathspec) riusato sia dalla normale flow sia da `runReset` (che prima *rifiutava* il tree sporco). (b) **`runReset` finalizer**: re-apply dello stash + `postUpdateAutoCommit` + emissione JSON (`action: 'reset'`) → tree pulito su tutti i path. (c) **divergenza overlay-able**: il default sotto `--yes` non rifiuta più — `resolveOverlayDivergenceSeamlessly` cattura+verifica gli uncovered (committandoli **prima** del reset così sopravvivono allo stash e alimentano il merge), poi reset-and-reapply; stop singolo solo su blocker. (d) **divergenza mixed/real-custom**: cattura il sottoinsieme overlay-able e si ferma una volta (i path `src/`/CHANGELOG non sono auto-risolvibili). (e) **preview reale**: `changelogSinceInstalled` mostra le entry del CHANGELOG upstream tra versione installata e remota (rimpiazza e **rimuove** il dead-code `git.diffWithRemote`, diff opt-in sempre-vuoto col subtree-squash). `--i-know` resta esplicito solo per il `--reset` standalone (implicito nel path seamless).
+- **`src/utils/git.js`** — rimosso il metodo morto `diffWithRemote` (nessun chiamante dopo la nuova preview).
+- **`src/commands/overlay.js`** — esporta `buildFrontmatter` (riusato da `overlay-capture.js` per scrivere overlay con frontmatter valido senza re-implementare la logica).
+- **`framework/.claude/skills/baldart-update/SKILL.md`** — riscritta per il flusso seamless: rimossa la replica chat dei 2 decision-point (preview + stash) e lo step di preview morto; la skill ora lancia `npx baldart update --yes` e riporta, sorvegliando l'unica pausa legittima (`divergence-capture-incomplete`). Description frontmatter, Hard rule #2, tabella decision-point, workflow (Step 0/1/2) e DRIFT-CHECK (`update_js_prompts: 5`, `last_verified: v4.8.0`) allineati.
+
+
 
 **`/new` smette di rifare per-card 4 review che la Final FULL gate già ripete sull'intero batch.** La Final Review F.3 gira sempre, incondizionata, su tutto il diff di batch: Codex + **doc-reviewer** + **api-perf-cost-auditor** + **qa-sentinel** (suite completa + build + audit). Quindi le passate *per-card* di quegli stessi reviewer sono, per la sicurezza del merge-gate, già coperte dalla rete finale — il loro unico valore residuo è il fail-fast/attribuzione. Quattro pruning, tutti deterministici e con la Final come rete: (1) **plan-auditor grounding** saltato (sequential) quando `/prd` ha già fatto l'holistic audit (`metadata.holistic_audit`) e non c'è drift sui path della card — mirror esatto del gate v4.3.0 Step 3d; (2) **doc-review per-card** deferita alla Final per le card `light` il cui diff non tocca file di documentazione; (3) **qa-sentinel per-card** che gira solo per `deep` (o `balanced` escalata da risk-drift) — `balanced` non-rischiose deferiscono la suite alla Final; (4) **api-perf-cost-auditor per-card** droppato via nuovo flag lean-contract `skip_api_perf_auditor`, deferito alla Final. **MINOR** (comportamento `/new` più lean; nessuna chiave `baldart.config.yml` — si appoggia su `review_profile` + `metadata.holistic_audit` già esistenti).
 

package/README.md

@@ -449,20 +449,32 @@ npx baldart add owner/repo   # Install from custom fork
 
 ### `npx baldart update`
 
-Update framework to latest version.
-
-- Shows changelog
-- Creates backup tag
-- Updates via Git subtree
-- Verifies symlinks
+Update framework to latest version — **seamless** (v4.8.0+): one command, zero
+iterations. The job is always the same — update and preserve overlays — so the
+CLI does the whole thing in one shot:
+
+- Shows the upstream CHANGELOG between your version and the remote
+- Auto-stashes any non-framework work and re-applies it after (single blanket
+  stash; handles tracked files inside `.gitignore`d dirs)
+- Creates a backup tag (`git reset --hard <tag>` to roll back)
+- Resolves divergence automatically: edits already covered by an overlay → clean
+  reinstall that re-applies the overlays; **uncovered edits → auto-captured into
+  overlays and verified** (the merge must reproduce the edit) before reinstall
+- Updates via Git subtree, verifies symlinks, and commits the BALDART-managed
+  reconcile — leaving a clean tree
+
+It stops **once** only when an edit cannot be captured+verified faithfully (a
+section deletion, a frontmatter/preamble change, a `src/` change) — never a
+silent destructive action.
 
 **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.
+action, installed_after, backup_tag, blockers, next_command, …}`) with all human
+output on stderr — no prose to scrape. `ok:true` ⟺ the framework is now at the
+remote version (`action` is `updated`, `reset`, or `already-current`). The escape
+hatches `--reset --yes --i-know` and `--on-divergence pull|scaffold-overlays|abort`
+still exist for power users, but the seamless default makes them unnecessary.
+`--json` requires `--yes` and rejects an explicit `--reset`.
 
 ### `npx baldart` (no args) / `doctor` (v3.2.0+)
 

package/VERSION

@@ -1 +1 @@
-4.7.0
+4.8.0

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

@@ -1,7 +1,7 @@
 ---
 name: baldart-update
 effort: medium
-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)."
+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. The update is SEAMLESS (v4.8.0+): a single `npx baldart update --yes` auto-stashes non-framework work, auto-resolves divergence (overlay-covered edits → clean reinstall that re-applies overlays; uncovered edits → auto-captured into overlays and verified), reconciles + commits BALDART-managed artifacts, and re-applies the stash — zero prompts in the happy path. The skill only narrates and reports; it never re-implements the CLI or replicates its prompts. Two modes, auto-detected: INTERACTIVE (a human is present) and AUTONOMOUS (unattended — CI / scheduled routine, signalled by BALDART_AUTONOMOUS / CI / GITHUB_ACTIONS env, uses --json). The CLI stops ONCE only when an edit cannot be captured+verified (a section deletion, a frontmatter/preamble change, a src/ change) — the skill surfaces that single pause. Always asserts post-flight that .framework/VERSION actually changed. For non-update drift, defers to `npx baldart` (smart doctor)."
 contamination_scan: skip
 ---
 
@@ -13,10 +13,10 @@ 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: 6
+update_js_prompts: 5
 hook_registry_entries: 4
 config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
-last_verified: v3.33.0
+last_verified: v4.8.0
 -->
 
 <!--
@@ -42,10 +42,13 @@ child agent to update autonomously can set it the same way.
 
 # /baldart-update — Update framework in this consumer
 
-Guide the user through an update of the BALDART framework inside their
-consumer repo, replicating in chat **every interactive decision point** the
-CLI would normally ask in the terminal — so the CLI can be driven with
-`--yes` while the user keeps full control of each choice.
+Drive a **seamless** update of the BALDART framework inside the consumer repo.
+The CLI does the whole job in one shot — `npx baldart update --yes` — and the
+job is always the same: **update and preserve overlays**. The skill runs that
+command, watches for the single legitimate pause (an edit that can't be
+captured+verified), and reports. It does NOT replicate the CLI's old
+preview/stash confirmations (the CLI handles both automatically since v4.8.0)
+and it NEVER re-implements the CLI's logic.
 
 ```
 ╔══════════════════════════════════════════════════════════════════════╗
@@ -89,35 +92,36 @@ printenv | grep -qE '^(BALDART_AUTONOMOUS|CI|GITHUB_ACTIONS)=' && echo AUTONOMOU
 
 ## 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:
-
-1. Run *read-only* probes to detect the same conditions `update.js` would
-   detect (version drift, dirty working tree, hooks drift, schema config
-   drift, BALDART-managed files to auto-commit).
-2. For each detected condition, surface it in chat and ask the user the
-   exact same question the CLI would ask in a TTY.
-3. Once every prompt has been answered in chat, launch `npx baldart update
-   --yes` via `Bash` (with a long timeout — see Hard rules). The `--yes`
-   flag is safe here precisely because there is no native prompt left to
-   silence: every one of them has already been resolved above.
-4. Parse the CLI output, report the backup tag + new version, surface any
-   stash-pop conflicts that may have happened after the subtree pull.
-
-This is the **intentional divergence** from `/baldart-push`, which is
-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.
+This is an **agent-driven, seamless** skill. The flow is short:
+
+1. Run the *read-only* pre-flight: `npx baldart version` (+ the CLI version
+   drift gate). Already aligned → report "already current" and STOP.
+2. Launch `npx baldart update --yes` via `Bash` (long timeout — see Hard
+   rules). No chat confirmation of preview or stash: the CLI auto-stashes the
+   dirty tree, shows the CHANGELOG preview itself, auto-resolves overlay-covered
+   divergence by a clean reinstall, auto-captures+verifies uncovered edits, and
+   auto-commits the BALDART-managed reconcile. The user authorized the seamless
+   behavior by invoking the skill — do not re-ask what the CLI already handles.
+3. Post-flight assert that `.framework/VERSION` changed, then report the version
+   delta, backup tag, any agent-layout migration, and (if the CLI stopped at the
+   single capture pause) the verbatim blockers + next step.
+
+The ONLY time the flow is not a single shot is when the CLI exits non-zero
+because an edit could not be captured+verified faithfully (section deletion,
+frontmatter/preamble change, or a `src/` change). That is a deliberate,
+data-safety pause — surface it; never force past it.
 
 ## 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`.
+leans entirely on the CLI's own safety gates — which auto-resolve seamlessly
+under bare `--yes` (auto-stash, overlay-covered reinstall, capture+verify of
+uncovered edits) and **stop hard** only when an edit cannot be captured+verified
+(`divergence-capture-incomplete`).
 
-**The contract: autonomy over mechanical work, hard STOP on anything that
-touches the user's custom content.**
+**The contract: autonomy over the whole seamless flow, hard STOP only on an
+edit that cannot be preserved safely.**
 
 ### Autonomous workflow
 
@@ -137,8 +141,10 @@ touches the user's custom content.**
    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.
+   seamless ceiling (v4.8.0+): the CLI auto-stashes, auto-resolves overlay-covered
+   divergence by a clean reinstall, and auto-captures+verifies uncovered edits.
+   It exits non-zero only when an edit cannot be captured+verified faithfully
+   (action `divergence-capture-incomplete`) — a correct stop that a human owns.
 
    **Fallback:** if the CLI predates v3.32.0 it rejects `--json` (unknown
    option, non-zero exit, empty/garbled stdout). Re-run without it
@@ -146,11 +152,12 @@ touches the user's custom content.**
    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.
+     `updated`, `reset`, or `already-current`) → success, go to post-flight
+     using `installed_after` / `backup_tag`. `ok === false` → the CLI stopped
+     or failed; read `action` (`divergence-capture-incomplete`, `failed`,
+     `framework-missing`, `usage-error`), `reason`, `blockers`, and
+     `next_command`. Report them verbatim. `action: 'reset'` is the seamless
+     overlay-covered resolution — a normal success, not an escape hatch.
    - 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:
@@ -160,7 +167,7 @@ touches the user's custom content.**
        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:
+4. **Post-flight assert (MANDATORY)** — identical to interactive Step 2:
    `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
@@ -169,16 +176,17 @@ touches the user's custom content.**
    `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.
+   (v3.27.0+), and — on a non-zero exit (`divergence-capture-incomplete`) — the
+   verbatim `blockers` list plus the `next_command` the CLI printed (typically
+   `npx baldart update --on-divergence pull`, or author the overlay by hand).
+   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.
+  `divergence-capture-incomplete` stop. That stop is a *correct* outcome (an
+  edit that cannot be preserved safely) and needs a human.
 - Report success when the post-flight assert fails.
 - Auto-resolve a stash-pop or merge conflict with `--hard` / `--no-verify`.
 
@@ -234,13 +242,12 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 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. **(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.
+2. **MUST NOT replicate CLI prompts in chat.** The seamless CLI (v4.8.0+) has
+   no happy-path prompts to replicate: it auto-stashes, shows its own CHANGELOG
+   preview, auto-resolves divergence, and auto-commits. Re-asking "Procedo?" or
+   "Stash?" is friction the user explicitly does not want. The only stop is the
+   CLI's own non-zero exit on an uncapturable edit — surface it, don't pre-empt
+   it. **(AUTONOMOUS mode) MUST NOT ask any chat question** either.
 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 +
@@ -256,39 +263,40 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    how to proceed or aborts. Never silence a decision point because a
    probe failed.
 
-## Decision points the skill still replicates (v3.26.0+)
-
-Before v3.26.0 this skill chat-replicated five CLI decision points. As of
-v3.26.0 the CLI itself silently auto-resolves three of them (hooks drift,
-schema config drift, BALDART-managed auto-commit) when they don't involve
-real user choices. The skill is now down to two prompts plus a mandatory
-post-flight assert:
-
-| # | Native CLI prompt           | Chat-side replication                                                                                                                                  | Detect via                                                                                                                                                          |
-|---|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 1 | "Proceed with update?"       | Show "Remote: vX.Y.Z" + (if known) last commit messages, ask "Procedo?"                                                                                 | `npx baldart version` (parse `Remote:` line with tolerant matcher — see Step 0)                                                                                     |
-| 2 | "Stash dirty working tree?"  | List modified files, explain they will go into `baldart-pre-update-<timestamp>`, ask explicit confirmation                                              | `git status --porcelain` in consumer root                                                                                                                            |
-
-**Auto-resolved by CLI in v3.26.0+** (no chat replication needed):
-- **Hooks drift**: missing hooks auto-registered silently; only command-level drift prompts (and only if interactive).
-- **Schema config drift**: surfaces as a warning post-update; never blocks.
-- **BALDART-managed auto-commit**: `--yes` commits silently with `chore(baldart):` subject.
-- **Subtree-merge / chore divergence commits**: classified by the CLI (merges detected by parent count, so plumbing/collaboration merges never poison the class); auto-resolved silently when `all-noise`, prompts for `overlay-able` / `real-custom` / `mixed` — or resolve non-interactively with `--on-divergence scaffold-overlays|pull|abort`.
-- **CLI self-upgrade**: transparent relaunch via `npx baldart@latest` when global CLI is stale.
-
-> **IMPORTANT — do NOT use `git -C .framework fetch`.** `.framework/` is a git
-> subtree, not a separate repo: git commands inside it fall back to the consumer's
-> own repo and would fetch the wrong remote. The correct pattern (mirroring
-> `update.js` + `src/utils/git.js`) is `git fetch <BALDART-repo-url> main` from
-> the consumer root, then `git log HEAD..FETCH_HEAD -- .framework/` for the
-> preview. The repo URL is exposed by `npx baldart version` in the
-> `Repository:` line.
+## Everything the CLI auto-resolves (no chat replication) — v4.8.0+
+
+The skill replicates **nothing**. The CLI owns the entire decision space; the
+skill runs it and reports. What the CLI does on its own under bare `--yes`:
+
+- **Preview**: prints the upstream CHANGELOG entries between the installed and
+  remote versions (the old `git log HEAD..FETCH_HEAD -- .framework/` was always
+  empty under subtree-squash — that dead preview is gone).
+- **Working-tree stash**: a single blanket `git stash push -u` auto-stashes any
+  dirty non-framework work and re-applies it after the update (or after the
+  reset). Handles tracked files inside `.gitignore`d dirs — the exact case the
+  old manual workaround failed on.
+- **Divergence** (consumer commits on `.framework/`): classified by the CLI.
+  `all-noise` (subtree plumbing / collaboration merges / CLI `[CHORE]`) →
+  silent. `overlay-able` where every edit is already covered by an overlay →
+  clean reinstall (`--reset`) that re-applies the overlays. `overlay-able`
+  uncovered → **auto-captured into populated overlays and VERIFIED** (the merge
+  must reproduce the edit) before the reinstall. `mixed` / `real-custom` (a
+  `src/`, CHANGELOG, … change) → the overlay-able subset is captured, then the
+  CLI **stops once** (action `divergence-capture-incomplete`) because non-overlay
+  paths can't be auto-resolved.
+- **Hooks drift**, **schema config drift**, **BALDART-managed auto-commit**,
+  **CLI self-upgrade** (`npx baldart@latest` relaunch) — all silent as before.
+
+Explicit overrides still exist for power users / CI (`--on-divergence
+pull|scaffold-overlays|abort`, `--reset --yes --i-know`) but are NOT the path
+the skill or the user needs anymore — the default IS the seamless path.
 
 ## 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.
+> In AUTONOMOUS mode follow `## Autonomous mode` instead. All three steps below
+> (pre-flight, run, post-flight) are shared by both modes — the only difference
+> is autonomous uses `--json` and never prints to chat. There are NO chat
+> confirmation steps anymore: the update is seamless.
 
 ### Step 0 — Pre-flight (read-only)
 
@@ -372,7 +380,7 @@ without suffix only when strictly required; if unsure, ASK the user.
 
 - Patterns 1 or 4 → "Already up-to-date — version v<installedVersion>". STOP.
   Do not launch the CLI.
-- Patterns 2 or 3 → continue with Step 1 (preview + update).
+- Patterns 2 or 3 → continue with Step 1 (run the CLI).
 - Pattern 5 → ask the user: "Vuoi forzare un fetch e ritentare, o procedere
   in modalità offline (l'update fallirà nel CLI)?". STOP if unclear.
 - **No pattern matches** → the CLI output format is unknown. Tell the user:
@@ -382,87 +390,27 @@ without suffix only when strictly required; if unsure, ASK the user.
 
 If `.framework/` does not exist, `npx baldart version` will say "framework not installed" — STOP and instruct `npx baldart add`. Do not attempt to recover.
 
-### Step 1 — Replicate decision point #1 (preview)
+### Step 1 — Run the CLI (seamless, one shot)
 
 ```bash
-# Use the URL extracted from Step 0, not `git -C .framework`.
-# This mirrors src/utils/git.js (fetch + diffWithRemote use FETCH_HEAD,
-# never `git -C .framework`).
-git fetch <BALDART-repo-url> main
-git log HEAD..FETCH_HEAD --oneline -- .framework/
-```
-
-Surface to the user:
-
-- Current installed version (from Step 0).
-- Number of commits behind (from Step 0).
-- One-line summary of each incoming commit (from the `git log` above).
-
-Ask: *"Procedo con l'aggiornamento?"*. If no → STOP.
-
-### Step 2 — Replicate decision point #2 (working tree)
-
-```bash
-git status --porcelain
+npx baldart update --yes
 ```
 
-If output is empty, proceed silently. If not, list the modified files in
-chat, explain:
-
-> *"Il working tree ha N file modificati. Il CLI li stasherà in un ref
-> `baldart-pre-update-<timestamp>` prima del pull e li ripristinerà dopo.
-> Posso procedere con lo stash automatico?"*
-
-If the user refuses → STOP, instruct them to commit or stash manually
-and re-run `/baldart-update`.
-
-### Step 3 — Run the CLI
+**Use the Bash tool with `timeout: 600000`** (10 minutes). Capture stdout and
+stderr — both are needed for Step 2. Do NOT pass `--auto-stash` (redundant with
+`--yes`), `--on-divergence`, or `--reset`: the seamless default already does the
+right thing. There is no chat confirmation before this — running the skill IS the
+authorization (the user asked to update; the CLI has a backup tag + rollback for
+safety).
 
-```bash
-npx baldart update --yes
-```
+Everything the CLI handles on its own is listed in **"## Everything the CLI
+auto-resolves"** above. The one outcome that is NOT a clean success is a non-zero
+exit with action `divergence-capture-incomplete`: an edit could not be
+captured+verified faithfully. Do NOT retry with `--on-divergence` or `--reset` to
+force past it — surface the verbatim blockers + `next_command` and stop (Step 2
+report covers this).
 
-**Use the Bash tool with `timeout: 600000`** (10 minutes). Capture stdout
-and stderr — both are needed for Step 4.
-
-Do NOT pass `--auto-stash` (redundant with `--yes`).
-
-**What the CLI auto-resolves without prompting** (since v3.26.0):
-
-- **Hooks drift**: missing hooks are auto-registered silently. Hooks with
-  modified commands stay user-customised (warning surfaced in `--yes` mode,
-  interactive prompt otherwise).
-- **Schema config drift**: new config keys are reported as a warning; the
-  user is told to run `npx baldart configure` later. The update never
-  blocks on schema drift.
-- **BALDART-managed auto-commit**: in `--yes` mode the CLI commits any
-  files it touched during the reconcile with `chore(baldart): post-update
-  reconcile to vX.Y.Z`. User-owned files are never staged.
-- **Subtree-merge / chore divergence commits**: when the consumer has
-  local commits that are just `git subtree pull` plumbing, ordinary
-  collaboration merges (detected by parent count, not just subject), or
-  CLI-generated `[CHORE]` commits, the CLI auto-resolves silently. Real
-  user-custom commits do NOT auto-resolve under bare `--yes` — but an agent
-  is no longer dead-ended: pass `--on-divergence` to resolve non-interactively
-  (since v3.29.0):
-  - `--on-divergence scaffold-overlays` → auto-creates overlay skeleton(s)
-    for the overlay-able commits, then stops so the edits can be filled in
-    (then re-run update). Use this when the divergence is `overlay-able`.
-  - `--on-divergence pull` → keeps the commits and lets the subtree pull
-    create a merge (non-destructive; resolve any conflicts that surface).
-    Works for `overlay-able`, `mixed`, and `real-custom`.
-  - `--on-divergence abort` → explicit no-op.
-  Bare `--yes` without a strategy still refuses (and now prints exactly which
-  flag to re-run with), so nothing destructive happens by accident.
-- **CLI self-upgrade**: if the global CLI is older than npm latest, the
-  update transparently relaunches itself via `npx baldart@latest update
-  --yes`. Loop-guarded by `BALDART_RELAUNCHED=1`.
-
-The skill no longer chat-replicates these decision points — they are
-either silent (no user choice involved) or only triggered by genuine
-user content, in which case the CLI surfaces the prompt directly.
-
-### Step 4 — Post-flight assert + Report
+### Step 2 — Post-flight assert + Report
 
 **Post-flight assert (MANDATORY — safety net against silent CLI bugs)**:
 
@@ -555,10 +503,11 @@ possible actions (install, configure, migrate, repair symlinks, register
 hooks, reconcile state ledger, …). When the user knows they want *only*
 to update, going through the doctor is more friction than signal.
 
-This skill is the direct path for that case, **and** it does what the
-terminal CLI does — surface every decision point as a confirmation —
-inside the chat instead of in the user's shell. The user keeps the
-control they would have in a TTY, but they get it conversationally.
+This skill is the direct path for that case: a single seamless `npx baldart
+update --yes` that updates and preserves overlays with zero friction, plus a
+mandatory post-flight assert and a clean report. The user no longer trades
+control for friction — the CLI's backup tag + rollback and its
+capture+verify safety pause keep the work safe without a wall of prompts.
 
 `/baldart-push` and `/baldart-update` together form the conversational
 spine of BALDART maintenance:
@@ -568,7 +517,7 @@ spine of BALDART maintenance:
 
 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
+is seamless in both modes; when run unattended (autonomous — CI / scheduled
+routine) it uses `--json`, but in both it leans on 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": "4.7.0",
+  "version": "4.8.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/overlay.js

@@ -486,4 +486,4 @@ async function drift(target, options = {}) {
   UI.info(`Summary: ${clean} clean, ${drifted} drifted, ${unknown} unknown — of ${targets.length} overlay(s).`);
 }
 
-module.exports = { scaffold, scaffoldFile, validate, drift, parseTarget, analyzeSkillConcat };
+module.exports = { scaffold, scaffoldFile, validate, drift, parseTarget, analyzeSkillConcat, buildFrontmatter };