pan-wizard 3.21.1 → 3.24.0

package/pan-wizard-core/bin/lib/distill.cjs

@@ -21,9 +21,21 @@ const SCANNABLE_EXTS = ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py'];
 
 // ─── Pass 1: Deterministic static analysis ───────────────────────────────────
 
+// Calls that genuinely CANNOT throw when given any single argument, so a
+// try/catch wrapping only such a call is truly phantom (dead catch clause).
+// Deliberately EXCLUDES throwing calls — JSON.parse (SyntaxError on bad input),
+// JSON.stringify (TypeError on circular refs / BigInt), new RegExp, fs.*Sync,
+// etc. — because their try/catch is load-bearing and must not be flagged for
+// removal. (M14: earlier the pattern listed JSON.parse/JSON.stringify and
+// wrongly flagged their guards as phantom.)
+const NON_THROWING_CALLS = ['Number', 'String', 'Boolean', 'parseInt', 'parseFloat'];
+
 function findPhantomTryCatch(content, filePath) {
   const findings = [];
-  const re = /try\s*\{\s*(?:return\s+)?(JSON\.parse|JSON\.stringify|Number|String|Boolean|parseInt|parseFloat)\([^)]*\)\s*;?\s*\}\s*catch/g;
+  const re = new RegExp(
+    'try\\s*\\{\\s*(?:return\\s+)?(' + NON_THROWING_CALLS.join('|') + ')\\([^)]*\\)\\s*;?\\s*\\}\\s*catch',
+    'g'
+  );
   let match;
   while ((match = re.exec(content)) !== null) {
     const line = content.slice(0, match.index).split('\n').length;
@@ -372,6 +384,12 @@ function readPatternsMemory(cwd) {
   return { patterns, file: filePath };
 }
 
+// M15: the patterns-memory file (distill-patterns.md) records DETECTIONS, not
+// resolutions — there is no resolution/fix marker in the entry schema
+// ({ date, pattern, file, note }). So a prior entry only proves the pattern was
+// SEEN before, not that it was ever fixed. Labeling a re-detection "REGRESSED —
+// last resolved <date>" was a false claim. We now report the honest signal:
+// the pattern is RECURRING (still present across sessions / previously detected).
 function detectRegressedPatterns(currentFindings, memory) {
   const regressed = [];
   for (const f of currentFindings) {
@@ -380,8 +398,8 @@ function detectRegressedPatterns(currentFindings, memory) {
       regressed.push({
         ...f,
         regressed: true,
-        previously_resolved: prior.date,
-        message: f.message + ` (REGRESSED — last resolved ${prior.date})`,
+        previously_detected: prior.date,
+        message: f.message + ` (RECURRING — previously detected ${prior.date})`,
       });
     }
   }
@@ -426,7 +444,7 @@ function writePatternsMemory(cwd, findings, opts) {
     fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
     return { written: true, file: filePath, count: all.length };
   } catch (e) {
-    return { written: false, error: e.message };
+    return { written: false, error: e.message || 'write_failed' };
   }
 }
 

package/pan-wizard-core/bin/lib/doc-lint.cjs

@@ -39,7 +39,10 @@ const DEFAULT_SCHEMA_PATH = path.join(
  * @param {string} cwd - working directory (used to resolve relative paths)
  * @param {string} dir - directory to scan (relative to cwd or absolute)
  * @param {object} opts - { schema: string, format: 'json'|'human', strict: bool, exclude: string[], raw: bool }
- * @returns {void} — writes to stdout via output(); exit code via process.exit
+ * @returns {void} — writes to stdout, then exits. Exit code: 0 clean, 1 violations
+ *   found, 2 the schema itself is malformed. output() exits, so every branch that
+ *   calls it must pass its verdict as output()'s 4th argument; a bare
+ *   process.exit() after an output() call is unreachable.
  */
 function cmdDocLint(cwd, dir, opts = {}) {
   const targetDir = path.isAbsolute(dir) ? dir : path.join(cwd, dir);
@@ -63,8 +66,16 @@ function cmdDocLint(cwd, dir, opts = {}) {
         process.stderr.write(`  ${schemaPath}:${e.line} — ${e.message}\n`);
       }
     } else {
-      output({ schema_errors: schemaErrors, schema: schemaPath }, false);
+      // Exit 2 is passed to output() because output() EXITS. The `process.exit(2)`
+      // below it was dead code on this branch, so `doc-lint --format json` against a
+      // malformed schema printed the errors and reported SUCCESS -- nothing was
+      // linted, and the caller was told everything was fine. The exit code is not
+      // derived here: `schema_errors` is a plural collection, deliberately outside
+      // output()'s error family (an empty array is truthy), so gates state their
+      // verdict explicitly.
+      output({ schema_errors: schemaErrors, schema: schemaPath }, false, undefined, 2);
     }
+    // Reached only on the --raw branch above, which does not call output().
     process.exit(2);
   }
 
@@ -102,6 +113,9 @@ function cmdDocLint(cwd, dir, opts = {}) {
       process.stdout.write(summaryLine(violations, fileCount) + '\n');
     }
   } else {
+    // Same verdict the --raw branch reports via the process.exit() below; passed
+    // explicitly because output() exits and would otherwise discard it, making
+    // `doc-lint --format json` a linter that never fails.
     output({
       directory: dir,
       schema: schemaPath,
@@ -109,7 +123,7 @@ function cmdDocLint(cwd, dir, opts = {}) {
       error_count: errorCount,
       warning_count: warningCount,
       violations,
-    }, false);
+    }, false, undefined, errorCount > 0 ? 1 : 0);
   }
 
   process.exit(errorCount > 0 ? 1 : 0);
