triad-plus 1.8.0 → 1.10.0

package/runtime/lib/model-config.mjs

@@ -0,0 +1,165 @@
+import { roleDefinitions } from '../../adapters/registry.mjs';
+
+const roleIds = new Set(roleDefinitions.map((role) => role.id));
+const modelFields = new Set(['model', 'reasoning_effort']);
+
+function nullableString(value, field) {
+  if (value === undefined || value === null) return;
+  if (typeof value !== 'string') throw new Error(`${field} must be a string or null.`);
+}
+
+function adapterModelRoles(adapter) {
+  return new Set(adapter?.modelRoles ?? roleDefinitions.map((role) => role.id));
+}
+
+function defaultSourceForHostField(field) {
+  return field === 'reasoningEffort' ? 'reasoning_effort' : field;
+}
+
+function hostValue(value) {
+  return typeof value === 'string' && !value.trim() ? null : value ?? null;
+}
+
+/**
+ * Return whether the selected host can materialize a model for this role.
+ * A team-record adapter still records the requested value in team.json, but
+ * deliberately returns false because it has no native file to update.
+ */
+export function supportsNativeModel(adapter, roleId) {
+  if (adapter?.modelBinding === 'global-profiles') return roleIds.has(roleId);
+  if (adapter?.modelBinding === 'project-frontmatter') return adapterModelRoles(adapter).has(roleId);
+  return false;
+}
+
+/** Return whether the selected host exposes a native reasoning field. */
+export function supportsNativeReasoning(adapter, roleId) {
+  if (!supportsNativeModel(adapter, roleId)) return false;
+  if (adapter?.modelBinding === 'global-profiles') return true;
+  return modelFieldMappings(adapter, roleId).some(({ source }) => source === 'reasoning_effort');
+}
+
+/**
+ * Describe the one-way mapping from canonical team.json fields to the
+ * host-native fields managed in a role asset. The adapter registry is the
+ * only place that chooses host names; callers never infer them by analogy.
+ */
+export function modelFieldMappings(adapter, roleId) {
+  if (!supportsNativeModel(adapter, roleId) || adapter?.modelBinding !== 'project-frontmatter') return [];
+  const fields = Array.isArray(adapter?.modelFields) && adapter.modelFields.length ? adapter.modelFields : ['model'];
+  const sources = adapter?.modelFieldSources ?? {};
+  return fields.map((field) => ({ field, source: sources[field] ?? defaultSourceForHostField(field) }));
+}
+
+/** Return the host field used for a canonical semantic field, if any. */
+export function hostModelField(adapter, roleId, source) {
+  return modelFieldMappings(adapter, roleId).find((mapping) => mapping.source === source)?.field ?? null;
+}
+
+/**
+ * Describe how a role's requested configuration is handled by the adapter.
+ * This is presentation metadata; team.json remains authoritative in every
+ * mode.
+ */
+export function modelBindingSummary(adapter, roleId) {
+  if (adapter?.modelBinding === 'team-record') return 'recorded in team.json (host-native binding unavailable)';
+  if (!supportsNativeModel(adapter, roleId)) return 'recorded in team.json (role field unsupported by host)';
+  if (supportsNativeReasoning(adapter, roleId)) {
+    // Global profile adapters expose their native effort field through the
+    // profile writer rather than project frontmatter metadata.
+    return `host-native model + ${hostModelField(adapter, roleId, 'reasoning_effort') ?? 'reasoning'}`;
+  }
+  return 'host-native model; reasoning is host-managed';
+}
+
+/**
+ * Validate a complete schema-version-1 team configuration without changing or
+ * stripping fields. Unknown fields remain forward-compatible and are
+ * preserved; malformed model values fail closed before installation/upgrade.
+ */
+export function validateTeamConfiguration(team) {
+  if (!team || typeof team !== 'object' || Array.isArray(team)) throw new Error('team config must be an object.');
+  if (team.schema_version !== 1) throw new Error('team config must contain schema_version 1.');
+  if (!team.interaction || typeof team.interaction !== 'object' || Array.isArray(team.interaction)) {
+    throw new Error('team config must contain interaction.');
+  }
+  if (!team.roles || typeof team.roles !== 'object' || Array.isArray(team.roles)) {
+    throw new Error('team config must contain roles.');
+  }
+  for (const role of roleDefinitions) {
+    const configuration = team.roles[role.id];
+    if (!configuration || typeof configuration !== 'object' || Array.isArray(configuration)) {
+      throw new Error(`team config has an invalid ${role.id} role definition.`);
+    }
+    if (typeof configuration.displayName !== 'string' || !configuration.displayName.trim()) {
+      throw new Error(`team config has an invalid ${role.id} displayName.`);
+    }
+    nullableString(configuration.model, `${role.id}.model`);
+    nullableString(configuration.reasoning_effort, `${role.id}.reasoning_effort`);
+    if (configuration.enabled !== undefined && typeof configuration.enabled !== 'boolean') {
+      throw new Error(`team config has an invalid ${role.id}.enabled value.`);
+    }
+  }
+  return team;
+}
+
+/**
+ * Validate a user-requested native model patch. This intentionally rejects
+ * unknown fields and fields the selected host cannot materialize. Callers
+ * that only want to record intent should use team.json directly and report
+ * the adapter's modelBindingSummary instead of pretending native support.
+ */
+export function validateRequestedModelPatch(adapter, roleId, patch) {
+  if (!roleIds.has(roleId)) throw new Error(`Unknown Triad role: ${roleId}.`);
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('model patch must be an object.');
+  for (const field of Object.keys(patch)) {
+    if (!modelFields.has(field)) throw new Error(`Unsupported model configuration field: ${field}.`);
+    nullableString(patch[field], `${roleId}.${field}`);
+    if (field === 'model' && !supportsNativeModel(adapter, roleId)) {
+      throw new Error(`Model binding is not natively supported for ${adapter?.id ?? 'the selected host'} role ${roleId}.`);
+    }
+    if (field === 'reasoning_effort' && !supportsNativeReasoning(adapter, roleId)) {
+      throw new Error(`Reasoning effort is not natively supported for ${adapter?.id ?? 'the selected host'} role ${roleId}.`);
+    }
+  }
+  return patch;
+}
+
+/**
+ * Apply an explicitly requested model/reasoning patch to an in-memory team
+ * document while preserving every unrelated field. Callers still decide when
+ * to persist the returned document and must use the adapter binding afterwards.
+ */
+export function mergeTeamModelConfiguration(team, roleId, patch) {
+  validateTeamConfiguration(team);
+  if (!roleIds.has(roleId)) throw new Error(`Unknown Triad role: ${roleId}.`);
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('model patch must be an object.');
+  for (const field of Object.keys(patch)) {
+    if (!modelFields.has(field)) throw new Error(`Unsupported model configuration field: ${field}.`);
+    nullableString(patch[field], `${roleId}.${field}`);
+  }
+  const updated = structuredClone(team);
+  Object.assign(updated.roles[roleId], patch);
+  return updated;
+}
+
+/** Return only fields that the adapter can materialize in host-managed assets. */
+export function materializedRoleConfiguration(adapter, roleId, configuration = {}) {
+  const result = {};
+  if (supportsNativeModel(adapter, roleId)) result.model = hostValue(configuration.model);
+  if (supportsNativeReasoning(adapter, roleId)) result.reasoning_effort = hostValue(configuration.reasoning_effort);
+  return result;
+}
+
+/**
+ * Translate canonical semantic values into the exact host fields declared by
+ * the adapter. Null values are retained so the managed writer can remove a
+ * stale host binding and restore the host default.
+ */
+export function materializedHostRoleConfiguration(adapter, roleId, configuration = {}) {
+  const semantic = materializedRoleConfiguration(adapter, roleId, configuration);
+  const result = {};
+  for (const { field, source } of modelFieldMappings(adapter, roleId)) {
+    result[field] = semantic[source] ?? null;
+  }
+  return result;
+}

