@gh-symphony/cli 0.0.21 → 0.1.2

package/README.md

@@ -36,6 +36,7 @@ Validate the machine and repo prerequisites before first use:
 gh-symphony doctor
 gh-symphony doctor --fix
 gh-symphony doctor --json
+gh-symphony doctor --smoke
 GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token gh-symphony doctor --json
 ```
 
@@ -62,6 +63,7 @@ gh-symphony workflow init
 gh-symphony workflow init --dry-run
 gh-symphony workflow validate
 gh-symphony workflow preview --issue owner/repo#123
+gh-symphony doctor --smoke --issue owner/repo#123
 ```
 
 The interactive wizard will:
@@ -105,16 +107,16 @@ You can further customize the agent's behavior by editing `WORKFLOW.md` — this
 
 > Currently supported runtimes: **Codex**, **Claude Code**
 
-### Project `.env` Mapping
+### Repository `.env` Mapping
 
-If your hooks or worker runs need staging hosts, database URLs, Playwright base URLs, or other runtime-only values, store them in the project runtime directory instead of hardcoding them in `WORKFLOW.md`.
+If your hooks or worker runs need staging hosts, database URLs, Playwright base URLs, or other runtime-only values, store them in the repository runtime directory instead of hardcoding them in `WORKFLOW.md`.
 
-1. Find the project id from `gh-symphony project list`.
+1. Initialize the repository runtime with `gh-symphony repo init`.
 2. Create the runtime env file:
 
 ```bash
-mkdir -p ~/.gh-symphony/projects/<project-id>
-cat > ~/.gh-symphony/projects/<project-id>/.env <<'EOF'
+mkdir -p .runtime/orchestrator
+cat > .runtime/orchestrator/.env <<'EOF'
 STAGING_API_HOST=https://staging.example.com
 DATABASE_URL=postgres://user:pass@staging-db:5432/app
 PLAYWRIGHT_BASE_URL=http://localhost:3000
@@ -135,14 +137,14 @@ Env precedence during hook execution and worker spawn is:
 - system env as the override layer
 - Symphony context vars such as `SYMPHONY_*` as the highest-priority layer
 
-If you use `--config <dir>`, replace `~/.gh-symphony` with that directory.
+The repository runtime always lives under `.runtime/orchestrator/`.
 
-## 3. Set Orchestrator Runner (Project)
+## 3. Set Orchestrator Runner (Repository)
 
-On the machine where you want the orchestrator to run, register a project:
+From inside the cloned repository that should run orchestration, initialize the workflow and repository runtime:
 
 ```bash
-gh-symphony project add
+gh-symphony setup
 ```
 
 The interactive wizard will:
@@ -150,8 +152,7 @@ The interactive wizard will:
 1. Authenticate via `GITHUB_GRAPHQL_TOKEN` or fall back to `gh` CLI
 2. Let you select a **GitHub Project**
 3. Optionally limit processing to issues assigned to the authenticated user
-4. Optionally customize advanced settings for repository filtering and workspace root directory
-5. Write project configuration to `~/.gh-symphony/`
+4. Write `WORKFLOW.md`, support files, and `.runtime/orchestrator/` in the repository
 
 This wizard uses the same pagination-aware discovery path as `workflow init`, so it can enumerate large personal and organization-backed GitHub accounts more reliably. If the CLI stops at a safety limit, it warns that the visible project list may be incomplete.
 
@@ -162,94 +163,125 @@ GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token \
   gh-symphony workflow init --non-interactive --project PVT_xxx --output WORKFLOW.md
 
 GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token \
-  gh-symphony project add --non-interactive --project PVT_xxx --workspace-dir ~/.gh-symphony/workspaces
+  gh-symphony repo init
 ```
 
-Token-only project registration is also supported:
+Token-only setup is also supported when exactly one GitHub Project is visible to the token:
 
 ```bash
 export GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token
-gh-symphony project add
+gh-symphony setup
 ```
 
