@imdeadpool/guardex 7.0.22 → 7.0.23

package/src/report/session-severity.js

@@ -0,0 +1,213 @@
+const TASK_SIZE_UPPER_BOUNDS = {
+  'narrow-patch': 1_800_000,
+  'medium-change': 4_000_000,
+  'large-change': 8_000_000,
+};
+
+const TASK_SIZE_VALUES = new Set(Object.keys(TASK_SIZE_UPPER_BOUNDS));
+const FRAGMENTATION_PRESET_SCORES = {
+  clean: 0,
+  'few-extra-checks': 5,
+  'repeated-follow-ups': 10,
+  looping: 18,
+  'dominant-loop': 25,
+};
+const FINISH_PATH_PRESET_SCORES = {
+  'clear-early': 0,
+  'minor-hesitation': 5,
+  'late-decision': 10,
+  reopening: 15,
+};
+const POST_PROOF_PRESET_SCORES = {
+  'stops-soon': 0,
+  'small-tail': 5,
+  'notable-tail': 10,
+  'heavy-tail': 15,
+};
+const DRIVER_TIE_BREAK = ['fragmentation', 'writeStdin', 'finishPath', 'postProof', 'cost'];
+const DRIVER_LABELS = {
+  cost: 'cost vs expected scope',
+  fragmentation: 'turn fragmentation',
+  writeStdin: 'write_stdin churn',
+  finishPath: 'finish-path discipline',
+  postProof: 'post-proof drift',
+};
+
+function parseRequiredPositiveInteger(name, rawValue, { allowZero = true } = {}) {
+  const parsed = Number.parseInt(String(rawValue || ''), 10);
+  if (!Number.isFinite(parsed) || (!allowZero && parsed <= 0) || (allowZero && parsed < 0)) {
+    throw new Error(`${name} requires ${allowZero ? 'a non-negative integer' : 'a positive integer'} value`);
+  }
+  return parsed;
+}
+
+function parseBooleanFlag(name, rawValue) {
+  const normalized = String(rawValue || '').trim().toLowerCase();
+  if (normalized === 'yes' || normalized === 'true' || normalized === '1') {
+    return true;
+  }
+  if (normalized === 'no' || normalized === 'false' || normalized === '0') {
+    return false;
+  }
+  throw new Error(`${name} requires yes/no (or true/false, 1/0)`);
+}
+
+function clampScore(value, min, max) {
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function parseTaskSize(rawTaskSize) {
+  const normalized = String(rawTaskSize || '').trim();
+  if (!TASK_SIZE_VALUES.has(normalized)) {
+    throw new Error(`--task-size must be one of: ${Array.from(TASK_SIZE_VALUES).join(', ')}`);
+  }
+  return normalized;
+}
+
+function resolveExpectedUpperBound(taskSize, rawExpectedBound) {
+  if (rawExpectedBound) {
+    return parseRequiredPositiveInteger('--expected-bound', rawExpectedBound, { allowZero: false });
+  }
+  return TASK_SIZE_UPPER_BOUNDS[taskSize];
+}
+
+function scoreCost(tokens, expectedUpperBound) {
+  const ratio = tokens / expectedUpperBound;
+  if (ratio <= 1.0) return 0;
+  if (ratio <= 1.5) return 5;
+  if (ratio <= 2.5) return 10;
+  if (ratio <= 4.0) return 18;
+  if (ratio <= 6.0) return 24;
+  return 30;
+}
+
+function scoreFragmentation(execCount, override) {
+  if (override) {
+    if (Object.prototype.hasOwnProperty.call(FRAGMENTATION_PRESET_SCORES, override)) {
+      return FRAGMENTATION_PRESET_SCORES[override];
+    }
+    return clampScore(parseRequiredPositiveInteger('--fragmentation', override), 0, 25);
+  }
+  if (execCount <= 4) return 0;
+  if (execCount <= 8) return 5;
+  if (execCount <= 16) return 10;
+  if (execCount <= 28) return 18;
+  return 25;
+}
+
+function scoreWriteStdin(writeStdinCount) {
+  if (writeStdinCount <= 0) return 0;
+  if (writeStdinCount <= 3) return 5;
+  if (writeStdinCount <= 6) return 10;
+  return 15;
+}
+
+function scoreFinishPath(completionBeforeTail, override) {
+  if (override) {
+    if (Object.prototype.hasOwnProperty.call(FINISH_PATH_PRESET_SCORES, override)) {
+      return FINISH_PATH_PRESET_SCORES[override];
+    }
+    return clampScore(parseRequiredPositiveInteger('--finish-path', override), 0, 15);
+  }
+  return completionBeforeTail ? 0 : 5;
+}
+
+function scorePostProof(completionBeforeTail, override) {
+  if (override) {
+    if (Object.prototype.hasOwnProperty.call(POST_PROOF_PRESET_SCORES, override)) {
+      return POST_PROOF_PRESET_SCORES[override];
+    }
+    return clampScore(parseRequiredPositiveInteger('--post-proof', override), 0, 15);
+  }
+  return completionBeforeTail ? 0 : 10;
+}
+
+function labelForTotal(total) {
+  if (total <= 15) return 'Healthy';
+  if (total <= 30) return 'Mildly fragmented';
+  if (total <= 50) return 'Inefficient';
+  if (total <= 75) return 'Runaway';
+  return 'Catastrophic';
+}
+
+function buildSessionSeverityReport(options) {
+  const taskSize = parseTaskSize(options.taskSize);
+  const tokens = parseRequiredPositiveInteger('--tokens', options.tokens);
+  const execCount = parseRequiredPositiveInteger('--exec-count', options.execCount);
+  const writeStdinCount = parseRequiredPositiveInteger('--write-stdin-count', options.writeStdinCount);
+  const completionBeforeTail = parseBooleanFlag('--completion-before-tail', options.completionBeforeTail);
+  const expectedUpperBound = resolveExpectedUpperBound(taskSize, options.expectedBound);
+  const costRatio = tokens / expectedUpperBound;
+  const scores = {
+    cost: scoreCost(tokens, expectedUpperBound),
+    fragmentation: scoreFragmentation(execCount, options.fragmentation),
+    writeStdin: scoreWriteStdin(writeStdinCount),
+    finishPath: scoreFinishPath(completionBeforeTail, options.finishPath),
+    postProof: scorePostProof(completionBeforeTail, options.postProof),
+  };
+  const total = scores.cost + scores.fragmentation + scores.writeStdin + scores.finishPath + scores.postProof;
+  const label = labelForTotal(total);
+  const rankedDimensions = Object.entries(scores)
+    .map(([key, score]) => ({ key, score, label: DRIVER_LABELS[key] }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => {
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+      return DRIVER_TIE_BREAK.indexOf(left.key) - DRIVER_TIE_BREAK.indexOf(right.key);
+    });
+  const primaryDriver = rankedDimensions[0] ? rankedDimensions[0].label : 'none';
+  const secondaries = rankedDimensions.slice(1).map((entry) => entry.label);
+
+  return {
+    taskSize,
+    expectedUpperBound,
+    tokens,
+    execCount,
+    writeStdinCount,
+    completionBeforeTail,
+    costRatio,
+    scores: {
+      ...scores,
+      total,
+    },
+    label,
+    primaryDriver,
+    secondaries,
+    outputLine: `Score ${total}/100 — ${label}. Primary: ${primaryDriver}. Secondaries: ${
+      secondaries.length > 0 ? secondaries.join(', ') : 'none'
+    }.`,
+  };
+}
+
+function renderSessionSeverityReport(report) {
+  return [
+    report.outputLine,
+    '',
+    `Task size: ${report.taskSize}`,
+    `Expected upper bound: ${report.expectedUpperBound}`,
+    `Actual tokens: ${report.tokens}`,
+    `Exec count: ${report.execCount}`,
+    `write_stdin count: ${report.writeStdinCount}`,
+    `Completion before tail churn: ${report.completionBeforeTail ? 'yes' : 'no'}`,
+    `Cost ratio: ${report.costRatio.toFixed(2)}x`,
+    '',
+    `A. Cost vs expected scope: ${report.scores.cost}`,
+    `B. Turn fragmentation: ${report.scores.fragmentation}`,
+    `C. write_stdin churn: ${report.scores.writeStdin}`,
+    `D. Finish-path discipline: ${report.scores.finishPath}`,
+    `E. Post-proof drift: ${report.scores.postProof}`,
+    '',
+    `Total: ${report.scores.total}`,
+    `Label: ${report.label}`,
+    `Primary driver: ${report.primaryDriver}`,
+    `Secondary drivers: ${report.secondaries.length > 0 ? report.secondaries.join(', ') : 'none'}`,
+  ].join('\n');
+}
+
+module.exports = {
+  TASK_SIZE_UPPER_BOUNDS,
+  buildSessionSeverityReport,
+  renderSessionSeverityReport,
+  labelForTotal,
+};

package/src/scaffold/index.js

@@ -1,6 +1,7 @@
 const {
   fs,
   path,
+  PACKAGE_ROOT,
   TOOL_NAME,
   SHORT_TOOL_NAME,
   GUARDEX_HOME_DIR,
@@ -9,6 +10,7 @@ const {
   HOOK_NAMES,
   LOCK_FILE_RELATIVE,
   LEGACY_MANAGED_PACKAGE_SCRIPTS,
+  PACKAGE_ROOT_SOURCE_OVERRIDES,
   USER_LEVEL_SKILL_ASSETS,
   AGENTS_MARKER_START,
   AGENTS_MARKER_END,
@@ -24,6 +26,7 @@ const {
   EXECUTABLE_RELATIVE_PATHS,
   CRITICAL_GUARDRAIL_PATHS,
 } = require('../context');
+const { parse: parseJsonc, printParseErrorCode } = require('jsonc-parser');
 const { run } = require('../core/runtime');
 
 function ensureParentDir(repoRoot, filePath, dryRun) {
@@ -172,17 +175,13 @@ function ensureHookShim(repoRoot, hookName, options = {}) {
   );
 }
 
-function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
-  const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
-  const destinationRelativePath = toDestinationPath(relativeTemplatePath);
-  const destinationPath = path.join(repoRoot, destinationRelativePath);
-
-  const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+function copyManagedSourceFile(repoRoot, sourcePath, destinationPath, destinationRelativePath, force, dryRun) {
+  const sourceContent = fs.readFileSync(sourcePath);
   const destinationExists = fs.existsSync(destinationPath);
 
   if (destinationExists) {
-    const existingContent = fs.readFileSync(destinationPath, 'utf8');
-    if (existingContent === sourceContent) {
+    const existingContent = fs.readFileSync(destinationPath);
+    if (existingContent.equals(sourceContent)) {
       ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       return { status: 'unchanged', file: destinationRelativePath };
     }
@@ -193,7 +192,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
 
   ensureParentDir(repoRoot, destinationPath, dryRun);
   if (!dryRun) {
-    fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+    fs.writeFileSync(destinationPath, sourceContent);
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
   }
 
@@ -204,22 +203,54 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
   return { status: destinationExists ? 'overwritten' : 'created', file: destinationRelativePath };
 }
 
+function normalizeTemplatePath(relativeTemplatePath) {
+  return String(relativeTemplatePath).replace(/\\/g, '/');
+}
+
+function usesPackageRootSource(repoRoot, relativeTemplatePath) {
+  return (
+    path.resolve(repoRoot) === PACKAGE_ROOT &&
+    PACKAGE_ROOT_SOURCE_OVERRIDES.has(normalizeTemplatePath(relativeTemplatePath))
+  );
+}
+
+function resolveTemplateSourcePath(repoRoot, relativeTemplatePath) {
+  if (usesPackageRootSource(repoRoot, relativeTemplatePath)) {
+    return path.join(PACKAGE_ROOT, relativeTemplatePath);
+  }
+  return path.join(TEMPLATE_ROOT, relativeTemplatePath);
+}
+
+function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
+  const sourcePath = resolveTemplateSourcePath(repoRoot, relativeTemplatePath);
+  const destinationRelativePath = toDestinationPath(relativeTemplatePath);
+  const destinationPath = path.join(repoRoot, destinationRelativePath);
+  return copyManagedSourceFile(
+    repoRoot,
+    sourcePath,
+    destinationPath,
+    destinationRelativePath,
+    force,
+    dryRun,
+  );
+}
+
 function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
-  const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
+  const sourcePath = resolveTemplateSourcePath(repoRoot, relativeTemplatePath);
   const destinationRelativePath = toDestinationPath(relativeTemplatePath);
   const destinationPath = path.join(repoRoot, destinationRelativePath);
-  const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+  const sourceContent = fs.readFileSync(sourcePath);
 
   if (fs.existsSync(destinationPath)) {
-    const existingContent = fs.readFileSync(destinationPath, 'utf8');
-    if (existingContent === sourceContent) {
+    const existingContent = fs.readFileSync(destinationPath);
+    if (existingContent.equals(sourceContent)) {
       ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       return { status: 'unchanged', file: destinationRelativePath };
     }
 
     if (isCriticalGuardrailPath(destinationRelativePath)) {
       if (!dryRun) {
-        fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+        fs.writeFileSync(destinationPath, sourceContent);
         ensureExecutable(destinationPath, destinationRelativePath, dryRun);
       }
       return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: destinationRelativePath };
@@ -230,13 +261,38 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
 
   ensureParentDir(repoRoot, destinationPath, dryRun);
   if (!dryRun) {
-    fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+    fs.writeFileSync(destinationPath, sourceContent);
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
   }
 
   return { status: 'created', file: destinationRelativePath };
 }
 
+function materializePackageRepoTemplateFiles(repoRoot, relativeTemplatePaths, dryRun) {
+  if (path.resolve(repoRoot) !== PACKAGE_ROOT) {
+    return [];
+  }
+
+  const operations = [];
+  for (const relativeTemplatePath of relativeTemplatePaths) {
+    if (!PACKAGE_ROOT_SOURCE_OVERRIDES.has(normalizeTemplatePath(relativeTemplatePath))) {
+      continue;
+    }
+    const templateRelativePath = path.posix.join('templates', normalizeTemplatePath(relativeTemplatePath));
+    operations.push(
+      copyManagedSourceFile(
+        PACKAGE_ROOT,
+        path.join(PACKAGE_ROOT, relativeTemplatePath),
+        path.join(PACKAGE_ROOT, templateRelativePath),
+        templateRelativePath,
+        true,
+        dryRun,
+      ),
+    );
+  }
+  return operations;
+}
+
 function lockFilePath(repoRoot) {
   return path.join(repoRoot, LOCK_FILE_RELATIVE);
 }
@@ -521,121 +577,13 @@ function ensureManagedGitignore(repoRoot, dryRun) {
   return { status: 'updated', file: '.gitignore', note: 'appended gitguardex-managed entries' };
 }
 
-function stripJsonComments(source) {
-  let result = '';
-  let inString = false;
-  let escapeNext = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-
-  for (let index = 0; index < source.length; index += 1) {
-    const current = source[index];
-    const next = source[index + 1];
-
-    if (inLineComment) {
-      if (current === '\n' || current === '\r') {
-        inLineComment = false;
-        result += current;
-      }
-      continue;
-    }
-
-    if (inBlockComment) {
-      if (current === '*' && next === '/') {
-        inBlockComment = false;
-        index += 1;
-        continue;
-      }
-      if (current === '\n' || current === '\r') {
-        result += current;
-      }
-      continue;
-    }
-
-    if (inString) {
-      result += current;
-      if (escapeNext) {
-        escapeNext = false;
-      } else if (current === '\\') {
-        escapeNext = true;
-      } else if (current === '"') {
-        inString = false;
-      }
-      continue;
-    }
-
-    if (current === '"') {
-      inString = true;
-      result += current;
-      continue;
-    }
-
-    if (current === '/' && next === '/') {
-      inLineComment = true;
-      index += 1;
-      continue;
-    }
-
-    if (current === '/' && next === '*') {
-      inBlockComment = true;
-      index += 1;
-      continue;
-    }
-
-    result += current;
-  }
-
-  return result;
-}
-
-function stripJsonTrailingCommas(source) {
-  let result = '';
-  let inString = false;
-  let escapeNext = false;
-
-  for (let index = 0; index < source.length; index += 1) {
-    const current = source[index];
-
-    if (inString) {
-      result += current;
-      if (escapeNext) {
-        escapeNext = false;
-      } else if (current === '\\') {
-        escapeNext = true;
-      } else if (current === '"') {
-        inString = false;
-      }
-      continue;
-    }
-
-    if (current === '"') {
-      inString = true;
-      result += current;
-      continue;
-    }
-
-    if (current === ',') {
-      let lookahead = index + 1;
-      while (lookahead < source.length && /\s/.test(source[lookahead])) {
-        lookahead += 1;
-      }
-      if (source[lookahead] === '}' || source[lookahead] === ']') {
-        continue;
-      }
-    }
-
-    result += current;
-  }
-
-  return result;
-}
-
 function parseJsonObjectLikeFile(source, relativePath) {
-  let parsed;
-  try {
-    parsed = JSON.parse(stripJsonTrailingCommas(stripJsonComments(source)));
-  } catch (error) {
-    throw new Error(`Unable to parse ${relativePath} as JSON or JSONC: ${error.message}`);
+  const errors = [];
+  const parsed = parseJsonc(source, errors, { allowTrailingComma: true });
+
+  if (errors.length > 0) {
+    const formattedErrors = errors.map((entry) => printParseErrorCode(entry.error)).join(', ');
+    throw new Error(`Unable to parse ${relativePath} as JSON or JSONC: ${formattedErrors}`);
   }
 
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -806,6 +754,7 @@ module.exports = {
   ensureHookShim,
   copyTemplateFile,
   ensureTemplateFilePresent,
+  materializePackageRepoTemplateFiles,
   ensureOmxScaffold,
   ensureLockRegistry,
   lockStateOrError,
@@ -815,8 +764,6 @@ module.exports = {
   removeLegacyManagedRepoFile,
   ensureAgentsSnippet,
   ensureManagedGitignore,
-  stripJsonComments,
-  stripJsonTrailingCommas,
   parseJsonObjectLikeFile,
   buildRepoVscodeSettings,
   ensureRepoVscodeSettings,

package/src/toolchain/index.js

@@ -17,50 +17,18 @@ const {
   envFlagIsTruthy,
 } = require('../context');
 const { run } = require('../core/runtime');
+const {
+  parseVersionString,
+  compareParsedVersions,
+  isNewerVersion,
+} = require('../core/versions');
+const { readSingleLineFromStdin } = require('../core/stdin');
 const { colorize } = require('../output');
 
 function isInteractiveTerminal() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
 
-const stdinWaitArray = new Int32Array(new SharedArrayBuffer(4));
-
-function sleepSyncMs(milliseconds) {
-  Atomics.wait(stdinWaitArray, 0, 0, milliseconds);
-}
-
-function readSingleLineFromStdin() {
-  let input = '';
-  const buffer = Buffer.alloc(1);
-
-  while (true) {
-    let bytesRead = 0;
-    try {
-      bytesRead = fs.readSync(process.stdin.fd, buffer, 0, 1);
-    } catch (error) {
-      if (error && ['EAGAIN', 'EWOULDBLOCK', 'EINTR'].includes(error.code)) {
-        sleepSyncMs(15);
-        continue;
-      }
-      return input;
-    }
-
-    if (bytesRead === 0) {
-      if (process.stdin.isTTY) {
-        sleepSyncMs(15);
-        continue;
-      }
-      return input;
-    }
-
-    const char = buffer.toString('utf8', 0, bytesRead);
-    if (char === '\n' || char === '\r') {
-      return input;
-    }
-    input += char;
-  }
-}
-
 function parseAutoApproval(name) {
   const raw = process.env[name];
   if (raw == null) return null;
@@ -70,38 +38,6 @@ function parseAutoApproval(name) {
   return null;
 }
 
-function parseVersionString(version) {
-  const match = String(version || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
-  if (!match) return null;
-  return [
-    Number.parseInt(match[1], 10),
-    Number.parseInt(match[2], 10),
-    Number.parseInt(match[3], 10),
-  ];
-}
-
-function compareParsedVersions(left, right) {
-  if (!left || !right) return 0;
-  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
-    const leftValue = left[index] || 0;
-    const rightValue = right[index] || 0;
-    if (leftValue > rightValue) return 1;
-    if (leftValue < rightValue) return -1;
-  }
-  return 0;
-}
-
-function isNewerVersion(latest, current) {
-  const latestParts = parseVersionString(latest);
-  const currentParts = parseVersionString(current);
-
-  if (!latestParts || !currentParts) {
-    return String(latest || '').trim() !== String(current || '').trim();
-  }
-
-  return compareParsedVersions(latestParts, currentParts) > 0;
-}
-
 function parseNpmVersionOutput(stdout) {
   const trimmed = String(stdout || '').trim();
   if (!trimmed) return '';

package/templates/AGENTS.multiagent-safety.md

@@ -10,6 +10,29 @@
 **Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
 Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
 
+## Token / Context Budget
+
+Default: less word, same proof.
+
+- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode: plan in at most 4 bullets, execute by phase, batch related reads/commands, avoid duplicate reads and interactive loops, keep outputs compact, and verify once per phase.
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
+- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next step`, and `evidence`.
+- Memory-driven starts stay ordered: read active `.omx/state` first, then one live `.omx/notepad.md` handoff, then external memory only when the task depends on prior repo decisions, a previous lane, or ambiguous continuity. Stop after the first 1-2 relevant hits.
+- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that only rediscover the same path state.
+- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals. If they appear alongside climbing input cost, stop the probe loop and batch the next phase.
+- Tool / hook summaries stay tiny: command, status, last meaningful lines only. Drop routine hook boilerplate.
+- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases. Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
+- When a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
+- Keep `.omx/notepad.md` lean: live handoffs only. Use exactly `branch`, `task`, `blocker`, `next step`, and `evidence`; move narrative proof into OpenSpec artifacts, PRs, or command output.
+
+## OMX Caveman Style
+
+- Commentary and progress updates use smart-caveman `ultra` by default: drop articles, filler, pleasantries, and hedging. Fragments are fine when they stay clear.
+- Answer order stays fixed: answer first, cause next, fix or next step last. If yes/no fits, say yes/no first.
+- Keep literals exact: code, commands, file paths, flags, env vars, URLs, numbers, timestamps, and error text are never caveman-compressed.
+- Auto-clarity wins: switch back to `lite` or normal wording for security warnings, irreversible actions, privacy/compliance notes, ordered instructions where fragments may confuse, or when the user is confused and needs more detail.
+- Boundaries stay normal/exact for code, commits, PR text, specs, logs, and blocker evidence.
+
 **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
@@ -25,6 +48,8 @@ OMX completion policy: when a task is done, the agent must commit the task chang
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
+**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes.
+
 **OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.

package/templates/scripts/agent-branch-finish.sh

@@ -409,6 +409,33 @@ is_remote_branch_missing_error() {
   return 1
 }
 
+local_branch_exists() {
+  local branch="$1"
+  git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}"
+}
+
+delete_local_branch_for_cleanup() {
+  local branch="$1"
+  local delete_output=""
+
+  if ! local_branch_exists "$branch"; then
+    echo "[agent-branch-finish] Local branch '${branch}' was already deleted; continuing cleanup." >&2
+    return 0
+  fi
+
+  if delete_output="$(git -C "$repo_root" branch -d "$branch" 2>&1)"; then
+    return 0
+  fi
+
+  if ! local_branch_exists "$branch"; then
+    echo "[agent-branch-finish] Local branch '${branch}' was already deleted; continuing cleanup." >&2
+    return 0
+  fi
+
+  echo "$delete_output" >&2
+  return 1
+}
+
 read_pr_state() {
   local state_line
   state_line="$("$GH_BIN" pr view "$SOURCE_BRANCH" --json state,mergedAt,url --jq '[.state, (.mergedAt // ""), (.url // "")] | join("\u001f")' 2>/dev/null || true)"
@@ -607,7 +634,9 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
     git -C "$repo_root" worktree remove "$source_worktree" --force >/dev/null 2>&1 || true
   fi
 
-  git -C "$repo_root" branch -d "$SOURCE_BRANCH"
+  if ! delete_local_branch_for_cleanup "$SOURCE_BRANCH"; then
+    exit 1
+  fi
 
   if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
     if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then