package/runtime/lib/repository-context.mjs

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { realpath, stat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { runProcess } from "./process.mjs";
+
+const SHA256 = /^[a-f0-9]{64}$/i;
+
+function contextError(message, code = "repository_context_invalid") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function inside(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/**
+ * Required repository skills are deliberately worktree-relative. Reject
+ * absolute paths and parent traversal instead of allowing a caller to combine
+ * files from the control workspace or another repository root.
+ */
+export function repositoryRelativePath(value, label = "repository skill path") {
+  if (typeof value !== "string" || !value.trim()) throw contextError(`${label} must be a non-empty repository-relative path`);
+  const normalized = value.trim().replaceAll("\\", "/");
+  if (path.posix.isAbsolute(normalized) || path.win32.isAbsolute(normalized)) {
+    throw contextError(`${label} must be repository-relative`);
+  }
+  const segments = normalized.split("/");
+  if (segments.includes("..") || segments.includes("")) {
+    throw contextError(`${label} must not contain parent traversal or empty path segments`);
+  }
+  return normalized;
+}
+
+async function gitTopLevel(cwd) {
+  const result = await runProcess("git", ["rev-parse", "--show-toplevel"], { cwd, timeoutMs: 15_000 });
+  if (result.exitCode !== 0) return null;
+  const value = result.stdout.trim();
+  if (!value) return null;
+  return realpath(value).catch(() => path.resolve(value));
+}
+
+async function shellPwd(cwd) {
+  const result = await runProcess("pwd", [], { cwd, timeoutMs: 15_000 });
+  return result.exitCode === 0 ? result.stdout.trim() || null : null;
+}
+
+function issue(code, message, details = {}) {
+  return { code, message, ...details };
+}
+
+/**
+ * Inspect the repository context bound to an assignment. This is intentionally
+ * read-only and host-neutral: it proves the assigned worktree, its Git root,
+ * and every required skill's real path/hash. `checkActualCwd` is used by a
+ * role activation; verifier/packet creation leave it false because they run
+ * from the control workspace and must not mistake that process cwd for the
+ * delegated role cwd.
+ */
+export async function inspectRepositoryContext({
+  worktree,
+  requiredSkills = [],
+  actualCwd = null,
+  checkActualCwd = false
+} = {}) {
+  if (typeof worktree !== "string" || !worktree.trim()) throw contextError("assigned worktree is required");
+  if (!Array.isArray(requiredSkills)) throw contextError("required repository skills must be an array");
+  const assignedWorktree = await realpath(worktree).catch(() => {
+    throw contextError(`assigned worktree is missing: ${worktree}`);
+  });
+  const assignedGitTopLevel = await gitTopLevel(assignedWorktree);
+  const issues = [];
+  if (!assignedGitTopLevel) {
+    issues.push(issue("assigned_repository_not_git", "assigned worktree has no resolvable Git top-level", {
+      assigned_worktree: assignedWorktree
+    }));
+  } else if (assignedGitTopLevel !== assignedWorktree) {
+    issues.push(issue("assigned_worktree_not_repository_root", "assigned worktree is not the repository Git top-level", {
+      assigned_worktree: assignedWorktree,
+      assigned_git_top_level: assignedGitTopLevel
+    }));
+  }
+
+  const skills = [];
+  const seen = new Set();
+  for (const [index, item] of requiredSkills.entries()) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      issues.push(issue("invalid_repository_skill_binding", "repository skill binding must be an object", { index }));
+      continue;
+    }
+    let relative;
+    try { relative = repositoryRelativePath(item.path, `repository skill [${index}] path`); }
+    catch (error) {
+      issues.push(issue("invalid_repository_skill_path", error.message, { index, path: item.path ?? null }));
+      continue;
+    }
+    if (seen.has(relative)) {
+      issues.push(issue("duplicate_repository_skill", `repository skill is declared more than once: ${relative}`, { path: relative }));
+      continue;
+    }
+    seen.add(relative);
+    if (typeof item.sha256 !== "string" || !SHA256.test(item.sha256)) {
+      issues.push(issue("invalid_repository_skill_hash", `repository skill requires a SHA-256 hash: ${relative}`, { path: relative }));
+      continue;
+    }
+    const lexical = path.resolve(assignedWorktree, relative);
+    if (!inside(assignedWorktree, lexical)) {
+      issues.push(issue("repository_skill_outside_worktree", `repository skill escapes assigned worktree: ${relative}`, { path: relative }));
+      continue;
+    }
+    let resolved;
+    try { resolved = await realpath(lexical); }
+    catch {
+      issues.push(issue("repository_skill_missing", `repository skill missing: ${relative}`, { path: relative, resolved_path: lexical }));
+      continue;
+    }
+    if (!inside(assignedWorktree, resolved)) {
+      issues.push(issue("repository_skill_symlink_escape", `repository skill resolves outside assigned worktree: ${relative}`, { path: relative, resolved_path: resolved }));
+      continue;
+    }
+    try {
+      if (!(await stat(resolved)).isFile()) throw new Error("not a regular file");
+    } catch {
+      issues.push(issue("repository_skill_not_file", `repository skill is not a regular file: ${relative}`, { path: relative, resolved_path: resolved }));
+      continue;
+    }
+    const actual = digest(await readFile(resolved));
+    const skillGitTopLevel = await gitTopLevel(path.dirname(resolved));
+    const entry = {
+      path: relative,
+      resolved_path: resolved,
+      sha256: actual,
+      repository_root: skillGitTopLevel
+    };
+    skills.push(entry);
+    if (actual.toLowerCase() !== item.sha256.toLowerCase()) {
+      issues.push(issue("repository_skill_hash_mismatch", `repository skill hash mismatch: ${relative}`, {
+        path: relative,
+        expected_sha256: item.sha256,
+        actual_sha256: actual
+      }));
+    }
+    if (assignedGitTopLevel && skillGitTopLevel !== assignedGitTopLevel) {
+      issues.push(issue("repository_skill_root_mismatch", `repository skill belongs to a different Git root: ${relative}`, {
+        path: relative,
+        skill_repository_root: skillGitTopLevel,
+        assigned_git_top_level: assignedGitTopLevel
+      }));
+    }
+  }
+
+  let actual = null;
+  if (checkActualCwd) {
+    const requested = actualCwd || process.cwd();
+    const resolved = await realpath(requested).catch(() => path.resolve(requested));
+    const gitRoot = await gitTopLevel(resolved);
+    actual = {
+      process_cwd: process.cwd(),
+      shell_pwd: await shellPwd(process.cwd()),
+      resolved_cwd: resolved,
+      git_top_level: gitRoot
+    };
+    if (resolved !== assignedWorktree) {
+      issues.push(issue("runtime_cwd_mismatch", "role process cwd does not match assigned worktree", {
+        expected_worktree: assignedWorktree,
+        actual_cwd: resolved
+      }));
+    }
+    if (assignedGitTopLevel && gitRoot !== assignedGitTopLevel) {
+      issues.push(issue("runtime_git_root_mismatch", "role process Git top-level does not match assigned repository", {
+        expected_git_top_level: assignedGitTopLevel,
+        actual_git_top_level: gitRoot
+      }));
+    }
+  }
+
+  return {
+    status: issues.length ? "blocked" : "pass",
+    assigned_worktree: assignedWorktree,
+    assigned_git_top_level: assignedGitTopLevel,
+    actual,
+    skills,
+    issues
+  };
+}
+
+export { SHA256 };

