@specforge/cli 0.1.0

package/dist/cli/config/agent-teams.types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Agent Teams Configuration Types — Claude Code specific
+ *
+ * Defines interfaces for the Agent Teams integration sections
+ * of the .specforge/config.json configuration file. These extend the
+ * existing ProjectConfig without breaking backward compatibility.
+ *
+ * Agent Teams is the Claude Code-specific orchestration layer that uses
+ * Claude Code primitives (TeamCreate, TaskCreate, SendMessage, etc.)
+ * to coordinate parallel ticket implementation.
+ *
+ * @see specforge-agent-teams-spec.md (v2.0.0)
+ */
+import type { ProjectConfig } from './types.js';
+/**
+ * Execution strategy for Agent Teams (Claude Code specific).
+ *
+ * - `auto`     – Analyzer picks based on spec structure (default)
+ * - `single`   – Sequential, one worker at a time (<=3 tickets, no epic deps)
+ * - `parallel` – All epic teams run concurrently (independent epics)
+ * - `phased`   – Epics run in dependency-ordered phases (cross-epic deps)
+ *
+ * @see specforge-agent-teams-spec.md Section 4.3
+ */
+export type AgentTeamsStrategy = 'auto' | 'single' | 'parallel' | 'phased';
+/**
+ * Currently active specification for Agent Teams implementation (Claude Code specific).
+ *
+ * Set automatically by `specforge spec activate`. Tells the Agent Teams Lead
+ * which specification to work on at startup.
+ *
+ * @see specforge-agent-teams-spec.md Section 4.2 (LOAD step)
+ */
+export interface ActiveSpecification {
+    /** SpecForge specification UUID */
+    id: string;
+    /** Human-readable spec title (for display) */
+    title: string;
+    /**
+     * ISO 8601 timestamp of activation.
+     * Set automatically by `specforge spec activate`.
+     */
+    activatedAt: string;
+}
+/**
+ * Agent Teams execution settings (Claude Code specific).
+ *
+ * Controls how Agent Teams orchestrate spec implementation.
+ * All fields are optional — sensible defaults are applied.
+ *
+ * v2.0.0 simplified to 6 fields. Previous fields (maxTokensPerWorker,
+ * branchPattern, autoValidate, validationCommands, escalationPolicy,
+ * monorepo) are ignored on read and stripped on write.
+ *
+ * @see specforge-agent-teams-spec.md Section 9.1
+ */
+export interface AgentTeamsConfig {
+    /**
+     * Master toggle for Agent Teams.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Execution strategy selection.
+     * @default "auto"
+     */
+    strategy?: AgentTeamsStrategy;
+    /**
+     * Maximum tickets assigned to a single team (1-20).
+     * @default 10
+     */
+    maxTicketsPerTeam?: number;
+    /**
+     * Maximum number of epics running in parallel (1-10).
+     * @default 3
+     */
+    maxParallelEpics?: number;
+    /**
+     * Git branch naming prefix.
+     * @default "ticket/"
+     */
+    branchPrefix?: string;
+    /**
+     * Per-worker timeout in minutes (5-60).
+     * @default 15
+     */
+    timeoutMinutes?: number;
+}
+/**
+ * Extended .specforge/config.json configuration with Agent Teams support.
+ *
+ * Extends the existing {@link ProjectConfig} with optional sections
+ * for Agent Teams integration (Claude Code specific). All new fields
+ * are optional to maintain full backward compatibility.
+ */
+export interface SpecforgeJsonConfig extends ProjectConfig {
+    /** Currently active specification for implementation (Agent Teams) */
+    activeSpecification?: ActiveSpecification;
+    /** Agent Teams execution settings (Claude Code specific) */
+    agentTeams?: AgentTeamsConfig;
+}
+/**
+ * Default values for AgentTeamsConfig fields (v2.0.0).
+ *
+ * @see specforge-agent-teams-spec.md Section 9.1
+ */
+export declare const AGENT_TEAMS_DEFAULTS: {
+    readonly enabled: false;
+    readonly strategy: AgentTeamsStrategy;
+    readonly maxTicketsPerTeam: 10;
+    readonly maxParallelEpics: 3;
+    readonly branchPrefix: "ticket/";
+    readonly timeoutMinutes: 15;
+};
+/**
+ * Fields that existed pre-v2.0.0 and should be stripped on config write.
+ * These are silently ignored on read for backward compatibility.
+ */
+export declare const DEPRECATED_AGENT_TEAMS_FIELDS: readonly ["maxParallelTeams", "maxTokensPerWorker", "branchPattern", "autoValidate", "validationCommands", "escalationPolicy", "maxWorkersPerTeam", "monorepo"];
+//# sourceMappingURL=agent-teams.types.d.ts.map

package/dist/cli/config/agent-teams.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-teams.types.d.ts","sourceRoot":"","sources":["../../../src/cli/config/agent-teams.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAM3E;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IAEX,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAE9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAE1C,4DAA4D;IAC5D,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAMD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;uBAEX,kBAAkB;;;;;CAK9B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,6BAA6B,iKAShC,CAAC"}

