@ngockhoale/ukit 3.0.3 → 3.0.4

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to UKit are documented here.
 
 
+## 3.0.4 - 2026-09-24
+
+- **Full source audit (cycle C53) — ~86 defects fixed across all 14 audit areas**; every fix carries a RED→GREEN regression test under `tests/audit/`:
+  - **CLI** (`bin/ukit`, `src/cli/**`): watchdog `unref()` silent-exit-0 on hung `runCli`; `--tools=` empty value deselecting all adapters; `install --help` exiting 1; `update`/`status` silently ignoring positional/unknown args; unknown `--adapter` silently mapping to `.claude`; `--flag=a=b` truncation; `extractFlag` swallowing the next flag as a value; `memory` crash on null ledger receipt.
+  - **Lifecycle** (`src/core` install/update/uninstall/plan): uninstall data loss — tracked *file* entries removed via recursive `fs.rm` (a user dir replacing a managed file was deleted wholesale); `cleanupEmptyParents` crash on ENOTEMPTY/ENOENT races.
+  - **Hooks/policy/security**: `hookChainDoctor` TypeError on missing `projectRoot`; `permissionPolicy` non-array surface lists miscompiled/crashed → now fail-closed `UKIT_EPOLICY`; `unattendedDoctor` counted only `'prompt'` not `'ask'`; uppercase SHA-256 allowlist digests silently unmatched; `gatewayProbe`/`resolveGatewayApiKey` threw despite never-throw contracts; `detectCustomGatewayAsync` was a dead sync wrapper now truly async and wired.
+  - **Handoff/contracts/compact/experiments**: 10 defects incl. forced anchors dropped past `maxLines` while still counted; unlocked read-modify-write race in `appendCompactHistory`; shallow freeze letting a judge hide hard-constraint violations; retry-corrupted `state.budget.remaining`.
+  - **Codeintel/output/token**: duplicate call edges + edges to non-existent callee nodes; `JsonGraphStore` crash on corrupt codegraph; `semanticProvider` reading `raw.files` vs `{items}` shape (index-wide resolve always empty); `PATH_RE` misrouting "and/or"/"n/a"; `packetToText` never rendering `packet.memory`; `drainDirty` dropping `saturated` flag; `parseCheckLine` returning wrong stderr line; `summaries` provider bound to `process.cwd()`; `sweepTeeCache` unenforceable maxFiles cap; `appendOutputHistory` dropping empty-command entries.
+  - **Memory**: `addRecord` never ran `ensureMigrated` (first v2 write stranded all v1 data); corrupt legacy JSON silently dropped and hidden from `needsMigration`; unbounded `observeLearningSignal` text; concurrent-run counter races.
+  - **Index/routing**: `queryCodeIndex`/`queryAnalog` TypeError on non-string input; corrupt artifact `items` crashing `groupBy`; substring signal misclassification ('score'→'core', 'install '→'all '); importers ignoring aliased specifiers; `extends: "pkg"` resolving `pkg.json` not `pkg/tsconfig.json`; `shellEscape` dropping apostrophes; empty verification-plan floor; `test:*` scripts missed by `TEST_RUNNER_COMMAND`; installed index-core mirror drift re-synced.
+  - **Decision plane**: `sanitizeValue` `__proto__` prototype mutation; half-open circuit breaker with no single-probe gate and never-refreshed `openedAt`; `invalidateLease` raw TypeError on malformed records.
+  - **Diagnostics/render/skill/learning/stack/bug**: `ledgerFiles` omitted-limit NaN → empty results; `renderTemplate` `{{constructor}}`/`{{toString}}` rendering `[native code]`; `statusSkillAudit` crash on null entries; `knownSignaturesAndTexts` missing legacy `signature` collection; `detectStack` raw SyntaxError on corrupt package.json; `triageBug` ignoring declared `packageManager`.
+  - **Scripts toolchain**: missing flag values silently defaulting across 9 scripts; unknown flags ignored; unhandled promise rejections; silent partial index on unreadable files; `audit-perf.mjs` unbounded `spawnSync`/`execFileSync` (hang) → 60s SIGKILL timeout.
+  - **Shipped hooks** (`template_project/.claude/hooks`): `block-dangerous` deadline fail-open + missed bare `git push -f`; `record-execution` never armed deadline; `sensitive-data-guard` missed joined/`=` credential forms and wrapper-command bypass (`sudo`/`env`/`bash -c`/`xargs`); `session-episode` hardcoded stdin watchdog; `handoff-model-guard` silent crash exit; `auto-allow-bash` unquoted glob expansion corrupting allow rules.
+  - **Template payload/manifests/docs**: stale dev telemetry shipped via `runtime-cache` manifest item; `pdf-processing-pro` frontmatter name mismatch; handoff-planner `§7` drift; PLAN.md seed format drift; `QUICK_START` `@ukit/cli` ref; `RULES.md` nonexistent `PLAN.md §7` reference; broken archive doc links.
+  - **Test health**: `test:handoff` now self-installs UKit first (19/50 failures on fresh clones); stale pre-TASK-025 watchdog wiring assertion fixed; dead conditionals removed.
+
 ## 3.0.3 - 2026-09-23
 
 - Same content as 3.0.2 (npm staged-publish never finalized; re-published as 3.0.3).

