musubix2 0.5.0 → 0.5.2

package/dist/index.js

@@ -11780,8 +11780,8 @@ __export(init_command_handler_exports, {
   InitCommandHandler: () => InitCommandHandler,
   createInitCommandHandler: () => createInitCommandHandler
 });
-import { readdirSync } from "node:fs";
-import { basename } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync10 } from "node:fs";
+import { basename, join as join5 } from "node:path";
 function createInitCommandHandler() {
   const locator = new PackageRootLocator();
   const catalog = new PackageAssetCatalog(locator);
@@ -11800,7 +11800,7 @@ function createInitCommandHandler() {
   const dryRunReporter = new DryRunReporter();
   return new InitCommandHandler(detector, confirmation, planner, copilotSetup, claudeSetup, merger, writer, updateService, dryRunReporter);
 }
-var InitCommandHandler;
+var STARTER_REQUIREMENTS, InitCommandHandler;
 var init_init_command_handler = __esm({
   "dist/interface/cli/init-command-handler.js"() {
     "use strict";
@@ -11819,6 +11819,20 @@ var init_init_command_handler = __esm({
     init_workspace_writer();
     init_confirmation_resolver();
     init_dry_run_reporter();
+    STARTER_REQUIREMENTS = `# \u8981\u4EF6\u5B9A\u7FA9\u66F8
+
+> \`musubix requirements analyze storage/specs/requirements.md\` \u3067\u89E3\u6790\u3067\u304D\u307E\u3059\u3002
+> \u8981\u4EF6\u306F\u898B\u51FA\u3057\u5F62\u5F0F\u30FBID \u306F \`REQ-<3\u6587\u5B57\u30C9\u30E1\u30A4\u30F3>-<3\u6841\u9023\u756A>\` \u3067\u8A18\u8FF0\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+
+## REQ-SMP-001: \u30B5\u30F3\u30D7\u30EB\u8981\u4EF6
+**\u7A2E\u5225**: UBIQUITOUS
+**\u512A\u5148\u5EA6**: P1
+**\u8981\u4EF6**:
+THE \u30B7\u30B9\u30C6\u30E0 SHALL \u30E6\u30FC\u30B6\u30FC\u306B\u30B5\u30F3\u30D7\u30EB\u6A5F\u80FD\u3092\u63D0\u4F9B\u3059\u308B\u3002
+
+**\u53D7\u5165\u57FA\u6E96**:
+- [ ] \u30B5\u30F3\u30D7\u30EB\u6A5F\u80FD\u304C\u52D5\u4F5C\u3059\u308B
+`;
     InitCommandHandler = class {
       detector;
       confirmation;
@@ -11886,22 +11900,49 @@ var init_init_command_handler = __esm({
           await this.writer.execute(copilotOps, false);
         }
         const summary = await this.writer.execute([], true);
+        const scaffolded = options.dryRun ? [] : this.scaffoldSddWorkspace(options.projectPath);
         return {
           detectedPlatforms: selection,
-          created: summary.created,
+          created: [...summary.created, ...scaffolded],
           updated: summary.updated,
           skipped: summary.skipped,
           warnings,
           durationMs: Date.now() - start
         };
       }
-      buildProjectContext(projectPath) {
-        const name = basename(projectPath);
-        let rootStructure = [];
+      /**
+       * Create the SDD directory skeleton and a parseable starter requirements
+       * document. Idempotent and non-destructive — existing files are left as-is.
+       * Returns the relative paths of files/dirs actually created.
+       */
+      scaffoldSddWorkspace(projectPath) {
+        const created = [];
         try {
-          rootStructure = readdirSync(projectPath, { withFileTypes: true }).slice(0, 20).map((d) => d.isDirectory() ? `${d.name}/` : d.name);
+          for (const dir of ["steering", "storage/specs"]) {
+            const abs = join5(projectPath, dir);
+            if (!existsSync10(abs)) {
+              mkdirSync2(abs, { recursive: true });
+              created.push(`${dir}/`);
+            }
+          }
+          const reqPath = join5(projectPath, "storage/specs/requirements.md");
+          if (!existsSync10(reqPath)) {
+            writeFileSync2(reqPath, STARTER_REQUIREMENTS, "utf-8");
+            created.push("storage/specs/requirements.md");
+          }
         } catch {
         }
+        return created;
+      }
+      buildProjectContext(projectPath) {
+        const name = basename(projectPath);
+        const rootStructure = [
+          "steering/            # \u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u30E1\u30E2\u30EA\uFF08\u6C7A\u5B9A\u524D\u306B\u53C2\u7167\uFF09",
+          "storage/specs/       # requirements / design / tasks \u4ED5\u69D8",
+          ".claude/skills/      # SDD Agent Skills",
+          "src/                 # \u5B9F\u88C5\u30B3\u30FC\u30C9",
+          "tests/               # \u30C6\u30B9\u30C8\u30B3\u30FC\u30C9"
+        ];
         return {
           projectName: name,
           packageManager: "npm",
@@ -12903,7 +12944,7 @@ __export(dist_exports16, {
 import { execFile } from "node:child_process";
 import { writeFile as writeFile3, unlink } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 import { promisify } from "node:util";
 import { randomBytes } from "node:crypto";
 function sanitizeName(raw) {
@@ -13106,7 +13147,7 @@ var init_dist16 = __esm({
       }
       async realSolve(smtScript) {
         const start = Date.now();
-        const tmpFile = join5(tmpdir2(), `musubix2-z3-${randomBytes(8).toString("hex")}.smt2`);
+        const tmpFile = join6(tmpdir2(), `musubix2-z3-${randomBytes(8).toString("hex")}.smt2`);
         try {
           await writeFile3(tmpFile, smtScript, "utf-8");
           const { stdout, stderr } = await execFileAsync(this.z3Path, ["-smt2", tmpFile], {
@@ -13330,7 +13371,7 @@ __export(dist_exports17, {
 import { execFile as execFile2 } from "node:child_process";
 import { writeFile as writeFile4, unlink as unlink2 } from "node:fs/promises";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 import { randomBytes as randomBytes2 } from "node:crypto";
 function createLeanIntegration() {
@@ -13454,7 +13495,7 @@ var init_dist17 = __esm({
             time: Date.now() - start
           };
         }
-        const tmpFile = join6(tmpdir3(), `musubix2-lean-${randomBytes2(8).toString("hex")}.lean`);
+        const tmpFile = join7(tmpdir3(), `musubix2-lean-${randomBytes2(8).toString("hex")}.lean`);
         try {
           await writeFile4(tmpFile, leanCode, "utf-8");
           const timeout = timeoutMs ?? this.defaultTimeoutMs;
@@ -15219,7 +15260,8 @@ init_dist5();
 init_dist6();
 init_dist();
 init_dist();
-import { readFileSync as readFileSync6, existsSync as existsSync10 } from "node:fs";
+import { readFileSync as readFileSync6, existsSync as existsSync11, statSync, readdirSync } from "node:fs";
+import { join as joinPath } from "node:path";
 function parseArgs(argv) {
   const command = argv[0] ?? "";
   let subcommand;
@@ -15279,7 +15321,7 @@ var COMMAND_HELP = {
     description: "\u8A2D\u8A08\u751F\u6210"
   },
   codegen: {
-    usage: "musubix codegen [options]",
+    usage: "musubix codegen [generate] <name> [--type class|interface|function|...]",
     description: "\u30B3\u30FC\u30C9\u751F\u6210"
   },
   tasks: {
@@ -15315,8 +15357,8 @@ var COMMAND_HELP = {
     description: "\u30B3\u30FC\u30C9\u30B0\u30E9\u30D5\u5206\u6790"
   },
   security: {
-    usage: "musubix security <path>",
-    description: "\u30BB\u30AD\u30E5\u30EA\u30C6\u30A3\u30B9\u30AD\u30E3\u30F3"
+    usage: "musubix security <path> [--fail-on critical|high|medium|low|info]",
+    description: "\u30BB\u30AD\u30E5\u30EA\u30C6\u30A3\u30B9\u30AD\u30E3\u30F3\uFF08\u30D5\u30A1\u30A4\u30EB/\u30C7\u30A3\u30EC\u30AF\u30C8\u30EA\u5BFE\u5FDC\uFF09"
   },
   skills: {
     usage: "musubix skills <list|validate|create> [args]",
@@ -15411,7 +15453,7 @@ var CLIDispatcher = class {
     if (!command) {
       throw new Error(`Unknown command: ${commandName}. Available: ${[...this.commands.keys()].join(", ")}`);
     }
-    await command.action(args);
+    return await command.action(args);
   }
   getHelp() {
     const lines = [
@@ -15449,12 +15491,12 @@ var CLIDispatcher = class {
       return ExitCode.SUCCESS;
     }
     try {
-      await this.dispatch(parsed.command, {
+      const result = await this.dispatch(parsed.command, {
         subcommand: parsed.subcommand,
         args: parsed.args,
         ...parsed.flags
       });
-      return ExitCode.SUCCESS;
+      return result ?? ExitCode.SUCCESS;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(message);
@@ -15556,21 +15598,21 @@ async function handleInit(targetPath = ".", name, force) {
     console.log(`  ${f}`);
   }
   try {
-    const { cpSync, existsSync: existsSync11, mkdirSync: mkdirSync2 } = await import("node:fs");
+    const { cpSync, existsSync: existsSync12, mkdirSync: mkdirSync3 } = await import("node:fs");
     const { resolve: resolve9, dirname: dirname4 } = await import("node:path");
     const { fileURLToPath: fileURLToPath2 } = await import("node:url");
     const thisDir = typeof __dirname !== "undefined" ? __dirname : dirname4(fileURLToPath2(import.meta.url));
     const pkgGithub = resolve9(thisDir, "..", ".github");
     const destGithub = resolve9(targetPath, ".github");
-    if (existsSync11(pkgGithub)) {
-      mkdirSync2(destGithub, { recursive: true });
+    if (existsSync12(pkgGithub)) {
+      mkdirSync3(destGithub, { recursive: true });
       const skillsSrc = resolve9(pkgGithub, "skills");
-      if (existsSync11(skillsSrc)) {
+      if (existsSync12(skillsSrc)) {
         cpSync(skillsSrc, resolve9(destGithub, "skills"), { recursive: true });
         console.log("  .github/skills/ (SDD skills)");
       }
       const instrSrc = resolve9(pkgGithub, "copilot-instructions.md");
-      if (existsSync11(instrSrc)) {
+      if (existsSync12(instrSrc)) {
         cpSync(instrSrc, resolve9(destGithub, "copilot-instructions.md"));
         console.log("  .github/copilot-instructions.md");
       }
@@ -15585,6 +15627,7 @@ async function handleTrace(sub, args) {
       const generator = createMatrixGenerator();
       const report = generator.generate([], [], []);
       console.log(generator.toMarkdown(report));
+      console.log("\n\u2139 No traceability data loaded \u2014 matrix is empty (completeness is N/A).");
       return ExitCode.SUCCESS;
     }
     case "validate": {
@@ -15616,6 +15659,11 @@ async function handleTrace(sub, args) {
 async function handleTraceVerify() {
   const validator = createTraceabilityValidator();
   const report = validator.validateCoverage([], [], [], []);
+  if (report.totalRequirements === 0) {
+    console.log("No traceability data loaded \u2014 nothing to verify.");
+    console.log("\u2139 Coverage cannot be computed with 0 requirements (reported as N/A).");
+    return ExitCode.SUCCESS;
+  }
   console.log(`Coverage: ${report.coveragePercent}%`);
   console.log(`Requirements: ${report.coveredRequirements}/${report.totalRequirements}`);
   if (report.gaps.length > 0) {
@@ -15715,6 +15763,31 @@ var EXT_TO_LANG = {
   hs: "haskell",
   lua: "lua"
 };
+var WALK_IGNORE = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "coverage", ".next", "build"]);
+function collectFiles(target, extFilter) {
+  const stat = statSync(target);
+  if (stat.isFile())
+    return [target];
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") && entry.name !== ".")
+        continue;
+      if (WALK_IGNORE.has(entry.name))
+        continue;
+      const full = joinPath(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        const ext = entry.name.split(".").pop() ?? "";
+        if (!extFilter || extFilter(ext))
+          out.push(full);
+      }
+    }
+  };
+  walk(target);
+  return out;
+}
 async function handleCodegraph(sub, args) {
   switch (sub) {
     case "index": {
@@ -15724,29 +15797,40 @@ async function handleCodegraph(sub, args) {
         return ExitCode.GENERAL_ERROR;
       }
       try {
-        const parser = createASTParser();
-        const content = readFileSync6(targetPath, "utf-8");
-        const ext = targetPath.split(".").pop() ?? "";
-        const lang = EXT_TO_LANG[ext];
-        if (!lang) {
-          console.error(`\u274C Unsupported file extension: .${ext}`);
+        if (!existsSync11(targetPath)) {
+          console.error(`\u274C Path not found: ${targetPath}`);
           return ExitCode.GENERAL_ERROR;
         }
-        const nodes = parser.parse(content, lang);
+        const parser = createASTParser();
         const engine = createGraphEngine();
-        for (const node of nodes) {
-          engine.addNode({
-            id: `${targetPath}:${node.name}`,
-            name: node.name,
-            kind: node.kind,
-            filePath: targetPath,
-            language: lang,
-            startLine: 0,
-            endLine: 0
-          });
+        const files = collectFiles(targetPath, (ext) => ext in EXT_TO_LANG);
+        if (files.length === 0) {
+          console.error(`\u274C No indexable source files found under: ${targetPath}`);
+          return ExitCode.GENERAL_ERROR;
+        }
+        let indexedFiles = 0;
+        for (const file of files) {
+          const ext = file.split(".").pop() ?? "";
+          const lang = EXT_TO_LANG[ext];
+          if (!lang)
+            continue;
+          const content = readFileSync6(file, "utf-8");
+          const nodes = parser.parse(content, lang);
+          for (const node of nodes) {
+            engine.addNode({
+              id: `${file}:${node.name}`,
+              name: node.name,
+              kind: node.kind,
+              filePath: file,
+              language: lang,
+              startLine: 0,
+              endLine: 0
+            });
+          }
+          indexedFiles++;
         }
         const stats = engine.getStats();
-        console.log(`\u2705 Indexed ${targetPath}: ${stats.nodeCount} nodes, ${stats.edgeCount} edges`);
+        console.log(`\u2705 Indexed ${targetPath}: ${indexedFiles} file(s), ${stats.nodeCount} nodes, ${stats.edgeCount} edges`);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`\u274C ${msg}`);
@@ -15788,40 +15872,54 @@ async function handleCodegraph(sub, args) {
       return ExitCode.SUCCESS;
   }
 }
-async function handleSecurity(filePath) {
+var SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"];
+async function handleSecurity(filePath, failOn) {
   try {
-    if (!existsSync10(filePath)) {
-      console.error(`\u274C File not found: ${filePath}`);
+    if (!existsSync11(filePath)) {
+      console.error(`\u274C Path not found: ${filePath}`);
       return ExitCode.GENERAL_ERROR;
     }
-    const code = readFileSync6(filePath, "utf-8");
     const secrets = createSecretDetector();
     const taint = new TaintAnalyzer();
     const deps = new DependencyScanner();
-    const findings = [
-      ...secrets.scan(code, filePath),
-      ...taint.analyze(code, filePath),
-      ...deps.scan(code, filePath)
-    ];
+    const files = collectFiles(filePath, (ext) => ext in EXT_TO_LANG);
+    const findings = [];
+    for (const file of files) {
+      const code = readFileSync6(file, "utf-8");
+      findings.push(...secrets.scan(code, file), ...taint.analyze(code, file), ...deps.scan(code, file));
+    }
     const bySeverity = /* @__PURE__ */ new Map();
     for (const f of findings) {
       const list = bySeverity.get(f.severity) ?? [];
       list.push(f);
       bySeverity.set(f.severity, list);
     }
-    console.log(`Security scan: ${filePath}`);
+    console.log(`Security scan: ${filePath} (${files.length} file(s))`);
     console.log(`Total findings: ${findings.length}`);
-    const severityOrder = ["critical", "high", "medium", "low", "info"];
-    for (const sev of severityOrder) {
+    for (const sev of SEVERITY_ORDER) {
       const items = bySeverity.get(sev);
       if (items && items.length > 0) {
         console.log(`
   ${sev.toUpperCase()} (${items.length}):`);
         for (const f of items) {
-          console.log(`    - ${f.description}`);
+          console.log(`    - ${f.description} (${f.location.file}:${f.location.line})`);
         }
       }
     }
+    if (failOn) {
+      const threshold = failOn.toLowerCase();
+      if (!SEVERITY_ORDER.includes(threshold)) {
+        console.error(`\u274C Invalid --fail-on severity: ${failOn} (use critical|high|medium|low|info)`);
+        return ExitCode.VALIDATION_ERROR;
+      }
+      const maxIdx = SEVERITY_ORDER.indexOf(threshold);
+      const gating = findings.filter((f) => SEVERITY_ORDER.indexOf(f.severity) <= maxIdx);
+      if (gating.length > 0) {
+        console.error(`
+\u274C ${gating.length} finding(s) at or above "${threshold}" \u2014 failing.`);
+        return ExitCode.VALIDATION_ERROR;
+      }
+    }
     return ExitCode.SUCCESS;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -15908,6 +16006,17 @@ async function handleReqValidate(filePath) {
     }
     if (requirements.length === 0) {
       console.log("No requirements found in file");
+      if (/REQ-/i.test(content)) {
+        const headingLike = /^#{1,4}\s+REQ-[A-Z]{3}-\d{3}:/m.test(content);
+        console.error('\u26A0 Found "REQ-" text but no parseable requirements. Requirements must be Markdown headings shaped like:');
+        console.error("    ## REQ-XXX-000: <title>   (XXX = 3-letter domain code)");
+        console.error("    **\u8981\u4EF6**:");
+        console.error("    THE \u30B7\u30B9\u30C6\u30E0 SHALL ...");
+        if (!headingLike) {
+          console.error('\u2139 Hint: list items (e.g. "- REQ-001: ...") and IDs without a 3-letter domain code are not recognized.');
+        }
+        return ExitCode.VALIDATION_ERROR;
+      }
     }
     return hasIssues ? ExitCode.VALIDATION_ERROR : ExitCode.SUCCESS;
   } catch (err) {
@@ -16498,7 +16607,7 @@ async function handleExplain(input) {
   const recorder = new ReasoningChainRecorder2();
   const generator = new ExplanationGenerator2();
   let code;
-  if (existsSync10(input)) {
+  if (existsSync11(input)) {
     code = readFileSync6(input, "utf-8");
   } else {
     code = input;
@@ -16626,6 +16735,29 @@ async function handleWatch(pattern) {
   });
   return ExitCode.SUCCESS;
 }
+function resolveTarget(args, verbs) {
+  const positional = args["args"] ?? [];
+  const sub = args["subcommand"];
+  const explicitFile = args["file"];
+  if (explicitFile)
+    return explicitFile;
+  if (sub && verbs.includes(sub.toLowerCase())) {
+    return positional[0];
+  }
+  return sub ?? positional[0];
+}
+async function reqAction(args) {
+  if (args["help"] === true || args["h"] === true) {
+    console.log(showHelp("requirements"));
+    return;
+  }
+  const filePath = resolveTarget(args, ["analyze", "validate"]);
+  if (!filePath) {
+    console.error("\u274C Usage: musubix requirements [analyze|validate] <file>");
+    return ExitCode.VALIDATION_ERROR;
+  }
+  return await handleReqValidate(filePath);
+}
 function getDefaultCommands() {
   return [
     {
@@ -16675,7 +16807,7 @@ function getDefaultCommands() {
           return;
         }
         const targetPath = args["subcommand"] ?? args["args"]?.[0] ?? ".";
-        await handleInit(targetPath, args["name"], args["force"] === true);
+        return await handleInit(targetPath, args["name"], args["force"] === true);
       }
     },
     {
@@ -16693,37 +16825,32 @@ function getDefaultCommands() {
           case "validate":
             if (!filePath) {
               console.error("\u274C Usage: musubix tasks validate <file>");
-              return;
+              return ExitCode.VALIDATION_ERROR;
             }
-            await handleTasksValidate(filePath);
+            return await handleTasksValidate(filePath);
             break;
           case "list":
-            await handleTasksList(filePath);
+            return await handleTasksList(filePath);
             break;
           case "stats":
-            await handleTasksStats(filePath);
+            return await handleTasksStats(filePath);
             break;
           default:
             console.log(showHelp("tasks"));
+            return;
         }
       }
     },
     {
       name: "req",
       description: "Analyze requirements (EARS validation)",
-      action: async (args) => {
-        if (args["help"] === true || args["h"] === true) {
-          console.log(showHelp("requirements"));
-          return;
-        }
-        const positionalArgs = args["args"] ?? [];
-        const filePath = args["file"] ?? args["subcommand"] ?? positionalArgs[0];
-        if (!filePath) {
-          console.error("\u274C Usage: musubix req <file>");
-          return;
-        }
-        await handleReqValidate(filePath);
-      }
+      action: reqAction
+    },
+    {
+      // Alias matching the documented `musubix requirements <analyze|validate> <file>` form.
+      name: "requirements",
+      description: "Analyze/validate requirements (EARS validation)",
+      action: reqAction
     },
     {
       name: "req:wizard",
@@ -16733,7 +16860,7 @@ function getDefaultCommands() {
           console.log(showHelp("requirements"));
           return;
         }
-        await handleReqWizard();
+        return await handleReqWizard();
       }
     },
     {
@@ -16744,7 +16871,7 @@ function getDefaultCommands() {
           console.log(showHelp("requirements"));
           return;
         }
-        await handleReqInterview(args);
+        return await handleReqInterview(args);
       }
     },
     {
@@ -16755,13 +16882,20 @@ function getDefaultCommands() {
           console.log(showHelp("design"));
           return;
         }
-        const positionalArgs = args["args"] ?? [];
-        const filePath = args["file"] ?? args["subcommand"] ?? positionalArgs[0];
+        if (args["subcommand"]?.toLowerCase() === "verify") {
+          const vf = resolveTarget(args, ["verify"]);
+          if (!vf) {
+            console.error("\u274C Usage: musubix design verify <design-file>");
+            return ExitCode.VALIDATION_ERROR;
+          }
+          return await handleDesignVerify(vf);
+        }
+        const filePath = resolveTarget(args, ["generate"]);
         if (!filePath) {
-          console.error("\u274C Usage: musubix design <requirements-file>");
-          return;
+          console.error("\u274C Usage: musubix design [generate] <requirements-file>");
+          return ExitCode.VALIDATION_ERROR;
         }
-        await handleDesignGenerate(filePath);
+        return await handleDesignGenerate(filePath);
       }
     },
     {
@@ -16776,10 +16910,10 @@ function getDefaultCommands() {
         const filePath = args["file"] ?? args["subcommand"] ?? positionalArgs[0];
         if (!filePath) {
           console.error("\u274C Usage: musubix design:c4 <file> [--level context|container|component]");
-          return;
+          return ExitCode.VALIDATION_ERROR;
         }
         const level = args["level"] ?? "context";
-        await handleDesignC4(filePath, level);
+        return await handleDesignC4(filePath, level);
       }
     },
     {
@@ -16794,9 +16928,9 @@ function getDefaultCommands() {
         const filePath = args["file"] ?? args["subcommand"] ?? positionalArgs[0];
         if (!filePath) {
           console.error("\u274C Usage: musubix design:verify <design-file>");
-          return;
+          return ExitCode.VALIDATION_ERROR;
         }
-        await handleDesignVerify(filePath);
+        return await handleDesignVerify(filePath);
       }
     },
     {
@@ -16807,14 +16941,13 @@ function getDefaultCommands() {
           console.log(showHelp("codegen"));
           return;
         }
-        const positionalArgs = args["args"] ?? [];
-        const name = args["subcommand"] ?? positionalArgs[0];
+        const name = resolveTarget(args, ["generate"]);
         if (!name) {
-          console.error("\u274C Usage: musubix codegen <name> [--type class|interface|function|...]");
-          return;
+          console.error("\u274C Usage: musubix codegen [generate] <name> [--type class|interface|function|...]");
+          return ExitCode.VALIDATION_ERROR;
         }
         const type = args["type"] ?? "class";
-        await handleCodegen(name, type);
+        return await handleCodegen(name, type);
       }
     },
     {
@@ -16829,9 +16962,9 @@ function getDefaultCommands() {
         const filePath = args["file"] ?? args["subcommand"] ?? positionalArgs[0];
         if (!filePath) {
           console.error("\u274C Usage: musubix test:gen <source-file>");
-          return;
+          return ExitCode.VALIDATION_ERROR;
         }
-        await handleTestGen(filePath);
+        return await handleTestGen(filePath);
       }
     },
     {
@@ -16844,7 +16977,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleTrace(sub, positionalArgs);
+        return await handleTrace(sub, positionalArgs);
       }
     },
     {
@@ -16855,7 +16988,7 @@ function getDefaultCommands() {
           console.log(showHelp("trace:verify"));
           return;
         }
-        await handleTraceVerify();
+        return await handleTraceVerify();
       }
     },
     {
@@ -16868,7 +17001,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handlePolicy(sub, positionalArgs);
+        return await handlePolicy(sub, positionalArgs);
       }
     },
     {
@@ -16880,7 +17013,7 @@ function getDefaultCommands() {
           return;
         }
         const sub = args["subcommand"];
-        await handleOntology(sub);
+        return await handleOntology(sub);
       }
     },
     {
@@ -16893,7 +17026,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleCodegraph(sub, positionalArgs);
+        return await handleCodegraph(sub, positionalArgs);
       }
     },
     {
@@ -16907,10 +17040,10 @@ function getDefaultCommands() {
         const positionalArgs = args["args"] ?? [];
         const filePath = args["subcommand"] ?? positionalArgs[0];
         if (!filePath) {
-          console.error("\u274C Usage: musubix security <path>");
-          return;
+          console.error("\u274C Usage: musubix security <path> [--fail-on critical|high|medium|low|info]");
+          return ExitCode.VALIDATION_ERROR;
         }
-        await handleSecurity(filePath);
+        return await handleSecurity(filePath, args["fail-on"]);
       }
     },
     {
@@ -16923,7 +17056,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleWorkflow(sub, positionalArgs);
+        return await handleWorkflow(sub, positionalArgs);
       }
     },
     {
@@ -16934,7 +17067,7 @@ function getDefaultCommands() {
           console.log(showHelp("status"));
           return;
         }
-        await handleStatus();
+        return await handleStatus();
       }
     },
     {
@@ -16947,7 +17080,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleSkills(sub, positionalArgs);
+        return await handleSkills(sub, positionalArgs);
       }
     },
     {
@@ -16960,7 +17093,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleKnowledge(sub, positionalArgs, args);
+        return await handleKnowledge(sub, positionalArgs, args);
       }
     },
     {
@@ -16973,7 +17106,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleDecision(sub, positionalArgs, args);
+        return await handleDecision(sub, positionalArgs, args);
       }
     },
     {
@@ -16986,7 +17119,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleDeepResearch(sub, positionalArgs);
+        return await handleDeepResearch(sub, positionalArgs);
       }
     },
     {
@@ -16997,7 +17130,7 @@ function getDefaultCommands() {
           console.log(showHelp("repl"));
           return;
         }
-        await handleRepl();
+        return await handleRepl();
       }
     },
     {
@@ -17010,7 +17143,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleScaffold(sub, positionalArgs);
+        return await handleScaffold(sub, positionalArgs);
       }
     },
     {
@@ -17023,7 +17156,7 @@ function getDefaultCommands() {
         }
         const positionalArgs = args["args"] ?? [];
         const input = args["subcommand"] ?? positionalArgs[0];
-        await handleExplain(input);
+        return await handleExplain(input);
       }
     },
     {
@@ -17036,7 +17169,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleLearn(sub, positionalArgs);
+        return await handleLearn(sub, positionalArgs);
       }
     },
     {
@@ -17049,7 +17182,7 @@ function getDefaultCommands() {
         }
         const sub = args["subcommand"];
         const positionalArgs = args["args"] ?? [];
-        await handleSynthesis(sub, positionalArgs);
+        return await handleSynthesis(sub, positionalArgs);
       }
     },
     {
@@ -17062,7 +17195,7 @@ function getDefaultCommands() {
         }
         const positionalArgs = args["args"] ?? [];
         const pattern = args["subcommand"] ?? positionalArgs[0];
-        await handleWatch(pattern);
+        return await handleWatch(pattern);
       }
     },
     // P3-07: MCP server launcher