@gh-symphony/cli 0.1.4 → 0.2.2

package/README.md

@@ -37,6 +37,7 @@ gh-symphony doctor
 gh-symphony doctor --fix
 gh-symphony doctor --json
 gh-symphony doctor --smoke
+gh-symphony doctor --bundle
 GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token gh-symphony doctor --json
 ```
 
@@ -107,6 +108,75 @@ You can further customize the agent's behavior by editing `WORKFLOW.md` — this
 
 > Currently supported runtimes: **Codex**, **Claude Code**
 
+### Explicit Priority Mapping
+
+GitHub Project V2 does not have a native issue priority. For GitHub Project workflows, dispatch priority is controlled only by the explicit `tracker.priority` policy in `WORKFLOW.md`; there is no fallback from Project fields to labels and no guessed label naming convention. Unmapped values resolve to `priority = null`, so dispatch falls back to created time and identifier.
+
+Project field source:
+
+```yaml
+tracker:
+  kind: github-project
+  project_id: PVT_kwDOxxxxxx
+  state_field: Status
+  priority:
+    source: project-field
+    field: Priority
+    values:
+      Urgent: 0
+      High: 1
+      Medium: 2
+      Low: 3
+```
+
+Label source:
+
+```yaml
+tracker:
+  kind: github-project
+  project_id: PVT_kwDOxxxxxx
+  state_field: Status
+  priority:
+    source: labels
+    labels:
+      P0: 0
+      P1: 1
+      P2: 2
+      P3: 3
+```
+
+Disabled:
+
+```yaml
+tracker:
+  kind: github-project
+  priority:
+    source: disabled
+```
+
+Legacy `tracker.priority_field: Priority` still works, but it is deprecated because it derives numeric priority from the live Project option order. Migrate by copying the field name into `tracker.priority.field` and writing each option display name under `values` with the intended number. If both keys are present, `tracker.priority` wins and `gh-symphony doctor` reports a warning.
+
+Run `gh-symphony workflow validate` for local schema errors and `gh-symphony doctor` for live drift warnings such as missing Project fields, missing labels, unmapped live options, stale mappings, and active issues whose priority-like value resolves to `priority = null`.
+
+### Linear Tracker Repositories
+
+For Linear, configure the tracker in `WORKFLOW.md` and initialize the repository runtime from the target GitHub repository:
+
+```yaml
+tracker:
+  kind: linear
+  api_key: $LINEAR_API_KEY
+  project_slug: symphony-0c79b11b75ea
+```
+
+`gh-symphony repo init` validates `tracker.project_slug` and resolves `tracker.api_key`, so `LINEAR_API_KEY` must be set before initialization. Linear aliases such as `tracker.project_id`, `projectId`, `project_id`, and `teamId` are rejected, and `.gh-symphony/config.json` is not a Linear source of truth.
+
+Linear runs are polling-only. There is no webhook setup command. Put state transition, workpad comment, and PR handoff policy in `WORKFLOW.md`; see `docs/examples/linear-WORKFLOW.md` in the repository for a complete example. Preview a Linear issue prompt with:
+
+```bash
+gh-symphony workflow preview ENG-123
+```
+
 ### 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 repository runtime directory instead of hardcoding them in `WORKFLOW.md`.
@@ -284,6 +354,22 @@ Without `--issue`, doctor auto-selects one active live issue from the managed pr
 - 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`
 
+`gh-symphony doctor --bundle` creates a redacted support bundle for bug reports:
+
+```bash
+gh-symphony doctor --bundle
+gh-symphony doctor --bundle ./tmp/support-bundle
+gh-symphony doctor --bundle --project-id your-project-id
+gh-symphony doctor --bundle --json
+```
+
+The bundle writes a deterministic directory containing `manifest.json`,
+`doctor.json`, redacted CLI/project config, `WORKFLOW.md`, runtime
+`status.json`/`issues.json` when available, and bounded recent run
+`events.ndjson`, `worker.log`, and `orchestrator.log` tails. Missing optional
+artifacts are listed in `manifest.missing`; redaction and truncation counts are
+reported in the command summary.
+
 The diagnostic checks cover:
 
 - the active GitHub auth source (`GITHUB_GRAPHQL_TOKEN` first, otherwise `gh`) and required scopes
@@ -302,6 +388,7 @@ Use JSON output for scripts and CI smoke checks. `--fix --json` includes a remed
 gh-symphony doctor --json
 gh-symphony doctor --fix --json
 gh-symphony doctor --smoke --json
