@gh-symphony/cli 0.0.21 → 0.1.2

package/dist/index.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
+import {
+  bold,
+  cyan,
+  setNoColor,
+  yellow
+} from "./chunk-MVRF7BES.js";
 import {
   resolveConfigDir
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-WOVNN5NW.js";
 
 // src/index.ts
 import { realpathSync } from "fs";
@@ -19,13 +25,6 @@ var TOP_LEVEL_COMMANDS = [
   "setup",
   "doctor",
   "upgrade",
-  "start",
-  "stop",
-  "status",
-  "run",
-  "recover",
-  "logs",
-  "project",
   "repo",
   "config",
   "completion",
@@ -58,70 +57,33 @@ var COMMAND_OPTIONS = {
     ...GLOBAL_OPTIONS
   ],
   "workflow:validate": ["--file", ...GLOBAL_OPTIONS],
-  "workflow:preview": [
-    "--file",
-    "--sample",
-    "--attempt",
-    ...GLOBAL_OPTIONS
-  ],
+  "workflow:preview": ["--file", "--sample", "--attempt", ...GLOBAL_OPTIONS],
   setup: [
     "--non-interactive",
-    "--project",
-    "--workspace-dir",
     "--assigned-only",
     "--output",
     "--skip-skills",
     "--skip-context",
     ...GLOBAL_OPTIONS
   ],
-  doctor: ["--project-id", "--project", ...GLOBAL_OPTIONS],
-  upgrade: [...GLOBAL_OPTIONS],
-  start: ["--project-id", "--project", "--daemon", "-d", ...GLOBAL_OPTIONS],
-  stop: ["--project-id", "--project", "--force", ...GLOBAL_OPTIONS],
-  status: ["--project-id", "--project", "--watch", "-w", ...GLOBAL_OPTIONS],
-  run: ["--project-id", "--project", "--watch", "-w", ...GLOBAL_OPTIONS],
-  recover: ["--project-id", "--project", "--dry-run", ...GLOBAL_OPTIONS],
-  logs: [
+  doctor: [
     "--project-id",
     "--project",
-    "--follow",
-    "-f",
+    "--fix",
+    "--smoke",
     "--issue",
-    "--run",
-    "--level",
-    ...GLOBAL_OPTIONS
-  ],
-  project: ["add", "list", "remove", "start", "stop", "switch", "status"],
-  "project:add": [
-    "--non-interactive",
-    "--project",
-    "--workspace-dir",
-    "--assigned-only",
-    ...GLOBAL_OPTIONS
-  ],
-  "project:list": [...GLOBAL_OPTIONS],
-  "project:remove": [...GLOBAL_OPTIONS],
-  "project:start": [
-    "--project-id",
-    "--project",
-    "--daemon",
-    "-d",
-    ...GLOBAL_OPTIONS
-  ],
-  "project:stop": ["--project-id", "--project", "--force", ...GLOBAL_OPTIONS],
-  "project:switch": [...GLOBAL_OPTIONS],
-  "project:status": [
-    "--project-id",
-    "--project",
-    "--watch",
-    "-w",
     ...GLOBAL_OPTIONS
   ],
-  repo: ["list", "add", "remove", "sync"],
-  "repo:list": [...GLOBAL_OPTIONS],
-  "repo:add": [...GLOBAL_OPTIONS],
-  "repo:remove": [...GLOBAL_OPTIONS],
-  "repo:sync": ["--dry-run", "--prune", ...GLOBAL_OPTIONS],
+  upgrade: [...GLOBAL_OPTIONS],
+  repo: ["init", "start", "status", "stop", "run", "recover", "logs", "explain"],
+  "repo:init": ["--repo-dir", "--workflow-file", ...GLOBAL_OPTIONS],
+  "repo:start": ["--daemon", "-d", "--once", "--http", "--web", "--log-level", ...GLOBAL_OPTIONS],
+  "repo:status": ["--watch", "-w", ...GLOBAL_OPTIONS],
+  "repo:stop": ["--force", ...GLOBAL_OPTIONS],
+  "repo:run": ["--watch", ...GLOBAL_OPTIONS],
+  "repo:recover": ["--dry-run", ...GLOBAL_OPTIONS],
+  "repo:logs": ["--follow", "-f", "--issue", "--run", "--level", ...GLOBAL_OPTIONS],
+  "repo:explain": ["--json", "--workflow", ...GLOBAL_OPTIONS],
   config: ["show", "set", "edit"],
   "config:show": [...GLOBAL_OPTIONS],
   "config:set": [...GLOBAL_OPTIONS],
@@ -140,7 +102,7 @@ function renderBashCasePatterns() {
       return
       ;;`;
       }
-      if (command === "workflow" || command === "project" || command === "repo" || command === "config") {
+      if (command === "workflow" || command === "repo" || command === "config") {
         return `    ${command})
       COMPREPLY=( $(compgen -W "${quoteWords(values)}" -- "$cur") )
       return
@@ -166,11 +128,6 @@ function renderFishLines() {
       `complete -c gh-symphony -f -n '__fish_use_subcommand' -a '${command}'`
     );
   }
-  for (const subcommand of COMMAND_OPTIONS.project ?? []) {
-    lines.push(
-      `complete -c gh-symphony -f -n '__fish_seen_subcommand_from project' -a '${subcommand}'`
-    );
-  }
   for (const subcommand of COMMAND_OPTIONS.repo ?? []) {
     lines.push(
       `complete -c gh-symphony -f -n '__fish_seen_subcommand_from repo' -a '${subcommand}'`
@@ -255,7 +212,7 @@ _gh_symphony_completion() {
     return
   fi
 
-  if [[ "\${path}" == "workflow" || "\${path}" == "project" || "\${path}" == "repo" || "\${path}" == "config" || "\${path}" == "completion" ]]; then
+  if [[ "\${path}" == "workflow" || "\${path}" == "repo" || "\${path}" == "config" || "\${path}" == "completion" ]]; then
     if [[ -n "\${GH_SYMPHONY_SUBCOMMAND}" ]]; then
       path="\${path}:\${GH_SYMPHONY_SUBCOMMAND}"
     fi
@@ -276,23 +233,194 @@ ${bashFunction}complete -F _gh_symphony_completion gh-symphony
 `;
 }
 
+// src/commands/help.ts
+var DESCRIPTION_COLUMN = 23;
+var COMMAND_COLUMN_WIDTH = DESCRIPTION_COLUMN - 2;
+var HELP_SECTIONS = [
+  {
+    title: "Setup",
+    entries: [
+      {
+        name: "setup",
+        description: "Run the one-command first-run setup flow"
+      },
+      {
+        name: "workflow init",
+        description: "Generate WORKFLOW.md and workflow support files"
+      },
+      {
+        name: "workflow validate",
+        description: "Strictly validate WORKFLOW.md"
+      },
+      {
+        name: "workflow preview",
+        description: "Render the worker prompt from a sample or live issue"
+      },
+      {
+        name: "doctor",
+        description: "Run diagnostics and optional remediation"
+      },
+      {
+        name: "config show",
+        description: "Show current configuration"
+      },
+      {
+        name: "config set",
+        description: "Set a configuration value"
+      },
+      {
+        name: "config edit",
+        description: "Open config in $EDITOR"
+      }
+    ]
+  },
+  {
+    title: "Orchestration (current repository)",
+    entries: [
+      {
+        name: "repo init",
+        description: "Initialize gh-symphony for the current repository"
+      },
+      {
+        name: "repo start",
+        description: "Start the orchestrator (foreground)"
+      },
+      {
+        name: "repo start --daemon",
+        description: "Start the orchestrator in the background"
+      },
+      {
+        name: "repo stop",
+        description: "Stop the background orchestrator"
+      },
+      {
+        name: "repo status",
+        description: "Show orchestrator status"
+      },
+      {
+        name: "repo run <issue>",
+        description: "Dispatch a single issue"
+      },
+      {
+        name: "repo recover",
+        description: "Recover stalled runs"
+      },
+      {
+        name: "repo logs",
+        description: "View orchestrator logs"
+      },
+      {
+        name: "repo explain <issue>",
+        description: "Explain why an issue is not dispatching"
+      }
+    ]
+  },
+  {
+    title: "Maintenance",
+    entries: [
+      {
+        name: "upgrade",
+        description: "Upgrade the CLI to the latest published version"
+      },
+      {
+        name: "completion <shell>",
+        description: "Print shell completion (bash/zsh/fish)"
+      },
+      {
+        name: "version",
+        description: "Show version"
+      },
+      {
+        name: "help [command]",
+        description: "Show help for a command"
+      }
+    ]
+  },
+  {
+    title: "Global Options",
+    entries: [
+      {
+        name: "--config <dir>",
+        description: [
+          "Config directory override (advanced; default uses initialized",
+          "cwd runtime, then ~/.gh-symphony)"
+        ]
+      },
+      {
+        name: "--verbose, -v",
+        description: "Verbose output"
+      },
+      {
+        name: "--json",
+        description: "JSON output"
+      },
+      {
+        name: "--no-color",
+        description: "Disable color output"
+      },
+      {
+        name: "--help, -h",
+        description: "Show help"
+      },
+      {
+        name: "--version, -V",
+        description: "Show version"
+      }
+    ]
+  }
+];
+function sectionTitle(title, color) {
+  const label = `${title}:`;
+  return color ? yellow(bold(label)) : label;
+}
+function entryName(name, color) {
+  return color ? cyan(name) : name;
+}
+function renderEntry(entry, color) {
+  const descriptions = Array.isArray(entry.description) ? entry.description : [entry.description];
+  const lines = [
+    `  ${entryName(entry.name, color)}${" ".repeat(
+      Math.max(COMMAND_COLUMN_WIDTH - entry.name.length, 1)
+    )}${descriptions[0]}`
+  ];
+  for (const line of descriptions.slice(1)) {
+    lines.push(`${" ".repeat(DESCRIPTION_COLUMN)}${line}`);
+  }
+  return lines;
+}
+function renderHelp(options) {
+  const lines = ["gh-symphony \u2014 AI Coding Agent Orchestrator", ""];
+  for (const [index, section] of HELP_SECTIONS.entries()) {
+    if (index > 0) {
+      lines.push("");
+    }
+    lines.push(sectionTitle(section.title, options.color));
+    for (const entry of section.entries) {
+      lines.push(...renderEntry(entry, options.color));
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/removed-command.ts
+function createRemovedCommandHandler(message) {
+  return async () => {
+    process.stderr.write(`${message}
+`);
+    process.exitCode = 2;
+  };
+}
+
 // src/index.ts
 var COMMANDS = {
-  workflow: () => import("./workflow-BLJH2HC3.js"),
-  init: () => import("./init-HZ3JEDGQ.js"),
-  setup: () => import("./setup-B2SVLW2R.js"),
-  doctor: () => import("./doctor-4HBRICHP.js"),
-  upgrade: () => import("./upgrade-OJXPZRYE.js"),
-  start: () => import("./start-I2CC7BLW.js"),
-  stop: () => import("./stop-7MFCBQVW.js"),
-  status: () => import("./status-QSCFVGRQ.js"),
-  run: () => import("./run-XJQ6BF7U.js"),
-  recover: () => import("./recover-L3MJHHDA.js"),
-  logs: () => import("./logs-6JKKYDGJ.js"),
-  project: () => import("./project-25NQ4J4Y.js"),
-  repo: () => import("./repo-TDCWQR6P.js"),
-  config: () => import("./config-cmd-DNXNL26Z.js"),
-  version: () => import("./version-TBDCTKDO.js")
+  workflow: () => import("./workflow-26QNZZWH.js"),
+  setup: () => import("./setup-XNHHRBGU.js"),
+  doctor: () => import("./doctor-EEPNFCGF.js"),
+  upgrade: () => import("./upgrade-NS53EO2B.js"),
+  repo: () => import("./repo-RX4OK7XH.js"),
+  config: () => import("./config-cmd-2ADPUYWA.js"),
+  version: () => import("./version-2RHFZ5CI.js")
 };
 function addGlobalOptions(command) {
   return command.option("--config <dir>", "Config directory").addOption(new Option("--config-dir <dir>").hideHelp()).option("-v, --verbose", "Enable verbose output").option("--json", "Output in JSON format").option("--no-color", "Disable color output");
@@ -308,6 +436,7 @@ function resolveGlobalOptions(values) {
   if (options.noColor) {
     process.env.NO_COLOR = "1";
   }
+  setNoColor(options.noColor);
   return options;
 }
 function resolveProjectId(values) {
@@ -326,6 +455,9 @@ async function invokeHandler(key, args, values) {
   const module = await COMMANDS[key]();
   await module.default(args, resolveGlobalOptions(values));
 }
+async function invokeRemovedCommand(message, values) {
+  await createRemovedCommandHandler(message)([], resolveGlobalOptions(values));
+}
 function shellArgument(value) {
   if (value === "bash" || value === "zsh" || value === "fish") {
     return value;
@@ -345,8 +477,24 @@ function resolveVersionOptions(argv) {
   if (options.noColor) {
     process.env.NO_COLOR = "1";
   }
+  setNoColor(options.noColor);
   return options;
 }
+function renderRootHelp(command) {
+  const values = command.optsWithGlobals();
+  const noColor = Boolean(values.noColor);
+  return renderHelp({ color: !noColor });
+}
+function registerRemovedCommand(program, commandSpec, message, markInvoked) {
+  const handler = createRemovedCommandHandler(message);
+  addGlobalOptions(
+    program.command(commandSpec, { hidden: true }).allowUnknownOption(true).allowExcessArguments(true)
+  ).action(async function() {
+    markInvoked();
+    const values = this.optsWithGlobals();
+    await handler([], resolveGlobalOptions(values));
+  });
+}
 function createProgram() {
   let actionInvoked = false;
   const markInvoked = () => {
@@ -355,21 +503,13 @@ function createProgram() {
   const program = addGlobalOptions(
     new Command().name("gh-symphony").description("AI Coding Agent Orchestrator").exitOverride().helpOption("-h, --help", "Show help").addHelpCommand("help [command]", "Show help for command").showHelpAfterError("(run with --help for usage)").option("-V, --version", "Show version")
   );
-  addGlobalOptions(
-    program.command("init", { hidden: true }).description("Alias for 'gh-symphony workflow init'").option("--non-interactive", "Run without prompts").option("--project <id>", "GitHub Project ID or URL").option("--output <path>", "Write WORKFLOW.md to a custom path").option("--runtime <kind>", "Runtime preset: codex-app-server or claude-print").option("--skip-skills", "Skip runtime skill generation").option("--skip-context", "Skip .gh-symphony/context.yaml generation").option("--dry-run", "Preview generated files without writing them").allowExcessArguments(false)
-  ).action(async function() {
-    markInvoked();
-    const values = this.optsWithGlobals();
-    const args = ["init"];
-    pushOption(args, "--non-interactive", values.nonInteractive);
-    pushOption(args, "--project", values.project);
-    pushOption(args, "--output", values.output);
-    pushOption(args, "--runtime", values.runtime);
-    pushOption(args, "--skip-skills", values.skipSkills);
-    pushOption(args, "--skip-context", values.skipContext);
-    pushOption(args, "--dry-run", values.dryRun);
-    await invokeHandler("workflow", args, values);
-  });
+  program.helpInformation = () => renderRootHelp(program);
+  registerRemovedCommand(
+    program,
+    "init",
+    "Use 'gh-symphony workflow init'.",
+    markInvoked
+  );
   const workflow = addGlobalOptions(
     program.command("workflow").description("Manage WORKFLOW.md authoring")
   );
@@ -382,7 +522,10 @@ function createProgram() {
     );
   });
   addGlobalOptions(
-    workflow.command("init").description("Generate WORKFLOW.md and workflow support files").option("--non-interactive", "Run without prompts").option("--project <id>", "GitHub Project ID or URL").option("--output <path>", "Write WORKFLOW.md to a custom path").option("--runtime <kind>", "Runtime preset: codex-app-server or claude-print").option("--skip-skills", "Skip runtime skill generation").option("--skip-context", "Skip .gh-symphony/context.yaml generation").option("--dry-run", "Preview generated files without writing them").allowExcessArguments(false)
+    workflow.command("init").description("Generate WORKFLOW.md and workflow support files").option("--non-interactive", "Run without prompts").option("--project <id>", "GitHub Project ID or URL").option("--output <path>", "Write WORKFLOW.md to a custom path").option(
+      "--runtime <kind>",
+      "Runtime preset: codex-app-server or claude-print"
+    ).option("--skip-skills", "Skip runtime skill generation").option("--skip-context", "Skip .gh-symphony/context.yaml generation").option("--dry-run", "Preview generated files without writing them").allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
@@ -419,14 +562,12 @@ function createProgram() {
     await invokeHandler("workflow", args, values);
   });
   addGlobalOptions(
-    program.command("setup").description("Run the one-command first-run setup flow").option("--non-interactive", "Run without prompts").option("--project <id>", "GitHub Project ID or URL").option("--workspace-dir <path>", "Workspace directory").option("--assigned-only", "Limit processing to assigned issues").option("--output <path>", "Write WORKFLOW.md to a custom path").option("--skip-skills", "Skip runtime skill generation").option("--skip-context", "Skip .gh-symphony/context.yaml generation").allowExcessArguments(false)
+    program.command("setup").description("Run the one-command first-run setup flow").option("--non-interactive", "Run without prompts").option("--assigned-only", "Limit processing to assigned issues").option("--output <path>", "Write WORKFLOW.md to a custom path").option("--skip-skills", "Skip runtime skill generation").option("--skip-context", "Skip .gh-symphony/context.yaml generation").allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
     const args = [];
     pushOption(args, "--non-interactive", values.nonInteractive);
-    pushOption(args, "--project", values.project);
-    pushOption(args, "--workspace-dir", values.workspaceDir);
     pushOption(args, "--assigned-only", values.assignedOnly);
     pushOption(args, "--output", values.output);
     pushOption(args, "--skip-skills", values.skipSkills);
@@ -437,13 +578,18 @@ function createProgram() {
     program.command("doctor").description("Run diagnostics and optional first-run remediation").option("--project-id <projectId>", "Project identifier").option(
       "--fix",
       "Apply safe remediation steps and print manual follow-ups"
-    ).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+    ).option(
+      "--smoke",
+      "Run a safe live issue readiness check without dispatching work"
+    ).option("--issue <owner/repo#number>", "Live issue to validate").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
     const args = [];
     pushOption(args, "--project-id", resolveProjectId(values));
     pushOption(args, "--fix", values.fix);
+    pushOption(args, "--smoke", values.smoke);
+    pushOption(args, "--issue", values.issue);
     await invokeHandler("doctor", args, values);
   });
   addGlobalOptions(
@@ -452,211 +598,178 @@ function createProgram() {
     markInvoked();
     await invokeHandler("upgrade", [], this.optsWithGlobals());
   });
+  registerRemovedCommand(
+    program,
+    "start",
+    "Use 'gh-symphony repo start' from the target repository.",
+    markInvoked
+  );
+  registerRemovedCommand(
+    program,
+    "stop",
+    "Use 'gh-symphony repo stop'.",
+    markInvoked
+  );
+  registerRemovedCommand(
+    program,
+    "status",
+    "Use 'gh-symphony repo status'.",
+    markInvoked
+  );
+  registerRemovedCommand(
+    program,
+    "run",
+    "Use 'gh-symphony repo run <issue>'.",
+    markInvoked
+  );
+  registerRemovedCommand(
+    program,
+    "recover",
+    "Use 'gh-symphony repo recover'.",
+    markInvoked
+  );
+  registerRemovedCommand(
+    program,
+    "logs",
+    "Use 'gh-symphony repo logs'.",
+    markInvoked
+  );
   addGlobalOptions(
-    program.command("start").description("Start the orchestrator").option("-d, --daemon", "Start in daemon mode").option("--once", "Run a single orchestration tick and exit").option(
-      "--http [port]",
-      "Expose dashboard and refresh endpoints over HTTP"
-    ).option(
-      "--web [port]",
-      "Expose the control plane web dashboard and API over HTTP"
-    ).option("--log-level <level>", "Orchestrator lifecycle log level").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
-  ).action(async function() {
-    markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--daemon", values.daemon);
-    pushOption(args, "--once", values.once);
-    pushOption(args, "--http", values.http);
-    pushOption(args, "--web", values.web);
-    pushOption(args, "--log-level", values.logLevel);
-    await invokeHandler("start", args, values);
-  });
-  addGlobalOptions(
-    program.command("stop").description("Stop the background orchestrator").option("--force", "Force stop with SIGKILL").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
-  ).action(async function() {
-    markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--force", values.force);
-    await invokeHandler("stop", args, values);
-  });
-  addGlobalOptions(
-    program.command("status").description("Show orchestrator status").option("-w, --watch", "Watch status continuously").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+    program.command("project").description("Removed project namespace").argument("[args...]", "Removed project command arguments").allowUnknownOption(true).allowExcessArguments(true)
   ).action(async function() {
     markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--watch", values.watch);
-    await invokeHandler("status", args, values);
+    await createRemovedCommandHandler(
+      "The 'project' command was removed. The orchestrator is now per-repository. Run 'gh-symphony repo init' in the target repository."
+    )([], resolveGlobalOptions(this.optsWithGlobals()));
   });
-  addGlobalOptions(
-    program.command("run").description("Dispatch a single issue").argument("<issue>", "Issue identifier").option("--log-level <level>", "Orchestrator lifecycle log level").option("-w, --watch", "Watch status after dispatch").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
-  ).action(async function(issue) {
+  const repo = addGlobalOptions(
+    program.command("repo").description("Manage the current repository runtime")
+  );
+  repo.action(async function() {
     markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [issue];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--log-level", values.logLevel);
-    pushOption(args, "--watch", values.watch);
-    await invokeHandler("run", args, values);
+    await invokeHandler("repo", [], this.optsWithGlobals());
   });
+  addGlobalOptions(repo.command("list").description("Removed")).action(
+    async function() {
+      markInvoked();
+      await invokeRemovedCommand(
+        "Removed. Repository identity is shown by 'repo status'.",
+        this.optsWithGlobals()
+      );
+    }
+  );
   addGlobalOptions(
-    program.command("recover").description("Recover stalled runs").option("--dry-run", "Show recoverable runs without recovering").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+    repo.command("add").description("Removed").argument("[owner/name]", "Repository spec").allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--dry-run", values.dryRun);
-    await invokeHandler("recover", args, values);
+    await invokeRemovedCommand(
+      "Removed. The orchestrator binds to the cwd repository via 'repo init'.",
+      this.optsWithGlobals()
+    );
   });
   addGlobalOptions(
-    program.command("logs").description("View orchestrator logs").option("-f, --follow", "Follow new log lines").option("--issue <issue>", "Filter by issue identifier").option("--run <runId>", "Read events for a specific run").option("--level <level>", "Filter by log level").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+    repo.command("remove").description("Removed").argument("[owner/name]", "Repository spec").allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--follow", values.follow);
-    pushOption(args, "--issue", values.issue);
-    pushOption(args, "--run", values.run);
-    pushOption(args, "--level", values.level);
-    await invokeHandler("logs", args, values);
-  });
-  const project = addGlobalOptions(
-    program.command("project").description("Manage configured projects")
-  );
-  project.action(async function() {
-    markInvoked();
-    await invokeHandler("project", [], this.optsWithGlobals());
+    await invokeRemovedCommand(
+      "Removed. The orchestrator binds to the cwd repository via 'repo init'.",
+      this.optsWithGlobals()
+    );
   });
   addGlobalOptions(
-    project.command("add").description("Add a new project").option("--non-interactive", "Run without prompts").option("--project <id>", "GitHub Project ID").option("--workspace-dir <path>", "Workspace directory").option("--assigned-only", "Limit processing to assigned issues").allowExcessArguments(false)
+    repo.command("sync").description("Removed").allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
-    const values = this.optsWithGlobals();
-    const args = [];
-    pushOption(args, "--non-interactive", values.nonInteractive);
-    pushOption(args, "--project", values.project);
-    pushOption(args, "--workspace-dir", values.workspaceDir);
-    pushOption(args, "--assigned-only", values.assignedOnly);
-    await invokeHandler("project", ["add", ...args], values);
+    await invokeRemovedCommand(
+      "Removed. Single-repo model has no linked-repo set to sync.",
+      this.optsWithGlobals()
+    );
   });
   addGlobalOptions(
-    project.command("list").description("List configured projects")
+    repo.command("init").description("Initialize gh-symphony for the current repository").option("--repo-dir <path>", "Repository directory").option("--workflow-file <path>", "Use a custom WORKFLOW.md path").allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
-    await invokeHandler("project", ["list"], values);
-  });
-  addGlobalOptions(
-    project.command("remove").description("Remove a project").argument("<projectId>", "Project identifier").allowExcessArguments(false)
-  ).action(async function(projectId) {
-    markInvoked();
-    await invokeHandler(
-      "project",
-      ["remove", projectId],
-      this.optsWithGlobals()
-    );
+    const args = ["init"];
+    pushOption(args, "--repo-dir", values.repoDir);
+    pushOption(args, "--workflow-file", values.workflowFile);
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    project.command("start").description("Start a specific project").option("-d, --daemon", "Start in daemon mode").option("--once", "Run a single orchestration tick and exit").option(
+    repo.command("start").description("Start the orchestrator for the current repository").option("-d, --daemon", "Start in daemon mode").option("--once", "Run a single orchestration tick and exit").option(
       "--http [port]",
       "Expose dashboard and refresh endpoints over HTTP"
     ).option(
       "--web [port]",
       "Expose the control plane web dashboard and API over HTTP"
-    ).option("--log-level <level>", "Orchestrator lifecycle log level").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+    ).option("--log-level <level>", "Orchestrator lifecycle log level").allowUnknownOption(true).allowExcessArguments(true)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
-    const args = ["start"];
-    pushOption(args, "--project-id", resolveProjectId(values));
+    const args = ["start", ...this.args];
     pushOption(args, "--daemon", values.daemon);
     pushOption(args, "--once", values.once);
     pushOption(args, "--http", values.http);
     pushOption(args, "--web", values.web);
     pushOption(args, "--log-level", values.logLevel);
-    await invokeHandler("project", args, values);
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    project.command("stop").description("Stop a specific project").option("--force", "Force stop with SIGKILL").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+    repo.command("status").description("Show current repository orchestrator status").option("-w, --watch", "Watch status continuously").allowUnknownOption(true).allowExcessArguments(true)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
-    const args = ["stop"];
-    pushOption(args, "--project-id", resolveProjectId(values));
-    pushOption(args, "--force", values.force);
-    await invokeHandler("project", args, values);
+    const args = ["status", ...this.args];
+    pushOption(args, "--watch", values.watch);
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    project.command("switch").description("Switch the active project")
+    repo.command("stop").description("Stop the current repository background orchestrator").option("--force", "Force stop with SIGKILL").allowUnknownOption(true).allowExcessArguments(true)
   ).action(async function() {
     markInvoked();
-    await invokeHandler(
-      "project",
-      ["switch"],
-      this.optsWithGlobals()
-    );
+    const values = this.optsWithGlobals();
+    const args = ["stop", ...this.args];
+    pushOption(args, "--force", values.force);
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    project.command("status").description("Show status for a specific project").option("-w, --watch", "Watch status continuously").option("--project-id <projectId>", "Project identifier").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
-  ).action(async function() {
+    repo.command("run").description("Dispatch a single issue from the current repository").argument("[args...]", "Issue identifier and passthrough options").option("--log-level <level>", "Orchestrator lifecycle log level").option("-w, --watch", "Watch status after dispatch").allowUnknownOption(true).allowExcessArguments(true)
+  ).action(async function(passthrough) {
     markInvoked();
     const values = this.optsWithGlobals();
-    const args = ["status"];
-    pushOption(args, "--project-id", resolveProjectId(values));
+    const args = ["run", ...passthrough];
+    pushOption(args, "--log-level", values.logLevel);
     pushOption(args, "--watch", values.watch);
-    await invokeHandler("project", args, values);
-  });
-  const repo = addGlobalOptions(
-    program.command("repo").description("Manage repositories in the active project")
-  );
-  repo.action(async function() {
-    markInvoked();
-    await invokeHandler("repo", [], this.optsWithGlobals());
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    repo.command("list").description("List repositories")
+    repo.command("recover").description("Recover stalled runs for the current repository").option("--dry-run", "Show recoverable runs without recovering").allowUnknownOption(true).allowExcessArguments(true)
   ).action(async function() {
     markInvoked();
-    await invokeHandler(
-      "repo",
-      ["list"],
-      this.optsWithGlobals()
-    );
-  });
-  addGlobalOptions(
-    repo.command("add").description("Add a repository").argument("<owner/name>", "Repository spec").allowExcessArguments(false)
-  ).action(async function(repoSpec) {
-    markInvoked();
-    await invokeHandler(
-      "repo",
-      ["add", repoSpec],
-      this.optsWithGlobals()
-    );
+    const values = this.optsWithGlobals();
+    const args = ["recover", ...this.args];
+    pushOption(args, "--dry-run", values.dryRun);
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    repo.command("remove").description("Remove a repository").argument("<owner/name>", "Repository spec").allowExcessArguments(false)
-  ).action(async function(repoSpec) {
+    repo.command("logs").description("View current repository orchestrator logs").option("-f, --follow", "Follow new log lines").option("--issue <issue>", "Filter by issue identifier").option("--run <runId>", "Read events for a specific run").option("--level <level>", "Filter by log level").allowUnknownOption(true).allowExcessArguments(true)
+  ).action(async function() {
     markInvoked();
-    await invokeHandler(
-      "repo",
-      ["remove", repoSpec],
-      this.optsWithGlobals()
-    );
+    const values = this.optsWithGlobals();
+    const args = ["logs", ...this.args];
+    pushOption(args, "--follow", values.follow);
+    pushOption(args, "--issue", values.issue);
+    pushOption(args, "--run", values.run);
+    pushOption(args, "--level", values.level);
+    await invokeHandler("repo", args, values);
   });
   addGlobalOptions(
-    repo.command("sync").description("Sync repositories from the active GitHub Project").option("--dry-run", "Preview repository changes without writing config").option("--prune", "Remove local repositories that are no longer linked").allowExcessArguments(false)
-  ).action(async function() {
+    repo.command("explain").description("Explain why a repository issue is not dispatching").argument("[args...]", "Issue identifier and passthrough options").option("--workflow <path>", "Path to the WORKFLOW.md file to evaluate").allowUnknownOption(true).allowExcessArguments(true)
+  ).action(async function(passthrough) {
     markInvoked();
     const values = this.optsWithGlobals();
-    const args = ["sync"];
-    pushOption(args, "--dry-run", values.dryRun);
-    pushOption(args, "--prune", values.prune);
+    const args = ["explain", ...passthrough];
+    pushOption(args, "--workflow", values.workflow);
     await invokeHandler("repo", args, values);
   });
   const config = addGlobalOptions(