package/dist/cli/config/agent-teams.types.js

@@ -0,0 +1,23 @@
+const AGENT_TEAMS_DEFAULTS = {
+  enabled: false,
+  strategy: "auto",
+  maxTicketsPerTeam: 10,
+  maxParallelEpics: 3,
+  branchPrefix: "ticket/",
+  timeoutMinutes: 15
+};
+const DEPRECATED_AGENT_TEAMS_FIELDS = [
+  "maxParallelTeams",
+  "maxTokensPerWorker",
+  "branchPattern",
+  "autoValidate",
+  "validationCommands",
+  "escalationPolicy",
+  "maxWorkersPerTeam",
+  "monorepo"
+];
+export {
+  AGENT_TEAMS_DEFAULTS,
+  DEPRECATED_AGENT_TEAMS_FIELDS
+};
+//# sourceMappingURL=agent-teams.types.js.map

package/dist/cli/config/agent-teams.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/config/agent-teams.types.ts"],"sourcesContent":["/**\n * Agent Teams Configuration Types — Claude Code specific\n *\n * Defines interfaces for the Agent Teams integration sections\n * of the .specforge/config.json configuration file. These extend the\n * existing ProjectConfig without breaking backward compatibility.\n *\n * Agent Teams is the Claude Code-specific orchestration layer that uses\n * Claude Code primitives (TeamCreate, TaskCreate, SendMessage, etc.)\n * to coordinate parallel ticket implementation.\n *\n * @see specforge-agent-teams-spec.md (v2.0.0)\n */\n\nimport type { ProjectConfig } from './types.js';\n\n// ---------------------------------------------------------------------------\n// Literal union types\n// ---------------------------------------------------------------------------\n\n/**\n * Execution strategy for Agent Teams (Claude Code specific).\n *\n * - `auto`     – Analyzer picks based on spec structure (default)\n * - `single`   – Sequential, one worker at a time (<=3 tickets, no epic deps)\n * - `parallel` – All epic teams run concurrently (independent epics)\n * - `phased`   – Epics run in dependency-ordered phases (cross-epic deps)\n *\n * @see specforge-agent-teams-spec.md Section 4.3\n */\nexport type AgentTeamsStrategy = 'auto' | 'single' | 'parallel' | 'phased';\n\n// ---------------------------------------------------------------------------\n// ActiveSpecification\n// ---------------------------------------------------------------------------\n\n/**\n * Currently active specification for Agent Teams implementation (Claude Code specific).\n *\n * Set automatically by `specforge spec activate`. Tells the Agent Teams Lead\n * which specification to work on at startup.\n *\n * @see specforge-agent-teams-spec.md Section 4.2 (LOAD step)\n */\nexport interface ActiveSpecification {\n  /** SpecForge specification UUID */\n  id: string;\n\n  /** Human-readable spec title (for display) */\n  title: string;\n\n  /**\n   * ISO 8601 timestamp of activation.\n   * Set automatically by `specforge spec activate`.\n   */\n  activatedAt: string;\n}\n\n// ---------------------------------------------------------------------------\n// AgentTeamsConfig (v2.0.0)\n// ---------------------------------------------------------------------------\n\n/**\n * Agent Teams execution settings (Claude Code specific).\n *\n * Controls how Agent Teams orchestrate spec implementation.\n * All fields are optional — sensible defaults are applied.\n *\n * v2.0.0 simplified to 6 fields. Previous fields (maxTokensPerWorker,\n * branchPattern, autoValidate, validationCommands, escalationPolicy,\n * monorepo) are ignored on read and stripped on write.\n *\n * @see specforge-agent-teams-spec.md Section 9.1\n */\nexport interface AgentTeamsConfig {\n  /**\n   * Master toggle for Agent Teams.\n   * @default false\n   */\n  enabled?: boolean;\n\n  /**\n   * Execution strategy selection.\n   * @default \"auto\"\n   */\n  strategy?: AgentTeamsStrategy;\n\n  /**\n   * Maximum tickets assigned to a single team (1-20).\n   * @default 10\n   */\n  maxTicketsPerTeam?: number;\n\n  /**\n   * Maximum number of epics running in parallel (1-10).\n   * @default 3\n   */\n  maxParallelEpics?: number;\n\n  /**\n   * Git branch naming prefix.\n   * @default \"ticket/\"\n   */\n  branchPrefix?: string;\n\n  /**\n   * Per-worker timeout in minutes (5-60).\n   * @default 15\n   */\n  timeoutMinutes?: number;\n}\n\n// ---------------------------------------------------------------------------\n// Extended .specforge/config.json\n// ---------------------------------------------------------------------------\n\n/**\n * Extended .specforge/config.json configuration with Agent Teams support.\n *\n * Extends the existing {@link ProjectConfig} with optional sections\n * for Agent Teams integration (Claude Code specific). All new fields\n * are optional to maintain full backward compatibility.\n */\nexport interface SpecforgeJsonConfig extends ProjectConfig {\n  /** Currently active specification for implementation (Agent Teams) */\n  activeSpecification?: ActiveSpecification;\n\n  /** Agent Teams execution settings (Claude Code specific) */\n  agentTeams?: AgentTeamsConfig;\n}\n\n// ---------------------------------------------------------------------------\n// Defaults (v2.0.0)\n// ---------------------------------------------------------------------------\n\n/**\n * Default values for AgentTeamsConfig fields (v2.0.0).\n *\n * @see specforge-agent-teams-spec.md Section 9.1\n */\nexport const AGENT_TEAMS_DEFAULTS = {\n  enabled: false,\n  strategy: 'auto' as AgentTeamsStrategy,\n  maxTicketsPerTeam: 10,\n  maxParallelEpics: 3,\n  branchPrefix: 'ticket/',\n  timeoutMinutes: 15,\n} as const;\n\n/**\n * Fields that existed pre-v2.0.0 and should be stripped on config write.\n * These are silently ignored on read for backward compatibility.\n */\nexport const DEPRECATED_AGENT_TEAMS_FIELDS = [\n  'maxParallelTeams',\n  'maxTokensPerWorker',\n  'branchPattern',\n  'autoValidate',\n  'validationCommands',\n  'escalationPolicy',\n  'maxWorkersPerTeam',\n  'monorepo',\n] as const;\n"],"mappings":"AA4IO,MAAM,uBAAuB;AAAA,EAClC,SAAS;AAAA,EACT,UAAU;AAAA,EACV,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,cAAc;AAAA,EACd,gBAAgB;AAClB;AAMO,MAAM,gCAAgC;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}