-If the selected GitHub Project is brand new and has no linked repositories yet, the setup still succeeds. The completion message reports `0 repositories` and suggests either `gh-symphony repo add <owner/name>` or adding a repo-linked issue to the GitHub Project.
-
-### Project Management
+### Repository Management
 
 ```bash
 gh-symphony doctor                   # Validate local prerequisites, auth, config, WORKFLOW.md, and runtime command
 gh-symphony doctor --fix             # Apply safe fixes and guide/launch follow-up recovery commands
-gh-symphony project list             # List all configured projects
-gh-symphony project remove <id>      # Remove a project
-gh-symphony repo add owner/name      # Validate and save a repo target manually
-gh-symphony repo sync                # Add newly linked repositories from the GitHub Project
-gh-symphony repo sync --dry-run      # Preview linked repository drift
-gh-symphony repo sync --prune        # Remove local repositories no longer linked
+gh-symphony doctor --smoke           # Final preflight: validate a live issue without dispatching work
+gh-symphony repo init                # Bind .runtime/orchestrator to the cwd repository
+gh-symphony repo status              # Show current repository orchestration status
+gh-symphony repo explain owner/repo#123  # Explain why one issue is not dispatching
+gh-symphony repo start               # Start this repository
+gh-symphony repo stop                # Stop this repository
 ```
 
-Use `gh-symphony repo add owner/name` as the onboarding safety check when a
-project starts empty or when you want to register a repository before it is
-linked on the GitHub Project board. Successful validation stores the canonical
-clone URL from the GitHub API. If auth is unavailable or the API is offline,
-the CLI still saves the repo with the fallback HTTPS clone URL and prints a
-warning that validation was skipped.
+`gh-symphony repo init` reads `WORKFLOW.md`, infers `owner/name` from the Git remote, and writes per-repo runtime state under `.runtime/orchestrator/`.
+
+### Why Is My Issue Not Running?
 
-Use `gh-symphony repo sync` when the GitHub Project board has gained or lost
-linked repositories since the project was first added locally. Default sync is
-additive; `--prune` switches to strict alignment, and `--json` prints the added,
-removed, unchanged, and final repository sets.
+Use `gh-symphony repo explain <owner/repo#number>` before digging through
+logs manually:
+
+```bash
+gh-symphony repo explain owner/repo#123
+gh-symphony repo explain owner/repo#123 --json
+gh-symphony repo explain owner/repo#123 --workflow ./WORKFLOW.md
+```
+
+The command checks project repository linkage, GitHub Project item presence,
+`WORKFLOW.md` active / wait / terminal state mapping, blocker state, existing
+run / retry / convergence ownership, and project or per-state concurrency
+limits.
+
+If the project has no previous local run snapshot and the repository path is
+not stored in the managed project config, pass `--workflow` so the command
+does not guess from the current shell directory.
+
+```text
+Issue dispatch explanation: owner/repo#123
+Not dispatchable: Issue has 1 unresolved blocker.
+
+Checks:
+  ✓ Repository owner/repo is linked to the active managed project.
+  ✓ Issue is present in the bound GitHub Project item set.
+  ✓ Project state "Todo" maps to an active state in WORKFLOW.md.
+  ✗ Issue has 1 unresolved blocker.
+    Hint: Move blocker issues to a terminal state or update the blocker relationship in GitHub.
+```
 
-For empty projects, use `gh-symphony repo add owner/name` after setup to seed the local repository list without re-running the whole wizard.
+The remediation hints point to existing commands such as `workflow preview`,
+`doctor`, `repo status`, and `repo logs --issue`.
 
 ## 4. Run the Orchestrator
 
 ### Foreground
 
 ```bash
-gh-symphony start
-gh-symphony start --once            # Run startup cleanup + one orchestration tick, then exit
-gh-symphony project start --once    # Same one-shot flow for an explicit project
+gh-symphony repo start
+gh-symphony repo start --once            # Run startup cleanup + one orchestration tick, then exit
 ```
 
 ### Background (daemon)
 
 ```bash
-gh-symphony start --daemon          # Start in background
-gh-symphony stop                    # Stop the daemon
+gh-symphony repo start --daemon          # Start in background
+gh-symphony repo stop                    # Stop the daemon
 ```
 
