baldart 3.35.0 → 3.35.2

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.35.2] - 2026-05-30
+
+Resolves the **3.35.1 known follow-up**: a flag introduced in a newer release (e.g. `--on-divergence`, v3.29.0) was rejected by an older global CLI with a cryptic `error: unknown option` **before** the `npx baldart@latest` auto-relaunch could self-upgrade — commander validates options during `program.parse()`, which runs *before* the action handler where the relaunch lives. The `update` command now parses **permissively**, so an unknown flag is captured instead of crashing the parser; the action then transparently relaunches under `@latest` (forwarding the raw argv so the unrecognized flag survives) or, when that isn't possible, emits an **actionable** error instead of commander's cryptic one. **No new `baldart.config.yml` keys** — the schema-propagation rule does not apply.
+
+> **Forward-looking by nature.** This cannot retroactively fix CLIs *already* installed at a pre-3.35.2 version — their commander still throws before any code we control runs. The fix rescues flags introduced *after* this release for anyone on 3.35.2+. For older installs the only path remains `npm i -g baldart@latest` (now surfaced by the helpful error + the update notifier).
+
+### Fixed — self-upgrade survives flags newer than the installed CLI
+
+- **[bin/baldart.js](bin/baldart.js)**: the `update` command gains `.allowUnknownOption()` + `.allowExcessArguments()` (scoped to `update` only — every other command keeps strict validation). Unknown tokens now land in `command.args` instead of throwing `commander.unknownOption` during parse; they are forwarded to `update(options, command.args)`.
+- **[src/commands/update.js](src/commands/update.js)** (`update`): an early unknown-flag block runs **before** any work. When unknown tokens are present it relaunches under `npx baldart@latest`, forwarding `process.argv.slice(3)` (raw flags, with the leading `update` subcommand token stripped so the child isn't spawned as `update update …`). The unrecognized flag never enters `options`, so raw-argv forwarding is the only faithful path.
+- **[src/commands/update.js](src/commands/update.js)** (`maybeRelaunchUnderLatest`): accepts `extra.rawArgs` (forward verbatim instead of reconstructing from parsed `options`) and `extra.unknown` (skip the interactive "proceed with current CLI" prompt — pointless when the CLI literally can't parse the flag; relaunch whenever a newer version exists). The normal stale-CLI relaunch path is unchanged (still reconstructs known flags, still forwards `--on-divergence` / `--json`).
+- **[src/commands/update.js](src/commands/update.js)** (`failOnUnknownArgs`): new helpful terminal error replacing commander's cryptic message — hedges between "recently-added flag → `npm i -g baldart@latest`" and "typo", and **suppresses the upgrade suggestion** when `BALDART_RELAUNCHED=1` (we are already the `@latest` child, so a typo is the only explanation). `--json`-aware: emits a `usage-error` JSON object on stdout.
+- **[src/commands/update.js](src/commands/update.js)**: `--json` mode is now **armed before** the unknown-flag block so the relaunch notice / helpful error route to STDERR — preserving the single-object STDOUT contract for `update --json --yes --<new-flag>` (the agent/CI scenario this machinery exists for).
+
+## [3.35.1] - 2026-05-30
+
+Fixes a **HIGH-severity** bug where `baldart update --reset` could leave a consumer **committed-without-`.framework/`** (broken install, manual recovery only). The reset path wiped `.framework/`, committed the deletion, then handed off to `add()` **programmatically with no repository** — the bin-layer default (`antbald/BALDART`) only applies on the CLI path, so `repo` arrived `undefined`, crashing at `repo.startsWith(...)` ("Cannot read properties of undefined") *after* the wipe was already committed. Three layers now make this unreachable: (1) repo resolved **before** any destructive step, (2) reinstall failures roll back to the pre-reset backup tag, (3) defensive guards + legible errors. **No new `baldart.config.yml` keys** — the schema-propagation rule does not apply.
+
+### Fixed — `update --reset` never leaves the consumer without `.framework/`
+
+- **[src/commands/update.js](src/commands/update.js)** (`runReset`): the upstream repo is now resolved via `State.resolveRepo()` **before** the backup tag / `rm -rf` / reset commit, then threaded **explicitly** into `add()` (was `addCmd(undefined, { yes: true })` — the root cause). The stale v3.28.1 comment claiming "undefined → use default from package.json" (which never existed in `add.js`) is corrected.
+- **[src/commands/update.js](src/commands/update.js)**: the reinstall is wrapped in a `try/catch` that, on **any** failure (undefined repo, network, ignored path, missing hooks), auto-runs `git reset --hard <backupTag>` to restore the pre-reset `.framework/` and prints an explicit recovery command. Safe because reset is gated on a clean working tree — the backup tag holds everything but the reset commit.
+- **[src/commands/add.js](src/commands/add.js)**: new `options.throwOnError` makes `add()` **re-throw** instead of `process.exit(1)` at every reachable failure point (download catch, gitignore-still-ignored, hooks-missing post-flight), so a programmatic caller can recover. CLI behavior is unchanged (flag absent → historical exit-1). Also resolves a falsy `repo` from the ledger as a last resort and fails fast **before** download with a recovery hint.
+- **[src/utils/git.js](src/utils/git.js)** (`normalizeRepoUrl`): guards a falsy/non-string `repo` with a legible `Error` ("repository non specificato …") instead of the cryptic `Cannot read properties of undefined (reading 'startsWith')`.
+
+### Changed — shared repo resolver (de-dup)
+
+- **[src/utils/state.js](src/utils/state.js)**: new exported `resolveRepo(cwd)` (cascade `state.framework_repo → DEFAULT_REPO`, never `undefined`, preserves a consumer's fork) + exported `DEFAULT_REPO` constant. `recordInstall` now uses the constant.
+- **[src/commands/version.js](src/commands/version.js)**: drops its local `REPO_DEFAULT` duplicate in favor of the shared `State.DEFAULT_REPO`.
+
+### Known follow-up (separate fix)
+
+- `--on-divergence` (v3.29.0) is rejected by an **older global CLI** with "unknown option" *before* the `npx baldart@latest` auto-relaunch can self-upgrade (commander validates options first). Tracked separately — workaround: `npm i -g baldart@latest` before using new flags.
+
 ## [3.35.0] - 2026-05-30
 
 De-duplicates the review chain in `/new` and adds a **Review Profile Selector** so the per-card pre-merge gate scales its *depth* by risk instead of running the full multi-agent `/codexreview` on every card — including trivial ones. The per-card gate stays **unconditional** (it always runs); only its breadth varies, and the safety-critical Codex adversarial pass + false-positive gate run on every card regardless of profile. Copertura invariata: every line is still code-reviewed once, every doc doc-reviewed once. **No new `baldart.config.yml` keys** — the profile is computed at runtime from signals already present (the Phase 3.7 high-risk-trigger detector + the QA profile), and lean mode is an internal caller→skill file contract, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.35.0
+3.35.2

package/bin/baldart.js

@@ -81,9 +81,24 @@ program
   .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) => {
+  // Parse permissively so an UNKNOWN flag does not crash commander before the
+  // CLI self-upgrade can kick in (v3.35.2+). The whole point of `update` is to
+  // be the self-healing entrypoint: when a flag introduced in a newer release
+  // reaches an older-but-still-this-or-later CLI, commander used to throw
+  // `error: unknown option` during parse — i.e. BEFORE the action handler runs,
+  // so the auto-relaunch under `npx baldart@latest` (which lives in the action)
+  // never got a chance. With both guards set, unknown tokens land in
+  // `command.args` instead of throwing; the action forwards them to a newer CLI
+  // (or emits a helpful error). Scoped to `update` only — every other command
+  // keeps strict validation.
+  .allowUnknownOption()
+  .allowExcessArguments()
+  .action(async (options, command) => {
     const updateCommand = require('../src/commands/update');
-    await updateCommand(options);
+    // command.args holds any tokens commander could not match to a known
+    // option/positional — for `update` (no positionals) that means unknown
+    // flags + their values. Forward them so update() can self-upgrade.
+    await updateCommand(options, command.args || []);
   });
 
 program

package/package.json

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

package/src/commands/add.js

@@ -14,6 +14,24 @@ async function add(repo, options) {
   // rm -rf `.framework/` themselves, so `git.frameworkExists()` is false
   // here and the destructive prompt is never reached.
   const nonInteractive = options && options.yes === true;
+  // When `add` is invoked programmatically (e.g. `update --reset`) the caller
+  // wants failures to bubble up so it can roll back, instead of add()'s default
+  // `process.exit(1)` which would kill the parent before it can recover.
+  const throwOnError = options && options.throwOnError === true;
+
+  // Repo resolution safety net. The CLI entrypoint (bin/baldart.js) defaults
+  // `repo` to the upstream before calling here, but programmatic callers may
+  // pass undefined. Resolve from the consumer's ledger (preserves forks) so
+  // we never reach git.addSubtree() with an undefined repo (the crash that
+  // broke `update --reset`: "Cannot read properties of undefined").
+  if (!repo) repo = State.resolveRepo();
+  if (!repo) {
+    UI.error('No framework repository to install from.');
+    UI.info('Expected from .baldart/state.json → framework_repo. Recover with:');
+    UI.info('  npx baldart add <owner/repo> --yes');
+    if (throwOnError) throw new Error('add: repository unresolved (state.json framework_repo empty)');
+    process.exit(1);
+  }
 
   try {
     // Step 1: Verify environment
@@ -114,10 +132,16 @@ async function add(repo, options) {
           UI.error('.framework/ is STILL ignored after auto-heal — install would fail.');
           UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
           UI.info('Resolve by removing that rule, then re-run `baldart add`.');
-          process.exit(1);
+          // Deliberate abort — flag it so the local catch propagates instead of
+          // downgrading to a warning, and let the single outer catch decide
+          // throw (throwOnError) vs process.exit (CLI).
+          const e = new Error('.framework/ still ignored after auto-heal');
+          e.fatalInstall = true;
+          throw e;
         }
       }
     } catch (err) {
+      if (err && err.fatalInstall) throw err;
       UI.warning(`Could not check .gitignore for .framework: ${err.message}`);
     }
 
@@ -139,11 +163,12 @@ async function add(repo, options) {
         '  • No internet connection',
         '  • Repository not accessible',
         `  • Invalid repository: ${repo}`,
+        '    (resolved from .baldart/state.json → framework_repo, else default)',
         '',
         'Solution:',
         '  • Check your internet connection',
-        '  • Verify repository exists',
-        '  • Try again later'
+        '  • Verify the repository exists / is reachable',
+        '  • Recover with an explicit repo: npx baldart add <owner/repo> --yes'
       ]);
       throw error;
     }
@@ -293,6 +318,13 @@ async function add(repo, options) {
           : `Hooks missing after install: ${verify.missing.join(', ')}. Install is NOT complete.`
       );
       UI.info('Run `npx baldart doctor` to repair, then re-check `npx baldart status`.');
+      if (throwOnError) {
+        throw new Error(
+          verify.malformed
+            ? 'settings.json malformed — hooks unverifiable'
+            : `hooks missing after install: ${verify.missing.join(', ')}`
+        );
+      }
       process.exit(1);
     }
 