package/dist/cli/config/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI Configuration Module
+ *
+ * Provides configuration loading, writing, and path resolution
+ * for the SpecForge CLI.
+ */
+export * from './types.js';
+export * from './agent-teams.types.js';
+export * from './validation.js';
+export * from './paths.js';
+export * from './loader.js';
+export * from './writer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/config/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/cli/config/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./agent-teams.types.js";
+export * from "./validation.js";
+export * from "./paths.js";
+export * from "./loader.js";
+export * from "./writer.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/config/index.ts"],"sourcesContent":["/**\n * CLI Configuration Module\n *\n * Provides configuration loading, writing, and path resolution\n * for the SpecForge CLI.\n */\n\nexport * from './types.js';\nexport * from './agent-teams.types.js';\nexport * from './validation.js';\nexport * from './paths.js';\nexport * from './loader.js';\nexport * from './writer.js';\n"],"mappings":"AAOA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/cli/config/loader.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Config Loader
+ *
+ * Loads and merges configuration from multiple sources with the following priority:
+ * 1. Environment variables (highest)
+ * 2. Project config (.specforge/config.json)
+ * 3. Global config (~/.specforge/config.json)
+ * 4. Default values (lowest)
+ *
+ * Project config is a pure read: no migration, no best-effort writes, no
+ * deprecation shims. The loader throws a {@link ConfigError} when the config
+ * is missing or when a legacy `.specforge.json` is detected.
+ */
+import { GlobalConfig, ResolvedConfig } from './types.js';
+import type { SpecforgeJsonConfig, ActiveSpecification, AgentTeamsConfig } from './agent-teams.types.js';
+/**
+ * AgentTeamsConfig with all defaults applied (all fields required).
+ *
+ * Claude Code Agent Teams only. Not used by MCP tool handlers.
+ */
+export type ResolvedAgentTeamsConfig = Required<AgentTeamsConfig>;
+/**
+ * Structured error thrown by {@link loadProjectConfig}.
+ *
+ * `CONFIG_MISSING`         — neither new nor legacy config exists
+ * `LEGACY_CONFIG_DETECTED` — only the legacy `.specforge.json` exists
+ */
+export type ConfigErrorCode = 'CONFIG_MISSING' | 'LEGACY_CONFIG_DETECTED';
+export declare class ConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    constructor(code: ConfigErrorCode, message: string);
+}
+/**
+ * Load global configuration from ~/.specforge/config.json
+ *
+ * @returns GlobalConfig object (empty object if file doesn't exist or is invalid)
+ */
+export declare function loadGlobalConfig(): GlobalConfig;
+/**
+ * Load project configuration from .specforge/config.json.
+ *
+ * Pure read: performs no filesystem writes under any code path.
+ *
+ * @throws {ConfigError} `LEGACY_CONFIG_DETECTED` when only `.specforge.json` exists
+ * @throws {ConfigError} `CONFIG_MISSING` when neither new nor legacy config exists
+ * @throws {Error} when the config file exists but cannot be parsed as a JSON object
+ */
+export declare function loadProjectConfig(): SpecforgeJsonConfig;
+/**
+ * Tolerant wrapper around {@link loadProjectConfig}.
+ *
+ * Returns `null` when the project config is missing (no file at all), which
+ * is a valid state for commands like `login` or `init` that can run outside
+ * a configured project. Rethrows `LEGACY_CONFIG_DETECTED` so legacy files
+ * keep surfacing the breaking-change notice on every operation.
+ */
+export declare function tryLoadProjectConfig(): SpecforgeJsonConfig | null;
+/**
+ * Resolve final configuration from all sources
+ *
+ * Merges configuration with the following priority (highest to lowest):
+ * 1. Environment variables
+ * 2. Project config (.specforge/config.json)
+ * 3. Global config (~/.specforge/config.json)
+ * 4. Default values
+ *
+ * @returns ResolvedConfig with all values and source tracking
+ */
+export declare function resolveConfig(): ResolvedConfig;
+/**
+ * Check if user is authenticated (has API key configured)
+ *
+ * @returns true if API key is available from any source
+ */
+export declare function isAuthenticated(): boolean;
+/**
+ * Get API key if available
+ *
+ * @returns API key string or null if not configured
+ */
+export declare function getApiKey(): string | null;
+/**
+ * Check if running in a project context
+ *
+ * @returns true if a valid project config was found (legacy files rethrow)
+ */
+export declare function hasProjectContext(): boolean;
+/**
+ * Get current project ID if available
+ */
+export declare function getProjectId(): string | null;
+/**
+ * Get current specification ID if available
+ */
+export declare function getSpecificationId(): string | null;
+/**
+ * Get Agent Teams config with defaults merged (v2.0.0).
+ *
+ * Claude Code Agent Teams only. Not used by MCP tool handlers.
+ *
+ * Always returns a fully-resolved config object — never null.
+ * Partial configs are merged with defaults via spread operator.
+ *
+ * @param config - Parsed project config (or null for all defaults)
+ * @returns Resolved Agent Teams config with all defaults applied
+ */
+export declare function getAgentTeamsConfig(config: SpecforgeJsonConfig | null): ResolvedAgentTeamsConfig;
+/**
+ * Get the active specification from config.
+ *
+ * Claude Code Agent Teams only. Not used by MCP tool handlers.
+ */
+export declare function getActiveSpecification(config: SpecforgeJsonConfig | null): ActiveSpecification | null;
+//# sourceMappingURL=loader.d.ts.map

