@gh-symphony/cli 0.0.21 → 0.0.22

package/dist/{chunk-ROGRTUFI.js → chunk-QIRE2VXS.js}

@@ -54,9 +54,15 @@ async function saveGlobalConfig(configDir, config) {
   await writeJsonFile(configFilePath(configDir), config);
 }
 async function loadProjectConfig(configDir, projectId) {
-  return readJsonFile(
-    projectConfigPath(configDir, projectId)
-  );
+  const config = await readJsonFile(projectConfigPath(configDir, projectId));
+  if (!config) {
+    return null;
+  }
+  const repository = config.repository ?? firstConfiguredRepository(config);
+  return {
+    ...config,
+    ...repository ? { repository } : {}
+  };
 }
 async function saveProjectConfig(configDir, projectId, config) {
   await writeJsonFile(projectConfigPath(configDir, projectId), config);
@@ -91,6 +97,11 @@ function isFileMissing(error) {
     error && typeof error === "object" && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")
   );
 }
+function firstConfiguredRepository(config) {
+  return config.repositories?.find(
+    (repository) => typeof repository.owner === "string" && repository.owner.length > 0 && typeof repository.name === "string" && repository.name.length > 0
+  );
+}
 
 export {
   resolveConfigDir,

package/dist/{chunk-S6VIK4FF.js → chunk-ZHOKYUO3.js}

@@ -4,34 +4,55 @@ import {
   generateProjectId,
   warnIfProjectDiscoveryPartial,
   writeConfig
-} from "./chunk-JN3TQVFV.js";
+} from "./chunk-HMLBBZNY.js";
 import {
   start_default
-} from "./chunk-KY6WKH66.js";
+} from "./chunk-E7HYEEZD.js";
+import {
+  explainIssueDispatch,
+  isActiveRunRecordStatus,
+  parseIssueIdentifier,
+  resolveTrackerAdapter
+} from "./chunk-PUDXVBSN.js";
+import {
+  findGithubProjectIssue
+} from "./chunk-2TSM3INR.js";
 import {
   GhAuthError,
   GitHubScopeError,
   checkRequiredScopes,
   createClient,
   discoverUserProjects,
+  getGhToken,
   getGhTokenWithSource,
   getProjectDetail,
   listUserProjects,
   resolveGitHubAuth,
   validateToken
 } from "./chunk-C67H3OUL.js";