@@ -131,8 +145,9 @@ function cmdDocLintSchemaCheck(cwd, schemaPath, opts = {}) {
     error_count: errors.length,
     errors,
   };
-  output(result, opts.raw);
-  process.exit(result.ok ? 0 : 1);
+  // output() is called on both branches here, so the process.exit() below it was
+  // unconditionally dead: schema-check reported a malformed schema and exited 0.
+  output(result, opts.raw, undefined, result.ok ? 0 : 1);
 }
 
 // ─── Count-drift lint (IMPROVEMENT-TODO P1, v3.7.10) ────────────────────────
@@ -178,6 +193,7 @@ const COUNT_ALLOWED_RE = /(^|[\\/])(CLAUDE\.md|CHANGELOG\.md|MEMORY\.md|SKILLS-F
 const COUNT_ALLOWED_DIR_SEGMENTS = [
   'decisions',  // ADRs — frozen
   'specs',      // feature specs — frozen
+  'audits',     // audit reports — point-in-time snapshots, exempt by their own preamble
   'experiments', // harvested experiment artifacts
   'learnings',  // AI-derived patterns; evidence quotes reference numbers
   'archive',    // archived old docs
@@ -278,8 +294,9 @@ function cmdDocLintCounts(cwd, dir, opts = {}) {
       process.stdout.write(`\n${violations.length} violation(s) across ${fileCount} files\n`);
     }
   } else {
-    output(result, false);
+    output(result, false, undefined, violations.length > 0 ? 1 : 0);
   }
+  // Reached only on the --raw branch (release-check gate 4 relies on this code).
   process.exit(violations.length > 0 ? 1 : 0);
 }
 
@@ -355,8 +372,9 @@ function cmdDocLintFlags(cwd, opts = {}, raw) {
       process.stdout.write(`\n${r.violation_count} aspirational flag(s)\n`);
     }
   } else {
-    output(r, false);
+    output(r, false, undefined, r.violation_count > 0 ? 1 : 0);
   }
+  // Reached only on the --raw branch.
   process.exit(r.violation_count > 0 ? 1 : 0);
 }
 

package/pan-wizard-core/bin/lib/experiment.cjs