@@ -339,6 +371,9 @@ async function add(repo, options) {
 
   } catch (error) {
     UI.error(`Installation failed: ${error.message}`);
+    // Programmatic callers (update --reset) need the failure to bubble so they
+    // can roll back; the CLI entrypoint keeps the historical exit-1 behavior.
+    if (throwOnError) throw error;
     process.exit(1);
   }
 }

package/src/commands/doctor.js

@@ -36,7 +36,6 @@ const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
 
 const FRAMEWORK_DIR = '.framework';
-const REPO_DEFAULT = 'antbald/BALDART';
 const CONFIG_FILE = 'baldart.config.yml';
 
 // ──────────────────────────────────────────────────────────────────────
@@ -214,7 +213,7 @@ async function detectState(cwd, opts = {}) {
       };
     }
 
-    state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
+    state.remote = await describeRemote(git, ledger.framework_repo || State.DEFAULT_REPO, !!opts.offline);
     state.commitsAhead = await commitsAheadOfRemote(git, state.remote);
     state.workingTreeDirty = await localFrameworkChanges(git);
 
@@ -360,7 +359,9 @@ function planActions(state) {
       autoOk: false,
       run: async () => {
         const add = require('./add');
-        await add(REPO_DEFAULT, { branch: 'main' });
+        // Fork-aware: resolve from the ledger (preserves a consumer's fork)
+        // rather than hardcoding the upstream default.
+        await add(State.resolveRepo(state.cwd), { branch: 'main' });
       },
     });
     return actions;