package/bin/ukit

@@ -6,9 +6,13 @@ import { fileURLToPath } from 'node:url';
 import { runCli } from '../src/cli/index.js';
 
 async function readPackageVersion(packageRoot) {
-  const raw = await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8');
-  const packageJson = JSON.parse(raw);
-  return packageJson.version;
+  const packageJsonPath = path.join(packageRoot, 'package.json');
+  const raw = await fs.readFile(packageJsonPath, 'utf8');
+  try {
+    return JSON.parse(raw).version;
+  } catch (error) {
+    throw new Error(`Failed to parse ${packageJsonPath}: ${error?.message ?? error}`);
+  }
 }
 
 const DEFAULT_CLI_DEADLINE_MS = 120_000;
@@ -26,7 +30,11 @@ async function main() {
     console.error(`[UKit] timed out after ${deadlineMs}ms — likely wedged filesystem; retry`);
     process.exit(1);
   }, deadlineMs);
-  watchdog.unref();
+  // NOT unref'd: a hung runCli that holds no event-loop handles (e.g. a promise
+  // that never settles after its input stream closed — the BUG-C21-13 class)
+  // would otherwise let the process exit 0 silently with the work unfinished.
+  // The ref'd timer is the only handle that guarantees the deadline still fires;
+  // it is always cleared in the finally below, so it cannot outlive main().
 
   try {
     const currentFile = fileURLToPath(import.meta.url);

package/manifests/engineConformance.yaml

@@ -24,9 +24,38 @@ classes:
       claude-code: { support: enforced, evidence: tests/hooks/executionLedgerRiskGate.test.js }
       codex:       { support: degraded, note: 'no Stop hook; completionEvidence is advisory in .codex/README.md' }
       omp:         { support: enforced, evidence: tests/hooks/ompHookBridge.test.js }
+    # C52 mechanism rows (FR-019). Each carries promotionEvidence (FR-020):
+    # {stage, evaluatedAt, verdict, evidenceRef}; verdict enum
+    # not-evaluated|net-gain|neutral|negative; not-evaluated => null date/ref.
+    mechanisms:
+      decision-plane-preflight:
+        hosts:
+          claude-code: { support: enforced, evidence: tests/decision/shadow.test.js }
+          codex:       { support: degraded, note: 'no hook surface; route-task shadow/preflight runs only when invoked manually, receipts advisory' }
+          omp:         { support: enforced, evidence: tests/index/unicDecision.test.js }
+        promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
+      resumable-run-state:
+        hosts:
+          claude-code: { support: enforced, evidence: tests/hooks/resumableRunWiring.test.js }
+          codex:       { support: degraded, note: 'no session-start/stop hooks; resume record is advisory context, never auto-reinjected' }
+          omp:         { support: enforced, evidence: tests/hooks/reinjectContextHook.test.js }
+        promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
+      learning-overlays:
+        hosts:
+          claude-code: { support: enforced, evidence: tests/core/deltaOverlays.test.js }
+          codex:       { support: degraded, note: 'overlay approval gate lives in shared runtime; codex consumes rendered policy without a hook gate' }
+          omp:         { support: enforced, evidence: tests/core/deltaOverlays.test.js }
+        promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
   advisory:
     description: stdout/prompt text the model is asked to respect (routes, suppress, budgets)
     hosts:
       claude-code: { support: advisory }
       codex:       { support: advisory }
       omp:         { support: advisory }
+    mechanisms:
+      experiment-flags:
+        hosts:
+          claude-code: { support: advisory }
+          codex:       { support: advisory }
+          omp:         { support: advisory }
+        promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }

package/manifests/platform.full.yaml

@@ -1738,6 +1738,18 @@ items:
     packs:
       - core
 
+  - id: ukit-index-unic-decision-script
+    type: config
+    sourceTemplate: .claude/ukit/index/unic-decision.mjs
+    targetPath: .claude/ukit/index/unic-decision.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-extract-image-script
     type: config
     sourceTemplate: .claude/ukit/index/extract-image.mjs
@@ -1757,6 +1769,7 @@ items:
       - ukit-index-cache-utils-script
       - ukit-index-route-catalog-script
       - ukit-index-unic-gateway-script
+      - ukit-index-unic-decision-script
       - ukit-index-extract-image-script
     mergeStrategy: overwrite_with_backup
     variables: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -63,6 +63,7 @@
     "release:verify": "node ./scripts/release/verify-release.mjs",
     "test": "vitest run",
     "test:liveness": "vitest run tests/liveness/",
+    "test:handoff": "node ./bin/ukit install >/dev/null && node --test --test-concurrency=1 'tests/handoff/**/*.test.mjs' 'tests/handoff/**/*.test.js'",
     "test:watch": "vitest"
   },
   "engines": {

package/scripts/audit/decision-coverage.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/**
+ * decision-coverage.mjs (TASK-004 / M07, SPEC §5 FR-010)
+ *
+ * CI coverage guard: every consequential decision point in the fixed scan set
+ * must be covered by a DECISION_REGISTRY entry or a committed allowlist entry.
+ *
+ * Discovery convention (deterministic, no invented semantics):
+ *   (a) an exported function named /^(derive|resolve|select|choose|decide)[A-Z]/
+ *       whose body returns a value drawn from a >=2-member choice set — a
+ *       Set/Object.freeze([...])/object-literal constant, a switch, or a
+ *       ternary over >=2 string literals;
+ *   (b) any site carrying a `// @decision-point <key>` annotation.
+ * Point key = the annotation key, else `<basename>:<functionName>`.
+ *
+ * Allowlist: docs/pstack/decision-coverage-allowlist.json —
+ *   [{"key":"<pointKey>","reason":"deterministic|delegated|out-of-scope","owner":"<file>"}]
+ *
+ * Exit 0 when every discovered point is covered; exit 1 printing each
+ * uncovered key (and each invalid allowlist entry). Reports only — does not
+ * yet block promotion.
+ *
+ * Usage: node scripts/audit/decision-coverage.mjs
+ *          [--root <dir>] [--allowlist <path>] [--extra-scan <file>...]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { DECISION_REGISTRY } from '../../src/decision/registry.js';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = path.resolve(SCRIPT_DIR, '..', '..');
+
+// Fixed scan set (FR-010) — relative to the repo root.
+const SCAN_FILES = [
+  'src/index/taskRouting.js',
+  'src/core/executionContracts.js',
+  'template_project/.claude/ukit/index/route-task.mjs',
+];
+const SCAN_GLOBS = ['src/decision/'];
+const DEFAULT_ALLOWLIST = 'docs/pstack/decision-coverage-allowlist.json';
+
+const DECISION_NAME_RE =
+  /^export\s+(?:async\s+)?function\s+((?:derive|resolve|select|choose|decide)[A-Z]\w*)\s*\(/gm;
+const ANNOTATION_RE = /@decision-point\s+([A-Za-z0-9._-]+)/g;
+const CONST_RE =
+  /(?:^|[;{}\n])\s*(?:export\s+)?const\s+([A-Z][A-Za-z0-9_]*)\s*=\s*(?:new\s+Set\s*\(|Object\.freeze\s*\()?\s*([\[{])/g;
+const ALLOWED_REASONS = new Set(['deterministic', 'delegated', 'out-of-scope']);
+
+// --- tiny lexical scanner (strings/comments aware) ---------------------------
+
+function skipString(source, i) {
+  const quote = source[i];
+  for (let j = i + 1; j < source.length; j += 1) {
+    if (source[j] === '\\') { j += 1; continue; }
+    if (source[j] === quote) return j;
+  }
+  return source.length;
+}
+
+function skipLineComment(source, i) {
+  const nl = source.indexOf('\n', i);
+  return nl === -1 ? source.length : nl;
+}
+
+function skipBlockComment(source, i) {
+  const end = source.indexOf('*/', i + 2);
+  return end === -1 ? source.length : end + 1;
+}
+
+// Index of the bracket closing source[openIdx], or -1.
+function findMatching(source, openIdx) {
+  const open = source[openIdx];
+  const close = open === '{' ? '}' : open === '[' ? ']' : ')';
+  let depth = 0;
+  for (let i = openIdx; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(source, i); continue; }
+    if (ch === '/' && source[i + 1] === '/') { i = skipLineComment(source, i); continue; }
+    if (ch === '/' && source[i + 1] === '*') { i = skipBlockComment(source, i); continue; }
+    if (ch === open) depth += 1;
+    else if (ch === close) {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+// Commas at bracket depth 0 inside (start, end) — member count = commas + 1.
+function countTopLevelCommas(source, start, end) {
+  let depth = 0;
+  let commas = 0;
+  let sawContent = false;
+  for (let i = start; i < end; i += 1) {
+    const ch = source[i];
+    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(source, i); sawContent = true; continue; }
+    if (ch === '/' && source[i + 1] === '/') { i = skipLineComment(source, i); continue; }
+    if (ch === '/' && source[i + 1] === '*') { i = skipBlockComment(source, i); continue; }
+    if (ch === '{' || ch === '[' || ch === '(') depth += 1;
+    else if (ch === '}' || ch === ']' || ch === ')') depth -= 1;
+    else if (ch === ',' && depth === 0) commas += 1;
+    else if (!/\s/.test(ch)) sawContent = true;
+  }
+  return sawContent ? commas + 1 : 0;
+}
+
+// --- discovery ---------------------------------------------------------------
+
+// Names of >=2-member choice-set constants declared anywhere in the file.
+function collectChoiceSets(source) {
+  const names = new Set();
+  CONST_RE.lastIndex = 0;
+  let match;
+  while ((match = CONST_RE.exec(source)) !== null) {
+    const openIdx = match.index + match[0].lastIndexOf(match[2]);
+    const closeIdx = findMatching(source, openIdx);
+    if (closeIdx === -1) continue;
+    if (countTopLevelCommas(source, openIdx + 1, closeIdx) >= 2) {
+      names.add(match[1]);
+    }
+    CONST_RE.lastIndex = openIdx + 1;
+  }
+  return names;
+}
+
+// Heuristic (a): the body returns from a >=2-member choice set — a switch, a
+// ternary over >=2 string literals, or a reference to a choice-set constant.
+function isConsequential(body, choiceSetNames) {
+  if (/\bswitch\s*\(/.test(body)) return true;
+  if (/\?\s*['"][^'"]*['"]\s*:\s*['"]/.test(body)) return true;
+  for (const name of choiceSetNames) {
+    if (new RegExp(`\\b${name}\\b`).test(body)) return true;
+  }
+  return false;
+}
+
+function discoverInSource(source, basename) {
+  const points = [];
+  const choiceSets = collectChoiceSets(source);
+
+  DECISION_NAME_RE.lastIndex = 0;
+  let match;
+  while ((match = DECISION_NAME_RE.exec(source)) !== null) {
+    const paramsOpen = source.indexOf('(', match.index + match[0].indexOf('('));
+    const paramsClose = findMatching(source, paramsOpen);
+    if (paramsClose === -1) continue;
+    const bodyOpen = source.indexOf('{', paramsClose);
+    if (bodyOpen === -1) continue;
+    const bodyClose = findMatching(source, bodyOpen);
+    if (bodyClose === -1) continue;
+    const body = source.slice(bodyOpen, bodyClose + 1);
+    if (isConsequential(body, choiceSets)) {
+      points.push(`${basename}:${match[1]}`);
+    }
+    DECISION_NAME_RE.lastIndex = bodyClose + 1;
+  }
+
+  ANNOTATION_RE.lastIndex = 0;
+  while ((match = ANNOTATION_RE.exec(source)) !== null) {
+    points.push(match[1]);
+  }
+  return points;
+}
+
+// --- CLI ---------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { root: DEFAULT_ROOT, allowlist: null, extraScan: [] };
+  const valueFor = (flag, i) => {
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      console.error(`missing value for ${flag}`);
+      process.exit(2);
+    }
+    return next;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') { args.root = path.resolve(valueFor('--root', i)); i += 1; }
+    else if (argv[i] === '--allowlist') { args.allowlist = path.resolve(valueFor('--allowlist', i)); i += 1; }
+    else if (argv[i] === '--extra-scan') { args.extraScan.push(path.resolve(valueFor('--extra-scan', i))); i += 1; }
+    else {
+      console.error(`unknown argument: ${argv[i]}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function scanFiles(root, extraScan) {
+  const files = SCAN_FILES.map((f) => path.join(root, f));
+  for (const dir of SCAN_GLOBS) {
+    const absDir = path.join(root, dir);
+    if (!fs.existsSync(absDir)) {
+      return { error: `scan directory missing: ${dir}` };
+    }
+    for (const entry of fs.readdirSync(absDir).sort()) {
+      if (entry.endsWith('.js')) files.push(path.join(absDir, entry));
+    }
+  }
+  files.push(...extraScan);
+  return { files };
+}
+
+function loadAllowlist(allowlistPath) {
+  if (!fs.existsSync(allowlistPath)) {
+    return { entries: [], errors: [`allowlist missing: ${allowlistPath}`] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(allowlistPath, 'utf8'));
+  } catch (error) {
+    return { entries: [], errors: [`allowlist is not valid JSON: ${error.message}`] };
+  }
+  if (!Array.isArray(parsed)) {
+    return { entries: [], errors: ['allowlist must be a JSON array'] };
+  }
+  const entries = [];
+  const errors = [];
+  parsed.forEach((entry, index) => {
+    const label = `allowlist[${index}]`;
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`${label}: entry must be an object`);
+      return;
+    }
+    if (typeof entry.key !== 'string' || entry.key.length === 0) {
+      errors.push(`${label}: key must be a non-empty string`);
+      return;
+    }
+    if (!ALLOWED_REASONS.has(entry.reason)) {
+      errors.push(
+        `${label} (${entry.key}): reason must be one of: ${[...ALLOWED_REASONS].join(', ')}`,
+      );
+      return;
+    }
+    if (typeof entry.owner !== 'string' || entry.owner.length === 0) {
+      errors.push(`${label} (${entry.key}): owner must be a non-empty string`);
+      return;
+    }
+    entries.push(entry);
+  });
+  return { entries, errors };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const allowlistPath = args.allowlist ?? path.join(args.root, DEFAULT_ALLOWLIST);
+
+  const { files, error } = scanFiles(args.root, args.extraScan);
+  if (error) {
+    console.error(`decision-coverage: ${error}`);
+    process.exit(1);
+  }
+
+  const discovered = [];
+  for (const file of files) {
+    if (!fs.existsSync(file)) {
+      console.error(`decision-coverage: scan file missing: ${path.relative(args.root, file)}`);
+      process.exit(1);
+    }
+    const source = fs.readFileSync(file, 'utf8');
+    discovered.push(...discoverInSource(source, path.basename(file)));
+  }
+
+  const registryKeys = new Set(DECISION_REGISTRY.map((entry) => entry.decisionKey));
+  const { entries, errors } = loadAllowlist(allowlistPath);
+  const allowlisted = new Set(entries.map((entry) => entry.key));
+
+  const uncovered = [...new Set(discovered)]
+    .filter((key) => !registryKeys.has(key) && !allowlisted.has(key))
+    .sort();
+
+  for (const err of errors) {
+    console.log(`INVALID-ALLOWLIST ${err}`);
+  }
+  for (const key of uncovered) {
+    console.log(`UNCOVERED ${key}`);
+  }
+
+  if (errors.length > 0 || uncovered.length > 0) {
+    console.log(
+      `decision-coverage: FAIL — ${uncovered.length} uncovered, ${errors.length} invalid allowlist entries`,
+    );
+    process.exit(1);
+  }
+  const registryCovered = [...new Set(discovered)].filter((k) => registryKeys.has(k)).length;
+  console.log(
+    `decision-coverage: ok — ${new Set(discovered).size} decision points covered ` +
+    `(registry: ${registryCovered}, allowlisted: ${new Set(discovered).size - registryCovered})`,
+  );
+}
+
+main();

package/scripts/bench/outline-savings.mjs

@@ -19,8 +19,12 @@ const DEFAULT_QUERY = 'resolveContext';
 
 async function main() {
   const args = process.argv.slice(2);
-  const rootDir = readFlagValue(args, '--root') ?? process.cwd();
-  const limit = Number.parseInt(readFlagValue(args, '--limit') ?? '3', 10);
+  const rootDir = path.resolve(readFlagValue(args, '--root') ?? process.cwd());
+  const limitRaw = readFlagValue(args, '--limit');
+  const limit = limitRaw === null ? 3 : Number.parseInt(limitRaw, 10);
+  if (limitRaw !== null && (Number.isNaN(limit) || limit < 1)) {
+    throw new Error(`invalid --limit value: "${limitRaw}" (expected a positive integer)`);
+  }
   const query = collectPositionalArgs(args, ['--root', '--limit']) || DEFAULT_QUERY;
 
   await buildCodeIndex({ rootDir });
@@ -68,7 +72,13 @@ function renderOutline(outline) {
 
 function readFlagValue(argv, flag) {
   const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  if (exact >= 0) {
+    const maybeValue = argv[exact + 1];
+    if (!maybeValue || maybeValue.startsWith('--')) {
+      throw new Error(`Missing value for ${flag}.`);
+    }
+    return maybeValue;
+  }
   const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
   return withEquals ? withEquals.slice(flag.length + 1) : null;
 }
@@ -89,4 +99,9 @@ function isFlagOrValue(argv, index, flagsWithValues = []) {
   return true;
 }
 
-await main();
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/scripts/bench/parallel-agents.mjs

@@ -28,12 +28,17 @@ const LEVEL_TIMEOUT_MS = Number(process.env.UKIT_BENCH_LEVEL_TIMEOUT_MS) || 30 *
 
 function parseArgs(argv) {
   const opts = { levels: '1,3,5,10', cmd: 'yarn test:release-core', out: '.cache/bench/parallel-agents.json' };
-  for (let i = 0; i < argv.length; i += 2) {
+  for (let i = 0; i < argv.length; i += 1) {
     const key = argv[i];
+    if (key !== '--levels' && key !== '--cmd' && key !== '--out') {
+      throw new Error(`unknown argument: ${key}`);
+    }
     const val = argv[i + 1];
-    if ((key === '--levels' || key === '--cmd' || key === '--out') && val !== undefined) {
-      opts[key.slice(2)] = val;
+    if (val === undefined || val.startsWith('--')) {
+      throw new Error(`missing value for ${key}`);
     }
+    opts[key.slice(2)] = val;
+    i += 1;
   }
   return opts;
 }
@@ -117,7 +122,13 @@ function fail(msg) {
 }
 
 async function main() {
-  const opts = parseArgs(process.argv.slice(2));
+  const opts = (() => {
+    try {
+      return parseArgs(process.argv.slice(2));
+    } catch (err) {
+      fail(err.message);
+    }
+  })();
   let levels;
   try {
     levels = parseLevels(opts.levels);

package/scripts/bench/runGold.mjs

@@ -12,20 +12,31 @@ import { fileURLToPath } from 'node:url';
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const DEFAULT_CORPUS = path.join(REPO_ROOT, 'scripts', 'bench', 'goldTasks.json');
 
+const USAGE = 'usage: runGold.mjs [--corpus <path>] [--project <dir>] [--json <path>]';
+
 function parseArgs(argv) {
   let corpusPath = DEFAULT_CORPUS;
   let projectRoot = REPO_ROOT;
   let jsonPath = null;
+  const valueFor = (flag, i) => {
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      throw new Error(`missing value for ${flag}`);
+    }
+    return next;
+  };
   for (let i = 0; i < argv.length; i += 1) {
     if (argv[i] === '--corpus') {
-      corpusPath = path.resolve(argv[i + 1] ?? corpusPath);
+      corpusPath = path.resolve(valueFor('--corpus', i));
       i += 1;
     } else if (argv[i] === '--project') {
-      projectRoot = path.resolve(argv[i + 1] ?? projectRoot);
+      projectRoot = path.resolve(valueFor('--project', i));
       i += 1;
     } else if (argv[i] === '--json') {
-      jsonPath = argv[i + 1] ? path.resolve(argv[i + 1]) : null;
+      jsonPath = path.resolve(valueFor('--json', i));
       i += 1;
+    } else {
+      throw new Error(`unknown argument: ${argv[i]}`);
     }
   }
   return { corpusPath, projectRoot, jsonPath };
@@ -202,7 +213,14 @@ export function printScorecard(results) {
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const { corpusPath, projectRoot, jsonPath } = parseArgs(process.argv.slice(2));
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`${USAGE}\n${error?.message ?? error}`);
+    process.exit(2);
+  }
+  const { corpusPath, projectRoot, jsonPath } = parsed;
   try {
     const { results, pass } = await runGold({ projectRoot, corpusPath });
     printScorecard(results);

package/scripts/bench/v3-ceremony.mjs

@@ -191,7 +191,13 @@ function renderTsv(report) {
 }
 
 async function main() {
-  const tsv = process.argv.slice(2).includes('--tsv');
+  const args = process.argv.slice(2);
+  const unknown = args.filter((arg) => arg !== '--tsv');
+  if (unknown.length > 0) {
+    console.error(`usage: v3-ceremony.mjs [--tsv]\nunknown argument: ${unknown[0]}`);
+    process.exit(2);
+  }
+  const tsv = args.includes('--tsv');
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ukit-v3-ceremony-'));
   try {
     await seedFixtureProject(tmpDir);

package/scripts/bug/triage.mjs

@@ -3,16 +3,28 @@ import path from 'node:path';
 
 import { triageBug } from '../../src/bug/triageBug.js';
 
-const args = process.argv.slice(2);
-const rootArg = readFlagValue(args, '--root');
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: remainingArgs } = extractFlagValue(args, '--root');
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
 
-const signature = args.filter((arg) => !arg.startsWith('--')).join(' ').trim();
+  // Everything after `--` is signature text; before it, only positional args
+  // are — the --root value was already consumed by extractFlagValue.
+  const separatorIndex = remainingArgs.indexOf('--');
+  const positional = separatorIndex === -1 ? remainingArgs : remainingArgs.slice(0, separatorIndex);
+  const afterSeparator = separatorIndex === -1 ? [] : remainingArgs.slice(separatorIndex + 1);
+  const unknown = positional.filter((arg) => arg.startsWith('--'));
+  if (unknown.length > 0) {
+    throw new Error(`unknown argument: ${unknown[0]}`);
+  }
+  const signature = [...positional, ...afterSeparator].join(' ').trim();
+
+  if (!signature) {
+    console.error('Usage: yarn bug:triage -- "<error signature>"');
+    process.exitCode = 1;
+    return;
+  }
 
-if (!signature) {
-  console.error('Usage: yarn bug:triage -- "<error signature>"');
-  process.exitCode = 1;
-} else {
   const result = await triageBug({ rootDir, signature });
   console.log('[bug:triage]');
   console.log(`lane: ${result.lane}`);
@@ -22,16 +34,43 @@ if (!signature) {
   console.log(`test: ${result.recommendedTestCommand}`);
 }
 
-function readFlagValue(argv, flag) {
-  const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) {
-    return argv[exact + 1];
-  }
+function extractFlagValue(argv, flag) {
+  let value = null;
+  const nextArgs = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
 
-  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
-  if (withEquals) {
-    return withEquals.slice(flag.length + 1);
+    if (arg === flag) {
+      if (value !== null) {
+        nextArgs.push(arg);
+        continue;
+      }
+      const maybeValue = argv[i + 1];
+      if (!maybeValue || maybeValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      value = maybeValue;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      if (value === null) {
+        value = arg.slice(flag.length + 1);
+        continue;
+      }
+    }
+
+    nextArgs.push(arg);
   }
 
-  return null;
+  return { value, args: nextArgs };
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
 }