opencode-swarm 7.56.2 → 7.57.0

package/dist/cli/index.js

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.56.2",
+    version: "7.57.0",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -39792,6 +39792,130 @@ var init_close = __esm(() => {
   ];
 });
 
+// src/commands/codebase-review.ts
+function sanitizeText(raw, maxLen) {
+  const stripped = raw.replace(/\[+\s*MODE\s*:[^\]]*(?:\]+|$)/gi, "");
+  const normalized = stripped.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLen)
+    return normalized;
+  return `${normalized.slice(0, maxLen)}...`;
+}
+function hasFlagValue(args, index) {
+  return index + 1 < args.length && !args[index + 1].startsWith("--");
+}
+function jsonForModeHeader(value) {
+  return JSON.stringify(value).replace(/[[\]]/g, (ch) => ch === "[" ? "\\u005B" : "\\u005D");
+}
+function parseArgs(args) {
+  const result = {
+    mode: DEFAULT_MODE,
+    tracks: "",
+    continueRun: "",
+    output: "markdown",
+    updateMain: true,
+    allowDirty: false,
+    rest: []
+  };
+  let i = 0;
+  while (i < args.length) {
+    const token = args[i];
+    if (token === "--help" || token === "-h") {
+      result.help = true;
+    } else if (token === "--mode") {
+      if (!hasFlagValue(args, i)) {
+        return { ...result, error: FLAG_VALUE_MISSING(token) };
+      }
+      const value = args[++i];
+      if (!MODES.has(value)) {
+        return {
+          ...result,
+          error: `Invalid mode "${value}". Must be one of: ${[...MODES].join(", ")}.`
+        };
+      }
+      result.mode = value;
+    } else if (token === "--tracks") {
+      if (!hasFlagValue(args, i)) {
+        return { ...result, error: FLAG_VALUE_MISSING(token) };
+      }
+      result.tracks = sanitizeText(args[++i], MAX_TRACKS_LEN);
+    } else if (token === "--continue") {
+      if (!hasFlagValue(args, i)) {
+        return { ...result, error: FLAG_VALUE_MISSING(token) };
+      }
+      const runId = sanitizeText(args[++i], MAX_RUN_ID_LEN);
+      if (!/^[A-Za-z0-9_.-]+$/.test(runId)) {
+        return {
+          ...result,
+          error: "Invalid --continue value. Use only letters, numbers, dot, underscore, or dash."
+        };
+      }
+      result.continueRun = runId;
+    } else if (token === "--json") {
+      result.output = "json";
+    } else if (token === "--skip-update") {
+      result.updateMain = false;
+    } else if (token === "--allow-dirty") {
+      result.allowDirty = true;
+    } else if (token.startsWith("--")) {
+      return { ...result, error: `Unknown flag "${token}"` };
+    } else {
+      result.rest.push(token);
+    }
+    i++;
+  }
+  return result;
+}
+async function handleCodebaseReviewCommand(_directory, args) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    return USAGE;
+  }
+  if (parsed.error) {
+    return `Error: ${parsed.error}
+
+${USAGE}`;
+  }
+  const scope = sanitizeText(parsed.rest.join(" "), MAX_SCOPE_LEN) || DEFAULT_SCOPE;
+  return [
+    `[MODE: CODEBASE_REVIEW mode=${parsed.mode} output=${parsed.output} update_main=${parsed.updateMain} allow_dirty=${parsed.allowDirty} tracks=${jsonForModeHeader(parsed.tracks)} continue_run=${jsonForModeHeader(parsed.continueRun)}]`,
+    `scope=${JSON.stringify(scope)}`
+  ].join(" ");
+}
+var MAX_SCOPE_LEN = 2000, MAX_TRACKS_LEN = 1000, MAX_RUN_ID_LEN = 128, CODEBASE_REVIEW_MODES, MODES, DEFAULT_MODE = "phase0", DEFAULT_SCOPE = "repository root", FLAG_VALUE_MISSING = (token) => `Flag "${token}" requires a value`, USAGE = `Usage: /swarm codebase-review [scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]
+
+Run the codebase-review-swarm workflow in the current repository.
+
+Examples:
+  /swarm codebase-review
+  /swarm codebase review src/auth --mode security
+  /swarm codebase-review "frontend accessibility" --mode ui --json
+  /swarm codebase-review --mode custom --tracks "security,testing"
+
+Flags:
+  --mode <name>       phase0, complete, defect, security, correctness, testing, ui, performance, ai-slop, enhancements, or custom
+  --tracks <list>     custom selected tracks or review notes passed to the workflow
+  --continue <run-id> continue an existing .swarm/review-v8 run
+  --json              request JSON-compatible report blocks
+  --skip-update       skip the repo update-to-main preflight
+  --allow-dirty       allow review to proceed with dirty worktree
+  --help              show this usage`;
+var init_codebase_review = __esm(() => {
+  CODEBASE_REVIEW_MODES = [
+    "phase0",
+    "complete",
+    "defect",
+    "security",
+    "correctness",
+    "testing",
+    "ui",
+    "performance",
+    "ai-slop",
+    "enhancements",
+    "custom"
+  ];
+  MODES = new Set(CODEBASE_REVIEW_MODES);
+});
+
 // src/commands/concurrency.ts
 async function handleConcurrencyCommand(directory, args, sessionID) {
   if (!sessionID || sessionID.trim() === "") {
@@ -39944,7 +40068,7 @@ function sanitizePresetName(raw) {
     return null;
   return trimmed;
 }
-function parseArgs(args) {
+function parseArgs2(args) {
   const out = { specReview: false, rest: [] };
   for (let i = 0;i < args.length; i++) {
     const token = args[i];
@@ -39967,10 +40091,10 @@ function parseArgs(args) {
   return out;
 }
 async function handleCouncilCommand(_directory, args) {
-  const parsed = parseArgs(args);
+  const parsed = parseArgs2(args);
   const question = sanitizeQuestion(parsed.rest.join(" "));
   if (!question) {
-    return USAGE;
+    return USAGE2;
   }
   const tokens = ["MODE: COUNCIL"];
   if (parsed.preset) {
@@ -39981,9 +40105,9 @@ async function handleCouncilCommand(_directory, args) {
   }
   return `[${tokens.join(" ")}] ${question}`;
 }
-var MAX_QUESTION_LEN = 2000, USAGE;
+var MAX_QUESTION_LEN = 2000, USAGE2;
 var init_council = __esm(() => {
-  USAGE = [
+  USAGE2 = [
     "Usage: /swarm council <question> [--preset <name>] [--spec-review]",
     "",
     "  question         The question to put to the council",
@@ -40442,9 +40566,9 @@ function sanitizeScope(raw) {
   const collapsed = raw.replace(/\s+/g, " ").trim();
   const stripped = collapsed.replace(/\[\s*MODE\s*:[^\]]*\]/gi, "");
   const normalized = stripped.replace(/\s+/g, " ").trim();
-  if (normalized.length <= MAX_SCOPE_LEN)
+  if (normalized.length <= MAX_SCOPE_LEN2)
     return normalized;
-  return `${normalized.slice(0, MAX_SCOPE_LEN)}\u2026`;
+  return `${normalized.slice(0, MAX_SCOPE_LEN2)}\u2026`;
 }
 function isValidPositiveInteger(raw) {
   if (!raw || !/^\d+$/.test(raw))
@@ -40454,7 +40578,7 @@ function isValidPositiveInteger(raw) {
     return false;
   return true;
 }
-function parseArgs2(args) {
+function parseArgs3(args) {
   const result = {
     profile: DEFAULT_PROFILE,
     maxExplorers: DEFAULT_MAX_EXPLORERS,
@@ -40507,15 +40631,15 @@ function parseArgs2(args) {
   return result;
 }
 async function handleDeepDiveCommand(_directory, args) {
-  const parsed = parseArgs2(args);
+  const parsed = parseArgs3(args);
   if (parsed.error) {
     return `Error: ${parsed.error}
 
-${USAGE2}`;
+${USAGE3}`;
   }
   const scope = sanitizeScope(parsed.rest.join(" "));
   if (!scope) {
-    return USAGE2;
+    return USAGE3;
   }
   if (parsed.profile === "full" && !parsed.maxExplorersExplicit) {
     parsed.maxExplorers = FULL_PROFILE_DEFAULT_MAX_EXPLORERS;
@@ -40523,7 +40647,7 @@ ${USAGE2}`;
   const header = `[MODE: DEEP_DIVE profile=${parsed.profile} max_explorers=${parsed.maxExplorers} output=${parsed.output} update_main=${parsed.updateMain} allow_dirty=${parsed.allowDirty}] ${scope}`;
   return header;
 }
-var MAX_SCOPE_LEN = 2000, PROFILES, DEFAULT_PROFILE = "standard", DEFAULT_MAX_EXPLORERS = 6, FULL_PROFILE_DEFAULT_MAX_EXPLORERS = 8, USAGE2 = `Usage: /swarm deep-dive <scope> [--profile standard|security|ux|architecture|full] [--max-explorers N] [--json] [--skip-update] [--allow-dirty]
+var MAX_SCOPE_LEN2 = 2000, PROFILES, DEFAULT_PROFILE = "standard", DEFAULT_MAX_EXPLORERS = 6, FULL_PROFILE_DEFAULT_MAX_EXPLORERS = 8, USAGE3 = `Usage: /swarm deep-dive <scope> [--profile standard|security|ux|architecture|full] [--max-explorers N] [--json] [--skip-update] [--allow-dirty]
 
 Run a bounded, evidence-backed deep dive on an application section.
 
@@ -40566,7 +40690,7 @@ function cleanFlagValue(raw) {
     return null;
   return raw;
 }
-function parseArgs3(args) {
+function parseArgs4(args) {
   const result = {
     out: "docs",
     lang: "auto",
@@ -40621,30 +40745,30 @@ function parseArgs3(args) {
   return result;
 }
 async function handleDesignDocsCommand(directory, args) {
-  const parsed = parseArgs3(args);
+  const parsed = parseArgs4(args);
   if (parsed.error) {
     return `Error: ${parsed.error}
 
-${USAGE3}`;
+${USAGE4}`;
   }
   try {
     const { config: config3 } = loadPluginConfigWithMeta(directory);
     if (config3.design_docs?.enabled !== true) {
       return "Error: design docs are disabled. Set `design_docs.enabled: true` in " + `opencode-swarm.json to enable the docs_design agent and this command.
 
-` + USAGE3;
+` + USAGE4;
     }
   } catch (configErr) {
     console.warn(`[design-docs] Could not read opencode-swarm.json (${String(configErr)}). ` + "Falling through \u2014 the architect will abort if docs_design is not registered.");
   }
   const description = sanitizeDescription(parsed.rest.join(" "));
   if (!description && !parsed.update) {
-    return USAGE3;
+    return USAGE4;
   }
   const header = `[MODE: DESIGN_DOCS out=${parsed.out} lang=${parsed.lang} update=${parsed.update}] ${description}`;
   return header.trimEnd();
 }
-var MAX_DESC_LEN = 2000, USAGE3 = `Usage: /swarm design-docs <description> [--out <dir>] [--lang <name>] [--update]
+var MAX_DESC_LEN = 2000, USAGE4 = `Usage: /swarm design-docs <description> [--out <dir>] [--lang <name>] [--update]
 
 Generate or sync language-agnostic design docs for the project under build:
   <out>/domain.md, <out>/technical-spec.md, <out>/behavior-spec.md,
@@ -46027,7 +46151,7 @@ function validateAndSanitizeUrl(rawUrl) {
     return { error: "Invalid URL format" };
   }
 }
-function parseArgs4(args) {
+function parseArgs5(args) {
   const out = {
     plan: false,
     trace: false,
@@ -46118,24 +46242,24 @@ function parseGitRemoteUrl(remoteUrl) {
   return null;
 }
 function handleIssueCommand(_directory, args) {
-  const parsed = parseArgs4(args);
+  const parsed = parseArgs5(args);
   const rawInput = parsed.rest.join(" ").trim();
   if (!rawInput) {
-    return USAGE4;
+    return USAGE5;
   }
   const isFullUrl = /^https?:\/\//i.test(rawInput);
   const issueInfo = parseIssueRef(isFullUrl ? sanitizeUrl(rawInput) : rawInput);
   if (!issueInfo) {
     return `Error: Could not parse issue reference from "${rawInput}"
 
-${USAGE4}`;
+${USAGE5}`;
   }
   const issueUrl = `https://github.com/${issueInfo.owner}/${issueInfo.repo}/issues/${issueInfo.number}`;
   const result = validateAndSanitizeUrl(issueUrl);
   if ("error" in result) {
     return `Error: ${result.error}
 
-${USAGE4}`;
+${USAGE5}`;
   }
   const flags = [];
   if (parsed.plan)
@@ -46147,9 +46271,9 @@ ${USAGE4}`;
   const flagsStr = flags.length > 0 ? ` ${flags.join(" ")}` : "";
   return `[MODE: ISSUE_INGEST issue="${result.sanitized}"${flagsStr}]`;
 }
-var MAX_URL_LEN = 2048, USAGE4;
+var MAX_URL_LEN = 2048, USAGE5;
 var init_issue = __esm(() => {
-  USAGE4 = [
+  USAGE5 = [
     "Usage: /swarm issue <url|owner/repo#N|N> [--plan] [--trace] [--no-repro]",
     "",
     "Ingest a GitHub issue into the swarm workflow.",
@@ -50248,7 +50372,7 @@ var init_pr_feedback = __esm(() => {
 });
 
 // src/commands/pr-review.ts
-function parseArgs5(args) {
+function parseArgs6(args) {
   const out = { council: false, rest: [] };
   for (const token of args) {
     if (token === "--council") {
@@ -50267,29 +50391,29 @@ function parseArgs5(args) {
   return out;
 }
 function handlePrReviewCommand(directory, args) {
-  const parsed = parseArgs5(args);
+  const parsed = parseArgs6(args);
   if (parsed.unknownFlag) {
     return `Error: Unknown flag "${parsed.unknownFlag}"
 
-${USAGE5}`;
+${USAGE6}`;
   }
   const resolved = resolvePrCommandInput(parsed.rest, directory);
   if (resolved === null) {
-    return USAGE5;
+    return USAGE6;
   }
   if ("error" in resolved) {
     return `Error: ${resolved.error}
 
-${USAGE5}`;
+${USAGE6}`;
   }
   const councilFlag = parsed.council ? "council=true" : "council=false";
   const signal = `[MODE: PR_REVIEW pr="${resolved.prUrl}" ${councilFlag}]`;
   return resolved.instructions ? `${signal} ${resolved.instructions}` : signal;
 }
-var USAGE5;
+var USAGE6;
 var init_pr_review = __esm(() => {
   init_pr_ref();
-  USAGE5 = [
+  USAGE6 = [
     "Usage: /swarm pr-review <url|owner/repo#N|N> [--council] [instructions...]",
     "",
     "Run a full swarm PR review on a GitHub pull request.",
@@ -58427,6 +58551,7 @@ __export(exports_commands, {
   handleCouncilCommand: () => handleCouncilCommand,
   handleConfigCommand: () => handleConfigCommand,
   handleConcurrencyCommand: () => handleConcurrencyCommand,
+  handleCodebaseReviewCommand: () => handleCodebaseReviewCommand,
   handleCloseCommand: () => handleCloseCommand,
   handleClarifyCommand: () => handleClarifyCommand,
   handleCheckpointCommand: () => handleCheckpointCommand,
@@ -58684,6 +58809,7 @@ var init_commands = __esm(() => {
   init_benchmark();
   init_checkpoint2();
   init_close();
+  init_codebase_review();
   init_command_dispatch();
   init_command_names();
   init_concurrency();
@@ -58907,6 +59033,7 @@ var init_registry = __esm(() => {
   init_benchmark();
   init_checkpoint2();
   init_close();
+  init_codebase_review();
   init_concurrency();
   init_config2();
   init_council();
@@ -59237,6 +59364,20 @@ Subcommands:
       category: "agent",
       aliasOf: "deep-dive"
     },
+    "codebase-review": {
+      handler: async (ctx) => handleCodebaseReviewCommand(ctx.directory, ctx.args),
+      description: "Launch codebase-review-swarm for a quote-grounded full-repo or large-subsystem audit",
+      args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]",
+      details: "Runs the codebase-review-swarm workflow: Phase 0 inventory, selected-track depth planning, non-diluting review passes, coverage closure, reviewer validation, critic challenge, and .swarm/review-v8 artifacts. The command is side-effect free and emits a MODE signal; the architect workflow must not mutate source files.",
+      category: "agent"
+    },
+    "codebase review": {
+      handler: async (ctx) => handleCodebaseReviewCommand(ctx.directory, ctx.args),
+      description: "Alias for /swarm codebase-review - launch codebase-review-swarm",
+      args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]",
+      category: "agent",
+      aliasOf: "codebase-review"
+    },
     "design-docs": {
       handler: async (ctx) => handleDesignDocsCommand(ctx.directory, ctx.args),
       description: "Generate or sync language-agnostic design docs (domain, technical-spec, behavior-spec, reference/) for the project under build [description]",

package/dist/commands/codebase-review.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Handle /swarm codebase-review command.
+ *
+ * Emits a CODEBASE_REVIEW mode signal for the architect. The command itself is
+ * intentionally side-effect free so it can be used from any repository.
+ */
+export declare const CODEBASE_REVIEW_MODES: readonly ["phase0", "complete", "defect", "security", "correctness", "testing", "ui", "performance", "ai-slop", "enhancements", "custom"];
+export declare function handleCodebaseReviewCommand(_directory: string, args: string[]): Promise<string>;

package/dist/commands/index.d.ts

@@ -8,6 +8,7 @@ export { handleBrainstormCommand } from './brainstorm';
 export { handleCheckpointCommand } from './checkpoint';
 export { handleClarifyCommand } from './clarify';
 export { handleCloseCommand } from './close';
+export { handleCodebaseReviewCommand } from './codebase-review';
 export { executeSwarmCommand, formatCommandNotFound, normalizeSwarmCommandInput, } from './command-dispatch.js';
 export type { CommandName } from './command-names.js';
 export { COMMAND_NAME_SET, COMMAND_NAMES } from './command-names.js';

package/dist/commands/registry.d.ts

@@ -329,6 +329,20 @@ export declare const COMMAND_REGISTRY: {
         readonly category: "agent";
         readonly aliasOf: "deep-dive";
     };
+    readonly 'codebase-review': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Launch codebase-review-swarm for a quote-grounded full-repo or large-subsystem audit";
+        readonly args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]";
+        readonly details: "Runs the codebase-review-swarm workflow: Phase 0 inventory, selected-track depth planning, non-diluting review passes, coverage closure, reviewer validation, critic challenge, and .swarm/review-v8 artifacts. The command is side-effect free and emits a MODE signal; the architect workflow must not mutate source files.";
+        readonly category: "agent";
+    };
+    readonly 'codebase review': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Alias for /swarm codebase-review - launch codebase-review-swarm";
+        readonly args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]";
+        readonly category: "agent";
+        readonly aliasOf: "codebase-review";
+    };
     readonly 'design-docs': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Generate or sync language-agnostic design docs (domain, technical-spec, behavior-spec, reference/) for the project under build [description]";

package/dist/index.js

@@ -69,7 +69,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.56.2",
+    version: "7.57.0",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -62173,6 +62173,130 @@ var init_close = __esm(() => {
   ];
 });
 
+// src/commands/codebase-review.ts
+function sanitizeText(raw, maxLen) {
+  const stripped = raw.replace(/\[+\s*MODE\s*:[^\]]*(?:\]+|$)/gi, "");
+  const normalized = stripped.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLen)
+    return normalized;
+  return `${normalized.slice(0, maxLen)}...`;
+}
+function hasFlagValue(args2, index) {
+  return index + 1 < args2.length && !args2[index + 1].startsWith("--");
+}
+function jsonForModeHeader(value) {
+  return JSON.stringify(value).replace(/[[\]]/g, (ch) => ch === "[" ? "\\u005B" : "\\u005D");
+}
+function parseArgs(args2) {
+  const result = {
+    mode: DEFAULT_MODE,
+    tracks: "",
+    continueRun: "",
+    output: "markdown",
+    updateMain: true,
+    allowDirty: false,
+    rest: []
+  };
+  let i2 = 0;
+  while (i2 < args2.length) {
+    const token = args2[i2];
+    if (token === "--help" || token === "-h") {
+      result.help = true;
+    } else if (token === "--mode") {
+      if (!hasFlagValue(args2, i2)) {
+        return { ...result, error: FLAG_VALUE_MISSING(token) };
+      }
+      const value = args2[++i2];
+      if (!MODES.has(value)) {
+        return {
+          ...result,
+          error: `Invalid mode "${value}". Must be one of: ${[...MODES].join(", ")}.`
+        };
+      }
+      result.mode = value;
+    } else if (token === "--tracks") {
+      if (!hasFlagValue(args2, i2)) {
+        return { ...result, error: FLAG_VALUE_MISSING(token) };
+      }
+      result.tracks = sanitizeText(args2[++i2], MAX_TRACKS_LEN);
+    } else if (token === "--continue") {
+      if (!hasFlagValue(args2, i2)) {
+        return { ...result, error: FLAG_VALUE_MISSING(token) };
+      }
+      const runId = sanitizeText(args2[++i2], MAX_RUN_ID_LEN);
+      if (!/^[A-Za-z0-9_.-]+$/.test(runId)) {
+        return {
+          ...result,
+          error: "Invalid --continue value. Use only letters, numbers, dot, underscore, or dash."
+        };
+      }
+      result.continueRun = runId;
+    } else if (token === "--json") {
+      result.output = "json";
+    } else if (token === "--skip-update") {
+      result.updateMain = false;
+    } else if (token === "--allow-dirty") {
+      result.allowDirty = true;
+    } else if (token.startsWith("--")) {
+      return { ...result, error: `Unknown flag "${token}"` };
+    } else {
+      result.rest.push(token);
+    }
+    i2++;
+  }
+  return result;
+}
+async function handleCodebaseReviewCommand(_directory, args2) {
+  const parsed = parseArgs(args2);
+  if (parsed.help) {
+    return USAGE;
+  }
+  if (parsed.error) {
+    return `Error: ${parsed.error}
+
+${USAGE}`;
+  }
+  const scope = sanitizeText(parsed.rest.join(" "), MAX_SCOPE_LEN) || DEFAULT_SCOPE;
+  return [
+    `[MODE: CODEBASE_REVIEW mode=${parsed.mode} output=${parsed.output} update_main=${parsed.updateMain} allow_dirty=${parsed.allowDirty} tracks=${jsonForModeHeader(parsed.tracks)} continue_run=${jsonForModeHeader(parsed.continueRun)}]`,
+    `scope=${JSON.stringify(scope)}`
+  ].join(" ");
+}
+var MAX_SCOPE_LEN = 2000, MAX_TRACKS_LEN = 1000, MAX_RUN_ID_LEN = 128, CODEBASE_REVIEW_MODES, MODES, DEFAULT_MODE = "phase0", DEFAULT_SCOPE = "repository root", FLAG_VALUE_MISSING = (token) => `Flag "${token}" requires a value`, USAGE = `Usage: /swarm codebase-review [scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]
+
+Run the codebase-review-swarm workflow in the current repository.
+
+Examples:
+  /swarm codebase-review
+  /swarm codebase review src/auth --mode security
+  /swarm codebase-review "frontend accessibility" --mode ui --json
+  /swarm codebase-review --mode custom --tracks "security,testing"
+
+Flags:
+  --mode <name>       phase0, complete, defect, security, correctness, testing, ui, performance, ai-slop, enhancements, or custom
+  --tracks <list>     custom selected tracks or review notes passed to the workflow
+  --continue <run-id> continue an existing .swarm/review-v8 run
+  --json              request JSON-compatible report blocks
+  --skip-update       skip the repo update-to-main preflight
+  --allow-dirty       allow review to proceed with dirty worktree
+  --help              show this usage`;
+var init_codebase_review = __esm(() => {
+  CODEBASE_REVIEW_MODES = [
+    "phase0",
+    "complete",
+    "defect",
+    "security",
+    "correctness",
+    "testing",
+    "ui",
+    "performance",
+    "ai-slop",
+    "enhancements",
+    "custom"
+  ];
+  MODES = new Set(CODEBASE_REVIEW_MODES);
+});
+
 // src/commands/concurrency.ts
 async function handleConcurrencyCommand(directory, args2, sessionID) {
   if (!sessionID || sessionID.trim() === "") {
@@ -62325,7 +62449,7 @@ function sanitizePresetName(raw) {
     return null;
   return trimmed;
 }
-function parseArgs(args2) {
+function parseArgs2(args2) {
   const out2 = { specReview: false, rest: [] };
   for (let i2 = 0;i2 < args2.length; i2++) {
     const token = args2[i2];
@@ -62348,10 +62472,10 @@ function parseArgs(args2) {
   return out2;
 }
 async function handleCouncilCommand(_directory, args2) {
-  const parsed = parseArgs(args2);
+  const parsed = parseArgs2(args2);
   const question = sanitizeQuestion(parsed.rest.join(" "));
   if (!question) {
-    return USAGE;
+    return USAGE2;
   }
   const tokens = ["MODE: COUNCIL"];
   if (parsed.preset) {
@@ -62362,9 +62486,9 @@ async function handleCouncilCommand(_directory, args2) {
   }
   return `[${tokens.join(" ")}] ${question}`;
 }
-var MAX_QUESTION_LEN = 2000, USAGE;
+var MAX_QUESTION_LEN = 2000, USAGE2;
 var init_council = __esm(() => {
-  USAGE = [
+  USAGE2 = [
     "Usage: /swarm council <question> [--preset <name>] [--spec-review]",
     "",
     "  question         The question to put to the council",
@@ -62834,9 +62958,9 @@ function sanitizeScope(raw) {
   const collapsed = raw.replace(/\s+/g, " ").trim();
   const stripped = collapsed.replace(/\[\s*MODE\s*:[^\]]*\]/gi, "");
   const normalized = stripped.replace(/\s+/g, " ").trim();
-  if (normalized.length <= MAX_SCOPE_LEN)
+  if (normalized.length <= MAX_SCOPE_LEN2)
     return normalized;
-  return `${normalized.slice(0, MAX_SCOPE_LEN)}…`;
+  return `${normalized.slice(0, MAX_SCOPE_LEN2)}…`;
 }
 function isValidPositiveInteger(raw) {
   if (!raw || !/^\d+$/.test(raw))
@@ -62846,7 +62970,7 @@ function isValidPositiveInteger(raw) {
     return false;
   return true;
 }
-function parseArgs2(args2) {
+function parseArgs3(args2) {
   const result = {
     profile: DEFAULT_PROFILE,
     maxExplorers: DEFAULT_MAX_EXPLORERS,
@@ -62899,15 +63023,15 @@ function parseArgs2(args2) {
   return result;
 }
 async function handleDeepDiveCommand(_directory, args2) {
-  const parsed = parseArgs2(args2);
+  const parsed = parseArgs3(args2);
   if (parsed.error) {
     return `Error: ${parsed.error}
 
-${USAGE2}`;
+${USAGE3}`;
   }
   const scope = sanitizeScope(parsed.rest.join(" "));
   if (!scope) {
-    return USAGE2;
+    return USAGE3;
   }
   if (parsed.profile === "full" && !parsed.maxExplorersExplicit) {
     parsed.maxExplorers = FULL_PROFILE_DEFAULT_MAX_EXPLORERS;
@@ -62915,7 +63039,7 @@ ${USAGE2}`;
   const header = `[MODE: DEEP_DIVE profile=${parsed.profile} max_explorers=${parsed.maxExplorers} output=${parsed.output} update_main=${parsed.updateMain} allow_dirty=${parsed.allowDirty}] ${scope}`;
   return header;
 }
-var MAX_SCOPE_LEN = 2000, PROFILES, DEFAULT_PROFILE = "standard", DEFAULT_MAX_EXPLORERS = 6, FULL_PROFILE_DEFAULT_MAX_EXPLORERS = 8, USAGE2 = `Usage: /swarm deep-dive <scope> [--profile standard|security|ux|architecture|full] [--max-explorers N] [--json] [--skip-update] [--allow-dirty]
+var MAX_SCOPE_LEN2 = 2000, PROFILES, DEFAULT_PROFILE = "standard", DEFAULT_MAX_EXPLORERS = 6, FULL_PROFILE_DEFAULT_MAX_EXPLORERS = 8, USAGE3 = `Usage: /swarm deep-dive <scope> [--profile standard|security|ux|architecture|full] [--max-explorers N] [--json] [--skip-update] [--allow-dirty]
 
 Run a bounded, evidence-backed deep dive on an application section.
 
@@ -62958,7 +63082,7 @@ function cleanFlagValue(raw) {
     return null;
   return raw;
 }
-function parseArgs3(args2) {
+function parseArgs4(args2) {
   const result = {
     out: "docs",
     lang: "auto",
@@ -63013,30 +63137,30 @@ function parseArgs3(args2) {
   return result;
 }
 async function handleDesignDocsCommand(directory, args2) {
-  const parsed = parseArgs3(args2);
+  const parsed = parseArgs4(args2);
   if (parsed.error) {
     return `Error: ${parsed.error}
 
-${USAGE3}`;
+${USAGE4}`;
   }
   try {
     const { config: config3 } = loadPluginConfigWithMeta(directory);
     if (config3.design_docs?.enabled !== true) {
       return "Error: design docs are disabled. Set `design_docs.enabled: true` in " + `opencode-swarm.json to enable the docs_design agent and this command.
 
-` + USAGE3;
+` + USAGE4;
     }
   } catch (configErr) {
     console.warn(`[design-docs] Could not read opencode-swarm.json (${String(configErr)}). ` + "Falling through — the architect will abort if docs_design is not registered.");
   }
   const description = sanitizeDescription(parsed.rest.join(" "));
   if (!description && !parsed.update) {
-    return USAGE3;
+    return USAGE4;
   }
   const header = `[MODE: DESIGN_DOCS out=${parsed.out} lang=${parsed.lang} update=${parsed.update}] ${description}`;
   return header.trimEnd();
 }
-var MAX_DESC_LEN = 2000, USAGE3 = `Usage: /swarm design-docs <description> [--out <dir>] [--lang <name>] [--update]
+var MAX_DESC_LEN = 2000, USAGE4 = `Usage: /swarm design-docs <description> [--out <dir>] [--lang <name>] [--update]
 
 Generate or sync language-agnostic design docs for the project under build:
   <out>/domain.md, <out>/technical-spec.md, <out>/behavior-spec.md,
@@ -68535,7 +68659,7 @@ function validateAndSanitizeUrl(rawUrl) {
     return { error: "Invalid URL format" };
   }
 }
-function parseArgs4(args2) {
+function parseArgs5(args2) {
   const out2 = {
     plan: false,
     trace: false,
@@ -68626,24 +68750,24 @@ function parseGitRemoteUrl(remoteUrl) {
   return null;
 }
 function handleIssueCommand(_directory, args2) {
-  const parsed = parseArgs4(args2);
+  const parsed = parseArgs5(args2);
   const rawInput = parsed.rest.join(" ").trim();
   if (!rawInput) {
-    return USAGE4;
+    return USAGE5;
   }
   const isFullUrl = /^https?:\/\//i.test(rawInput);
   const issueInfo = parseIssueRef(isFullUrl ? sanitizeUrl(rawInput) : rawInput);
   if (!issueInfo) {
     return `Error: Could not parse issue reference from "${rawInput}"
 
-${USAGE4}`;
+${USAGE5}`;
   }
   const issueUrl = `https://github.com/${issueInfo.owner}/${issueInfo.repo}/issues/${issueInfo.number}`;
   const result = validateAndSanitizeUrl(issueUrl);
   if ("error" in result) {
     return `Error: ${result.error}
 
-${USAGE4}`;
+${USAGE5}`;
   }
   const flags2 = [];
   if (parsed.plan)
@@ -68655,9 +68779,9 @@ ${USAGE4}`;
   const flagsStr = flags2.length > 0 ? ` ${flags2.join(" ")}` : "";
   return `[MODE: ISSUE_INGEST issue="${result.sanitized}"${flagsStr}]`;
 }
-var MAX_URL_LEN = 2048, USAGE4;
+var MAX_URL_LEN = 2048, USAGE5;
 var init_issue = __esm(() => {
-  USAGE4 = [
+  USAGE5 = [
     "Usage: /swarm issue <url|owner/repo#N|N> [--plan] [--trace] [--no-repro]",
     "",
     "Ingest a GitHub issue into the swarm workflow.",
@@ -73747,7 +73871,7 @@ var init_pr_feedback = __esm(() => {
 });
 
 // src/commands/pr-review.ts
-function parseArgs5(args2) {
+function parseArgs6(args2) {
   const out2 = { council: false, rest: [] };
   for (const token of args2) {
     if (token === "--council") {
@@ -73766,29 +73890,29 @@ function parseArgs5(args2) {
   return out2;
 }
 function handlePrReviewCommand(directory, args2) {
-  const parsed = parseArgs5(args2);
+  const parsed = parseArgs6(args2);
   if (parsed.unknownFlag) {
     return `Error: Unknown flag "${parsed.unknownFlag}"
 
-${USAGE5}`;
+${USAGE6}`;
   }
   const resolved = resolvePrCommandInput(parsed.rest, directory);
   if (resolved === null) {
-    return USAGE5;
+    return USAGE6;
   }
   if ("error" in resolved) {
     return `Error: ${resolved.error}
 
-${USAGE5}`;
+${USAGE6}`;
   }
   const councilFlag = parsed.council ? "council=true" : "council=false";
   const signal = `[MODE: PR_REVIEW pr="${resolved.prUrl}" ${councilFlag}]`;
   return resolved.instructions ? `${signal} ${resolved.instructions}` : signal;
 }
-var USAGE5;
+var USAGE6;
 var init_pr_review = __esm(() => {
   init_pr_ref();
-  USAGE5 = [
+  USAGE6 = [
     "Usage: /swarm pr-review <url|owner/repo#N|N> [--council] [instructions...]",
     "",
     "Run a full swarm PR review on a GitHub pull request.",
@@ -82296,6 +82420,7 @@ __export(exports_commands, {
   handleCouncilCommand: () => handleCouncilCommand,
   handleConfigCommand: () => handleConfigCommand,
   handleConcurrencyCommand: () => handleConcurrencyCommand,
+  handleCodebaseReviewCommand: () => handleCodebaseReviewCommand,
   handleCloseCommand: () => handleCloseCommand,
   handleClarifyCommand: () => handleClarifyCommand,
   handleCheckpointCommand: () => handleCheckpointCommand,
@@ -82553,6 +82678,7 @@ var init_commands = __esm(() => {
   init_benchmark();
   init_checkpoint2();
   init_close();
+  init_codebase_review();
   init_command_dispatch();
   init_command_names();
   init_concurrency();
@@ -82776,6 +82902,7 @@ var init_registry = __esm(() => {
   init_benchmark();
   init_checkpoint2();
   init_close();
+  init_codebase_review();
   init_concurrency();
   init_config2();
   init_council();
@@ -83106,6 +83233,20 @@ Subcommands:
       category: "agent",
       aliasOf: "deep-dive"
     },
+    "codebase-review": {
+      handler: async (ctx) => handleCodebaseReviewCommand(ctx.directory, ctx.args),
+      description: "Launch codebase-review-swarm for a quote-grounded full-repo or large-subsystem audit",
+      args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]",
+      details: "Runs the codebase-review-swarm workflow: Phase 0 inventory, selected-track depth planning, non-diluting review passes, coverage closure, reviewer validation, critic challenge, and .swarm/review-v8 artifacts. The command is side-effect free and emits a MODE signal; the architect workflow must not mutate source files.",
+      category: "agent"
+    },
+    "codebase review": {
+      handler: async (ctx) => handleCodebaseReviewCommand(ctx.directory, ctx.args),
+      description: "Alias for /swarm codebase-review - launch codebase-review-swarm",
+      args: "[scope] [--mode phase0|complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements|custom] [--tracks <list>] [--continue <run-id>] [--json] [--skip-update] [--allow-dirty]",
+      category: "agent",
+      aliasOf: "codebase-review"
+    },
     "design-docs": {
       handler: async (ctx) => handleDesignDocsCommand(ctx.directory, ctx.args),
       description: "Generate or sync language-agnostic design docs (domain, technical-spec, behavior-spec, reference/) for the project under build [description]",
@@ -84486,6 +84627,25 @@ HARD CONSTRAINTS (apply regardless of skill load success):
 - Explorers generate candidate findings only — reviewers verify or reject
 - Critics challenge only HIGH/CRITICAL findings — do NOT waste cycles on lower severity
 
+### MODE: CODEBASE_REVIEW
+Activates when: architect receives \`[MODE: CODEBASE_REVIEW mode=X output=X update_main=X allow_dirty=X tracks="..." continue_run="..."] scope="..."\` signal from the codebase-review command handler.
+
+Purpose: Run codebase-review-swarm as a read-only full-repo or large-subsystem review with Phase 0 inventory, selected-track depth planning, coverage closure, reviewer validation, critic challenge, and \`.swarm/review-v8\` artifacts. This mode does NOT mutate source code, does NOT delegate to coder, and does NOT call declare_scope.
+
+ACTION: Load skill file:.opencode/skills/codebase-review-swarm/SKILL.md immediately and follow its protocol.
+
+HARD CONSTRAINTS (apply regardless of skill load success):
+- Do NOT delegate to coder
+- Do NOT call declare_scope
+- Do NOT mutate source code
+- Write artifacts only under \`.swarm/review-v8/runs/<run_id>/\`
+- Run Phase 0 inventory first
+- Treat \`mode=phase0\` as inventory-only: stop at 0K for review-mode selection.
+- Treat \`mode=complete|defect|security|correctness|testing|ui|performance|ai-slop|enhancements\` as the user's preselected authorization to continue through 0L and the selected tracks after Phase 0.
+- Treat \`mode=custom\` as preselected only when \`tracks\` is non-empty; otherwise stop at 0K for track selection.
+- Every repo-derived factual claim needs quote-grounded evidence with file path and line/range
+- Final report is forbidden until selected-track coverage is closed and final critic passes
+
 ### MODE: DESIGN_DOCS
 Activates when: architect receives \`[MODE: DESIGN_DOCS out=X lang=X update=X] <description>\` signal from the design-docs command handler (issue #1080).
 
@@ -114537,14 +114697,14 @@ init_knowledge_events();
 init_knowledge_store();
 init_logger();
 init_create_tool();
-var MODES = ["archive", "quarantine", "purge"];
+var MODES2 = ["archive", "quarantine", "purge"];
 var knowledge_archive = createSwarmTool({
   description: "Archive (default), quarantine, or purge a swarm knowledge entry by ID, appending an immutable audit tombstone. 'archive'/'quarantine' set the entry status reversibly and hide it from recall; 'purge' hard-deletes and requires allow_purge:true.",
   args: {
     id: exports_external.string().min(1).describe("UUID of the knowledge entry"),
     reason: exports_external.string().min(1).max(500).describe("Why the entry is being archived/quarantined/purged"),
     evidence: exports_external.string().max(1000).optional().describe('Supporting evidence (e.g. "ignored 8 times, contradicted by tests")'),
-    mode: exports_external.enum(MODES).optional().describe("Default 'archive'"),
+    mode: exports_external.enum(MODES2).optional().describe("Default 'archive'"),
     allow_purge: exports_external.boolean().optional().describe("Admin flag required when mode='purge'")
   },
   execute: async (args2, directory, ctx) => {
@@ -118287,6 +118447,7 @@ import * as path143 from "node:path";
 async function runFinalCouncilGate(ctx) {
   const { phase, dir, sessionID, agentsDispatched, safeWarn } = ctx;
   let finalCouncilEnabled = false;
+  const gateWarnings = [];
   try {
     const plan = await loadPlan(dir);
     if (plan) {
@@ -118374,11 +118535,17 @@ async function runFinalCouncilGate(ctx) {
                       warnings: []
                     };
                   }
-                  if (entry.verdict !== "approved" && entry.verdict !== "APPROVED") {
+                  if (entry.verdict === "concerns" || entry.verdict === "CONCERNS") {
+                    const advisoryNotes = Array.isArray(entry.advisoryNotes) ? entry.advisoryNotes.filter((note) => typeof note === "string") : [];
+                    const warning = advisoryNotes.length > 0 ? `Final council returned CONCERNS (non-blocking): ${advisoryNotes.join("; ")}` : "Final council returned CONCERNS (non-blocking).";
+                    gateWarnings.push(warning);
+                    safeWarn(`[phase_complete] ${warning}`, undefined);
+                  }
+                  if (entry.verdict !== "approved" && entry.verdict !== "APPROVED" && entry.verdict !== "concerns" && entry.verdict !== "CONCERNS") {
                     return {
                       blocked: true,
                       reason: "FINAL_COUNCIL_INVALID_VERDICT",
-                      message: `Phase ${phase} (last phase) cannot be completed: final council evidence contains unrecognized verdict '${entry.verdict}'. Expected 'approved'.`,
+                      message: `Phase ${phase} (last phase) cannot be completed: final council evidence contains unrecognized verdict '${entry.verdict}'. Expected one of: approved, concerns, rejected.`,
                       agentsDispatched,
                       agentsMissing: [],
                       warnings: []
@@ -118423,7 +118590,12 @@ async function runFinalCouncilGate(ctx) {
       safeWarn(`[phase_complete] Final council gate error (non-blocking):`, fcError);
     }
   }
-  return { blocked: false, agentsDispatched, agentsMissing: [], warnings: [] };
+  return {
+    blocked: false,
+    agentsDispatched,
+    agentsMissing: [],
+    warnings: gateWarnings
+  };
 }
 // src/tools/phase-complete/gates/hallucination-gate.ts
 init_qa_gate_profile();
@@ -130326,8 +130498,14 @@ var ArgsSchema8 = exports_external.object({
   roundNumber: exports_external.number().int().min(1).max(10).optional(),
   verdicts: exports_external.array(VerdictSchema3).min(1).max(5)
 });
-function normalizeFinalVerdict(verdict) {
-  return verdict === "APPROVE" ? "approved" : "rejected";
+function normalizeFinalVerdict(verdict, requiredFixesCount) {
+  if (verdict === "APPROVE") {
+    return "approved";
+  }
+  if (verdict === "REJECT") {
+    return "rejected";
+  }
+  return requiredFixesCount > 0 ? "rejected" : "concerns";
 }
 async function executeWriteFinalCouncilEvidence(args2, directory) {
   const parsed = ArgsSchema8.safeParse(args2);
@@ -130360,7 +130538,7 @@ async function executeWriteFinalCouncilEvidence(args2, directory) {
   const synthesis = synthesizeFinalCouncilAdvisory(input.projectSummary.trim(), input.verdicts, input.roundNumber ?? 1, config3.council);
   const plan = await loadPlan(directory);
   const planId = plan ? derivePlanId(plan) : "unknown";
-  const normalizedVerdict = normalizeFinalVerdict(synthesis.overallVerdict);
+  const normalizedVerdict = normalizeFinalVerdict(synthesis.overallVerdict, synthesis.requiredFixes.length);
   const evidenceEntry = {
     type: "final-council",
     phase: input.phase,
@@ -131277,7 +131455,7 @@ async function initializeOpenCodeSwarm(ctx) {
         ...opencodeConfig.command || {},
         swarm: {
           template: "/swarm $ARGUMENTS",
-          description: "Swarm management commands: /swarm [status|show-plan|plan|agents|history|config|help|evidence|handoff|archive|diagnose|diagnosis|preflight|sync-plan|benchmark|export|reset|rollback|retrieve|clarify|analyze|specify|brainstorm|council|pr-review|pr-feedback|deep-dive|design-docs|issue|qa-gates|dark-matter|knowledge|memory|curate|concurrency|turbo|full-auto|write-retro|reset-session|simulate|promote|checkpoint|acknowledge-spec-drift|doctor tools|finalize|close]"
+          description: "Swarm management commands: /swarm [status|show-plan|plan|agents|history|config|help|evidence|handoff|archive|diagnose|diagnosis|preflight|sync-plan|benchmark|export|reset|rollback|retrieve|clarify|analyze|specify|brainstorm|council|pr-review|pr-feedback|deep-dive|codebase-review|design-docs|issue|qa-gates|dark-matter|knowledge|memory|curate|concurrency|turbo|full-auto|write-retro|reset-session|simulate|promote|checkpoint|acknowledge-spec-drift|doctor tools|finalize|close]"
         },
         "swarm-status": {
           template: "/swarm status",
@@ -131383,6 +131561,10 @@ async function initializeOpenCodeSwarm(ctx) {
           template: "/swarm deep-dive $ARGUMENTS",
           description: "Use /swarm deep-dive to launch a read-only deep audit with parallel explorer waves, dual reviewers, and critic challenge"
         },
+        "swarm-codebase-review": {
+          template: "/swarm codebase-review $ARGUMENTS",
+          description: "Use /swarm codebase-review to launch codebase-review-swarm for a quote-grounded full-repo or large-subsystem audit"
+        },
         "swarm-design-docs": {
           template: "/swarm design-docs $ARGUMENTS",
           description: "Use /swarm design-docs to generate or sync language-agnostic design docs for the project under build"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.56.2",
+	"version": "7.57.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",