package/src/commands/update.js

@@ -255,6 +255,15 @@ async function runReset(git, options, autoYes) {
     }
   }
 
+  // Resolve the upstream repo BEFORE anything destructive. The reinstall hands
+  // off to add() programmatically (no bin-layer default), so an unresolved repo
+  // would surface as "Downloading from undefined" / "Cannot read properties of
+  // undefined" AFTER .framework/ was already wiped and committed. Resolving here
+  // (state.framework_repo → default, never undefined) makes that unreachable and
+  // preserves a consumer's fork.
+  const repo = State.resolveRepo();
+  UI.info(`Reinstall source: ${repo}`);
+
   // Safety gate #3: backup tag before doing anything destructive.
   const backupTag = await git.createBackupTag();
   UI.success(`Backup tag created: ${backupTag}`);
@@ -310,12 +319,42 @@ async function runReset(git, options, autoYes) {
   UI.newline();
   UI.info('Re-installing framework via `baldart add`…');
   const addCmd = require('./add');
-  // `add(repo, options)` — first arg is the repo URL (undefined → use default
-  // from package.json). Pre-v3.28.1 we incorrectly passed `{ yes: true }` as
-  // the first arg, so `options` was undefined and every interactive prompt
-  // ("Install framework?", "Configure git aliases?", …) fired despite the
-  // parent `update --reset --yes --i-know` having already established intent.
-  await addCmd(undefined, { yes: true });
+  // `add(repo, options)` — the repo MUST be threaded explicitly: the bin-layer
+  // default ('antbald/BALDART') only applies when add is invoked from the CLI,
+  // not on this programmatic path (the v3.28.1 comment claiming "undefined →
+  // default from package.json" was wrong and caused the undefined-repo crash).
+  // `throwOnError` makes add() re-throw instead of process.exit(1), so a failed
+  // reinstall lands in the catch below and we can roll back to the backup tag —
+  // the consumer is NEVER left committed-without-.framework/.
+  try {
+    await addCmd(repo, { yes: true, throwOnError: true });
+  } catch (err) {
+    UI.newline();
+    UI.error(`Reinstall failed: ${err.message}`);
+    UI.warning('Rolling back to pre-reset state…');
+    try {
+      await git.git.raw(['reset', '--hard', backupTag]);
+      // The clean-tree gate (hasCleanWorkingTree → status.isClean(), which counts
+      // untracked) guaranteed ZERO untracked files at backup-tag time, so every
+      // untracked file now is partial-install cruft created by the failed add()
+      // (symlinks, copied templates) — safe to sweep. `-d` dirs, no `-x` so
+      // gitignored paths are left untouched. Non-fatal: .framework/ is already
+      // restored by the reset above regardless.
+      try {
+        await git.git.raw(['clean', '-fd']);
+      } catch (cleanErr) {
+        UI.warning(`Could not sweep partial-install leftovers (${cleanErr.message}). .framework/ is restored; run \`git clean -fd\` to tidy.`);
+      }
+      UI.success(`Restored .framework/ from ${backupTag}. Working tree back to pre-reset state.`);
+    } catch (rollbackErr) {
+      UI.error(`Auto-rollback FAILED: ${rollbackErr.message}`);
+      UI.info(`Recover manually: git reset --hard ${backupTag}`);
+    }
+    UI.newline();
+    UI.info('Then retry, or reinstall explicitly:');
+    UI.info(`  npx baldart add ${repo} --yes`);
+    process.exit(1);
+  }
 
   // Post-restore sanity check — confirm nothing user-owned got clobbered.
   const stillPresent = {
@@ -367,7 +406,16 @@ function snapshotCustomEntries(dir) {
 // child inherits stdio (preserves prompts), and BALDART_RELAUNCHED=1 in env
 // is a loop guard: if npm cache somehow serves an older version, the child
 // sees the flag and skips its own relaunch check.
-async function maybeRelaunchUnderLatest(options) {
+// `extra.rawArgs` — when set, forward these verbatim to the child instead of
+// reconstructing flags from the parsed `options`. Used by the unknown-flag path
+// (v3.35.2+): an option this CLI doesn't recognize never lands in `options`, so
+// reconstruction would silently drop it — only the raw argv carries it intact.
+// The caller MUST have already stripped the leading `update` subcommand token.
+// `extra.unknown` — true when triggered by an unknown flag rather than a plain
+// stale-CLI check. In that case the interactive "proceed with current CLI"
+// branch is pointless (the current CLI literally cannot honor the flag), so we
+// relaunch whenever a newer version exists and skip the prompt.
+async function maybeRelaunchUnderLatest(options, extra = {}) {
   if (process.env.BALDART_RELAUNCHED === '1') return false;
   if (process.env.BALDART_NO_RELAUNCH === '1') return false;
 
@@ -385,7 +433,13 @@ async function maybeRelaunchUnderLatest(options) {
 
   const autoYes = options.yes === true;
   let proceed = autoYes;
-  if (!autoYes) {
+  if (extra.unknown) {
+    // Unknown flag + a newer CLI exists: relaunch unconditionally. Asking
+    // "proceed with current CLI?" makes no sense — it can't parse the flag.
+    proceed = true;
+    UI.newline();
+    UI.warning(`Unknown option for the installed CLI (v${cliVersion}); a newer release (v${info.latest}) may support it.`);
+  } else if (!autoYes) {
     UI.newline();
     UI.warning(`The installed CLI is older than npm latest: v${cliVersion} → v${info.latest}.`);
     const choice = await UI.select('How would you like to proceed?', [
@@ -401,17 +455,24 @@ async function maybeRelaunchUnderLatest(options) {
   }
   if (!proceed) return false;
 
-  // Reconstruct the original argv flags for the child.
-  const flags = [];
-  if (options.yes === true) flags.push('--yes');
-  if (options.autoStash === true && options.yes !== true) flags.push('--auto-stash');
-  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');
+  // Build the child argv. The unknown-flag path forwards the raw argv (already
+  // stripped of the `update` token); the normal stale-CLI path reconstructs
+  // from parsed options.
+  let flags;
+  if (Array.isArray(extra.rawArgs)) {
+    flags = extra.rawArgs;
+  } else {
+    flags = [];
+    if (options.yes === true) flags.push('--yes');
+    if (options.autoStash === true && options.yes !== true) flags.push('--auto-stash');
+    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}…`);
@@ -427,7 +488,30 @@ async function maybeRelaunchUnderLatest(options) {
   process.exit(res.status || 0);
 }
 
-async function update(options = {}) {
+// Helpful terminal error when an unknown flag reached this CLI and a relaunch
+// under a newer version was not possible (already on latest / offline / opted
+// out, or we ARE the relaunched child). Replaces commander's cryptic
+// `error: unknown option` with actionable guidance. (v3.35.2+)
+function failOnUnknownArgs(unknownArgs, options) {
+  const tokens = unknownArgs.filter((a) => typeof a === 'string');
+  const firstOpt = tokens.find((a) => a.startsWith('-')) || tokens[0] || '(unknown)';
+  // In the relaunched child we are already on @latest, so "upgrade" is wrong —
+  // an unknown flag here means a genuine typo.
+  const alreadyLatest = process.env.BALDART_RELAUNCHED === '1';
+  const reason = alreadyLatest
+    ? `Unknown option ${firstOpt}. Even the latest CLI does not recognize it — check for a typo.`
+    : `Unknown option ${firstOpt}. If it is a recently-added flag, upgrade with \`npm i -g baldart@latest\`; otherwise check for a typo.`;
+  if (options.json === true) {
+    emitUpdateJson({ ok: false, action: 'usage-error', reason }, 2);
+  }
+  UI.error(reason);
+  if (!alreadyLatest) {
+    UI.info(`Then retry: npx baldart update ${tokens.join(' ')}`.trim());
+  }
+  process.exit(2);
+}
+
+async function update(options = {}, unknownArgs = []) {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
   const repo = 'antbald/BALDART'; // Default repo
@@ -439,13 +523,35 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Arm machine-readable mode FIRST (v3.35.2+). The unknown-flag handling below
+  // can emit human lines (relaunch notice / helpful error); they must route to
+  // STDERR before anything reaches STDOUT, or a `--json --yes --new-flag` run
+  // would pollute the single-object stdout contract.
+  JSON_MODE = options.json === true;
+  if (JSON_MODE) UI.setJsonMode(true);
+
+  // Unknown-flag self-upgrade (v3.35.2+). Commander now parses `update`
+  // permissively (see bin/baldart.js), so a flag this CLI doesn't know lands
+  // in `unknownArgs` instead of crashing the parser. That flag was almost
+  // certainly introduced in a newer release — transparently relaunch under
+  // `npx baldart@latest`, forwarding the RAW argv (the unknown token never made
+  // it into `options`, so only raw argv carries it). If we can't relaunch
+  // (already latest / offline / opted out / we ARE the child), fail with an
+  // actionable message instead of a cryptic crash.
+  if (Array.isArray(unknownArgs) && unknownArgs.length > 0) {
+    // process.argv = [node, baldart, 'update', ...flags] — drop the first 3 so
+    // the child isn't spawned as `update update …` (it already gets 'update').
+    const rawArgs = process.argv.slice(3);
+    await maybeRelaunchUnderLatest(options, { rawArgs, unknown: true });
+    // Relaunch did not happen → this (latest-or-offline) CLI can't honor it.
+    failOnUnknownArgs(unknownArgs, options);
+  }
+
   // 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);

package/src/commands/version.js

@@ -3,7 +3,6 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const UpdateNotifier = require('../utils/update-notifier');
 
-const REPO_DEFAULT = 'antbald/BALDART';
 const FRAMEWORK_DIR = '.framework';
 
 function fmtDate(iso) {
@@ -61,7 +60,7 @@ async function version(opts = {}) {
     const verbose = opts.verbose === true;
 
     // SSOT (v3.25.0+): one query, version-compare authority.
-    const repo = state.framework_repo || REPO_DEFAULT;
+    const repo = state.framework_repo || State.DEFAULT_REPO;
     let status;
     if (opts.offline === true) {
       status = {

package/src/utils/git.js

@@ -144,6 +144,17 @@ class GitUtils {
     // - "https://github.com/owner/repo" -> "https://github.com/owner/repo.git"
     // - "https://github.com/owner/repo.git" -> unchanged
 
+    // Fail loud and legible instead of "Cannot read properties of undefined
+    // (reading 'startsWith')". A falsy repo here means a caller skipped repo
+    // resolution (see State.resolveRepo) — surface that, don't crash cryptically.
+    if (!repo || typeof repo !== 'string') {
+      throw new Error(
+        `normalizeRepoUrl: repository non specificato (got ${JSON.stringify(repo)}). ` +
+        `Risolvilo via .baldart/state.json → framework_repo o passalo esplicito ` +
+        `(es. npx baldart add <owner/repo> --yes).`
+      );
+    }
+
     if (repo.startsWith('http://') || repo.startsWith('https://')) {
       return repo.endsWith('.git') ? repo : `${repo}.git`;
     }

package/src/utils/state.js

@@ -35,6 +35,13 @@ const STATE_FILE = path.join(STATE_DIR, 'state.json');
 const STATE_VERSION = 1;
 const HISTORY_LIMIT = 20;
 
+// Upstream framework repository. SSOT for the "where do we install from"
+// default — duplicated literals in version.js / doctor.js / recordInstall
+// used to drift independently. Always resolve through `resolveRepo()` so a
+// consumer's fork (recorded in state.framework_repo at install time) is
+// preserved instead of being silently overridden by this constant.
+const DEFAULT_REPO = 'antbald/BALDART';
+
 function defaultState() {
   return {
     state_version: STATE_VERSION,
@@ -87,7 +94,7 @@ function recordInstall({ version, repo }, cwd = process.cwd()) {
   const now = new Date().toISOString();
   const wasFirstInstall = !state.installed_version;
   state.installed_version = version;
-  state.framework_repo = repo || state.framework_repo || 'antbald/BALDART';
+  state.framework_repo = repo || state.framework_repo || DEFAULT_REPO;
   if (wasFirstInstall) state.install_date = now;
   state.history = appendHistory(state, {
     event: wasFirstInstall ? 'install' : 'reinstall',
@@ -142,6 +149,20 @@ function recordPush({ from, to, description }, cwd = process.cwd()) {
   return state;
 }
 
+/**
+ * Resolve the upstream framework repository to install/update from. Cascade:
+ * `state.framework_repo` (recorded at install — preserves a consumer's fork)
+ * → DEFAULT_REPO. Never returns undefined, so callers that thread the result
+ * into git.addSubtree() / normalizeRepoUrl() can't trip the "undefined repo"
+ * crash that broke `update --reset` (it called add() with no repo).
+ *
+ * `baldart.config.yml` and the subtree's git remote are intentionally NOT
+ * consulted — neither stores the repo, so they'd be dead lookups.
+ */
+function resolveRepo(cwd = process.cwd()) {
+  return load(cwd).framework_repo || DEFAULT_REPO;
+}
+
 /**
  * Read the framework's VERSION file from .framework/VERSION. Used by version /
  * status commands to cross-check what the symlinked framework reports vs what
@@ -164,7 +185,9 @@ module.exports = {
   recordUpdate,
   recordPush,
   reconcileInstalledVersion,
+  resolveRepo,
   readFrameworkVersion,
+  DEFAULT_REPO,
   STATE_FILE,
   STATE_VERSION,
 };