maiass 5.14.2 → 5.15.3

package/README.md

@@ -10,7 +10,9 @@
 
 ---
 
-Run `maiass` in any git repo and it stages your changes, writes the commit message, bumps the version, updates the changelog, and merges the branch. It's for developers who do this routine every day and want the keystrokes back. Anonymous on first run — no email, no card, no sign-up.
+Run `maiass` in any git repo and it commits your staged changes, writes the commit message, bumps the version, updates the changelog, and merges the branch. It's for developers who do this routine every day and want the keystrokes back. Anonymous on first run — no email, no card, no sign-up.
+
+By default MAIASS only ever commits changes you have already staged — it leaves unstaged and untracked files alone. To have it stage everything for you, either answer the interactive prompt, pass `--auto-stage` for a single run, or set `MAIASS_AUTO_STAGE_UNSTAGED=true` to make it the default.
 
 > Site: [maiass.net](https://maiass.net) · Bash/Homebrew source: [bashmaiass](https://github.com/vsmash/bashmaiass)
 
@@ -47,8 +49,11 @@ maiass
 maiass minor    # 1.2.3 → 1.3.0
 maiass major    # 1.2.3 → 2.0.0
 
-# Commit only, skip version management
-maiass --commits-only
+# Interactive commit-only, skip version management
+maiass --commits-only        # short: -c or -co
+
+# Unattended commit-only — commit STAGED changes, push, then stop (no merge, no bump)
+maiass --unattended-commit   # short: -uc (interactive sibling: -co / --commits-only)
 
 # Preview without making changes
 maiass --dry-run patch

package/lib/account-info.js

@@ -444,7 +444,7 @@ export async function handleAccountInfoCommand(options = {}) {
       console.log('Explanation:     Your token was rejected. Ensure it is correct, not expired, and associated with an active subscription.');
     } else if (result.status === 401 || statusField === 401) {
       console.log('Status:          401 Unauthorized');
-      console.log('Explanation:     Missing or invalid credentials. Try updating your token with \'nma config --global maiass_token=your_token\'.');
+      console.log('Explanation:     Missing or invalid credentials. Try updating your token with \'maiass config --global maiass_token=your_token\'.');
     } else if (result.status >= 200 && result.status < 300) {
       console.log(`Status:          ${result.status} OK`);
     } else {

package/lib/bootstrap.js

@@ -552,6 +552,10 @@ MAIASS_STAGINGBRANCH=${config.branches.staging}
 
   // Add standard options
   content += `# Auto-Yes Functionality (for CI/CD and non-interactive mode)
+# MAIASS_AUTO_STAGE_UNSTAGED: opt-in only (MAI-93). When false (default), even
+# unattended runs (-a / -uc / --silent) commit ONLY already-staged changes and
+# leave unstaged/untracked files alone. Set to true to restore the old
+# 'git add -A' sweep that stages everything before committing.
 #MAIASS_AUTO_STAGE_UNSTAGED=false
 #MAIASS_AUTO_PUSH_COMMITS=false
 #MAIASS_AUTO_MERGE_TO_DEVELOP=false

package/lib/commit.js

@@ -1038,16 +1038,34 @@ export async function commitThis(options = {}) {
   // Handle unstaged/untracked changes first
   if (status.unstagedCount > 0 || status.untrackedCount > 0) {
     if (!autoStage) {
+      // MAI-93: auto-staging of unstaged/untracked changes is now strictly
+      // opt-in. The only thing that triggers a `git add -A` sweep here is the
+      // user/config explicitly setting MAIASS_AUTO_STAGE_UNSTAGED=true.
+      const optInAutoStage = process.env.MAIASS_AUTO_STAGE_UNSTAGED === 'true';
+      // An unattended run is one where prompts are auto-answered: either a
+      // silent run, or an auto/-co run that auto-approves AI suggestions.
+      const unattended = silent || process.env.MAIASS_AUTO_APPROVE_AI_SUGGESTIONS === 'true';
+
       let reply;
-      const autoStage = process.env.MAIASS_AUTO_STAGE_UNSTAGED === 'true';
-      if (silent || autoStage) {
+      if (optInAutoStage) {
+        // Explicit opt-in → preserve the historical `git add -A` sweep.
         reply = 'y';
-        if (autoStage) {
-          console.log('🔄 |)) Automatically staging changes (MAIASS_AUTO_STAGE_UNSTAGED=true)');
-        } else {
-          console.log('🔄 |)) Automatically staging changes (silent mode)');
+        console.log('🔄 |)) Automatically staging changes (MAIASS_AUTO_STAGE_UNSTAGED=true)');
+      } else if (unattended) {
+        // MAI-93: unattended but auto-stage OFF → never prompt, never sweep.
+        // Proceed with already-staged changes only.
+        if (status.stagedCount > 0) {
+          log.info(SYMBOLS.INFO, 'Proceeding with staged changes only');
+          return await handleStagedCommit(gitInfo, { silent, dryRun, providedMessage });
         }
+        // Nothing staged → clean no-op (exit 0). This is the unattended
+        // commit-only path with nothing to commit. Use console.log (not
+        // log.info, which is suppressed at brief/normal verbosity) so the
+        // skip reason always surfaces.
+        console.log('Nothing staged; MAIASS_AUTO_STAGE_UNSTAGED=false — skipping commit');
+        return true;
       } else {
+        // Interactive (non-auto) behaviour is unchanged — prompt as before.
         reply = await getSingleCharInput('Do you want to stage and commit them? [y/N] ');
       }
       if (reply === 'y') {

package/lib/config-command.js

@@ -1,5 +1,5 @@
 // Configuration command handler for MAIASS CLI
-// Implements: nma config [options] [key[=value]]
+// Implements: maiass config [options] [key[=value]]
 
 import { log, logger } from './logger.js';
 import colors from './colors.js';

package/lib/config-manager.js

@@ -321,7 +321,7 @@ export function validateConfig(config) {
       errors.push({
         key,
         error: 'Unknown configuration variable',
-        suggestion: 'Check available variables with: nma config --list-vars'
+        suggestion: 'Check available variables with: maiass config --list-vars'
       });
       return;
     }

package/lib/maiass-command.js

@@ -12,8 +12,11 @@ import colors from './colors.js';
  */
 export const FLAGS = [
   '--auto', '-a',
-  '--auto-commit', '-ac',
-  '--commits-only', '-c',
+  // MAI-93: -uc / --unattended-commit is the UNATTENDED commit-only flag
+  // (replaces the removed -ac / --auto-commit).
+  '--unattended-commit', '-uc',
+  // Interactive commit-only. -co is an alias of --commits-only (bash parity).
+  '--commits-only', '-c', '-co',
   '--auto-stage',
   '--dry-run', '-d',
   '--force', '-f',
@@ -21,7 +24,7 @@ export const FLAGS = [
   '--tag', '-t',
   // -m / --message <value>: supply the commit message verbatim, non-interactively
   // (MAI-XX node+bash parity). Bypasses AI + interactive prompt. Works with the
-  // default workflow and commits-only (-c / -ac).
+  // default workflow, commits-only (-c / -co), and unattended-commit (-uc).
   '--message', '-m',
 ];
 

package/lib/maiass-pipeline.js

@@ -239,6 +239,132 @@ async function validateAndHandleBranching(options = {}) {
   };
 }
 
+/**
+ * MAI-93: get the current stash ref SHA, or null if there is no stash.
+ * Used to detect whether `git stash push` actually created a stash (it is a
+ * no-op on a clean tree and we must NOT then try to pop).
+ * @returns {string|null} The SHA of refs/stash, or null if no stash exists.
+ */
+export function getStashRef() {
+  const result = executeGitCommand('git rev-parse --verify --quiet refs/stash', true);
+  if (!result.success) return null;
+  const sha = (result.output || '').trim();
+  return sha.length > 0 ? sha : null;
+}
+
+/**
+ * MAI-93: stash leftover (unstaged tracked + untracked) changes so the
+ * merge/version pipeline runs on a clean tree, avoiding `git checkout`/`git
+ * merge` refusing on collisions or carrying edits onto the wrong branch.
+ *
+ * `git stash push` is a no-op on a clean tree, so we compare refs/stash before
+ * and after to decide whether a stash was actually created. Only when one was
+ * created do we report `stashed: true` — the caller must then pop it.
+ *
+ * @returns {{stashed: boolean, ref: string|null, message: string|null}}
+ */
+export function stashLeftoverChanges() {
+  const before = getStashRef();
+  const message = `maiass-auto-${Date.now()}`;
+  const result = executeGitCommand(
+    `git stash push --include-untracked -m "${message}"`,
+  );
+  if (!result.success) {
+    return { stashed: false, ref: null, message: null };
+  }
+  const after = getStashRef();
+  // A stash was created iff refs/stash now points somewhere new.
+  const stashed = after !== null && after !== before;
+  return { stashed, ref: stashed ? after : null, message: stashed ? message : null };
+}
+
+/**
+ * MAI-93: restore changes stashed by stashLeftoverChanges().
+ *
+ * Runs `git stash pop`. On a clean pop the stash entry is removed and the
+ * user's leftover work is back in the working tree. On a conflicting pop, git
+ * leaves the stash entry INTACT (exit non-zero) — we must NOT discard it; we
+ * surface a prominent warning telling the user where their work lives and
+ * return a non-fatal warning rather than crashing.
+ *
+ * @param {{message?: string|null}} stashInfo - Info from stashLeftoverChanges().
+ * @returns {{success: boolean, conflict: boolean, message?: string}}
+ */
+export function restoreStashedChanges(stashInfo = {}) {
+  const result = executeGitCommand('git stash pop', true);
+  if (result.success) {
+    log.success(SYMBOLS.CHECKMARK, 'Restored your stashed changes to the working tree');
+    return { success: true, conflict: false };
+  }
+
+  // Pop failed — almost always a merge conflict on restore. Do NOT drop the
+  // stash; it is still at stash@{0}. Warn loudly so work is never lost silently.
+  const ref = stashInfo.message ? `stash@{0} (${stashInfo.message})` : 'stash@{0}';
+  console.log();
+  log.warning(SYMBOLS.WARNING, 'Could not automatically restore your stashed changes (conflict on pop)');
+  log.warning(SYMBOLS.WARNING, `Your changes are preserved in ${ref} — resolve manually`);
+  log.info(SYMBOLS.INFO, 'Run `git stash pop` and resolve the conflicts when ready.');
+  return { success: false, conflict: true, message: ref };
+}
+
+/**
+ * MAI-93: guarded stash restore — pop only after we are back on the branch the
+ * stash was taken from.
+ *
+ * On the happy path version management returns us to the original branch before
+ * the finally runs, so a bare pop is fine. But on early-return FAILURE paths
+ * (merge failure, version failure) the pipeline may still be on develop /
+ * release/* when cleanup runs. Popping a user's feature-branch work onto the
+ * wrong branch is worse than not popping, so this:
+ *   1. checks the current branch;
+ *   2. if it differs from the target, attempts a guarded checkout;
+ *   3. only pops if we are (or got) on the target branch;
+ *   4. if we can't get there, PRESERVES the stash and warns where it lives.
+ * It never throws — safe to call from a finally block.
+ *
+ * Dependencies are injectable for unit testing; defaults use the module's git
+ * helpers and the real pop.
+ *
+ * @param {{stashed?: boolean, ref?: string, message?: string|null}} stashInfo
+ * @param {string} targetBranch - branch the stash was captured on.
+ * @param {object} [deps] - { getCurrentBranchFn, switchToBranchFn, restoreFn }
+ * @returns {Promise<{popped: boolean, preserved: boolean, reason?: string}>}
+ */
+export async function restoreStashedChangesOnBranch(stashInfo = {}, targetBranch, deps = {}) {
+  if (!stashInfo || !stashInfo.stashed) {
+    return { popped: false, preserved: false, reason: 'no-stash' };
+  }
+  const getCurrentBranchFn = deps.getCurrentBranchFn || getCurrentBranch;
+  const switchToBranchFn = deps.switchToBranchFn || switchToBranch;
+  const restoreFn = deps.restoreFn || restoreStashedChanges;
+
+  const stashRef = () =>
+    stashInfo.message ? `stash@{0} (${stashInfo.message})` : 'stash@{0}';
+
+  try {
+    const current = getCurrentBranchFn();
+    if (targetBranch && current !== targetBranch) {
+      const switched = await switchToBranchFn(targetBranch);
+      if (!switched) {
+        log.warning(SYMBOLS.WARNING, `Could not return to ${targetBranch} to restore your stashed changes`);
+        log.warning(
+          SYMBOLS.WARNING,
+          `Your changes are preserved in ${stashRef()} — checkout ${targetBranch} and run \`git stash pop\` manually`,
+        );
+        return { popped: false, preserved: true, reason: 'checkout-failed' };
+      }
+    }
+  } catch (e) {
+    // Never let cleanup throw out of a finally — preserve the stash instead.
+    log.warning(SYMBOLS.WARNING, `Could not verify the branch before restoring your stash: ${e.message}`);
+    log.warning(SYMBOLS.WARNING, `Your changes are preserved in ${stashRef()} — restore manually with \`git stash pop\``);
+    return { popped: false, preserved: true, reason: 'branch-check-threw' };
+  }
+
+  restoreFn(stashInfo);
+  return { popped: true, preserved: false };
+}
+
 /**
  * Handle the commit workflow phase
  * @param {Object} branchInfo - Branch information from validation
@@ -265,20 +391,57 @@ async function handleCommitWorkflow(branchInfo, options = {}) {
       return { success: false, cancelled: true, error: 'Commit workflow cancelled by user' };
     }
 
-    // After commit workflow, check if working directory is clean for version management
-    // If we're not in commits-only mode, we need a clean working directory to proceed
+    // After commit workflow, check if working directory is clean for version
+    // management. If we're not in commits-only mode, an unclean working tree
+    // normally stops the pipeline so unrelated work isn't silently swept into
+    // the version bump.
+    //
+    // MAI-93: in an UNATTENDED auto run with auto-stage OFF, the user has
+    // explicitly asked for an unattended bump. The merge/version pipeline does
+    // branch switching (checkout develop, merge, release branch, merge-back),
+    // which `git checkout`/`git merge` will refuse on a dirty tree (or worse,
+    // carry the edits onto the wrong branch). So instead of proceeding dirty we
+    // STASH the leftover changes, let the pipeline run on a clean tree, and the
+    // caller restores them afterward (see runMaiassPipeline's finally block).
+    // Interactive runs keep the protective stop.
     if (!commitsOnly) {
       const postCommitGitInfo = getGitInfo();
       const postCommitStatus = postCommitGitInfo.status;
-      
-      if (postCommitStatus.unstagedCount > 0 || postCommitStatus.untrackedCount > 0) {
-        // Working directory is not clean, cannot proceed with version management
-        console.log();
-        log.warning(SYMBOLS.WARNING, 'Working directory has uncommitted changes');
-        log.info(SYMBOLS.INFO, 'Cannot proceed with version management - pipeline stopped');
-        log.info(SYMBOLS.INFO, `Current branch: ${getCurrentBranch()}`);
-        log.success('', 'Thank you for using MAIASS.');
-        return { success: true, stoppedDueToUncommittedChanges: true };
+      const leftover =
+        (postCommitStatus?.unstagedCount || 0) + (postCommitStatus?.untrackedCount || 0);
+
+      if (leftover > 0) {
+        const optInAutoStage = process.env.MAIASS_AUTO_STAGE_UNSTAGED === 'true';
+        const unattended =
+          silent || process.env.MAIASS_AUTO_APPROVE_AI_SUGGESTIONS === 'true';
+
+        if (unattended && !optInAutoStage) {
+          // MAI-93: stash the leftover changes so the version pipeline runs on a
+          // clean tree. The caller pops the stash once we're back on the
+          // original branch (try/finally — restored even if the pipeline fails).
+          const stashInfo = stashLeftoverChanges();
+          if (stashInfo.stashed) {
+            // Use success-level so it is visible even in brief verbosity (the
+            // default) — the user must know their work was set aside, and the
+            // matching "Restored..." confirmation is also success-level.
+            log.success(
+              SYMBOLS.INFO,
+              `Stashed ${leftover} unrelated change${leftover === 1 ? '' : 's'} for the version pipeline; will restore after`,
+            );
+            return { success: true, stashInfo };
+          }
+          // Push reported success but created no stash (e.g. all leftover was
+          // ignored/no-op) — nothing to restore, proceed normally.
+          return { success: true };
+        } else {
+          // Working directory is not clean, cannot proceed with version management
+          console.log();
+          log.warning(SYMBOLS.WARNING, 'Working directory has uncommitted changes');
+          log.info(SYMBOLS.INFO, 'Cannot proceed with version management - pipeline stopped');
+          log.info(SYMBOLS.INFO, `Current branch: ${getCurrentBranch()}`);
+          log.success('', 'Thank you for using MAIASS.');
+          return { success: true, stoppedDueToUncommittedChanges: true };
+        }
       }
     }
 
@@ -601,6 +764,59 @@ async function handleVersionManagement(branchInfo, mergeResult, options = {}) {
   }
 }
 
+/**
+ * MAI-93: stage ONLY the version + changelog files for the version-bump commit.
+ *
+ * Previously the version commit ran `git add -A`, which swept any unrelated
+ * unstaged/untracked files in the working tree into the "Bumped version"
+ * commit. A `-a` run on a dirty tree must bump+commit ONLY version/changelog
+ * files and leave everything else untouched.
+ *
+ * @param {Object} versionResult - Result of updateVersionFiles() — its
+ *   `.updated[]` entries carry the `.path` of each written version file.
+ * @returns {{success: boolean, error?: string, staged: string[]}}
+ */
+function stageVersionAndChangelogFiles(versionResult) {
+  // Collect version file paths from the update result.
+  const paths = new Set();
+  for (const entry of (versionResult?.updated || [])) {
+    // MAI-93: prefer `path`, but fall back to `file` so any result shape that
+    // only carries a filename (e.g. secondary version files) is still staged.
+    const p = entry?.path || entry?.file;
+    if (p) paths.add(p);
+  }
+
+  // Add the changelog file(s) written by updateChangelogNew — computed from
+  // the same env vars the changelog writer uses, so they stay in lockstep.
+  const changelogPath = process.env.MAIASS_CHANGELOG_PATH || '.';
+  const changelogName = process.env.MAIASS_CHANGELOG_NAME || 'CHANGELOG.md';
+  const changelogInternalName = process.env.MAIASS_CHANGELOG_INTERNAL_NAME || '.CHANGELOG_internal.md';
+  const changelogInternalPath = process.env.MAIASS_CHANGELOG_INTERNAL_PATH || changelogPath;
+  const changelogFile = path.join(changelogPath, changelogName);
+  const changelogInternalFile = path.join(changelogInternalPath, changelogInternalName);
+  // Only stage changelog files that actually exist on disk (the internal one
+  // is optional, and the public one may be skipped if there was nothing to add).
+  for (const f of [changelogFile, changelogInternalFile]) {
+    try {
+      if (fs.existsSync(f)) paths.add(f);
+    } catch { /* ignore */ }
+  }
+
+  const fileList = [...paths];
+  if (fileList.length === 0) {
+    // Nothing to stage — let the caller's commit step decide what to do.
+    return { success: true, staged: [] };
+  }
+
+  // Stage each path explicitly. Quote to survive spaces in paths.
+  const quoted = fileList.map(p => `"${p}"`).join(' ');
+  const addResult = executeGitCommand(`git add -- ${quoted}`);
+  if (!addResult.success) {
+    return { success: false, error: 'Git add failed', staged: [] };
+  }
+  return { success: true, staged: fileList };
+}
+
 /**
  * Handle simple version bump without release branch or tagging
  * @param {string} newVersion - New version to set
@@ -624,20 +840,21 @@ async function handleSimpleVersionBump(newVersion, versionInfo, developBranch, o
     const changelogPath = process.env.MAIASS_CHANGELOG_PATH || '.';
     await updateChangelogNew(changelogPath, newVersion);
     
-    // Commit version changes
+    // Commit version changes. MAI-93: stage ONLY version + changelog files,
+    // never `git add -A`, so unrelated unstaged work is left untouched.
     logger.info(SYMBOLS.GEAR, 'Committing version changes...');
-    const addResult = executeGitCommand('git add -A');
+    const addResult = stageVersionAndChangelogFiles(versionResult);
     if (!addResult.success) {
-      logger.error(SYMBOLS.CROSS, 'Git operation failed: add -A');
+      logger.error(SYMBOLS.CROSS, 'Git operation failed: add (version/changelog files)');
       return { success: false, error: 'Git add failed' };
     }
-    
+
     const { success: committed } = executeGitCommand(`git commit -m "Bumped version to ${newVersion}"`);
     if (!committed) {
       logger.error(SYMBOLS.CROSS, 'Git operation failed: commit');
       return { success: false, error: 'Version commit failed' };
     }
-    
+
     // Push to remote if exists
     const hasRemote = await checkRemoteExists('origin');
     if (hasRemote) {
@@ -710,20 +927,21 @@ async function handleReleaseBranchWorkflow(newVersion, versionInfo, developBranc
     const changelogPath = process.env.MAIASS_CHANGELOG_PATH || '.';
     await updateChangelogNew(changelogPath, newVersion);
     
-    // Commit version changes
+    // Commit version changes. MAI-93: stage ONLY version + changelog files,
+    // never `git add -A`, so unrelated unstaged work is left untouched.
     logger.info(SYMBOLS.GEAR, 'Committing version changes...');
-    const addResult = executeGitCommand('git add -A');
+    const addResult = stageVersionAndChangelogFiles(versionResult);
     if (!addResult.success) {
-      logger.error(SYMBOLS.CROSS, 'Git operation failed: add -A');
+      logger.error(SYMBOLS.CROSS, 'Git operation failed: add (version/changelog files)');
       return { success: false, error: 'Git add failed' };
     }
-    
+
     const { success: committed } = executeGitCommand(`git commit -m "Bumped version to ${newVersion}"`);
     if (!committed) {
       logger.error(SYMBOLS.CROSS, 'Git operation failed: commit');
       return { success: false, error: 'Version commit failed' };
     }
-    
+
     // Create version tag
     logger.info(SYMBOLS.GEAR, `Creating version tag...`);
     const { success: tagged } = executeGitCommand(`git tag -a ${newVersion} -m "Release version ${newVersion}"`);
@@ -898,59 +1116,77 @@ export async function runMaiassPipeline(options = {}) {
       console.log(colors.BBlue(`${SYMBOLS.INFO} Current branch: ${getCurrentBranch()}`));
       return { success: true, phase: 'commits-only', dryRun };
     }
-    
+
     console.log();
-    
-    // Phase 3: Merge to Develop    
-    log.blue(SYMBOLS.INFO, 'Phase 3: Merge to Develop');
-    const mergeResult = await handleMergeToDevelop(branchInfo, commitResult, { 
-      force, 
-      silent, 
-      originalGitInfo, 
-      autoSwitch: !commitsOnly,
-      versionBump,
-      tag
-    });
-    
-    if (!mergeResult.success) {
-      return mergeResult;
-    }
-    
-    // If merge was cancelled by user, stop here gracefully
-    if (mergeResult.cancelled) {
-      console.log();
-      logger.success(SYMBOLS.CHECKMARK, `Workflow completed on ${getCurrentBranch()}`);
-      logger.info(SYMBOLS.INFO, 'Thank you for using MAIASS!');
-      return { success: true, cancelled: true, phase: 'merge-cancelled' };
-    }
 
-    // If PR flow was used, the merge will happen on the platform — stop the
-    // pipeline here. Version management will run on the next maiass invocation
-    // after the user merges the PR.
-    if (mergeResult.pullRequest) {
-      console.log();
-      logger.info(SYMBOLS.INFO, 'Thank you for using MAIASS!');
-      return { success: true, pullRequest: true, url: mergeResult.url };
-    }
-    
-    console.log('');
-    
-    // Phase 4: Version Management
-    log.blue(SYMBOLS.INFO, 'Phase 4: Version Management');
-    const versionResult = await handleVersionManagement(branchInfo, mergeResult, {
-      versionBump,
-      versionBumpExplicit,
-      dryRun,
-      tag,
-      force,
-      silent,
-      originalGitInfo
-    });
-    
-    if (!versionResult.success) {
-      return versionResult;
+    // MAI-93: if the commit phase stashed leftover changes (unattended -a with a
+    // dirty tree), the merge/version pipeline below runs on a clean tree. The
+    // stash MUST be popped once we're back on the original branch — even if the
+    // pipeline throws or returns failure — so the user's work is never stranded.
+    // The try/finally guarantees the pop runs. The pop itself preserves the
+    // stash on conflict (restoreStashedChanges) rather than discarding work.
+    const stashInfo = commitResult.stashInfo || null;
+    let mergeResult, versionResult;
+    try {
+      // Phase 3: Merge to Develop
+      log.blue(SYMBOLS.INFO, 'Phase 3: Merge to Develop');
+      mergeResult = await handleMergeToDevelop(branchInfo, commitResult, {
+        force,
+        silent,
+        originalGitInfo,
+        autoSwitch: !commitsOnly,
+        versionBump,
+        tag
+      });
+
+      if (!mergeResult.success) {
+        return mergeResult;
+      }
+
+      // If merge was cancelled by user, stop here gracefully
+      if (mergeResult.cancelled) {
+        console.log();
+        logger.success(SYMBOLS.CHECKMARK, `Workflow completed on ${getCurrentBranch()}`);
+        logger.info(SYMBOLS.INFO, 'Thank you for using MAIASS!');
+        return { success: true, cancelled: true, phase: 'merge-cancelled' };
+      }
+
+      // If PR flow was used, the merge will happen on the platform — stop the
+      // pipeline here. Version management will run on the next maiass invocation
+      // after the user merges the PR.
+      if (mergeResult.pullRequest) {
+        console.log();
+        logger.info(SYMBOLS.INFO, 'Thank you for using MAIASS!');
+        return { success: true, pullRequest: true, url: mergeResult.url };
+      }
+
+      console.log('');
+
+      // Phase 4: Version Management
+      log.blue(SYMBOLS.INFO, 'Phase 4: Version Management');
+      versionResult = await handleVersionManagement(branchInfo, mergeResult, {
+        versionBump,
+        versionBumpExplicit,
+        dryRun,
+        tag,
+        force,
+        silent,
+        originalGitInfo
+      });
+
+      if (!versionResult.success) {
+        return versionResult;
+      }
+    } finally {
+      // Pop only when we actually stashed (clean-tree -a / CI never stashes),
+      // and only after we are back on the branch the stash was captured on —
+      // otherwise an early-return failure path could pop the user's work onto
+      // develop/release/*. The helper is failure-safe (never throws).
+      if (stashInfo && stashInfo.stashed) {
+        await restoreStashedChangesOnBranch(stashInfo, branchInfo?.originalBranch);
+      }
     }
-    
+
     // Cache branch info to avoid multiple git calls that might hang
     const finalBranch = getCurrentBranch();
     const originalBranch = branchInfo.originalBranch;

package/lib/maiass-variables.js

@@ -8,8 +8,11 @@ export const MAIASS_VARIABLES = {
   'MAIASS_DEBUG': { default: 'false', description: 'Enable debug mode' },
   'MAIASS_BRAND': { default: 'MAIASS', description: 'Brand name for display' },
 
-  // Auto-yes flags — set by -a (all four) or -ac (first three only).
-  // Setting any of these in .env.maiass makes that prompt auto-approve permanently.
+  // Auto-yes flags. -a (--auto) and -uc (--unattended-commit) set
+  // MAIASS_AUTO_PUSH_COMMITS + MAIASS_AUTO_APPROVE_AI_SUGGESTIONS; -a also sets
+  // MAIASS_AUTO_MERGE_TO_DEVELOP. Neither sets MAIASS_AUTO_STAGE_UNSTAGED any
+  // more (MAI-93 — auto-staging is opt-in). Setting any of these in .env.maiass
+  // makes that prompt auto-approve permanently.
   'MAIASS_AUTO_STAGE_UNSTAGED': { default: 'false', description: 'Auto-stage unstaged changes during commit phase' },
   'MAIASS_AUTO_PUSH_COMMITS': { default: 'false', description: 'Auto-push commits to origin' },
   'MAIASS_AUTO_APPROVE_AI_SUGGESTIONS': { default: 'false', description: 'Auto-approve AI commit message suggestions' },

package/lib/version-manager.js

@@ -438,7 +438,12 @@ function updatePhpVersionConstant(filePath, constantName, newVersion) {
 function updateWordPressVersions(newVersion, projectPath = process.cwd()) {
   const wpConfig = getWordPressConfig(projectPath);
   let success = true;
-  
+  // MAI-93: collect every file we actually modify so the caller can stage them
+  // into the version commit (mirrors bash's track_bumped_file). Without this the
+  // pipeline's targeted `git add` bumps WordPress files on disk but omits them
+  // from the release commit.
+  const updatedFiles = [];
+
   // Handle plugin path
   if (wpConfig.pluginPath) {
     const pluginPath = path.isAbsolute(wpConfig.pluginPath) 
@@ -465,6 +470,8 @@ function updateWordPressVersions(newVersion, projectPath = process.cwd()) {
       const constantName = wpConfig.versionConstant || generateVersionConstant(wpConfig.pluginPath);
       if (!updatePhpVersionConstant(mainPluginFile, constantName, newVersion)) {
         success = false;
+      } else {
+        updatedFiles.push(mainPluginFile);
       }
     } else {
       console.log(colors.BYellow(`${SYMBOLS.WARNING} Could not find main plugin file in ${pluginPath}`)); // codeql[js/clear-text-logging] -- pluginPath is a file path, not a credential
@@ -513,6 +520,8 @@ function updateWordPressVersions(newVersion, projectPath = process.cwd()) {
       
       if (!updatePhpVersionConstant(functionsFile, constantName, newVersion)) {
         success = false;
+      } else {
+        updatedFiles.push(functionsFile);
       }
     } else {
       console.log(colors.BYellow(`${SYMBOLS.WARNING} Could not find functions.php in ${themePath}`)); // codeql[js/clear-text-logging] -- themePath is a file path, not a credential
@@ -529,13 +538,18 @@ function updateWordPressVersions(newVersion, projectPath = process.cwd()) {
       logger.debug(` style.css found, updating theme version header`);
       if (!updateThemeStyleVersion(styleFile, newVersion)) {
         success = false;
+      } else {
+        updatedFiles.push(styleFile);
       }
     } else {
       logger.debug(` style.css not found at: ${styleFile}`);
     }
   }
-  
-  return success;
+
+  // MAI-93: return both the overall success flag and the list of modified files
+  // so the caller can stage them. Returned as an object; the previous boolean
+  // return is now `success`.
+  return { success, updatedFiles };
 }
 
 /**
@@ -891,6 +905,11 @@ async function updateSecondaryVersionFiles(newVersion, config, dryRun = false) {
         logger.success(SYMBOLS.CHECKMARK, `Updated version to ${newVersion} in ${filename}`);
         results.updated.push({
           file: filename,
+          // MAI-93: the pipeline stager keys off `path` to build the targeted
+          // `git add`. Without it, secondary files are bumped on disk but never
+          // staged into the version commit. Keep `file` too in case other code
+          // reads it.
+          path: filename,
           type,
           pattern,
           newVersion
@@ -993,7 +1012,17 @@ export async function updateVersionFiles(newVersion, versionFiles, dryRun = fals
   if (!dryRun) {
     // change to use logger
     logger.info(SYMBOLS.INFO, 'Checking for WordPress plugin/theme version updates...');
-    const wpSuccess = updateWordPressVersions(newVersion);
+    const { success: wpSuccess, updatedFiles: wpFiles } = updateWordPressVersions(newVersion);
+    // MAI-93: stage the WordPress files we actually modified (style.css,
+    // functions.php, plugin header PHP). `path` is the key the pipeline stager
+    // uses to build its targeted `git add`.
+    for (const wpFile of (wpFiles || [])) {
+      results.updated.push({
+        file: wpFile,
+        path: wpFile,
+        newVersion
+      });
+    }
     if (!wpSuccess) {
       results.success = false;
       results.failed.push({

package/maiass.mjs

@@ -101,7 +101,7 @@ if (firstArg && versionBumpTypes.includes(firstArg)) {
     console.log('Version bump types:');
     console.log('  ' + versionBumpTypes.join(', '));
     console.log('');
-    console.log(`Run 'nma --help' for more information.`);
+    console.log(`Run 'maiass --help' for more information.`);
     process.exit(1);
   }
   command = firstArg;
@@ -110,14 +110,30 @@ if (firstArg && versionBumpTypes.includes(firstArg)) {
   command = 'maiass';
 }
 
+// MAI-93: `-ac` / `--auto-commit` has been REMOVED (breaking change, no alias).
+// Reject it early — before any work — and point users at the replacement.
+// Skip any position that is the VALUE of -m/--message, so a legitimate commit
+// message like `maiass -uc -m "-ac"` is NOT treated as the removed flag.
+const usesRemovedAutoCommit = args.some(
+  (a, i) => (a === '--auto-commit' || a === '-ac') && !messageArgIndices.has(i)
+);
+if (usesRemovedAutoCommit) {
+  console.error('Please use -uc (--unattended-commit)');
+  process.exit(1);
+}
+
 // Auto modes:
-// -a  / --auto:        full auto — stage, push, merge to develop, version bump
-//                      (kept identical to historical behaviour for CI compatibility)
-// -ac / --auto-commit: auto-yes for commit phase only — stops after commit
-//                      (no merge, no bump). Useful for CI runs that just want
-//                      the AI commit captured without touching develop.
-const isAutoCommit = args.includes('--auto-commit') || args.includes('-ac');
-const isAuto = !isAutoCommit && (args.includes('--auto') || args.includes('-a'));
+// -a  / --auto:              full auto — push, merge to develop, version bump.
+//                            Does NOT force-stage unstaged/untracked changes any
+//                            more (MAI-93) — auto-staging is opt-in via
+//                            MAIASS_AUTO_STAGE_UNSTAGED=true.
+// -uc / --unattended-commit: auto-yes for commit phase only — commits STAGED
+//                            changes, pushes the current branch, then stops (no
+//                            merge, no bump). Unattended but does NOT force-stage
+//                            (MAI-93). Distinct from the INTERACTIVE commits-only
+//                            (-c / -co / --commits-only), which prompts.
+const isUnattendedCommit = args.includes('--unattended-commit') || args.includes('-uc');
+const isAuto = !isUnattendedCommit && (args.includes('--auto') || args.includes('-a'));
 
 // Auto-mode env vars are applied AFTER flag validation below — see
 // "Apply auto-mode env vars" block. Detected here only because the booleans
@@ -180,7 +196,7 @@ if (!flagValidation.valid) {
   if (longFlags.length) console.log('  ' + longFlags.join(', '));
   if (shortFlags.length) console.log('  ' + shortFlags.join(', '));
   console.log('');
-  console.log(`Run 'nma --help' or 'nma ${command} --help' for more information.`);
+  console.log(`Run 'maiass --help' or 'maiass ${command} --help' for more information.`);
   process.exit(1);
 }
 
@@ -195,9 +211,13 @@ if (providedMessage !== null && providedMessage.trim() === '') {
 // Apply auto-mode env vars now that validation has passed. Setting these
 // before validation would leak MAIASS_AUTO_* into process.env for commands
 // that reject --auto (e.g. `account-info --auto`) — see MAI-43 code review.
-if (isAuto || isAutoCommit) {
-  // Shared auto-yes vars for both modes
-  process.env.MAIASS_AUTO_STAGE_UNSTAGED = 'true';
+//
+// MAI-93: auto modes NO LONGER force MAIASS_AUTO_STAGE_UNSTAGED. Auto-staging
+// of unstaged/untracked changes is now opt-in — whatever the user/config set
+// (loaded into process.env at maiass.mjs:25) is preserved; default off. The
+// auto-yes vars below only cover push and AI-suggestion approval.
+if (isAuto || isUnattendedCommit) {
+  // Shared auto-yes vars for both modes (NOT auto-stage — see MAI-93 above)
   process.env.MAIASS_AUTO_PUSH_COMMITS = 'true';
   process.env.MAIASS_AUTO_APPROVE_AI_SUGGESTIONS = 'true';
 }
@@ -208,11 +228,11 @@ if (isAuto) {
   if (process.env.MAIASS_DEBUG === 'true') {
     logger.debug('[DEBUG] Auto mode enabled — full pipeline runs unattended');
   }
-} else if (isAutoCommit) {
-  // -ac: stop after commit phase. Implemented by treating it as commits-only
+} else if (isUnattendedCommit) {
+  // -uc: stop after commit phase. Implemented by treating it as commits-only
   process.env.MAIASS_AUTO_FINISH_AFTER_COMMIT = 'true';
   if (process.env.MAIASS_DEBUG === 'true') {
-    logger.debug('[DEBUG] Auto-commit mode enabled — stops after commit phase');
+    logger.debug('[DEBUG] Unattended-commit mode enabled — stops after commit phase');
   }
 }
 
@@ -243,12 +263,15 @@ if (args.includes('--help') || args.includes('-h') || command === 'help') {
   console.log('\nOptions:');
   console.log('  --account-info     Show your account status (masked token)');
   console.log('  --cleanup-changelogs  AI-clean CHANGELOG.md + .CHANGELOG_internal.md (backfills from git; writes .bak)');
-  console.log('  --auto, -a         Full auto — stage, commit, push, merge to develop, bump version');
-  console.log('  --auto-commit, -ac Auto-yes for commit phase only — stops after commit (no merge, no bump)');
-  console.log('  --commits-only, -c Generate AI commits without version management');
+  console.log('  --auto, -a         Full auto — commit staged, push, merge to develop, bump version');
+  console.log('                     (auto-staging of UNSTAGED changes is opt-in: MAIASS_AUTO_STAGE_UNSTAGED=true)');
+  console.log('  --commits-only, -c, -co  Interactive commit-only — generate AI commits without version management');
+  console.log('  --unattended-commit, -uc Unattended commit-only — commits STAGED changes, pushes current branch,');
+  console.log('                     then stops (no merge/bump; auto-staging of unstaged changes is opt-in)');
   console.log('  --message, -m <msg> Use this commit message verbatim (skips AI + the message prompt; no credit/token needed).');
-  console.log('                     Supplies the message only; for fully unattended use combine with -ac (or --auto-stage).');
-  console.log('  --auto-stage       Automatically stage all changes');
+  console.log('                     Supplies the message only; for fully unattended use combine with -uc (or --auto-stage).');
+  console.log('  --auto-stage       Stage all changes for this run (one-shot opt-in; otherwise unstaged');
+  console.log('                     changes are left alone unless MAIASS_AUTO_STAGE_UNSTAGED=true)');
   console.log('  --setup, --bootstrap Run interactive project setup');
   console.log('  --help, -h         Show this help message');
   console.log('  --version, -v      Show version');
@@ -361,8 +384,11 @@ if (args.includes('--show-bb-excerpt'))  { showBitbucketExcerpt(); process.exit(
         // Positionals must exclude the -m/--message value token (it doesn't start
         // with '-' but is NOT a command/bump-type positional).
         _: process.argv.slice(2).filter((arg, i) => !arg.startsWith('-') && !messageArgIndices.has(i)),
-        // -ac is equivalent to -c (commits-only) plus auto-yes prompts
-        'commits-only': args.includes('--commits-only') || args.includes('-c') || args.includes('--auto-commit') || args.includes('-ac'),
+        // commits-only is the INTERACTIVE commit-only mode: -c / -co / --commits-only.
+        // The UNATTENDED variant -uc / --unattended-commit also maps here, then adds
+        // the auto-yes / auto-finish env vars set above (MAI-93).
+        'commits-only': args.includes('--commits-only') || args.includes('-c') || args.includes('-co')
+          || args.includes('--unattended-commit') || args.includes('-uc'),
         'auto-stage': args.includes('--auto-stage'),
         'auto': args.includes('--auto') || args.includes('-a'),
         'version-bump': versionBump,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "maiass",
   "type": "module",
-  "version": "5.14.2",
+  "version": "5.15.3",
   "description": "AI commit messages, version bumps, and changelogs from one command. Stages, commits, merges, tags. Anonymous on first run — no email, no card.",
   "main": "maiass.mjs",
   "bin": {