package/runtime/lib/terminal.mjs

@@ -0,0 +1,86 @@
+import { roleDefinitions } from '../../adapters/registry.mjs';
+import { hostModelField, modelBindingSummary, supportsNativeReasoning } from './model-config.mjs';
+
+const ANSI = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  cyan: '\u001b[36m',
+  blue: '\u001b[34m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  red: '\u001b[31m'
+};
+
+const toneCodes = {
+  title: `${ANSI.bold}${ANSI.cyan}`,
+  section: `${ANSI.bold}${ANSI.blue}`,
+  value: ANSI.bold,
+  success: ANSI.green,
+  warning: ANSI.yellow,
+  error: ANSI.red,
+  hint: ANSI.dim
+};
+
+export function colorEnabled(stream = process.stdout) {
+  return Boolean(stream?.isTTY) && process.env.NO_COLOR === undefined;
+}
+
+export function paint(value, tone, { stream = process.stdout } = {}) {
+  const text = String(value);
+  if (!colorEnabled(stream) || !toneCodes[tone]) return text;
+  return `${toneCodes[tone]}${text}${ANSI.reset}`;
+}
+
+export function statusText(status, { stream = process.stdout } = {}) {
+  const normalized = String(status).toLowerCase();
+  if (['ok', 'pass', 'passed', 'configured', 'installed', 'enabled'].includes(normalized) || /^ok\b/.test(normalized)) return paint(status, 'success', { stream });
+  if (['warning', 'warn', 'disabled', 'not configured', 'not installed', 'unavailable', 'host default'].includes(normalized) || normalized.startsWith('not installed') || normalized.startsWith('host rule detected')) return paint(status, 'warning', { stream });
+  if (['error', 'fail', 'failed', 'invalid', 'incomplete', 'missing'].includes(normalized) || normalized.startsWith('missing ') || normalized.startsWith('invalid ')) return paint(status, 'error', { stream });
+  return String(status);
+}
+
+function display(value, fallback = 'host default') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function roleModelLine(adapter, role, configuration, stream) {
+  const model = display(configuration?.model);
+  const parts = [`${role.label.padEnd(14)} ${display(configuration?.displayName, role.label)} — model: ${model}`];
+  if (supportsNativeReasoning(adapter, role.id)) {
+    const field = hostModelField(adapter, role.id, 'reasoning_effort');
+    parts.push(`${field === 'variant' ? 'variant' : 'reasoning'}: ${display(configuration?.reasoning_effort)}`);
+  }
+  parts.push(`binding: ${modelBindingSummary(adapter, role.id)}`);
+  return `  ${parts.join(' — ')}`;
+}
+
+/** Render the compact confirmation shown before the interactive install. */
+export function formatSetupSummary({ adapter, control, global = false, team, stream = process.stdout }) {
+  const interaction = team?.interaction ?? {};
+  const lines = [
+    paint('Triad+ setup summary', 'title', { stream }),
+    `${paint('Host', 'section', { stream })}: ${paint(`${adapter.label} (${adapter.id})`, 'value', { stream })}`,
+    `${paint('Control workspace', 'section', { stream })}: ${control}`,
+    `${paint('User-level assets', 'section', { stream })}: ${global ? 'yes' : 'no'}`,
+    `${paint('Interaction', 'section', { stream })}: ${display(interaction.language, 'English')} — owner ${display(interaction.owner_name, 'Owner')} — ${display(interaction.communication_style, 'professional and concise')}`,
+    `${paint('Evaluator+', 'section', { stream })}: ${team?.roles?.evaluator?.enabled === true ? statusText('enabled', { stream }) : statusText('disabled', { stream })}`,
+    paint('Roles', 'section', { stream }),
+    ...roleDefinitions.map((role) => roleModelLine(adapter, role, team?.roles?.[role.id], stream)),
+    paint('Confirm installation', 'section', { stream })
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/** Render a doctor row while preserving scanner-friendly plain text. */
+export function formatDoctorLine(label, status, { stream = process.stdout } = {}) {
+  return `${label.padEnd(14)} ${statusText(status, { stream })}`;
+}
+
+export function formatDoctorSection(title, { stream = process.stdout } = {}) {
+  return paint(title, 'section', { stream });
+}
+
+export function formatModelValue(value) {
+  return display(value);
+}

package/runtime/triad-assignment-packet.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeAssignmentPacket } from "./lib/assignment-packet.mjs";
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function usage() {
+  process.stderr.write(`Usage: node .triad-runtime/triad-assignment-packet.mjs --project <control-workspace> --assignment <assignment.json> [--output <packet.md>]\n`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    usage();
+    return;
+  }
+  const project = option(argv, "--project") ?? process.cwd();
+  const assignmentOption = option(argv, "--assignment");
+  if (!assignmentOption) throw Object.assign(new Error("--assignment is required"), { code: "assignment_packet_invalid" });
+  const projectRoot = path.resolve(project);
+  const assignmentPath = path.resolve(projectRoot, assignmentOption);
+  const assignment = JSON.parse(await readFile(assignmentPath, "utf8"));
+  const output = option(argv, "--output");
+  const result = await writeAssignmentPacket(assignment, {
+    projectRoot,
+    assignmentPath,
+    packetPath: output ? path.resolve(projectRoot, output) : null,
+  });
+  process.stdout.write(`${JSON.stringify({
+    status: "ready",
+    assignment: {
+      id: result.assignment.assignment_id,
+      feature_id: result.assignment.feature_id,
+      attempt: result.assignment.attempt,
+    },
+    packet_path: result.assignment.assignment_packet_path,
+    packet_absolute_path: result.packetPath,
+    packet_sha256: result.sha256,
+    dispatch: {
+      cwd: result.context.cwd,
+      control_workspace: result.context.controlWorkspace,
+      repository: result.context.repository,
+      branch: result.context.branch,
+      card_path: result.assignment.card_path,
+      packet_path: result.assignment.assignment_packet_path,
+      mandatory_skill_paths: result.context.requiredSkills.map((skill) => skill.path),
+    },
+  })}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.code ? `${error.code}: ` : ""}${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/runtime/triad-bmad-intake.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { access } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const runtimeDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+async function loadIntegration() {
+  const candidates = [
+    path.join(runtimeDirectory, 'integrations', 'bmad', 'epics-parser.mjs'),
+    path.resolve(runtimeDirectory, '..', 'integrations', 'bmad', 'epics-parser.mjs')
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return import(pathToFileURL(candidate).href);
+    } catch {}
+  }
+  throw new Error('BMAD native intake assets are not installed');
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function repeated(argv, name) {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== name) continue;
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value`);
+    values.push(value);
+    index += 1;
+  }
+  return values;
+}
+
+function usage() {
+  process.stderr.write(`Native BMAD epics.md intake (integration/automation API)
+
+Usage:
+  node .triad-runtime/triad-bmad-intake.mjs --source <epics.md>
+  node .triad-runtime/triad-bmad-intake.mjs --source <epics.md> --project <control> --output <features-dir> [--repository <id>] [--required-gate <story-id>=<gate-id>] [--depends-on <story-id>=<card-id>]
+
+Without --output the command performs read-only ingestion and prints canonical
+Stories. With --output it resolves Triad execution readiness and writes normal
+Cards plus integration-side provenance. This command is an internal
+deterministic primitive; the normal user entry point is the host's /triad
+workflow with the epics.md path.
+`);
+}
+
+function keyed(values, label) {
+  const result = {};
+  for (const value of values) {
+    const separator = value.indexOf('=');
+    if (separator <= 0 || separator === value.length - 1) throw new Error(`${label} must use STORY-ID=VALUE`);
+    const storyId = value.slice(0, separator).trim();
+    const item = value.slice(separator + 1).trim();
+    if (!storyId || !item) throw new Error(`${label} must use STORY-ID=VALUE`);
+    (result[storyId] ??= []).push(item);
+  }
+  return result;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    usage();
+    return;
+  }
+  const source = option(argv, '--source');
+  if (!source) throw new Error('--source is required');
+  const output = option(argv, '--output');
+  const project = option(argv, '--project');
+  const repository = option(argv, '--repository');
+  const requiredGatesByStory = keyed(repeated(argv, '--required-gate'), '--required-gate');
+  const dependsOnByStory = keyed(repeated(argv, '--depends-on'), '--depends-on');
+  const { ingestBmadEpics, writeImportedEpics } = await loadIntegration();
+  if (output && !project) throw new Error('--project is required when --output is supplied');
+  const options = {
+    sourcePath: source,
+    projectRoot: project,
+    targetRepository: repository,
+    requiredGatesByStory,
+    dependsOnByStory
+  };
+  if (output) {
+    const result = await writeImportedEpics({ ...options, outputDirectory: output });
+    process.stdout.write(`${JSON.stringify({
+      status: 'ready',
+      source_kind: result.source_kind,
+      source_path: result.source_path,
+      source_sha256: result.source_sha256,
+      epic_count: result.epics.length,
+      story_count: result.stories.length,
+      card_count: result.outputs.length,
+      cards: result.outputs.map(({ story, cardPath, provenancePath, provenance }) => ({
+        story_id: story.id,
+        epic_id: story.epicId,
+        card_path: cardPath,
+        provenance_path: provenancePath,
+        card_sha256: provenance.card_sha256
+      }))
+    })}\n`);
+    return;
+  }
+  const result = await ingestBmadEpics(options);
+  process.stdout.write(`${JSON.stringify({
+    status: 'ingested',
+    source_kind: result.source_kind,
+    source_path: result.source_path,
+    source_sha256: result.source_sha256,
+    epic_count: result.epics.length,
+    story_count: result.stories.length,
+    stories: result.stories.map((story) => ({
+      epic_id: story.epicId,
+      epic_title: story.epicTitle,
+      story_id: story.id,
+      title: story.title,
+      status: story.status,
+      ingestion_ready: story.ingestionReady,
+      execution_ready: story.executionReady,
+      source_heading: story.sourceHeading,
+      source_range: story.sourceRange
+    }))
+  })}\n`);
+}
+
+// `mktemp`/system temporary roots on macOS are commonly reached through the
+// `/var` -> `/private/var` symlink.  Compare canonical paths so the installed
+// runtime CLI still runs when invoked from such a control workspace.
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main().catch((error) => {
+    process.stderr.write(`${error.code ? `${error.code}: ` : ''}${error.message}\n`);
+    process.exitCode = 2;
+  });
+}