package/dist/cli/config/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/cli/config/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,YAAY,EACZ,cAAc,EAMf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAahC;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,wBAAwB,CAAC;AAE1E,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBAEnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,CAyB/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAqCvD;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,GAAG,IAAI,CASjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,IAAI,cAAc,CAyE9C;AASD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAG5C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAGlD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,GAAG,wBAAwB,CAUhG;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,GAAG,mBAAmB,GAAG,IAAI,CAErG"}

package/dist/cli/config/loader.js

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import {
+  CONFIG_DEFAULTS,
+  CONFIG_ENV_VARS,
+  CONFIG_FILES
+} from "./types.js";
+import {
+  AGENT_TEAMS_DEFAULTS
+} from "./agent-teams.types.js";
+import {
+  getGlobalConfigPath,
+  findProjectConfigPath
+} from "./paths.js";
+import {
+  validateSpecforgeJson,
+  formatValidationErrors
+} from "./validation.js";
+class ConfigError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ConfigError";
+    this.code = code;
+  }
+}
+function loadGlobalConfig() {
+  const configPath = getGlobalConfigPath();
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.warn(`Warning: ${configPath} is not a valid config object`);
+      return {};
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      console.warn(`Warning: Failed to parse ${configPath} - invalid JSON`);
+    } else {
+      console.warn(`Warning: Failed to read ${configPath}`);
+    }
+    return {};
+  }
+}
+function loadProjectConfig() {
+  const configPath = findProjectConfigPath();
+  if (!configPath) {
+    throw new ConfigError(
+      "CONFIG_MISSING",
+      "No SpecForge config found. Run `specforge init` to initialize this project."
+    );
+  }
+  if (configPath.endsWith(CONFIG_FILES.LEGACY_PROJECT_CONFIG)) {
+    throw new ConfigError(
+      "LEGACY_CONFIG_DETECTED",
+      "Legacy .specforge.json detected. Run `specforge init` to upgrade to the new .specforge/config.json layout. This is a one-time breaking change for the first production release."
+    );
+  }
+  const content = fs.readFileSync(configPath, "utf-8");
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON in ${configPath}: ${detail}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${configPath} is not a valid config object`);
+  }
+  const validation = validateSpecforgeJson(parsed);
+  if (!validation.valid) {
+    const lines = formatValidationErrors(validation.errors);
+    console.warn(`Warning: Invalid config in ${configPath}:
+${lines.join("\n")}`);
+  }
+  return parsed;
+}
+function tryLoadProjectConfig() {
+  try {
+    return loadProjectConfig();
+  } catch (error) {
+    if (error instanceof ConfigError && error.code === "CONFIG_MISSING") {
+      return null;
+    }
+    throw error;
+  }
+}
+function resolveConfig() {
+  const globalConfig = loadGlobalConfig();
+  const projectConfig = tryLoadProjectConfig();
+  const sources = {
+    apiKey: null,
+    projectId: null,
+    specificationId: null,
+    mcpOutputFormat: "default"
+  };
+  const resolved = {
+    apiKey: null,
+    apiUrl: CONFIG_DEFAULTS.apiUrl,
+    mcpOutputFormat: CONFIG_DEFAULTS.mcpOutputFormat,
+    projectId: null,
+    specificationId: null,
+    autoSetContext: CONFIG_DEFAULTS.autoSetContext,
+    debug: CONFIG_DEFAULTS.debug,
+    sources
+  };
+  if (process.env[CONFIG_ENV_VARS.API_KEY]) {
+    resolved.apiKey = process.env[CONFIG_ENV_VARS.API_KEY];
+    sources.apiKey = "env";
+  } else if (globalConfig.apiKey) {
+    resolved.apiKey = globalConfig.apiKey;
+    sources.apiKey = "global";
+  }
+  if (process.env[CONFIG_ENV_VARS.API_URL]) {
+    resolved.apiUrl = process.env[CONFIG_ENV_VARS.API_URL];
+  }
+  resolved.debug = process.env[CONFIG_ENV_VARS.DEBUG] === "true";
+  const envFormat = process.env[CONFIG_ENV_VARS.MCP_OUTPUT_FORMAT];
+  if (envFormat && isValidFormat(envFormat)) {
+    resolved.mcpOutputFormat = envFormat;
+    sources.mcpOutputFormat = "env";
+  } else if (projectConfig?.mcpOutputFormat && isValidFormat(projectConfig.mcpOutputFormat)) {
+    resolved.mcpOutputFormat = projectConfig.mcpOutputFormat;
+    sources.mcpOutputFormat = "project";
+  } else if (globalConfig.mcpOutputFormat && isValidFormat(globalConfig.mcpOutputFormat)) {
+    resolved.mcpOutputFormat = globalConfig.mcpOutputFormat;
+    sources.mcpOutputFormat = "global";
+  }
+  if (projectConfig?.projectId) {
+    resolved.projectId = projectConfig.projectId;
+    sources.projectId = "project";
+  } else if (globalConfig.defaultProjectId) {
+    resolved.projectId = globalConfig.defaultProjectId;
+    sources.projectId = "global";
+  }
+  if (projectConfig?.specificationId) {
+    resolved.specificationId = projectConfig.specificationId;
+    sources.specificationId = "project";
+  }
+  if (projectConfig?.autoSetContext !== void 0) {
+    resolved.autoSetContext = projectConfig.autoSetContext;
+  }
+  return resolved;
+}
+function isValidFormat(format) {
+  return format === "json" || format === "toon";
+}
+function isAuthenticated() {
+  const config = resolveConfig();
+  return config.apiKey !== null;
+}
+function getApiKey() {
+  const config = resolveConfig();
+  return config.apiKey;
+}
+function hasProjectContext() {
+  return tryLoadProjectConfig() !== null;
+}
+function getProjectId() {
+  const config = resolveConfig();
+  return config.projectId;
+}
+function getSpecificationId() {
+  const config = resolveConfig();
+  return config.specificationId;
+}
+function getAgentTeamsConfig(config) {
+  const partial = config?.agentTeams;
+  return {
+    enabled: partial?.enabled ?? AGENT_TEAMS_DEFAULTS.enabled,
+    strategy: partial?.strategy ?? AGENT_TEAMS_DEFAULTS.strategy,
+    maxTicketsPerTeam: partial?.maxTicketsPerTeam ?? AGENT_TEAMS_DEFAULTS.maxTicketsPerTeam,
+    maxParallelEpics: partial?.maxParallelEpics ?? AGENT_TEAMS_DEFAULTS.maxParallelEpics,
+    branchPrefix: partial?.branchPrefix ?? AGENT_TEAMS_DEFAULTS.branchPrefix,
+    timeoutMinutes: partial?.timeoutMinutes ?? AGENT_TEAMS_DEFAULTS.timeoutMinutes
+  };
+}
+function getActiveSpecification(config) {
+  return config?.activeSpecification ?? null;
+}
+export {
+  ConfigError,
+  getActiveSpecification,
+  getAgentTeamsConfig,
+  getApiKey,
+  getProjectId,
+  getSpecificationId,
+  hasProjectContext,
+  isAuthenticated,
+  loadGlobalConfig,
+  loadProjectConfig,
+  resolveConfig,
+  tryLoadProjectConfig
+};
+//# sourceMappingURL=loader.js.map

package/dist/cli/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/config/loader.ts"],"sourcesContent":["/**\n * Config Loader\n *\n * Loads and merges configuration from multiple sources with the following priority:\n * 1. Environment variables (highest)\n * 2. Project config (.specforge/config.json)\n * 3. Global config (~/.specforge/config.json)\n * 4. Default values (lowest)\n *\n * Project config is a pure read: no migration, no best-effort writes, no\n * deprecation shims. The loader throws a {@link ConfigError} when the config\n * is missing or when a legacy `.specforge.json` is detected.\n */\n\nimport fs from 'node:fs';\nimport {\n  GlobalConfig,\n  ResolvedConfig,\n  ConfigSources,\n  OutputFormat,\n  CONFIG_DEFAULTS,\n  CONFIG_ENV_VARS,\n  CONFIG_FILES,\n} from './types.js';\nimport type {\n  SpecforgeJsonConfig,\n  ActiveSpecification,\n  AgentTeamsConfig,\n} from './agent-teams.types.js';\nimport {\n  AGENT_TEAMS_DEFAULTS,\n} from './agent-teams.types.js';\nimport {\n  getGlobalConfigPath,\n  findProjectConfigPath,\n} from './paths.js';\nimport {\n  validateSpecforgeJson,\n  formatValidationErrors,\n} from './validation.js';\n\n/**\n * AgentTeamsConfig with all defaults applied (all fields required).\n *\n * Claude Code Agent Teams only. Not used by MCP tool handlers.\n */\nexport type ResolvedAgentTeamsConfig = Required<AgentTeamsConfig>;\n\n/**\n * Structured error thrown by {@link loadProjectConfig}.\n *\n * `CONFIG_MISSING`         — neither new nor legacy config exists\n * `LEGACY_CONFIG_DETECTED` — only the legacy `.specforge.json` exists\n */\nexport type ConfigErrorCode = 'CONFIG_MISSING' | 'LEGACY_CONFIG_DETECTED';\n\nexport class ConfigError extends Error {\n  readonly code: ConfigErrorCode;\n\n  constructor(code: ConfigErrorCode, message: string) {\n    super(message);\n    this.name = 'ConfigError';\n    this.code = code;\n  }\n}\n\n/**\n * Load global configuration from ~/.specforge/config.json\n *\n * @returns GlobalConfig object (empty object if file doesn't exist or is invalid)\n */\nexport function loadGlobalConfig(): GlobalConfig {\n  const configPath = getGlobalConfigPath();\n\n  if (!fs.existsSync(configPath)) {\n    return {};\n  }\n\n  try {\n    const content = fs.readFileSync(configPath, 'utf-8');\n    const parsed = JSON.parse(content);\n\n    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n      console.warn(`Warning: ${configPath} is not a valid config object`);\n      return {};\n    }\n\n    return parsed as GlobalConfig;\n  } catch (error) {\n    if (error instanceof SyntaxError) {\n      console.warn(`Warning: Failed to parse ${configPath} - invalid JSON`);\n    } else {\n      console.warn(`Warning: Failed to read ${configPath}`);\n    }\n    return {};\n  }\n}\n\n/**\n * Load project configuration from .specforge/config.json.\n *\n * Pure read: performs no filesystem writes under any code path.\n *\n * @throws {ConfigError} `LEGACY_CONFIG_DETECTED` when only `.specforge.json` exists\n * @throws {ConfigError} `CONFIG_MISSING` when neither new nor legacy config exists\n * @throws {Error} when the config file exists but cannot be parsed as a JSON object\n */\nexport function loadProjectConfig(): SpecforgeJsonConfig {\n  const configPath = findProjectConfigPath();\n\n  if (!configPath) {\n    throw new ConfigError(\n      'CONFIG_MISSING',\n      'No SpecForge config found. Run `specforge init` to initialize this project.'\n    );\n  }\n\n  if (configPath.endsWith(CONFIG_FILES.LEGACY_PROJECT_CONFIG)) {\n    throw new ConfigError(\n      'LEGACY_CONFIG_DETECTED',\n      'Legacy .specforge.json detected. Run `specforge init` to upgrade to the new .specforge/config.json layout. This is a one-time breaking change for the first production release.'\n    );\n  }\n\n  const content = fs.readFileSync(configPath, 'utf-8');\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(content);\n  } catch (error) {\n    const detail = error instanceof Error ? error.message : String(error);\n    throw new Error(`Invalid JSON in ${configPath}: ${detail}`);\n  }\n\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    throw new Error(`${configPath} is not a valid config object`);\n  }\n\n  const validation = validateSpecforgeJson(parsed);\n  if (!validation.valid) {\n    const lines = formatValidationErrors(validation.errors);\n    console.warn(`Warning: Invalid config in ${configPath}:\\n${lines.join('\\n')}`);\n  }\n\n  return parsed as SpecforgeJsonConfig;\n}\n\n/**\n * Tolerant wrapper around {@link loadProjectConfig}.\n *\n * Returns `null` when the project config is missing (no file at all), which\n * is a valid state for commands like `login` or `init` that can run outside\n * a configured project. Rethrows `LEGACY_CONFIG_DETECTED` so legacy files\n * keep surfacing the breaking-change notice on every operation.\n */\nexport function tryLoadProjectConfig(): SpecforgeJsonConfig | null {\n  try {\n    return loadProjectConfig();\n  } catch (error) {\n    if (error instanceof ConfigError && error.code === 'CONFIG_MISSING') {\n      return null;\n    }\n    throw error;\n  }\n}\n\n/**\n * Resolve final configuration from all sources\n *\n * Merges configuration with the following priority (highest to lowest):\n * 1. Environment variables\n * 2. Project config (.specforge/config.json)\n * 3. Global config (~/.specforge/config.json)\n * 4. Default values\n *\n * @returns ResolvedConfig with all values and source tracking\n */\nexport function resolveConfig(): ResolvedConfig {\n  const globalConfig = loadGlobalConfig();\n  const projectConfig = tryLoadProjectConfig();\n\n  const sources: ConfigSources = {\n    apiKey: null,\n    projectId: null,\n    specificationId: null,\n    mcpOutputFormat: 'default',\n  };\n\n  const resolved: ResolvedConfig = {\n    apiKey: null,\n    apiUrl: CONFIG_DEFAULTS.apiUrl,\n    mcpOutputFormat: CONFIG_DEFAULTS.mcpOutputFormat,\n    projectId: null,\n    specificationId: null,\n    autoSetContext: CONFIG_DEFAULTS.autoSetContext,\n    debug: CONFIG_DEFAULTS.debug,\n    sources,\n  };\n\n  // --- API Key: ENV > Global ---\n  if (process.env[CONFIG_ENV_VARS.API_KEY]) {\n    resolved.apiKey = process.env[CONFIG_ENV_VARS.API_KEY]!;\n    sources.apiKey = 'env';\n  } else if (globalConfig.apiKey) {\n    resolved.apiKey = globalConfig.apiKey;\n    sources.apiKey = 'global';\n  }\n\n  // --- API URL: ENV > Default ---\n  if (process.env[CONFIG_ENV_VARS.API_URL]) {\n    resolved.apiUrl = process.env[CONFIG_ENV_VARS.API_URL]!;\n  }\n\n  // --- Debug: ENV only ---\n  resolved.debug = process.env[CONFIG_ENV_VARS.DEBUG] === 'true';\n\n  // --- MCP output format: ENV > Project > Global > Default ---\n  const envFormat = process.env[CONFIG_ENV_VARS.MCP_OUTPUT_FORMAT];\n  if (envFormat && isValidFormat(envFormat)) {\n    resolved.mcpOutputFormat = envFormat;\n    sources.mcpOutputFormat = 'env';\n  } else if (projectConfig?.mcpOutputFormat && isValidFormat(projectConfig.mcpOutputFormat)) {\n    resolved.mcpOutputFormat = projectConfig.mcpOutputFormat;\n    sources.mcpOutputFormat = 'project';\n  } else if (globalConfig.mcpOutputFormat && isValidFormat(globalConfig.mcpOutputFormat)) {\n    resolved.mcpOutputFormat = globalConfig.mcpOutputFormat;\n    sources.mcpOutputFormat = 'global';\n  }\n\n  // --- Project ID: Project > Global ---\n  if (projectConfig?.projectId) {\n    resolved.projectId = projectConfig.projectId;\n    sources.projectId = 'project';\n  } else if (globalConfig.defaultProjectId) {\n    resolved.projectId = globalConfig.defaultProjectId;\n    sources.projectId = 'global';\n  }\n\n  // --- Specification ID: Project only ---\n  if (projectConfig?.specificationId) {\n    resolved.specificationId = projectConfig.specificationId;\n    sources.specificationId = 'project';\n  }\n\n  // --- Auto Set Context: Project > Default ---\n  if (projectConfig?.autoSetContext !== undefined) {\n    resolved.autoSetContext = projectConfig.autoSetContext;\n  }\n\n  return resolved;\n}\n\n/**\n * Validate that a string is a valid output format\n */\nfunction isValidFormat(format: string): format is OutputFormat {\n  return format === 'json' || format === 'toon';\n}\n\n/**\n * Check if user is authenticated (has API key configured)\n *\n * @returns true if API key is available from any source\n */\nexport function isAuthenticated(): boolean {\n  const config = resolveConfig();\n  return config.apiKey !== null;\n}\n\n/**\n * Get API key if available\n *\n * @returns API key string or null if not configured\n */\nexport function getApiKey(): string | null {\n  const config = resolveConfig();\n  return config.apiKey;\n}\n\n/**\n * Check if running in a project context\n *\n * @returns true if a valid project config was found (legacy files rethrow)\n */\nexport function hasProjectContext(): boolean {\n  return tryLoadProjectConfig() !== null;\n}\n\n/**\n * Get current project ID if available\n */\nexport function getProjectId(): string | null {\n  const config = resolveConfig();\n  return config.projectId;\n}\n\n/**\n * Get current specification ID if available\n */\nexport function getSpecificationId(): string | null {\n  const config = resolveConfig();\n  return config.specificationId;\n}\n\n// ---------------------------------------------------------------------------\n// Agent Teams config helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Get Agent Teams config with defaults merged (v2.0.0).\n *\n * Claude Code Agent Teams only. Not used by MCP tool handlers.\n *\n * Always returns a fully-resolved config object — never null.\n * Partial configs are merged with defaults via spread operator.\n *\n * @param config - Parsed project config (or null for all defaults)\n * @returns Resolved Agent Teams config with all defaults applied\n */\nexport function getAgentTeamsConfig(config: SpecforgeJsonConfig | null): ResolvedAgentTeamsConfig {\n  const partial = config?.agentTeams;\n  return {\n    enabled: partial?.enabled ?? AGENT_TEAMS_DEFAULTS.enabled,\n    strategy: partial?.strategy ?? AGENT_TEAMS_DEFAULTS.strategy,\n    maxTicketsPerTeam: partial?.maxTicketsPerTeam ?? AGENT_TEAMS_DEFAULTS.maxTicketsPerTeam,\n    maxParallelEpics: partial?.maxParallelEpics ?? AGENT_TEAMS_DEFAULTS.maxParallelEpics,\n    branchPrefix: partial?.branchPrefix ?? AGENT_TEAMS_DEFAULTS.branchPrefix,\n    timeoutMinutes: partial?.timeoutMinutes ?? AGENT_TEAMS_DEFAULTS.timeoutMinutes,\n  };\n}\n\n/**\n * Get the active specification from config.\n *\n * Claude Code Agent Teams only. Not used by MCP tool handlers.\n */\nexport function getActiveSpecification(config: SpecforgeJsonConfig | null): ActiveSpecification | null {\n  return config?.activeSpecification ?? null;\n}\n"],"mappings":"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","names":[]}

package/dist/cli/config/paths.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Config Paths Resolution
+ *
+ * Provides functions for resolving configuration file paths.
+ * Handles both global (~/.specforge/) and project-level (.specforge.json) paths.
+ */
+import { ConfigPaths } from './types.js';
+/**
+ * Get all configuration file paths
+ *
+ * @returns ConfigPaths object with all resolved paths
+ *
+ * @example
+ * ```typescript
+ * const paths = getConfigPaths();
+ * console.log(paths.globalDir);    // /home/user/.specforge
+ * console.log(paths.globalConfig); // /home/user/.specforge/config.json
+ * console.log(paths.projectConfig); // /current/dir/.specforge.json
+ * ```
+ */
+export declare function getConfigPaths(): ConfigPaths;
+/**
+ * Get the global configuration directory path
+ *
+ * Uses $HOME/.specforge on all platforms.
+ * Does not create the directory - that's handled by the writer.
+ *
+ * @returns Absolute path to global config directory
+ *
+ * @example
+ * ```typescript
+ * const dir = getGlobalConfigDir();
+ * // Linux/macOS: /home/user/.specforge
+ * // Windows: C:\Users\user\.specforge
+ * ```
+ */
+export declare function getGlobalConfigDir(): string;
+/**
+ * Get the global configuration file path
+ *
+ * @returns Absolute path to ~/.specforge/config.json
+ */
+export declare function getGlobalConfigPath(): string;
+/**
+ * Get the project configuration file path
+ *
+ * Resolves to .specforge.json in the current working directory.
+ * Note: This returns the path in CWD only - for searching up the
+ * directory tree, use findProjectConfigPath().
+ *
+ * @returns Absolute path to .specforge.json in current directory
+ */
+export declare function getProjectConfigPath(): string;
+/**
+ * Get the MCP configuration file path
+ *
+ * @returns Absolute path to .mcp.json in current directory
+ */
+export declare function getMcpConfigPath(): string;
+/**
+ * Get the planning-sessions registry path (M9.6 §2.6).
+ *
+ * Lives alongside config.json under the channel-aware project config dir
+ * (`.specforge/planning-sessions.json` on stable, `.specforge-canary/...` on
+ * canary — `CONFIG_FILES.PROJECT_DIR` flows from `CHANNEL.configDir`).
+ *
+ * @param targetDir - Project root (defaults to cwd)
+ * @returns Absolute path to the planning-sessions registry file
+ */
+export declare function getPlanningSessionsRegistryPath(targetDir?: string): string;
+/**
+ * Find project config by searching up the directory tree
+ *
+ * Starts from the current directory and walks up to the filesystem root,
+ * looking for .specforge.json at each level.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to .specforge.json if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // Given: /home/user/projects/myapp/src/components
+ * // With .specforge.json at /home/user/projects/myapp/.specforge.json
+ *
+ * const configPath = findProjectConfigPath();
+ * // Returns: /home/user/projects/myapp/.specforge.json
+ * ```
+ */
+export declare function findProjectConfigPath(startDir?: string): string | null;
+/**
+ * Get the directory containing the project config
+ *
+ * Useful for resolving relative paths from the project root.
+ *
+ * @returns Directory path if project config found, null otherwise
+ */
+export declare function findProjectRoot(): string | null;
+/**
+ * Check if a path is within the global config directory
+ *
+ * Security check to prevent path traversal attacks.
+ *
+ * @param targetPath - Path to check
+ * @returns true if path is within ~/.specforge/
+ */
+export declare function isWithinGlobalDir(targetPath: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/cli/config/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/cli/config/paths.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAS5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAG1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA+BtE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAU/C;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAO7D"}