+import {
+  WorkflowConfigStore
+} from "./chunk-EEQQWTXS.js";
 import {
   status_default
-} from "./chunk-XN5ABWZ6.js";
+} from "./chunk-DFLXHNYQ.js";
 import {
-  stripAnsi
-} from "./chunk-MVRF7BES.js";
+  bold,
+  green,
+  red,
+  stripAnsi,
+  yellow
+} from "./chunk-36KYEDEO.js";
 import {
   resolveRuntimeRoot
-} from "./chunk-5NV3LSAJ.js";
+} from "./chunk-IWFX2FMA.js";
 import {
   stop_default
-} from "./chunk-Y6TYJMNT.js";
+} from "./chunk-GSX2FV3M.js";
+import {
+  handleMissingManagedProjectConfig,
+  resolveManagedProjectConfig
+} from "./chunk-DDL4BWSL.js";
 import {
   daemonPidPath,
   httpStatusPath,
@@ -39,14 +60,15 @@ import {
   loadProjectConfig,
   projectConfigDir,
   saveGlobalConfig
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/commands/project.ts
 import * as p from "@clack/prompts";
 import { execFile as execFileCallback } from "child_process";
 import { promisify } from "util";
-import { readFile } from "fs/promises";
+import { readdir, readFile } from "fs/promises";
 import { join } from "path";
+import { resolve } from "path";
 var execFile = promisify(execFileCallback);
 var KNOWN_REQUIRED_SCOPES = ["repo", "read:org", "project"];
 function formatProjectRepoSummary(selectedRepos, totalLinked) {
@@ -113,6 +135,47 @@ function parseProjectAddFlags(args) {
   }
   return flags;
 }
+function parseProjectExplainFlags(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--project" || arg === "--project-id") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        parsed.error = `Option '${arg}' argument missing`;
+        return parsed;
+      }
+      parsed.projectId = value;
+      i += 1;
+      continue;
+    }
+    if (arg === "--workflow" || arg === "--workflow-path") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        parsed.error = `Option '${arg}' argument missing`;
+        return parsed;
+      }
+      parsed.workflowPath = value;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("-")) {
+      parsed.error = `Unknown option '${arg}'`;
+      return parsed;
+    }
+    if (parsed.identifier) {
+      parsed.error = "Only one issue identifier can be explained at a time";
+      return parsed;
+    }
+    parsed.identifier = arg;
+  }
+  if (!parsed.identifier) {
+    parsed.error = "Issue identifier argument missing";
+  } else if (!parseIssueIdentifier(parsed.identifier)) {
+    parsed.error = "Issue identifier must use the form <owner>/<repo>#<number>";
+  }
+  return parsed;
+}
 var handler = async (args, options) => {
   const [subcommand, ...rest] = args;
   switch (subcommand) {
@@ -137,9 +200,12 @@ var handler = async (args, options) => {
     case "status":
       await status_default(rest, options);
       return;
+    case "explain":
+      await projectExplain(rest, options);
+      return;
     default:
       process.stdout.write(
-        "Usage: gh-symphony project <add|list|remove|start|stop|switch|status>\n"
+        "Usage: gh-symphony project <add|list|remove|start|stop|switch|status|explain>\n"
       );
   }
 };
@@ -237,9 +303,260 @@ async function readPersistedSnapshot(configDir, projectId) {
 async function fetchProjectSnapshot(configDir, projectId) {
   return readPersistedSnapshot(configDir, projectId);
 }
+async function projectExplain(args, options) {
+  const parsed = parseProjectExplainFlags(args);
+  if (parsed.error) {
+    process.stderr.write(`${parsed.error}
+`);
+    process.stderr.write(
+      "Usage: gh-symphony project explain <owner/repo#number> [--project-id <project-id>] [--workflow <path>]\n"
+    );
+    process.exitCode = 2;
+    return;
+  }
+  const projectConfig = await resolveManagedProjectConfig({
+    configDir: options.configDir,
+    requestedProjectId: parsed.projectId
+  });
+  if (!projectConfig) {
+    handleMissingManagedProjectConfig();
+    return;
+  }
+  const identifier = parsed.identifier;
+  const parsedIdentifier = parseIssueIdentifier(identifier);
+  const fallbackRepository = {
+    owner: parsedIdentifier.owner,
+    name: parsedIdentifier.name,
+    cloneUrl: `https://github.com/${parsedIdentifier.owner}/${parsedIdentifier.name}.git`
+  };
+  const workflowRepository = projectConfig.repository ?? fallbackRepository;
+  let token;
+  try {
+    token = getGhToken();
+  } catch (error) {
+    if (error instanceof GhAuthError) {
+      process.stderr.write(
+        `Error: GitHub authentication is required for project explain. ${error.message}
+`
+      );
+      process.stderr.write(
+        "Run 'gh auth login --scopes repo,read:org,project' or set GITHUB_GRAPHQL_TOKEN, then re-run this command.\n"
+      );
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+  const trackerAdapter = resolveTrackerAdapter(projectConfig.tracker);
+  const orchestratorProject = {
+    ...projectConfig,
+    repository: workflowRepository
+  };
+  const trackerDependencies = {
+    token,
+    projectItemsCache: createProjectItemsCache()
+  };
+  const runtimeRoot = join(
+    resolveRuntimeRoot(options.configDir),
+    "projects",
+    projectConfig.projectId
+  );
+  const issuesPromise = trackerAdapter.listIssues(
+    orchestratorProject,
+    trackerDependencies
+  );
+  const issuePromise = projectConfig.tracker.adapter === "github-project" ? findGithubProjectIssue(
+    orchestratorProject,
+    identifier,
+    trackerDependencies
+  ) : issuesPromise.then(
+    (issues2) => issues2.find(
+      (candidate) => candidate.identifier.trim().toLowerCase() === identifier.trim().toLowerCase()
+    ) ?? null
+  );
+  const [issues, issue, issueRecords, runs, snapshot] = await Promise.all([
+    issuesPromise,
+    issuePromise,
+    readJsonFile(join(runtimeRoot, "issues.json")),
+    readRuns(runtimeRoot, projectConfig.projectId),
+    readPersistedSnapshot(options.configDir, projectConfig.projectId)
+  ]);
+  let workflow;
+  try {
+    workflow = await loadExplainWorkflow({
+      explicitWorkflowPath: parsed.workflowPath,
+      repository: workflowRepository,
+      runs
+    });
+  } catch (error) {
+    if (error instanceof ProjectExplainWorkflowError) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.stderr.write(
+        "Hint: pass --workflow <path-to-WORKFLOW.md> or run 'gh-symphony workflow preview --file <path>' to verify the workflow file.\n"
+      );
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+  const activeRunCount = runs.filter(
+    (run) => isActiveRunRecordStatus(run.status)
+  ).length;
+  const report = explainIssueDispatch({
+    identifier,
+    issue,
+    projectRepository: projectConfig.repository ?? null,
+    allIssues: issues,
+    lifecycle: workflow.lifecycle,
+    issueRecords: issueRecords ?? [],
+    runs,
+    activeRunCount,
+    maxConcurrentAgents: workflow.maxConcurrentAgents,
+    maxConcurrentAgentsByState: workflow.maxConcurrentAgentsByState
+  });
+  const enrichedReport = {
+    ...report,
+    project: {
+      id: projectConfig.projectId,
+      slug: projectConfig.slug,
+      tracker: projectConfig.tracker,
+      lastTickAt: snapshot?.lastTickAt ?? null,
+      health: snapshot?.health ?? null
+    }
+  };
+  if (options.json) {
+    process.stdout.write(JSON.stringify(enrichedReport, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(renderProjectExplainReport(report, options.noColor));
+}
+var ProjectExplainWorkflowError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProjectExplainWorkflowError";
+  }
+};
+async function loadExplainWorkflow(input) {
+  const workflowPaths = resolveExplainWorkflowCandidates(input);
+  if (workflowPaths.length === 0) {
+    throw new ProjectExplainWorkflowError(
+      "No WORKFLOW.md path could be resolved from --workflow, the configured repository path, or previous run records."
+    );
+  }
+  const failures = [];
+  for (const workflowPath of workflowPaths) {
+    try {
+      const resolution = await new WorkflowConfigStore().load(workflowPath);
+      return {
+        lifecycle: resolution.lifecycle,
+        maxConcurrentAgents: resolution.workflow.agent.maxConcurrentAgents,
+        maxConcurrentAgentsByState: resolution.workflow.agent.maxConcurrentAgentsByState
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`${workflowPath}: ${message}`);
+    }
+  }
+  throw new ProjectExplainWorkflowError(
+    `Unable to load WORKFLOW.md for project explain. Checked: ${failures.join("; ")}`
+  );
+}
+function resolveExplainWorkflowCandidates(input) {
+  const paths = [];
+  if (input.explicitWorkflowPath) {
+    paths.push(resolve(input.explicitWorkflowPath));
+  }
+  if (input.repository.path) {
+    paths.push(join(resolve(input.repository.path), "WORKFLOW.md"));
+  }
+  const newestRuns = [...input.runs].sort(
+    (left, right) => (Date.parse(right.updatedAt) || 0) - (Date.parse(left.updatedAt) || 0)
+  );
+  for (const run of newestRuns) {
+    if (run.workflowPath) {
+      paths.push(resolve(run.workflowPath));
+    }
+    if (run.workingDirectory) {
+      paths.push(join(resolve(run.workingDirectory), "WORKFLOW.md"));
+    }
+  }
+  return [...new Set(paths)];
+}
+function createProjectItemsCache() {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    getOrLoad(key, load) {
+      const cached = entries.get(key);
+      if (cached) {
+        return cached;
+      }
+      const pending = load().catch((error) => {
+        entries.delete(key);
+        throw error;
+      });
+      entries.set(key, pending);
+      return pending;
+    }
+  };
+}
+async function readRuns(runtimeRoot, projectId) {
+  let runIds;
+  try {
+    runIds = await readdir(join(runtimeRoot, "runs"));
+  } catch {
+    return [];
+  }
+  const runs = await Promise.all(
+    runIds.map(
+      (runId) => readJsonFile(
+        join(runtimeRoot, "runs", runId, "run.json")
+      )
+    )
+  );
+  return runs.filter(
+    (run) => run !== null && run.projectId === projectId
+  );
+}
+async function readJsonFile(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function renderProjectExplainReport(report, noColor) {
+  const apply = noColor ? (value) => stripAnsi(value) : (value) => value;
+  const lines = [
+    apply(bold(`Issue dispatch explanation: ${report.issue.identifier}`)),
+    report.summary,
+    "",
+    `State: ${report.issue.state ?? "unknown"}`,
+    `Repository: ${report.issue.repository}`,
+    "",
+    "Checks:"
+  ];
+  for (const check of report.checks) {
+    const marker = check.status === "pass" ? green("\u2713") : check.status === "warn" ? yellow("!") : red("\u2717");
+    lines.push(`  ${apply(marker)} ${check.message}`);
+    if (check.hint) {
+      lines.push(`    Hint: ${check.hint}`);
+    }
+  }
+  lines.push("");
+  lines.push("Related commands:");
+  lines.push("  gh-symphony workflow preview");
+  lines.push("  gh-symphony doctor");
+  lines.push("  gh-symphony project status");
+  lines.push("  gh-symphony logs --issue " + report.issue.identifier);
+  return lines.join("\n") + "\n";
+}
 async function readHttpEndpoint(configDir, projectId) {
   try {
-    const content = await readFile(httpStatusPath(configDir, projectId), "utf8");
+    const content = await readFile(
+      httpStatusPath(configDir, projectId),
+      "utf8"
+    );
     const state = JSON.parse(content);
     return typeof state.endpoint === "string" && state.endpoint.length > 0 ? state.endpoint : null;
   } catch {
@@ -251,7 +568,12 @@ async function readProcessUptime(pid) {
     return "-";
   }
   try {
-    const { stdout } = await execFile("ps", ["-o", "etime=", "-p", String(pid)]);
+    const { stdout } = await execFile("ps", [
+      "-o",
+      "etime=",
+      "-p",
+      String(pid)
+    ]);
     const seconds = parsePsElapsedTime(stdout);
     return seconds === null ? "-" : formatDuration(seconds);
   } catch {
@@ -660,7 +982,9 @@ async function projectRemove(args, options) {
     process.exitCode = 1;
     return;
   }
-  const updatedProjects = global.projects.filter((entry) => entry !== projectId);
+  const updatedProjects = global.projects.filter(
+    (entry) => entry !== projectId
+  );
   if (updatedProjects.length === global.projects.length) {
     process.stderr.write(`Project "${projectId}" not found.
 `);

package/dist/{config-cmd-DNXNL26Z.js → config-cmd-Z3A7V6NC.js}

@@ -3,7 +3,7 @@ import {
   configFilePath,
   loadGlobalConfig,
   saveGlobalConfig
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/commands/config-cmd.ts
 import { spawn } from "child_process";

package/dist/{doctor-4HBRICHP.js → doctor-EJUMPBMW.js}

@@ -19,14 +19,14 @@ import {
   resolveClaudeCommandBinary,
   resolveRuntimeCommandBinary,
   runClaudePreflight
-} from "./chunk-QEONJ5DZ.js";
+} from "./chunk-EEQQWTXS.js";
 import {
   resolveRuntimeRoot
-} from "./chunk-5NV3LSAJ.js";
+} from "./chunk-IWFX2FMA.js";
 import {
   inspectManagedProjectSelection
-} from "./chunk-C7G7RJ4G.js";
-import "./chunk-ROGRTUFI.js";
+} from "./chunk-DDL4BWSL.js";
+import "./chunk-QIRE2VXS.js";
 
 // src/commands/doctor.ts
 import { constants } from "fs";

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   resolveConfigDir
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/index.ts
 import { realpathSync } from "fs";
@@ -278,21 +278,21 @@ ${bashFunction}complete -F _gh_symphony_completion gh-symphony
 
 // 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-L3KT6HB7.js"),
+  init: () => import("./init-54HMKNYI.js"),
+  setup: () => import("./setup-TZJSM3QV.js"),
+  doctor: () => import("./doctor-EJUMPBMW.js"),
+  upgrade: () => import("./upgrade-O33S2SJK.js"),
+  start: () => import("./start-RTAHQMR2.js"),
+  stop: () => import("./stop-MDKMJPVR.js"),
+  status: () => import("./status-F4D52OVK.js"),
+  run: () => import("./run-IHN3ZL35.js"),
+  recover: () => import("./recover-LTLKMTRX.js"),
+  logs: () => import("./logs-GTZ4U5JE.js"),
+  project: () => import("./project-RMYMZSFV.js"),
+  repo: () => import("./repo-WI7GF6XQ.js"),
+  config: () => import("./config-cmd-Z3A7V6NC.js"),
+  version: () => import("./version-CW54Q7BK.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");
@@ -356,7 +356,10 @@ function createProgram() {
     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)
+    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();
@@ -382,7 +385,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();
@@ -459,7 +465,7 @@ function createProgram() {
     ).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").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
@@ -473,7 +479,7 @@ function createProgram() {
     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)
+    program.command("stop").description("Stop the background orchestrator").option("--force", "Force stop with SIGKILL").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
@@ -483,7 +489,7 @@ function createProgram() {
     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("status").description("Show orchestrator status").option("-w, --watch", "Watch status continuously").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
   ).action(async function() {
     markInvoked();
     const values = this.optsWithGlobals();
@@ -612,6 +618,16 @@ function createProgram() {
     pushOption(args, "--watch", values.watch);
     await invokeHandler("project", args, values);
   });
+  addGlobalOptions(
+    project.command("explain").description("Explain why a project issue is not dispatching").argument("<issue>", "Issue identifier, for example owner/repo#123").option("--project-id <projectId>", "Project identifier").option("--workflow <path>", "Path to the WORKFLOW.md file to evaluate").addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+  ).action(async function(issue) {
+    markInvoked();
+    const values = this.optsWithGlobals();
+    const args = ["explain", issue];
+    pushOption(args, "--project-id", resolveProjectId(values));
+    pushOption(args, "--workflow", values.workflow);
+    await invokeHandler("project", args, values);
+  });
   const repo = addGlobalOptions(
     program.command("repo").description("Manage repositories in the active project")
   );
@@ -629,6 +645,57 @@ function createProgram() {
       this.optsWithGlobals()
     );
   });
+  addGlobalOptions(
+    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").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+  ).action(async function() {
+    markInvoked();
+    const values = this.optsWithGlobals();
+    const args = ["init"];
+    pushOption(args, "--repo-dir", values.repoDir);
+    pushOption(args, "--workflow-file", values.workflowFile);
+    pushOption(args, "--project-id", resolveProjectId(values));
+    await invokeHandler("repo", args, values);
+  });
+  addGlobalOptions(
+    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").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+  ).action(async function() {
+    markInvoked();
+    const values = this.optsWithGlobals();
+    const args = ["start"];
+    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("repo", args, values);
+  });
+  addGlobalOptions(
+    repo.command("status").description("Show current repository orchestrator status").option("-w, --watch", "Watch status continuously").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+  ).action(async function() {
+    markInvoked();
+    const values = this.optsWithGlobals();
+    const args = ["status"];
+    pushOption(args, "--project-id", resolveProjectId(values));
+    pushOption(args, "--watch", values.watch);
+    await invokeHandler("repo", args, values);
+  });
+  addGlobalOptions(
+    repo.command("stop").description("Stop the current repository background orchestrator").option("--force", "Force stop with SIGKILL").addOption(new Option("--project-id <projectId>").hideHelp()).addOption(new Option("--project <projectId>").hideHelp()).allowExcessArguments(false)
+  ).action(async function() {
+    markInvoked();
+    const values = this.optsWithGlobals();
+    const args = ["stop"];
+    pushOption(args, "--project-id", resolveProjectId(values));
+    pushOption(args, "--force", values.force);
+    await invokeHandler("repo", args, values);
+  });
   addGlobalOptions(
     repo.command("add").description("Add a repository").argument("<owner/name>", "Repository spec").allowExcessArguments(false)
   ).action(async function(repoSpec) {

package/dist/{init-HZ3JEDGQ.js → init-54HMKNYI.js}

@@ -15,10 +15,10 @@ import {
   writeConfig,
   writeEcosystem,
   writeWorkflowPlan
-} from "./chunk-JN3TQVFV.js";
+} from "./chunk-HMLBBZNY.js";
 import "./chunk-C67H3OUL.js";
-import "./chunk-QEONJ5DZ.js";
-import "./chunk-ROGRTUFI.js";
+import "./chunk-EEQQWTXS.js";
+import "./chunk-QIRE2VXS.js";
 export {
   abortIfCancelled,
   buildAutomaticStateMappings,