-Use `start --once` for the first real managed-project run or a CI smoke check. It reuses the configured GitHub Project binding and `WORKFLOW.md` and performs exactly one poll/reconcile/dispatch cycle instead of entering the long-running orchestration loop. `--daemon --once` is rejected because the modes conflict. If you add `--http`, the dashboard/API remains available after that one-shot tick completes, and the process stays up until you interrupt it with `Ctrl+C`.
+Run `doctor --smoke` before the first `start --once` when you want a safe pre-dispatch readiness check. Use `start --once` for the first real managed-project run or a CI smoke check. It reuses the configured GitHub Project binding and `WORKFLOW.md` and performs exactly one poll/reconcile/dispatch cycle instead of entering the long-running orchestration loop. `--daemon --once` is rejected because the modes conflict. If you add `--http`, the dashboard/API remains available after that one-shot tick completes, and the process stays up until you interrupt it with `Ctrl+C`.
 
 ### Monitor
 
 ```bash
-gh-symphony status                  # Show current status
-gh-symphony status --watch          # Live dashboard
-gh-symphony logs                    # View event logs
-gh-symphony logs --follow           # Stream logs in real-time
+gh-symphony repo status                  # Show current status
+gh-symphony repo status --watch          # Live dashboard
+gh-symphony repo logs                    # View event logs
+gh-symphony repo logs --follow           # Stream logs in real-time
 ```
 
 ### Dispatch a Single Issue
 
 ```bash
-gh-symphony run org/repo#123
+gh-symphony repo run org/repo#123
 ```
 
 ### Recover Stalled Runs
 
 ```bash
-gh-symphony recover                 # Recover stalled runs
-gh-symphony recover --dry-run       # Preview what would be recovered
+gh-symphony repo recover                 # Recover stalled runs
+gh-symphony repo recover --dry-run       # Preview what would be recovered
 ```
 
 ## Diagnostics
 
-`gh-symphony doctor` validates the most common first-run prerequisites in one pass. `gh-symphony doctor --fix` extends that flow with safe remediation and guided follow-up:
+`gh-symphony doctor` validates the most common first-run prerequisites in one pass. `gh-symphony doctor --smoke` is the recommended final preflight before `gh-symphony repo start --once`: it resolves the active managed project, checks the GitHub Project binding, confirms the repository and target issue are readable through the project, renders `WORKFLOW.md` for that issue, verifies the runtime command, workspace root, and configured hook paths, and exits without dispatching a worker.
+
+Use an explicit issue when you want a deterministic check:
+
+```bash
+gh-symphony doctor --smoke --issue owner/repo#123
+gh-symphony doctor --smoke --issue owner/repo#123 --json
+```
+
+Without `--issue`, doctor auto-selects one active live issue from the managed project. If none is suitable, the report explains which active states it expected and suggests re-running with `--issue`.
+
+`gh-symphony doctor --fix` extends the regular diagnostic flow with safe remediation and guided follow-up:
 
 - creates missing config/runtime/workspace directories
 - launches `gh auth login` or `gh auth refresh` when a TTY is available, otherwise prints the exact command to run
-- launches `gh-symphony init` when `WORKFLOW.md` is missing or invalid
-- launches `gh-symphony project add` when managed project setup or GitHub Project binding must be repaired
+- launches `gh-symphony workflow init` when `WORKFLOW.md` is missing or invalid
+- launches `gh-symphony setup` when repository runtime setup or GitHub Project binding must be repaired
 - prints concrete runtime install guidance when the configured command is missing on `PATH`
 
 The diagnostic checks cover:
@@ -258,17 +290,19 @@ The diagnostic checks cover:
 - Node.js runtime version against the documented minimum (`v24+`) and the current `process.version`
 - Git installation availability on `PATH`, including `git --version` when available
 - GitHub authentication via `GITHUB_GRAPHQL_TOKEN` or `gh`, including required scopes