@@ -156,7 +156,31 @@ function newExperiment(slug, opts = {}) {
   // going because the workflow-level commit step exit code was 0.
   initExperimentGit(expPath);
 
-  // Optional: invoke installer for the chosen runtime in the experiment folder
+  // Optional: invoke installer for the chosen runtime in the experiment folder.
+  // M16: the installer only ships in the PAN SOURCE repo (bin/install.js). In an
+  // INSTALLED host project PAN_SOURCE_ROOT resolves to the config dir (e.g.
+  // .claude/), which never contains bin/install.js — so the installer step would
+  // always fail. Detect the missing installer up front and default to skip with a
+  // clear note, rather than attempting a spawn that is doomed to error.
+  const installerPresent = fs.existsSync(path.join(PAN_SOURCE_ROOT, 'bin', 'install.js'));
+  if (!opts.skipInstaller && !installerPresent) {
+    manifest.status = 'scaffolded';
+    manifest.installer_skipped = 'installer not available (bin/install.js absent — PAN is installed, not running from source); run the PAN installer manually in the experiment folder if a runtime is needed';
+    try {
+      fs.writeFileSync(
+        path.join(expPath, '.planning', 'experiment.json'),
+        JSON.stringify(manifest, null, 2)
+      );
+    } catch { /* best effort — non-fatal */ }
+    return {
+      experiment_id: slug,
+      path: expPath,
+      runtime,
+      idea_path: manifest.idea_path,
+      created_at: createdAt,
+      installer_skipped: manifest.installer_skipped,
+    };
+  }
   if (!opts.skipInstaller) {
     const installerError = runInstaller(expPath, runtime);
     if (installerError) {

package/pan-wizard-core/bin/lib/focus.cjs

@@ -8,7 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, safeReadFile, loadConfig, scanPendingTodos, scanSourceTodos, toPosix, isGitRepo, execGit, escapeRegex } = require('./core.cjs');
+const { output, EXIT_OK, error, safeReadFile, loadConfig, scanPendingTodos, scanSourceTodos, toPosix, isGitRepo, execGit, escapeRegex, normalizePhaseName } = require('./core.cjs');
 const {
   PLANNING_DIR, PHASES_DIR, ROADMAP_FILE, PATTERNS_FILE, EFFORT_POINTS, PRIORITY_LEVELS, EFFORT_SIZES,
   FOCUS_MODES, FOCUS_TIERS, FOCUS_DIR,
@@ -46,7 +46,17 @@ function collectWorkItems(cwd) {
     try { dirs = fs.readdirSync(phasesDir); } catch { dirs = []; }
 
     for (const phase of phases) {
-      const dirName = dirs.find(d => d.startsWith(phase.number + '-') || d === phase.number);
+      // Normalize before matching. Roadmap headings are UNPADDED — the shipped
+      // templates/roadmap.md writes "### Phase 1:" and `phase add` appends the same —
+      // while phase directories are zero-padded (`01-foundation`). Matching the raw
+      // heading number meant '1-' never matched '01-foundation', so focus scan found
+      // ZERO work items on a roadmap in PAN's own format, and the whole focus family
+      // (scan/plan/classify-stages/exec/auto) was a no-op on any default-shaped
+      // project. normalizePhaseName pads and is idempotent, so a roadmap that already
+      // says "Phase 01" still matches. Same normalization core.cjs searchPhaseInDir
+      // applies, which is why `find-phase 1` always worked where this did not.
+      const normalized = normalizePhaseName(phase.number);
+      const dirName = dirs.find(d => d.startsWith(normalized + '-') || d === normalized);
       if (!dirName) continue;
 
       const phaseDir = path.join(phasesDir, dirName);
@@ -344,7 +354,13 @@ function cmdFocusPlan(cwd, raw, ...args) {
   // Collect items
   const { items, sources } = collectWorkItems(cwd);
   if (items.length === 0) {
-    output({ error: 'No work items found. Run focus scan first or add phases/todos.' }, raw);
+    // EXIT_OK: an empty backlog is a legitimate answer, not a failure — it is the
+    // desired end state of a burn-down loop. `focus scan` already reports zero items
+    // as a success payload ({ items: [], total: 0 }) and the shipped scenario test
+    // asserts `focus plan` succeeds on a project with no TODOs
+    // (tests/scenarios/workflow-focus.test.cjs), so exiting non-zero here would make
+    // "nothing left to do" indistinguishable from a crash for the same caller.
+    output({ error: 'No work items found. Run focus scan first or add phases/todos.' }, raw, undefined, EXIT_OK);
     return;
   }
 
@@ -404,23 +420,35 @@ function checkDocStaleness(cwd, opts) {
   const current = [];
   const options = opts || {};
 
-  // Count actuals
+  // Count actuals. M17: a filesystem count only reconciles a documented count
+  // when the corresponding SOURCE directory actually exists. In an INSTALLED
+  // host project commands/pan, agents/, and pan-wizard-core/bin/lib are all
+  // absent — reconciling a documented "N commands" against an actual of 0 there
+  // is a false positive, so the per-entity check is SKIPPED when its dir is
+  // missing (tracked via *Present flags below). Explicit --tests/--suites and the
+  // version cross-reference are layout-independent and always run.
   let commandCount = 0;
+  let commandsPresent = false;
   try {
     const cmdDir = path.join(cwd, 'commands', 'pan');
     commandCount = fs.readdirSync(cmdDir).filter(f => f.endsWith('.md')).length;
+    commandsPresent = true;
   } catch { /* no commands dir */ }
 
   let agentCount = 0;
+  let agentsPresent = false;
   try {
     const agentDir = path.join(cwd, 'agents');
     agentCount = fs.readdirSync(agentDir).filter(f => f.endsWith('.md')).length;
+    agentsPresent = true;
   } catch { /* no agents dir */ }
 
   let moduleCount = 0;
+  let modulesPresent = false;
   try {
     const libDir = path.join(cwd, 'pan-wizard-core', 'bin', 'lib');
     moduleCount = fs.readdirSync(libDir).filter(f => f.endsWith('.cjs')).length;
+    modulesPresent = true;
   } catch { /* no lib dir */ }
 
   const actuals = { commands: commandCount, agents: agentCount, modules: moduleCount };
@@ -429,9 +457,9 @@ function checkDocStaleness(cwd, opts) {
   for (const relFile of DOC_SYNC_FILES) {
     const content = safeReadFile(path.join(cwd, relFile));
     if (!content) continue;
-    checkCount(content, relFile, 'commands', commandCount, stale, current);
-    checkCount(content, relFile, 'agents', agentCount, stale, current);
-    checkCount(content, relFile, 'modules', moduleCount, stale, current);
+    if (commandsPresent) checkCount(content, relFile, 'commands', commandCount, stale, current);
+    if (agentsPresent) checkCount(content, relFile, 'agents', agentCount, stale, current);
+    if (modulesPresent) checkCount(content, relFile, 'modules', moduleCount, stale, current);
 
     // Check test/suite counts if provided
     if (options.tests != null) {
@@ -790,6 +818,13 @@ function focusAutoUpdate(cwd, raw, getVal) {
     timestamp: new Date().toISOString(),
   };
 
+  // M18: wire --prompts-remaining so the `prompts_complete` stop reason is
+  // reachable (focus-auto.md step 8 instructs recording it). Absent → null, so
+  // determineStopReason's `prompts_remaining === 0` check never fires spuriously
+  // for non-prompts categories or when the flag isn't supplied.
+  const promptsRemainingRaw = getVal('--prompts-remaining', null);
+  cycle.prompts_remaining = promptsRemainingRaw != null ? Number(promptsRemainingRaw) : null;
+
   // Anti-fake: re-run the suite when verification is enabled; else record that
   // this count was self-reported (tests_verified:false) so the trust is visible.
   const tv = verifyTestCount(cwd, loadConfig(cwd), cycle.tests_after);

package/pan-wizard-core/bin/lib/frontmatter.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, output, error } = require('./core.cjs');
+const { safeReadFile, output, error, escapeRegex } = require('./core.cjs');
 const { FIELD_VALUE_RE, PRIORITY_LEVELS, EFFORT_SIZES } = require('./constants.cjs');
 
 // --- Inline array rendering thresholds -------------------------------------------
@@ -157,7 +157,10 @@ function renderYamlEntry(lines, key, value, depth) {
   if (Array.isArray(value)) {
     if (value.length === 0) {
       lines.push(`${indent}${key}: []`);
-    } else if (value.every(item => typeof item === 'string') && value.length <= MAX_INLINE_ARRAY_ITEMS && value.join(', ').length < MAX_INLINE_ARRAY_WIDTH) {
+    } else if (value.every(item => typeof item === 'string') && value.length <= MAX_INLINE_ARRAY_ITEMS && value.join(', ').length < MAX_INLINE_ARRAY_WIDTH && value.every(item => !item.includes(','))) {
+      // Inline form `[a, b, c]` is delimited by ', ', so an item that itself
+      // contains a comma would be re-split into multiple items on parse (lossy).
+      // Force multi-line ("- item") for those arrays so each item survives whole.
       lines.push(`${indent}${key}: [${value.join(', ')}]`);
     } else {
       lines.push(`${indent}${key}:`);
@@ -226,56 +229,84 @@ function parseMustHavesBlock(content, blockName) {
   if (!fmMatch) return [];
 
   const yaml = fmMatch[1];
+  const lines = yaml.split('\n');
+  const indentOf = (line) => line.match(/^(\s*)/)[1].length;
+
+  // Find `blockName:` as a child of `must_haves:` — by RELATIVE indent, never a
+  // fixed column. This function used to require exactly 4 spaces
+  // (`^\s{4}artifacts:`) with list items at exactly 6 and continuations at 8+.
+  // Nothing PAN ships is written that way: `template fill plan`,
+  // templates/phase-prompt.md, agents/pan-planner.md and agents/pan-verifier.md
+  // all put `must_haves:` at column 0 with its children at 2. So every real plan
+  // parsed as ZERO must_haves, and `verify reconcile` — the anti-rubber-stamp gate
+  // — reported "no must_haves declared … verdict trusted" and exited 0 on a stub.
+  // The 2026-08 audit chain missed it for five rounds because its fixtures were
+  // hand-written at 4-space, i.e. it verified the parser against itself.
+  const mustHavesIdx = lines.findIndex(l => /^\s*must_haves:\s*$/.test(l));
+  if (mustHavesIdx === -1) return [];
+  const mustHavesIndent = indentOf(lines[mustHavesIdx]);
+
+  // The block header is the first `blockName:` deeper than must_haves and before
+  // the next line at must_haves' own level or shallower (which ends the section).
+  let blockIdx = -1;
+  for (let i = mustHavesIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+    const ind = indentOf(line);
+    if (ind <= mustHavesIndent) break; // left the must_haves section
+    if (new RegExp(`^\\s*${escapeRegex(blockName)}:\\s*$`).test(line)) { blockIdx = i; break; }
+  }
+  if (blockIdx === -1) return [];
+  const blockIndent = indentOf(lines[blockIdx]);
 
-  // Locate the block header at exactly 4-space indent (must_haves child level)
-  const blockPattern = new RegExp(`^\\s{4}${blockName}:\\s*$`, 'm');
-  const blockStart = yaml.search(blockPattern);
-  if (blockStart === -1) return [];
-
-  const afterBlock = yaml.slice(blockStart);
-  // Skip the header line itself, then process remaining lines
-  const blockLines = afterBlock.split('\n').slice(1);
+  const blockLines = lines.slice(blockIdx + 1);
 
   const items = [];
   let currentItem = null;
+  // Indent of the list-item dashes, learned from the first one we see, so that
+  // continuation lines can be told apart from items without assuming a width.
+  let itemIndent = null;
 
   for (const line of blockLines) {
     // Skip blank lines within the block
     if (line.trim() === '') continue;
 
-    // --- Indentation-based grouping ---
-    // Measure indent to detect when we've left the block (indent <= 4
-    // means we've returned to must_haves level or a sibling block)
-    const indent = line.match(/^(\s*)/)[1].length;
-    if (indent <= 4 && line.trim() !== '') break;
+    // Leaving the block: back to the block header's level or shallower (a sibling
+    // block such as key_links, or back out to must_haves).
+    const indent = indentOf(line);
+    if (indent <= blockIndent) break;
 
-    if (line.match(/^\s{6}-\s+/)) {
-      // New list item at 6-space indent (direct child of the block)
+    const dashMatch = line.match(/^(\s*)-\s+(.*)$/);
+    const isNewItem = dashMatch && (itemIndent === null || dashMatch[1].length <= itemIndent);
+
+    if (isNewItem) {
+      if (itemIndent === null) itemIndent = dashMatch[1].length;
+      // New list item (direct child of the block)
       if (currentItem) items.push(currentItem);
       currentItem = {};
 
-      // Check if it is a simple string item (no colon means not key-value)
-      const simpleMatch = line.match(/^\s{6}-\s+"?([^"]+)"?\s*$/);
-      if (simpleMatch && !line.includes(':')) {
-        currentItem = simpleMatch[1];
+      const body = dashMatch[2];
+      // A plain string item — no `key: value` shape.
+      const kvMatch = body.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+      if (kvMatch) {
+        currentItem = {};
+        currentItem[kvMatch[1]] = kvMatch[2];
       } else {
-        // Key-value on same line as dash: "- path: value"
-        const kvMatch = line.match(/^\s{6}-\s+(\w+):\s*"?([^"]*)"?\s*$/);
-        if (kvMatch) {
-          currentItem = {};
-          currentItem[kvMatch[1]] = kvMatch[2];
-        }
+        currentItem = body.replace(/^"|"$/g, '').trim();
       }
     } else if (currentItem && typeof currentItem === 'object') {
-      // Continuation key-value at 8+ space indent (properties of current list item)
-      const kvMatch = line.match(/^\s{8,}(\w+):\s*"?([^"]*)"?\s*$/);
+      // Continuation key-value: deeper than the item's dash (properties of it)
+      const kvMatch = line.match(/^\s+(\w+):\s*"?([^"]*)"?\s*$/);
       if (kvMatch) {
         const val = kvMatch[2];
         // Coerce pure-integer strings to numbers for convenience
         currentItem[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
       }
-      // Array items nested under a property at 10+ space indent
-      const arrMatch = line.match(/^\s{10,}-\s+"?([^"]+)"?\s*$/);
+      // Array items nested under a property. Any dash line reaching this branch is
+      // already deeper than the list-item dash (a shallower one would have been
+      // treated as a new item above), so relative depth alone identifies it —
+      // no fixed column.
+      const arrMatch = line.match(/^\s+-\s+"?([^"]+)"?\s*$/);
       if (arrMatch) {
         // Convert the most recently added key's scalar value into an array,
         // then append this item to that array

package/pan-wizard-core/bin/lib/git.cjs

@@ -3,6 +3,25 @@
 const { output, error, isGitRepo, execGit, loadConfig } = require('./core.cjs');
 const { runCommitSafetyChecks, VALID_COMMIT_TYPES } = require('./commands.cjs');
 
+// ─── Failure reporting ────────────────────────────────────────────────────────
+//
+// Every subcommand here asks git to DO something. When git refuses, the payload
+// says `<verb>: false` — a shape output() cannot classify on its own, because the
+// same shape also carries legitimate negative answers elsewhere in PAN (see the
+// exit-code contract in core.cjs). So each failure site names itself with an
+// error-family key, which is what output() derives a non-zero exit from.
+//
+// Whatever the value is, it must never be able to come out EMPTY: git does not
+// always write to stderr, and an empty string is falsy — it would launder the
+// failure back into exit 0. Two safe forms are used here:
+//   • a stable code (`error: 'push_failed'`) — the form the query subcommands in
+//     this file already used (`error: 'status_failed', detail: r.stderr`);
+//   • stderr with a fallback (`error: r.stderr || 'unknown git error'`) — used by
+//     `commit` only, so all three of PAN's commit paths (this one, cmdCommit and
+//     cmdBatchCommit in commands.cjs) report a refused commit identically.
+// The stderr text stays in `detail` where it always was, so existing consumers
+// keep reading the same field.
+
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
 function getCurrentBranch(cwd) {
@@ -52,7 +71,10 @@ function cmdGitCommit(cwd, opts, raw) {
   const config = loadConfig(cwd);
   const safety = runCommitSafetyChecks(cwd, config, force);
   if (safety.blocked) {
-    output({ committed: false, reason: safety.reason, safety_checks: safety.safetyChecks, hint: safety.hint }, raw, 'blocked');
+    // A blocked commit is a refusal that protected something (staged deletions, a
+    // secret) — the commit did NOT happen, so the caller must be able to stop. Same
+    // classification CLI-REFERENCE already documents for `dirty_working_tree`.
+    output({ committed: false, reason: safety.reason, error: 'commit_blocked', safety_checks: safety.safetyChecks, hint: safety.hint }, raw, 'blocked');
     return;
   }
 
@@ -61,10 +83,16 @@ function cmdGitCommit(cwd, opts, raw) {
   const r = execGit(cwd, commitArgs);
   if (r.exitCode !== 0) {
     if (r.stdout.includes('nothing to commit') || r.stderr.includes('nothing to commit')) {
+      // No error key, exit 0: nothing to commit means no change was NEEDED, not that
+      // a change failed. Pinned as a success in CLI-REFERENCE ("Error Shape").
       output({ committed: false, reason: 'nothing_to_commit' }, raw, 'nothing to commit');
       return;
     }
-    output({ committed: false, reason: 'commit_failed', detail: r.stderr }, raw, 'commit failed');
+    // `|| 'unknown git error'` is load-bearing: the exit code is derived from a
+    // TRUTHY error key and git does not always write to stderr, so an empty string
+    // would launder this real failure back into exit 0. Same shape as the two
+    // sibling commit paths in commands.cjs (cmdCommit, cmdBatchCommit).
+    output({ committed: false, reason: 'commit_failed', error: r.stderr || 'unknown git error', detail: r.stderr }, raw, 'commit failed');
     return;
   }
   const hash = execGit(cwd, ['rev-parse', '--short', 'HEAD']).stdout || null;
@@ -90,7 +118,7 @@ function cmdGitBranch(cwd, sub, opts, raw) {
     if (!branchName) { error('--name or --phase required for branch create'); }
     const r = execGit(cwd, ['checkout', '-b', branchName]);
     if (r.exitCode !== 0) {
-      output({ created: false, branch: branchName, detail: r.stderr }, raw, 'failed');
+      output({ created: false, branch: branchName, error: 'branch_create_failed', detail: r.stderr }, raw, 'failed');
       return;
     }
     output({ created: true, branch: branchName }, raw, branchName);
@@ -100,7 +128,7 @@ function cmdGitBranch(cwd, sub, opts, raw) {
     if (!name) { error('--name required for branch switch'); }
     const r = execGit(cwd, ['checkout', name]);
     if (r.exitCode !== 0) {
-      output({ switched: false, branch: name, detail: r.stderr }, raw, 'failed');
+      output({ switched: false, branch: name, error: 'branch_switch_failed', detail: r.stderr }, raw, 'failed');
       return;
     }
     output({ switched: true, branch: name }, raw, name);
@@ -111,7 +139,7 @@ function cmdGitBranch(cwd, sub, opts, raw) {
     const flag = force ? '-D' : '-d';
     const r = execGit(cwd, ['branch', flag, name]);
     if (r.exitCode !== 0) {
-      output({ deleted: false, branch: name, detail: r.stderr, hint: force ? null : 'Use --force to delete unmerged branches' }, raw, 'failed');
+      output({ deleted: false, branch: name, error: 'branch_delete_failed', detail: r.stderr, hint: force ? null : 'Use --force to delete unmerged branches' }, raw, 'failed');
       return;
     }
     output({ deleted: true, branch: name }, raw, name);
@@ -134,7 +162,7 @@ function cmdGitPush(cwd, opts, raw) {
 
   const r = execGit(cwd, pushArgs);
   if (r.exitCode !== 0) {
-    output({ pushed: false, remote, branch, detail: r.stderr }, raw, 'push failed');
+    output({ pushed: false, remote, branch, error: 'push_failed', detail: r.stderr }, raw, 'push failed');
     return;
   }
   output({ pushed: true, remote, branch, force: !!force }, raw, remote + '/' + branch);
@@ -182,14 +210,14 @@ function cmdGitStash(cwd, sub, opts, raw) {
   if (sub === 'save') {
     const args = name ? ['stash', 'push', '-m', name] : ['stash', 'push'];
     const r = execGit(cwd, args);
-    if (r.exitCode !== 0) { output({ stashed: false, detail: r.stderr }, raw, 'stash failed'); return; }
+    if (r.exitCode !== 0) { output({ stashed: false, error: 'stash_save_failed', detail: r.stderr }, raw, 'stash failed'); return; }
     output({ stashed: true, name: name || null }, raw, 'stashed');
     return;
   }
   if (sub === 'pop') {
     const args = index != null ? ['stash', 'pop', 'stash@{' + index + '}'] : ['stash', 'pop'];
     const r = execGit(cwd, args);
-    if (r.exitCode !== 0) { output({ popped: false, detail: r.stderr }, raw, 'pop failed'); return; }
+    if (r.exitCode !== 0) { output({ popped: false, error: 'stash_pop_failed', detail: r.stderr }, raw, 'pop failed'); return; }
     output({ popped: true }, raw, 'popped');
     return;
   }
@@ -202,7 +230,7 @@ function cmdGitStash(cwd, sub, opts, raw) {
   if (sub === 'drop') {
     const args = index != null ? ['stash', 'drop', 'stash@{' + index + '}'] : ['stash', 'drop'];
     const r = execGit(cwd, args);
-    if (r.exitCode !== 0) { output({ dropped: false, detail: r.stderr }, raw, 'drop failed'); return; }
+    if (r.exitCode !== 0) { output({ dropped: false, error: 'stash_drop_failed', detail: r.stderr }, raw, 'drop failed'); return; }
     output({ dropped: true }, raw, 'dropped');
     return;
   }
@@ -250,7 +278,7 @@ function cmdGitRollback(cwd, opts, raw) {
     }
     const r = execGit(cwd, ['reset', '--hard', targetTag]);
     if (r.exitCode !== 0) {
-      output({ rolled_back: false, tag: targetTag, detail: r.stderr }, raw, 'rollback failed');
+      output({ rolled_back: false, tag: targetTag, error: 'rollback_failed', detail: r.stderr }, raw, 'rollback failed');
       return;
     }
   }
@@ -280,7 +308,7 @@ function cmdGitTag(cwd, sub, opts, raw) {
       : ['-c', 'tag.gpgsign=false', 'tag', name];
     const r = execGit(cwd, args);
     if (r.exitCode !== 0) {
-      output({ created: false, tag: name, detail: r.stderr }, raw, 'tag create failed');
+      output({ created: false, tag: name, error: 'tag_create_failed', detail: r.stderr }, raw, 'tag create failed');
       return;
     }
     output({ created: true, tag: name }, raw, name);
@@ -290,7 +318,7 @@ function cmdGitTag(cwd, sub, opts, raw) {
     if (!name) { error('--name required for tag delete'); }
     const r = execGit(cwd, ['tag', '-d', name]);
     if (r.exitCode !== 0) {
-      output({ deleted: false, tag: name, detail: r.stderr }, raw, 'tag delete failed');
+      output({ deleted: false, tag: name, error: 'tag_delete_failed', detail: r.stderr }, raw, 'tag delete failed');
       return;
     }
     output({ deleted: true, tag: name }, raw, name);
@@ -310,14 +338,14 @@ function cmdGitSync(cwd, opts, raw) {
 
   const fetchR = execGit(cwd, ['fetch', remote]);
   if (fetchR.exitCode !== 0) {
-    output({ synced: false, detail: fetchR.stderr }, raw, 'fetch failed');
+    output({ synced: false, error: 'fetch_failed', detail: fetchR.stderr }, raw, 'fetch failed');
     return;
   }
 
   const pullArgs = rebase ? ['pull', '--rebase', remote, branch] : ['pull', remote, branch];
   const pullR = execGit(cwd, pullArgs);
   if (pullR.exitCode !== 0) {
-    output({ synced: false, detail: pullR.stderr }, raw, 'pull failed');
+    output({ synced: false, error: 'pull_failed', detail: pullR.stderr }, raw, 'pull failed');
     return;
   }
 
@@ -337,15 +365,22 @@ function cmdGit(cwd, subcommand, args, raw) {
   const hasFlag = flag => args.includes(flag);
 
   switch (subcommand) {
-    case 'commit':
+    case 'commit': {
+      // M20: filter positional file paths from args AFTER dropping the leading
+      // subcommand token ('commit'). Operating on the full args left 'commit'
+      // itself in the files list, so a path literally named 'commit' got staged.
+      // Also drop the value that follows --type / --message so a flag's argument
+      // is never mistaken for a file path.
+      const commitArgs = args.slice(1);
       return cmdGitCommit(cwd, {
         type: getOpt('--type', null),
         message: getOpt('--message', null),
         all: hasFlag('--all'),
         amend: hasFlag('--amend'),
         force: hasFlag('--force'),
-        files: args.filter((a, i) => a !== '--type' && a !== '--message' && !a.startsWith('--') && args[i - 1] !== '--type' && args[i - 1] !== '--message'),
+        files: commitArgs.filter((a, i) => !a.startsWith('--') && commitArgs[i - 1] !== '--type' && commitArgs[i - 1] !== '--message'),
       }, raw);
+    }
     case 'branch':
       return cmdGitBranch(cwd, sub2, {
         name: getOpt('--name', null),