+gh-symphony doctor --bundle --json
 gh-symphony repo start --once
 ```
 

package/dist/{chunk-HT3FAJAO.js → chunk-27UZ6KX2.js}

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import {
   workflow_init_default
-} from "./chunk-RHLUIMBN.js";
+} from "./chunk-PLBG7TZA.js";
 import {
   fetchGithubProjectIssueByRepositoryAndNumber,
-  inspectManagedProjectSelection
-} from "./chunk-YIARPBOR.js";
+  inspectManagedProjectSelection,
+  resolveTrackerAdapter
+} from "./chunk-X4QSP3AX.js";
 import {
   GitHubApiError,
   createClient,
@@ -13,16 +14,198 @@ import {
   getGhTokenWithSource,
   getProjectDetail,
   validateGitHubToken
-} from "./chunk-Z3NZOPLZ.js";
+} from "./chunk-BOM2BYZQ.js";
 import {
   buildPromptVariables,
   parseWorkflowMarkdown,
   renderPrompt
-} from "./chunk-EWTMSDCE.js";
+} from "./chunk-3SKN5L3I.js";
+import {
+  loadActiveProjectConfig
+} from "./chunk-4ICDSQCJ.js";
 
 // src/commands/workflow.ts
 import { readFile } from "fs/promises";
 import { resolve } from "path";
+
+// src/priority-diagnostics.ts
+function buildPriorityConfigDiagnostics(workflow) {
+  const diagnostics = [];
+  if (workflow.tracker.priorityFieldName) {
+    if (workflow.tracker.priority) {
+      diagnostics.push({
+        title: "Priority mapping precedence",
+        summary: "Both legacy tracker.priority_field and explicit tracker.priority are configured; explicit tracker.priority wins.",
+        remediation: "Remove tracker.priority_field after confirming the explicit tracker.priority mapping is correct.",
+        details: {
+          priorityFieldName: workflow.tracker.priorityFieldName,
+          explicitSource: workflow.tracker.priority.source
+        }
+      });
+    } else {
+      diagnostics.push({
+        title: "Legacy priority mapping",
+        summary: "tracker.priority_field is deprecated and still supported with legacy Project option-order semantics.",
+        remediation: "Migrate to tracker.priority with an explicit project-field, labels, or disabled source.",
+        details: {
+          priorityFieldName: workflow.tracker.priorityFieldName
+        }
+      });
+    }
+  }
+  return diagnostics;
+}
+function buildPriorityDriftDiagnostics(input) {
+  const priority = input.workflow.tracker.priority;
+  if (!priority || priority.source === "disabled") {
+    return [];
+  }
+  if (priority.source === "project-field") {
+    return buildProjectFieldDriftDiagnostics({
+      priority,
+      projectDetail: input.projectDetail,
+      activeIssues: input.activeIssues
+    });
+  }
+  return buildLabelDriftDiagnostics({
+    priority,
+    repositoryLabels: input.repositoryLabels,
+    activeIssues: input.activeIssues
+  });
+}
+function buildProjectFieldDriftDiagnostics(input) {
+  const diagnostics = [];
+  const field = input.projectDetail.statusFields.find(
+    (candidate) => candidate.name === input.priority.field
+  );
+  if (!field) {
+    diagnostics.push({
+      title: "Priority Project field drift",
+      summary: `Configured priority field "${input.priority.field}" was not found in the GitHub Project schema.`,
+      remediation: "Update tracker.priority.field to the exact live Project V2 single-select field name, or disable priority mapping.",
+      details: {
+        field: input.priority.field,
+        availableFields: input.projectDetail.statusFields.map(
+          (candidate) => candidate.name
+        )
+      }
+    });
+    return diagnostics;
+  }
+  const liveOptions = new Set(field.options.map((option) => option.name));
+  const mappedOptions = new Set(Object.keys(input.priority.values));
+  const unmappedLiveOptions = [...liveOptions].filter(
+    (option) => !mappedOptions.has(option)
+  );
+  const missingConfiguredOptions = [...mappedOptions].filter(
+    (option) => !liveOptions.has(option)
+  );
+  if (unmappedLiveOptions.length > 0) {
+    diagnostics.push({
+      title: "Unmapped priority Project options",
+      summary: `Priority field "${field.name}" has live option(s) not mapped in tracker.priority.values: ${unmappedLiveOptions.join(", ")}.`,
+      remediation: "Add explicit numeric mappings for these options or accept that issues holding them resolve to priority = null.",
+      details: { field: field.name, unmappedLiveOptions }
+    });
+  }
+  if (missingConfiguredOptions.length > 0) {
+    diagnostics.push({
+      title: "Missing priority Project options",
+      summary: `tracker.priority.values references option(s) that do not exist in priority field "${field.name}": ${missingConfiguredOptions.join(", ")}.`,
+      remediation: "Rename the mapping keys to match live Project option display names or remove stale mappings.",
+      details: { field: field.name, missingConfiguredOptions }
+    });
+  }
+  const activeUnmapped = input.activeIssues.flatMap((issue) => {
+    const rawValue = issue.metadata?.[field.name];
+    return typeof rawValue === "string" && rawValue.length > 0 && !mappedOptions.has(rawValue) ? [{ issue: issue.identifier, value: rawValue }] : [];
+  });
+  if (activeUnmapped.length > 0) {
+    diagnostics.push({
+      title: "Active issues with unmapped priority values",
+      summary: `Active issue(s) currently hold unmapped "${field.name}" value(s); they resolve to priority = null.`,
+      remediation: "Map the live value in tracker.priority.values, change the issue value, or leave it unmapped intentionally.",
+      details: { field: field.name, activeUnmapped }
+    });
+  }
+  return diagnostics;
+}
+function buildLabelDriftDiagnostics(input) {
+  const diagnostics = [];
+  const configuredLabels = Object.keys(input.priority.labels);
+  if (input.repositoryLabels) {
+    const missingByRepository = input.repositoryLabels.flatMap((snapshot) => {
+      const live = new Set(snapshot.labels);
+      const missing = configuredLabels.filter((label) => !live.has(label));
+      return missing.length > 0 ? [{ repository: snapshot.repository, missing }] : [];
+    });
+    if (missingByRepository.length > 0) {
+      diagnostics.push({
+        title: "Missing configured priority labels",
+        summary: "One or more configured tracker.priority.labels entries are absent from linked repositories.",
+        remediation: "Create the labels in each linked repository, rename the mapping keys to exact live labels, or remove stale mappings.",
+        details: { missingByRepository }
+      });
+    }
+    const liveLabels = new Set(
+      input.repositoryLabels.flatMap((snapshot) => snapshot.labels)
+    );
+    const missingEverywhere = configuredLabels.filter(
+      (label) => !liveLabels.has(label)
+    );
+    if (missingEverywhere.length > 0) {
+      diagnostics.push({
+        title: "Stale priority label mappings",
+        summary: `tracker.priority.labels references label(s) that do not exist in any linked repository: ${missingEverywhere.join(", ")}.`,
+        remediation: "Rename the mapping keys to exact live labels, create those labels, or remove stale mappings.",
+        details: { missingEverywhere }
+      });
+    }
+  }
+  const configuredLabelByNormalized = new Map(
+    configuredLabels.map((label) => [normalizeLabelForComparison(label), label])
+  );
+  const activeConflicts = input.activeIssues.flatMap((issue) => {
+    const matches = issue.labels.flatMap((label) => {
+      const configuredLabel = configuredLabelByNormalized.get(
+        normalizeLabelForComparison(label)
+      );
+      return configuredLabel ? [configuredLabel] : [];
+    });
+    return matches.length > 1 ? [{ issue: issue.identifier, labels: matches }] : [];
+  });
+  if (activeConflicts.length > 0) {
+    diagnostics.push({
+      title: "Active issues with multiple priority labels",
+      summary: "Active issue(s) have multiple configured priority labels; runtime chooses the lowest numeric value and emits priority.label_conflict_resolved.",
+      remediation: "Remove extra priority labels from the issue if only one priority label should apply.",
+      details: { activeConflicts }
+    });
+  }
+  const activeUnmapped = input.activeIssues.flatMap((issue) => {
+    const labels = issue.labels.filter(
+      (label) => isPriorityLikeLabel(label) && !configuredLabelByNormalized.has(normalizeLabelForComparison(label))
+    );
+    return labels.length > 0 ? [{ issue: issue.identifier, labels }] : [];
+  });
+  if (activeUnmapped.length > 0) {
+    diagnostics.push({
+      title: "Active issues with unmapped priority labels",
+      summary: "Active issue(s) have priority-like labels not mapped by tracker.priority.labels; those labels do not affect dispatch priority.",
+      remediation: "Add explicit mappings for these labels, rename the issue labels, or leave them unmapped intentionally.",
+      details: { activeUnmapped }
+    });
+  }
+  return diagnostics;
+}
+function isPriorityLikeLabel(label) {
+  return /^(p\d+|priority[:/\s_-].+|prio[:/\s_-].+)$/i.test(label.trim());
+}
+function normalizeLabelForComparison(label) {
+  return label.trim().toLowerCase();
+}
+
+// src/commands/workflow.ts
 var SAMPLE_ISSUE = {
   id: "issue-157-sample",
   identifier: "octo/hello-world#157",
@@ -65,7 +248,9 @@ var workflowCommandDependencies = {
   fetchLiveIssue: fetchGithubProjectIssueByRepositoryAndNumber,
   getGitHubProjectDetail: getProjectDetail,
   getGitHubTokenWithSource: getGhTokenWithSource,
+  loadActiveProjectConfig,
   resolveManagedProjectSelection: inspectManagedProjectSelection,
+  resolveTrackerAdapter,
   validateGitHubToken
 };
 function setWorkflowCommandDependenciesForTest(overrides) {
@@ -76,7 +261,9 @@ function resetWorkflowCommandDependenciesForTest() {
   workflowCommandDependencies.fetchLiveIssue = fetchGithubProjectIssueByRepositoryAndNumber;
   workflowCommandDependencies.getGitHubProjectDetail = getProjectDetail;
   workflowCommandDependencies.getGitHubTokenWithSource = getGhTokenWithSource;
+  workflowCommandDependencies.loadActiveProjectConfig = loadActiveProjectConfig;
   workflowCommandDependencies.resolveManagedProjectSelection = inspectManagedProjectSelection;
+  workflowCommandDependencies.resolveTrackerAdapter = resolveTrackerAdapter;
   workflowCommandDependencies.validateGitHubToken = validateGitHubToken;
 }
 function parseWorkflowArgs(args) {
@@ -140,6 +327,9 @@ function parsePreviewFlags(args) {
         if (!value || value.startsWith("-")) {
           throw new Error("Option '--issue' argument missing");
         }
+        if (flags.issue) {
+          throw new Error("Only one preview issue identifier can be provided.");
+        }
         flags.issue = value;
         i += 1;
         break;
@@ -162,6 +352,10 @@ function parsePreviewFlags(args) {
         if (arg?.startsWith("-")) {
           throw new Error(`Unknown option '${arg}'`);
         }
+        if (flags.issue) {
+          throw new Error("Only one preview issue identifier can be provided.");
+        }
+        flags.issue = arg;
         break;
     }
   }
@@ -185,7 +379,9 @@ Commands:
 Options:
   workflow init [--non-interactive] [--project <id>] [--output <path>] [--skip-skills] [--skip-context] [--dry-run]
   workflow validate [--file <path>]
-  workflow preview [--file <path>] [--issue <owner/repo#number>] [--project-id <projectId>] [--sample <json>] [--attempt <n>]
+  workflow preview [issue] [--file <path>] [--issue <owner/repo#number|ENG-123>] [--project-id <projectId>] [--sample <json>] [--attempt <n>]
+
+Linear workflows use polling through the configured tracker adapter. No Linear webhook setup command is provided.
 `);
 }
 async function loadWorkflowMarkdown(workflowPath) {
@@ -399,7 +595,7 @@ function renderIssueWorkflowPreview(input) {
 function formatAuthError(error) {
   return `GitHub authentication is required for live issue preview. ${error.message}`;
 }
-async function loadLiveIssue(issueReference, projectId, options) {
+async function loadLiveIssue(issueReference, projectId, workflow, options) {
   const issue = parseIssueReference(issueReference);
   const selection = await workflowCommandDependencies.resolveManagedProjectSelection({
     configDir: options.configDir,
@@ -453,6 +649,7 @@ async function loadLiveIssue(issueReference, projectId, options) {
       token: auth.token,
       apiUrl: selection.projectConfig.tracker.apiUrl,
       assignedOnly: selection.projectConfig.tracker.settings?.assignedOnly === true,
+      priority: workflow.tracker.priority,
       priorityFieldName: typeof selection.projectConfig.tracker.settings?.priorityFieldName === "string" ? selection.projectConfig.tracker.settings.priorityFieldName : void 0,
       timeoutMs: typeof selection.projectConfig.tracker.settings?.timeoutMs === "number" ? selection.projectConfig.tracker.settings.timeoutMs : void 0
     },
@@ -472,6 +669,58 @@ async function loadLiveIssue(issueReference, projectId, options) {
     sampleSource: `live:${trackedIssue.identifier}`
   };
 }
+var LINEAR_IDENTIFIER_PATTERN = /^[A-Z][A-Z0-9]*-\d+$/;
+function isLinearIssueIdentifier(value) {
+  return LINEAR_IDENTIFIER_PATTERN.test(value.trim().toUpperCase());
+}
+async function loadLinearIssue(issueIdentifier, workflow, options) {
+  const projectConfig = await workflowCommandDependencies.loadActiveProjectConfig(
+    options.configDir
+  );
+  if (!projectConfig?.repository) {
+    throw new Error(
+      "Linear live issue preview requires a repository runtime initialized with 'gh-symphony repo init'."
+    );
+  }
+  const workflowProjectSlug = workflow.tracker.projectSlug?.trim();
+  if (!workflowProjectSlug) {
+    throw new Error(
+      'Linear live issue preview requires WORKFLOW.md field "tracker.project_slug".'
+    );
+  }
+  if (!workflow.tracker.apiKey?.trim()) {
+    throw new Error(
+      'Linear live issue preview requires WORKFLOW.md field "tracker.api_key" to resolve, for example "$LINEAR_API_KEY".'
+    );
+  }
+  if (projectConfig.tracker.adapter !== "linear" || projectConfig.tracker.bindingId !== workflowProjectSlug) {
+    throw new Error(
+      `Linear live issue preview requires an active repository runtime initialized for project "${workflowProjectSlug}". Run 'gh-symphony repo init' from this repository, then re-run the preview.`
+    );
+  }
+  const orchestratorProject = {
+    projectId: projectConfig.projectId,
+    slug: projectConfig.slug,
+    workspaceDir: projectConfig.workspaceDir,
+    repository: projectConfig.repository,
+    tracker: projectConfig.tracker
+  };
+  const trackerAdapter = workflowCommandDependencies.resolveTrackerAdapter(projectConfig.tracker);
+  const [issue] = await trackerAdapter.fetchIssueStatesByIds(
+    orchestratorProject,
+    [issueIdentifier.trim().toUpperCase()],
+    { token: workflow.tracker.apiKey }
+  );
+  if (!issue) {
+    throw new Error(
+      `Linear issue ${issueIdentifier} was not found in project "${workflow.tracker.projectSlug}".`
+    );
+  }
+  return {
+    issue,
+    sampleSource: `live:${issue.identifier}`
+  };
+}
 function validateWorkflow(workflowPath, markdown) {
   const workflow = parseWorkflowMarkdown(markdown);
   const promptFreshVariables = buildPromptVariables(SAMPLE_ISSUE, {
@@ -495,6 +744,7 @@ function validateWorkflow(workflowPath, markdown) {
       promptRetry: "pass",
       continuationGuidance: continuationGuidanceStatus
     },
+    warnings: buildPriorityConfigDiagnostics(workflow),
     summary: {
       trackerKind: workflow.tracker.kind,
       githubProjectId: workflow.githubProjectId,
@@ -565,6 +815,17 @@ Hooks
   before_remove=${report.summary.hooks.beforeRemove ?? "unset"}
   hooks.timeout_ms=${report.summary.hooks.timeoutMs}
 `);
+  if (report.warnings.length > 0) {
+    process.stdout.write("\nWarnings\n");
+    for (const warning of report.warnings) {
+      process.stdout.write(`  ${warning.title}: ${warning.summary}
+`);
+      if (warning.remediation) {
+        process.stdout.write(`    Fix: ${warning.remediation}
+`);
+      }
+    }
+  }
 }
 async function runValidate(args, options) {
   const flags = parseValidateFlags(args);
@@ -586,12 +847,12 @@ async function runPreview(args, options) {
   }
   const { workflowPath, markdown } = await loadWorkflowMarkdown(flags.file);
   const workflow = parseWorkflowMarkdown(markdown);
-  if (flags.issue && workflow.tracker.kind !== "github-project") {
+  if (flags.issue && workflow.tracker.kind !== "github-project" && !(workflow.tracker.kind === "linear" && isLinearIssueIdentifier(flags.issue))) {
     throw new Error(
-      "Live issue preview requires 'tracker.kind: github-project' in WORKFLOW.md."
+      "Live issue preview requires 'tracker.kind: github-project' with owner/repo#number or 'tracker.kind: linear' with a Linear identifier such as ENG-123."
     );
   }
-  const { issue, sampleSource } = flags.issue ? await loadLiveIssue(flags.issue, flags.projectId, options) : await loadSampleIssue(flags.sample);
+  const { issue, sampleSource } = flags.issue ? workflow.tracker.kind === "linear" ? await loadLinearIssue(flags.issue, workflow, options) : await loadLiveIssue(flags.issue, flags.projectId, workflow, options) : await loadSampleIssue(flags.sample);
   const renderedPrompt = renderIssueWorkflowPreview({
     workflow,
     issue,
@@ -662,6 +923,8 @@ var handler = async (args, options) => {
 var workflow_default = handler;
 
 export {
+  buildPriorityConfigDiagnostics,
+  buildPriorityDriftDiagnostics,
   setWorkflowCommandDependenciesForTest,
   resetWorkflowCommandDependenciesForTest,
   parseIssueReference,