-- managed project selection plus GitHub Project binding resolution
-- config/runtime/workspace path writability
+- repository runtime selection plus GitHub Project binding resolution
+- runtime/workspace path writability
 - repository `WORKFLOW.md` presence and parse validity
 - runtime command availability on `PATH`
+- with `--smoke`: linked repository readiness, live issue readability, strict prompt rendering, and hook path resolution
 
 Use JSON output for scripts and CI smoke checks. `--fix --json` includes a remediation section where each step is reported as `applied`, `skipped`, or `manual`.
 
 ```bash
 gh-symphony doctor --json
 gh-symphony doctor --fix --json
-gh-symphony start --once
+gh-symphony doctor --smoke --json
+gh-symphony repo start --once
 ```
 
 JSON output includes the resolved auth source as `env` or `gh`.
@@ -277,33 +311,30 @@ JSON output includes the resolved auth source as `env` or `gh`.
 
 ```
 Setup:
+  setup               Generate WORKFLOW.md and initialize the cwd repository runtime
   workflow init       Interactive repository setup wizard
   workflow validate   Parse and strictly validate WORKFLOW.md
   workflow preview    Render the final worker prompt from a sample or live issue
-  doctor              Run diagnostics and optional first-run remediation
+  doctor              Run diagnostics, smoke checks, and optional remediation
   config show         Show current configuration
   config set          Set a configuration value
   config edit         Open config in $EDITOR
 
 Orchestration:
-  start               Start the orchestrator (foreground)
-  start --once        Run a single orchestration tick and exit
-  start --daemon      Start the orchestrator (background)
-  stop                Stop the background orchestrator
-  status              Show orchestrator status
-  run <issue>         Dispatch a single issue
-  recover             Recover stalled runs
-  logs                View orchestrator logs
+  repo init           Bind .runtime/orchestrator to the cwd repository
+  repo start          Start the orchestrator (foreground)
+  repo start --once   Run a single orchestration tick and exit
+  repo start --daemon Start the orchestrator (background)
+  repo stop           Stop the background orchestrator
+  repo status         Show orchestrator status
+  repo run <issue>    Dispatch a single issue
+  repo recover        Recover stalled runs
+  repo logs           View orchestrator logs
+  repo explain        Explain why an issue is not dispatching
   completion <shell>  Print shell completion for bash/zsh/fish
 
-Project Management:
-  project add          Add a new project (interactive wizard)
-  project list         List all configured projects
-  project remove       Remove a project
-  repo sync            Refresh repositories from the linked GitHub Project
-
 Global Options:
-  --config <dir>      Config directory (default: ~/.gh-symphony)
+  --config <dir>      Config directory (default: initialized cwd runtime, then ~/.gh-symphony)
   --verbose           Enable verbose output
   --json              Output in JSON format
   --no-color          Disable color output

package/dist/chunk-6I753NYO.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import {
+  REPO_RUNTIME_DIR
+} from "./chunk-WOVNN5NW.js";
+
+// src/orchestrator-runtime.ts
+import { resolve } from "path";
+function resolveRuntimeRoot(configDir) {
+  return resolve(configDir);
+}
+function resolveRepoRuntimeRoot(repoDir = process.cwd()) {
+  return resolve(repoDir, REPO_RUNTIME_DIR);
+}
+
+export {
+  resolveRuntimeRoot,
+  resolveRepoRuntimeRoot
+};

package/dist/{workflow-BLJH2HC3.js → chunk-B4ZJMAZL.js}

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import {
-  init_default
-} from "./chunk-JN3TQVFV.js";
+  workflow_init_default
+} from "./chunk-WM2B6BJ7.js";
 import {
-  fetchGithubProjectIssueByRepositoryAndNumber
-} from "./chunk-SXGT7LOF.js";
+  fetchGithubProjectIssueByRepositoryAndNumber,
+  inspectManagedProjectSelection
+} from "./chunk-DLZAJXZL.js";
 import {
   GitHubApiError,
   createClient,
@@ -12,16 +13,12 @@ import {
   getGhTokenWithSource,
   getProjectDetail,
   validateGitHubToken
-} from "./chunk-C67H3OUL.js";
+} from "./chunk-Z3NZOPLZ.js";
 import {
   buildPromptVariables,
   parseWorkflowMarkdown,
   renderPrompt
-} from "./chunk-QEONJ5DZ.js";
-import {
-  inspectManagedProjectSelection
-} from "./chunk-C7G7RJ4G.js";
-import "./chunk-ROGRTUFI.js";
+} from "./chunk-GPRCOJDJ.js";
 
 // src/commands/workflow.ts
 import { readFile } from "fs/promises";
@@ -391,6 +388,14 @@ function readGitHubProjectBinding(projectConfig) {
   const settingsProjectId = projectConfig.tracker.settings?.projectId;
   return typeof settingsProjectId === "string" && settingsProjectId.trim().length > 0 ? settingsProjectId.trim() : null;
 }
+function renderIssueWorkflowPreview(input) {
+  const variables = buildPromptVariables(input.issue, {
+    attempt: input.attempt
+  });
+  return renderPrompt(input.workflow.promptTemplate, variables, {
+    strict: true
+  });
+}
 function formatAuthError(error) {
   return `GitHub authentication is required for live issue preview. ${error.message}`;
 }
@@ -406,7 +411,7 @@ async function loadLiveIssue(issueReference, projectId, options) {
   const githubProjectId = readGitHubProjectBinding(selection.projectConfig);
   if (!githubProjectId) {
     throw new Error(
-      `Managed project "${selection.projectId}" is not bound to a GitHub Project. Re-run 'gh-symphony project add' and select a valid GitHub Project binding.`
+      `Managed project "${selection.projectId}" is not bound to a GitHub Project. Run 'gh-symphony workflow init' to select a valid GitHub Project binding, then run 'gh-symphony repo init'.`
     );
   }
   let auth;
@@ -439,7 +444,7 @@ async function loadLiveIssue(issueReference, projectId, options) {
   }
   if (!findLinkedRepository(detail, issue.owner, issue.name)) {
     throw new Error(
-      `Repository ${issue.owner}/${issue.name} is not linked to the configured GitHub Project "${detail.title}". Run 'gh-symphony repo add ${issue.owner}/${issue.name}' or re-run 'gh-symphony project add' with the correct project binding.`
+      `Repository ${issue.owner}/${issue.name} is not linked to the configured GitHub Project "${detail.title}". Run 'gh-symphony setup' from inside the target repository, or run 'gh-symphony workflow init' followed by 'gh-symphony repo init'.`
     );
   }
   const trackedIssue = await workflowCommandDependencies.fetchLiveIssue(
@@ -587,12 +592,11 @@ async function runPreview(args, options) {
     );
   }
   const { issue, sampleSource } = flags.issue ? await loadLiveIssue(flags.issue, flags.projectId, options) : await loadSampleIssue(flags.sample);
-  const variables = buildPromptVariables(issue, {
+  const renderedPrompt = renderIssueWorkflowPreview({
+    workflow,
+    issue,
     attempt: flags.attempt
   });
-  const renderedPrompt = renderPrompt(workflow.promptTemplate, variables, {
-    strict: true
-  });
   if (options.json) {
     process.stdout.write(
       `${JSON.stringify(
@@ -639,7 +643,7 @@ var handler = async (args, options) => {
   try {
     switch (parsed.subcommand) {
       case "init":
-        await init_default(parsed.args, options);
+        await workflow_init_default(parsed.args, options);
         return;
       case "validate":
         await runValidate(parsed.args, options);
@@ -656,8 +660,12 @@ var handler = async (args, options) => {
   }
 };
 var workflow_default = handler;
+
 export {
-  workflow_default as default,
+  setWorkflowCommandDependenciesForTest,
   resetWorkflowCommandDependenciesForTest,
-  setWorkflowCommandDependenciesForTest
+  parseIssueReference,
+  readGitHubProjectBinding,
+  renderIssueWorkflowPreview,
+  workflow_default
 };