@llm-dev-ops/agentics-cli 1.4.7 → 1.4.8

package/dist/contracts/adr-006-claude-code-synthesis-runner.js

@@ -0,0 +1,177 @@
+/**
+ * ADR-006: Claude Code Synthesis Runner — Subprocess Invocation & Contract Binding
+ *
+ * STATUS: Proposed
+ * DATE: 2026-02-07
+ * AUTHORS: Platform Engineering
+ * DEPENDS-ON: ADR-001 (Command Semantics), ADR-002 (Operational Enforcement)
+ *
+ * ============================================================================
+ * CONTEXT
+ * ============================================================================
+ *
+ * The Agentics CLI needs to invoke Claude Code (the locally-installed Claude
+ * CLI binary) for decision-grade subcommands. This is modeled after how
+ * Claude Flow performs a single synthesis+plan step per command invocation.
+ *
+ * Currently, the CLI has an "executive synthesis" tool that runs as a detached
+ * fire-and-forget process (src/cli/index.ts:42-67). This is insufficient:
+ *
+ * - It does not capture Claude Code's output synchronously
+ * - It does not validate output against contract schemas
+ * - It is not subcommand-aware (fires on all commands that produce output)
+ * - It cannot feed structured JSON into the platform pipeline
+ *
+ * We need a focused module that:
+ * 1. Detects the Claude Code binary (claude, claude-code, or env-configured)
+ * 2. Invokes it synchronously via child_process.execFileSync or spawn+await
+ * 3. Sends a structured prompt via --print flag (non-interactive, JSON output)
+ * 4. Captures stdout, strips code fences, parses JSON
+ * 5. Validates against the agentics-contracts schema for that subcommand
+ * 6. Returns the typed object for downstream pipeline consumption
+ *
+ * ============================================================================
+ * DECISION
+ * ============================================================================
+ *
+ * 1. A new module `src/runtime/claude-code-runner.ts` will be created.
+ *
+ * 2. It will use Node.js `child_process.execFileSync` for synchronous
+ *    single-invocation semantics (one call per decision command).
+ *
+ * 3. The binary is resolved in order:
+ *    a. AGENTICS_CLAUDE_BIN environment variable (explicit path)
+ *    b. `claude` on PATH (standard Claude Code CLI)
+ *    c. `claude-code` on PATH (alternate binary name)
+ *    If none found, throw a CLIError with code ECLI-SYNTH-001.
+ *
+ * 4. Invocation uses the `--print` flag for non-interactive JSON output:
+ *    ```
+ *    claude --print --output-format json --model <model> "<prompt>"
+ *    ```
+ *    The prompt is a single string constructed by the synthesis router.
+ *
+ * 5. Environment variables supported:
+ *    - AGENTICS_CLAUDE_BIN: Override binary path
+ *    - AGENTICS_CLAUDE_MODEL: Override model (default: claude-sonnet-4-20250514)
+ *    - AGENTICS_CLAUDE_TIMEOUT_MS: Timeout (default: 120000)
+ *    - AGENTICS_DEV: When set, enables verbose debug output to stderr
+ *
+ * 6. Output processing:
+ *    a. Capture stdout as string
+ *    b. Strip markdown code fences if present (```json ... ```)
+ *    c. JSON.parse the result
+ *    d. Validate against the contract schema for the given subcommand
+ *    e. Return typed object or throw ContractValidationError
+ *
+ * 7. Each invocation includes a run-id and seed in the prompt for
+ *    determinism and traceability.
+ *
+ * ============================================================================
+ * INTERFACE CONTRACT
+ * ============================================================================
+ *
+ * ```typescript
+ * interface ClaudeCodeRunnerOptions {
+ *   model?: string;
+ *   timeoutMs?: number;
+ *   runId: string;
+ *   seed?: number;
+ *   verbose?: boolean;
+ * }
+ *
+ * interface ClaudeCodeRunnerResult<T> {
+ *   data: T;
+ *   runId: string;
+ *   model: string;
+ *   durationMs: number;
+ *   rawOutput: string;
+ * }
+ *
+ * interface IClaudeCodeRunner {
+ *   resolve(): string;  // Returns binary path or throws
+ *   invoke<T>(prompt: string, options: ClaudeCodeRunnerOptions): ClaudeCodeRunnerResult<T>;
+ * }
+ * ```
+ *
+ * ============================================================================
+ * ERROR CODES
+ * ============================================================================
+ *
+ * | Code              | Meaning                                     | Exit |
+ * |-------------------|---------------------------------------------|------|
+ * | ECLI-SYNTH-001    | Claude Code binary not found                | 127  |
+ * | ECLI-SYNTH-002    | Claude Code invocation failed (non-zero)    | 1    |
+ * | ECLI-SYNTH-003    | Output is not valid JSON                    | 140  |
+ * | ECLI-SYNTH-004    | Output failed contract validation           | 140  |
+ * | ECLI-SYNTH-005    | Invocation timed out                        | 124  |
+ *
+ * ============================================================================
+ * ALTERNATIVES CONSIDERED
+ * ============================================================================
+ *
+ * A. Use the Anthropic API directly (HTTP client):
+ *    Rejected — the requirement is to use the locally-installed Claude Code
+ *    binary, matching Claude Flow's execution model. This also avoids
+ *    managing API keys in the CLI when Claude Code already handles auth.
+ *
+ * B. Use the existing executive-synthesis detached process:
+ *    Rejected — fire-and-forget cannot feed results into the platform
+ *    pipeline. Synchronous capture is required.
+ *
+ * C. Use stdin piping instead of --print flag:
+ *    Rejected — --print is the Claude Code standard for non-interactive
+ *    programmatic use. Stdin piping is for interactive sessions.
+ *
+ * ============================================================================
+ * CONSEQUENCES
+ * ============================================================================
+ *
+ * - Claude Code must be installed locally for decision-grade commands
+ * - Commands that are SYNTHESIS_FORBIDDEN never invoke this module
+ * - Each decision-grade invocation has exactly one Claude Code call
+ * - All outputs are contract-validated before reaching the platform
+ * - Binary resolution is deterministic and debuggable via AGENTICS_DEV
+ *
+ * ============================================================================
+ * SECURITY CONSIDERATIONS
+ * ============================================================================
+ *
+ * - The prompt is constructed entirely from CLI arguments and templates;
+ *   no user input is interpolated without sanitization.
+ * - The Claude Code binary inherits the user's environment but no
+ *   additional secrets are passed beyond what's already in the shell.
+ * - Output is validated against a strict schema; malformed output is
+ *   rejected with ECLI-SYNTH-003/004.
+ * - Timeout prevents runaway processes.
+ */
+/**
+ * Schema mapping: maps (command, subcommand) to the response schema name
+ * used for validating Claude Code output.
+ *
+ * This is the bridge between ADR-001 command semantics and the contract
+ * validator. Each decision-grade subcommand maps to exactly one schema.
+ */
+export const SYNTHESIS_SCHEMA_MAP = {
+    'simulate.create': 'simulation',
+    'simulate.run': 'simulation',
+    'plan.create': 'plan',
+    'plan.approve': 'plan',
+    'deploy.preview': 'intent',
+    'deploy.run': 'intent',
+    'deploy.rollback': 'intent',
+    'export.terraform': 'export',
+    'export.kubernetes': 'export',
+    'export.erp': 'export',
+    'policy.create': 'base',
+    'policy.edit': 'base',
+    'policy.enable': 'base',
+    'policy.disable': 'base',
+    'policy.dry-run': 'base',
+    'quantify.create': 'roiReport',
+    'quantify.compare': 'roiReport',
+    'erp.surface': 'base',
+    'erp.map': 'base',
+    'erp.export': 'export',
+};
+//# sourceMappingURL=adr-006-claude-code-synthesis-runner.js.map

package/dist/contracts/adr-006-claude-code-synthesis-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-006-claude-code-synthesis-runner.js","sourceRoot":"","sources":["../../src/contracts/adr-006-claude-code-synthesis-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJG;AAkDH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAqC;IACpE,iBAAiB,EAAE,YAAY;IAC/B,cAAc,EAAE,YAAY;IAC5B,aAAa,EAAE,MAAM;IACrB,cAAc,EAAE,MAAM;IACtB,gBAAgB,EAAE,QAAQ;IAC1B,YAAY,EAAE,QAAQ;IACtB,iBAAiB,EAAE,QAAQ;IAC3B,kBAAkB,EAAE,QAAQ;IAC5B,mBAAmB,EAAE,QAAQ;IAC7B,YAAY,EAAE,QAAQ;IACtB,eAAe,EAAE,MAAM;IACvB,aAAa,EAAE,MAAM;IACrB,eAAe,EAAE,MAAM;IACvB,gBAAgB,EAAE,MAAM;IACxB,gBAAgB,EAAE,MAAM;IACxB,iBAAiB,EAAE,WAAW;IAC9B,kBAAkB,EAAE,WAAW;IAC/B,aAAa,EAAE,MAAM;IACrB,SAAS,EAAE,MAAM;IACjB,YAAY,EAAE,QAAQ;CACd,CAAC"}

package/dist/contracts/adr-007-subcommand-synthesis-router.d.ts

@@ -0,0 +1,273 @@
+/**
+ * ADR-007: Subcommand-Aware Synthesis Router
+ *
+ * STATUS: Proposed
+ * DATE: 2026-02-07
+ * AUTHORS: Platform Engineering
+ * DEPENDS-ON: ADR-001 (Command Semantics), ADR-006 (Claude Code Runner)
+ *
+ * ============================================================================
+ * CONTEXT
+ * ============================================================================
+ *
+ * ADR-001 defines a COMMAND_REGISTRY with synthesis governance classifications:
+ * - SYNTHESIS_REQUIRED: LLM invocation expected
+ * - SYNTHESIS_FORBIDDEN: Must NEVER trigger synthesis
+ * - COMMITMENT_GRADE: Requires ID + confirmation + synthesis
+ *
+ * The current CLI dispatches commands via a monolithic switch statement in
+ * src/cli/index.ts. Decision-grade subcommands call their respective
+ * command executors (executePlanCreateCommand, executeSimulateRunCommand, etc.)
+ * which talk to the platform API. The executive synthesis tool fires as an
+ * afterthought (fire-and-forget detached process).
+ *
+ * What's missing is a routing layer that sits BETWEEN argument parsing and
+ * command execution, intercepting decision-grade subcommands to:
+ * 1. Construct a subcommand-specific prompt
+ * 2. Call Claude Code Runner (ADR-006)
+ * 3. Validate the output
+ * 4. Feed it into the platform pipeline
+ *
+ * ============================================================================
+ * DECISION
+ * ============================================================================
+ *
+ * 1. A new module `src/synthesis/router.ts` will implement the synthesis
+ *    routing layer.
+ *
+ * 2. The router takes a SynthesisRequest:
+ *    ```typescript
+ *    interface SynthesisRequest {
+ *      command: string;          // e.g. "simulate"
+ *      subcommand: string;       // e.g. "create"
+ *      positionalArgs: string[]; // from parsed CLI args
+ *      options: Record<string, string>;
+ *      flags: Record<string, boolean>;
+ *      userContext: {
+ *        userId: string;
+ *        orgId: string;
+ *        traceId: string;
+ *      };
+ *    }
+ *    ```
+ *
+ * 3. Routing logic:
+ *    a. Look up (command, subcommand) in ADR-001 COMMAND_REGISTRY
+ *    b. If synthesis === 'SYNTHESIS_FORBIDDEN', return null immediately
+ *    c. If synthesis === 'SYNTHESIS_REQUIRED' or 'COMMITMENT_GRADE':
+ *       i.   Generate a run-id (UUID v4)
+ *       ii.  Load the prompt template for this (command, subcommand)
+ *       iii. Inject arguments, context, run-id, and contract requirements
+ *       iv.  Call ClaudeCodeRunner.invoke()
+ *       v.   Return the validated SynthesisResult
+ *
+ * 4. SynthesisResult structure:
+ *    ```typescript
+ *    interface SynthesisResult<T> {
+ *      data: T;                    // Contract-validated output
+ *      runId: string;              // UUID for this synthesis run
+ *      command: string;
+ *      subcommand: string;
+ *      model: string;              // Model used
+ *      durationMs: number;
+ *      contractSchema: string;     // Schema name used for validation
+ *    }
+ *    ```
+ *
+ * 5. The router is a pure function with no side effects beyond calling
+ *    ClaudeCodeRunner. It does NOT:
+ *    - Write artifacts (that's ADR-008)
+ *    - Call the platform API (that's the command executor)
+ *    - Modify CLI state
+ *
+ * ============================================================================
+ * PROMPT TEMPLATE SYSTEM
+ * ============================================================================
+ *
+ * 1. Templates live in `src/synthesis/prompts/` as exported string constants
+ *    (not .txt files — TypeScript provides compile-time safety and tree-shaking).
+ *
+ * 2. Each template is a function: (args: PromptArgs) => string
+ *
+ * 3. PromptArgs includes:
+ *    - runId: string
+ *    - seed: number
+ *    - command: string
+ *    - subcommand: string
+ *    - positionalArgs: string[]
+ *    - contractSchemaName: string
+ *    - contractSchemaFields: string (human-readable field list)
+ *
+ * 4. Every template MUST include:
+ *    - "Respond ONLY with a JSON object. No prose, no markdown, no explanation."
+ *    - The exact contract schema name
+ *    - The run-id and seed
+ *    - The required fields for the output schema
+ *
+ * 5. Template naming: `{command}_{subcommand}` (e.g., simulate_create)
+ *
+ * ============================================================================
+ * DECISION-GRADE SUBCOMMAND MATRIX
+ * ============================================================================
+ *
+ * | Command   | Subcommand | Synthesis Class      | Contract Schema  |
+ * |-----------|------------|----------------------|------------------|
+ * | simulate  | create     | SYNTHESIS_REQUIRED   | simulation       |
+ * | simulate  | run        | COMMITMENT_GRADE     | simulation       |
+ * | plan      | create     | SYNTHESIS_REQUIRED   | plan             |
+ * | plan      | approve    | COMMITMENT_GRADE     | plan             |
+ * | deploy    | preview    | SYNTHESIS_REQUIRED   | intent           |
+ * | deploy    | run        | COMMITMENT_GRADE     | intent           |
+ * | deploy    | rollback   | COMMITMENT_GRADE     | intent           |
+ * | export    | terraform  | SYNTHESIS_REQUIRED   | export           |
+ * | export    | kubernetes | SYNTHESIS_REQUIRED   | export           |
+ * | export    | erp        | SYNTHESIS_REQUIRED   | export           |
+ * | policy    | create     | SYNTHESIS_REQUIRED   | base             |
+ * | policy    | edit       | SYNTHESIS_REQUIRED   | base             |
+ * | policy    | enable     | COMMITMENT_GRADE     | base             |
+ * | policy    | disable    | SYNTHESIS_REQUIRED   | base             |
+ * | policy    | dry-run    | SYNTHESIS_REQUIRED   | base             |
+ * | quantify  | create     | SYNTHESIS_REQUIRED   | roiReport        |
+ * | quantify  | compare    | COMMITMENT_GRADE     | roiReport        |
+ * | erp       | surface    | SYNTHESIS_REQUIRED   | base             |
+ * | erp       | map        | SYNTHESIS_REQUIRED   | base             |
+ * | erp       | export     | SYNTHESIS_REQUIRED   | export           |
+ *
+ * All other (command, subcommand) combinations return null from the router.
+ *
+ * ============================================================================
+ * INTEGRATION POINT
+ * ============================================================================
+ *
+ * The router is called from the CLI dispatch in src/cli/index.ts.
+ * The integration follows this pattern:
+ *
+ * ```typescript
+ * // In the command handler (e.g., simulate create)
+ * const synthesisResult = synthesisRouter.route({
+ *   command: parsed.command,
+ *   subcommand: parsed.subcommand,
+ *   positionalArgs: parsed.positionalArgs,
+ *   options: parsed.options,
+ *   flags: parsed.flags,
+ *   userContext: { userId, orgId, traceId },
+ * });
+ *
+ * if (synthesisResult) {
+ *   // Decision-grade: use Claude Code output
+ *   const platformResult = await executeWithSynthesis(synthesisResult);
+ *   await persistArtifacts(synthesisResult, platformResult);
+ * } else {
+ *   // Non-synthesis: proceed with existing command handler
+ *   await executeExistingHandler(...);
+ * }
+ * ```
+ *
+ * ============================================================================
+ * ALTERNATIVES CONSIDERED
+ * ============================================================================
+ *
+ * A. Middleware-based routing (intercept all commands):
+ *    Rejected — synthesis is the exception, not the rule. A middleware
+ *    pattern would add overhead to every command, including the majority
+ *    that are SYNTHESIS_FORBIDDEN.
+ *
+ * B. Prompt templates as external .txt files:
+ *    Rejected — TypeScript functions provide compile-time safety,
+ *    argument validation, and can reference contract types. External
+ *    files would need a runtime loader and lose type safety.
+ *
+ * C. One giant prompt for all subcommands:
+ *    Rejected — each subcommand has unique argument shapes, contract
+ *    schemas, and domain-specific instructions. Specialized prompts
+ *    produce better-structured output.
+ *
+ * ============================================================================
+ * CONSEQUENCES
+ * ============================================================================
+ *
+ * - Every decision-grade subcommand gets exactly one Claude Code call
+ * - Non-decision commands have zero synthesis overhead
+ * - Prompt templates are version-controlled and type-safe
+ * - New decision-grade subcommands require:
+ *   a. ADR-001 COMMAND_REGISTRY entry with SYNTHESIS_REQUIRED/COMMITMENT_GRADE
+ *   b. ADR-006 SYNTHESIS_SCHEMA_MAP entry
+ *   c. A prompt template function in src/synthesis/prompts/
+ *   d. CLI handler integration per the pattern above
+ * - The router is stateless and testable in isolation
+ */
+/**
+ * Narrowed synthesis governance class for decision-grade subcommands.
+ * SYNTHESIS_FORBIDDEN commands never reach the router — only these two are valid.
+ */
+export type SynthesisGovernanceClass = 'SYNTHESIS_REQUIRED' | 'COMMITMENT_GRADE';
+export interface SynthesisRequest {
+    readonly command: string;
+    readonly subcommand: string;
+    readonly positionalArgs: readonly string[];
+    readonly options: Readonly<Record<string, string>>;
+    readonly flags: Readonly<Record<string, boolean>>;
+    readonly userContext: {
+        readonly userId: string;
+        readonly orgId: string;
+        readonly traceId: string;
+    };
+}
+export interface SynthesisResult<T = unknown> {
+    /** Contract-validated output from Claude Code */
+    readonly data: T;
+    /** UUID for this synthesis run */
+    readonly runId: string;
+    /** Primary command */
+    readonly command: string;
+    /** Subcommand */
+    readonly subcommand: string;
+    /** Model used for synthesis */
+    readonly model: string;
+    /** Duration of Claude Code invocation */
+    readonly durationMs: number;
+    /** Contract schema used for validation */
+    readonly contractSchema: string;
+    /** Raw Claude Code output (for artifact persistence) */
+    readonly rawOutput: string;
+    /** ADR-001 synthesis governance classification */
+    readonly synthesisClass: SynthesisGovernanceClass;
+    /** The prompt that was sent to Claude Code (for artifact persistence and debugging) */
+    readonly prompt: string;
+}
+export interface PromptArgs {
+    readonly runId: string;
+    readonly seed: number;
+    readonly command: string;
+    readonly subcommand: string;
+    readonly positionalArgs: readonly string[];
+    readonly options: Readonly<Record<string, string>>;
+    readonly contractSchemaName: string;
+}
+/** Type for prompt template functions */
+export type PromptTemplate = (args: PromptArgs) => string;
+/**
+ * Result of building a synthesis prompt without invoking Claude Code.
+ * Used for dry-run mode and testing.
+ */
+export interface SynthesisPromptResult {
+    /** The fully-constructed prompt string */
+    readonly prompt: string;
+    /** Generated run identifier */
+    readonly runId: string;
+    /** Generated seed for determinism */
+    readonly seed: number;
+    /** The (command.subcommand) routing key */
+    readonly key: string;
+    /** Contract schema name for validation */
+    readonly contractSchema: string;
+    /** ADR-001 synthesis governance classification */
+    readonly synthesisClass: SynthesisGovernanceClass;
+}
+/**
+ * The decision-grade subcommand set.
+ * This is the canonical list; any subcommand NOT in this set
+ * must NEVER trigger Claude Code invocation.
+ */
+export declare const DECISION_GRADE_SUBCOMMANDS: ReadonlySet<string>;
+//# sourceMappingURL=adr-007-subcommand-synthesis-router.d.ts.map

package/dist/contracts/adr-007-subcommand-synthesis-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-007-subcommand-synthesis-router.d.ts","sourceRoot":"","sources":["../../src/contracts/adr-007-subcommand-synthesis-router.ts"],"names":[],"mappings":"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"}

package/dist/contracts/adr-007-subcommand-synthesis-router.js

@@ -0,0 +1,226 @@
+/**
+ * ADR-007: Subcommand-Aware Synthesis Router
+ *
+ * STATUS: Proposed
+ * DATE: 2026-02-07
+ * AUTHORS: Platform Engineering
+ * DEPENDS-ON: ADR-001 (Command Semantics), ADR-006 (Claude Code Runner)
+ *
+ * ============================================================================
+ * CONTEXT
+ * ============================================================================
+ *
+ * ADR-001 defines a COMMAND_REGISTRY with synthesis governance classifications:
+ * - SYNTHESIS_REQUIRED: LLM invocation expected
+ * - SYNTHESIS_FORBIDDEN: Must NEVER trigger synthesis
+ * - COMMITMENT_GRADE: Requires ID + confirmation + synthesis
+ *
+ * The current CLI dispatches commands via a monolithic switch statement in
+ * src/cli/index.ts. Decision-grade subcommands call their respective
+ * command executors (executePlanCreateCommand, executeSimulateRunCommand, etc.)
+ * which talk to the platform API. The executive synthesis tool fires as an
+ * afterthought (fire-and-forget detached process).
+ *
+ * What's missing is a routing layer that sits BETWEEN argument parsing and
+ * command execution, intercepting decision-grade subcommands to:
+ * 1. Construct a subcommand-specific prompt
+ * 2. Call Claude Code Runner (ADR-006)
+ * 3. Validate the output
+ * 4. Feed it into the platform pipeline
+ *
+ * ============================================================================
+ * DECISION
+ * ============================================================================
+ *
+ * 1. A new module `src/synthesis/router.ts` will implement the synthesis
+ *    routing layer.
+ *
+ * 2. The router takes a SynthesisRequest:
+ *    ```typescript
+ *    interface SynthesisRequest {
+ *      command: string;          // e.g. "simulate"
+ *      subcommand: string;       // e.g. "create"
+ *      positionalArgs: string[]; // from parsed CLI args
+ *      options: Record<string, string>;
+ *      flags: Record<string, boolean>;
+ *      userContext: {
+ *        userId: string;
+ *        orgId: string;
+ *        traceId: string;
+ *      };
+ *    }
+ *    ```
+ *
+ * 3. Routing logic:
+ *    a. Look up (command, subcommand) in ADR-001 COMMAND_REGISTRY
+ *    b. If synthesis === 'SYNTHESIS_FORBIDDEN', return null immediately
+ *    c. If synthesis === 'SYNTHESIS_REQUIRED' or 'COMMITMENT_GRADE':
+ *       i.   Generate a run-id (UUID v4)
+ *       ii.  Load the prompt template for this (command, subcommand)
+ *       iii. Inject arguments, context, run-id, and contract requirements
+ *       iv.  Call ClaudeCodeRunner.invoke()
+ *       v.   Return the validated SynthesisResult
+ *
+ * 4. SynthesisResult structure:
+ *    ```typescript
+ *    interface SynthesisResult<T> {
+ *      data: T;                    // Contract-validated output
+ *      runId: string;              // UUID for this synthesis run
+ *      command: string;
+ *      subcommand: string;
+ *      model: string;              // Model used
+ *      durationMs: number;
+ *      contractSchema: string;     // Schema name used for validation
+ *    }
+ *    ```
+ *
+ * 5. The router is a pure function with no side effects beyond calling
+ *    ClaudeCodeRunner. It does NOT:
+ *    - Write artifacts (that's ADR-008)
+ *    - Call the platform API (that's the command executor)
+ *    - Modify CLI state
+ *
+ * ============================================================================
+ * PROMPT TEMPLATE SYSTEM
+ * ============================================================================
+ *
+ * 1. Templates live in `src/synthesis/prompts/` as exported string constants
+ *    (not .txt files — TypeScript provides compile-time safety and tree-shaking).
+ *
+ * 2. Each template is a function: (args: PromptArgs) => string
+ *
+ * 3. PromptArgs includes:
+ *    - runId: string
+ *    - seed: number
+ *    - command: string
+ *    - subcommand: string
+ *    - positionalArgs: string[]
+ *    - contractSchemaName: string
+ *    - contractSchemaFields: string (human-readable field list)
+ *
+ * 4. Every template MUST include:
+ *    - "Respond ONLY with a JSON object. No prose, no markdown, no explanation."
+ *    - The exact contract schema name
+ *    - The run-id and seed
+ *    - The required fields for the output schema
+ *
+ * 5. Template naming: `{command}_{subcommand}` (e.g., simulate_create)
+ *
+ * ============================================================================
+ * DECISION-GRADE SUBCOMMAND MATRIX
+ * ============================================================================
+ *
+ * | Command   | Subcommand | Synthesis Class      | Contract Schema  |
+ * |-----------|------------|----------------------|------------------|
+ * | simulate  | create     | SYNTHESIS_REQUIRED   | simulation       |
+ * | simulate  | run        | COMMITMENT_GRADE     | simulation       |
+ * | plan      | create     | SYNTHESIS_REQUIRED   | plan             |
+ * | plan      | approve    | COMMITMENT_GRADE     | plan             |
+ * | deploy    | preview    | SYNTHESIS_REQUIRED   | intent           |
+ * | deploy    | run        | COMMITMENT_GRADE     | intent           |
+ * | deploy    | rollback   | COMMITMENT_GRADE     | intent           |
+ * | export    | terraform  | SYNTHESIS_REQUIRED   | export           |
+ * | export    | kubernetes | SYNTHESIS_REQUIRED   | export           |
+ * | export    | erp        | SYNTHESIS_REQUIRED   | export           |
+ * | policy    | create     | SYNTHESIS_REQUIRED   | base             |
+ * | policy    | edit       | SYNTHESIS_REQUIRED   | base             |
+ * | policy    | enable     | COMMITMENT_GRADE     | base             |
+ * | policy    | disable    | SYNTHESIS_REQUIRED   | base             |
+ * | policy    | dry-run    | SYNTHESIS_REQUIRED   | base             |
+ * | quantify  | create     | SYNTHESIS_REQUIRED   | roiReport        |
+ * | quantify  | compare    | COMMITMENT_GRADE     | roiReport        |
+ * | erp       | surface    | SYNTHESIS_REQUIRED   | base             |
+ * | erp       | map        | SYNTHESIS_REQUIRED   | base             |
+ * | erp       | export     | SYNTHESIS_REQUIRED   | export           |
+ *
+ * All other (command, subcommand) combinations return null from the router.
+ *
+ * ============================================================================
+ * INTEGRATION POINT
+ * ============================================================================
+ *
+ * The router is called from the CLI dispatch in src/cli/index.ts.
+ * The integration follows this pattern:
+ *
+ * ```typescript
+ * // In the command handler (e.g., simulate create)
+ * const synthesisResult = synthesisRouter.route({
+ *   command: parsed.command,
+ *   subcommand: parsed.subcommand,
+ *   positionalArgs: parsed.positionalArgs,
+ *   options: parsed.options,
+ *   flags: parsed.flags,
+ *   userContext: { userId, orgId, traceId },
+ * });
+ *
+ * if (synthesisResult) {
+ *   // Decision-grade: use Claude Code output
+ *   const platformResult = await executeWithSynthesis(synthesisResult);
+ *   await persistArtifacts(synthesisResult, platformResult);
+ * } else {
+ *   // Non-synthesis: proceed with existing command handler
+ *   await executeExistingHandler(...);
+ * }
+ * ```
+ *
+ * ============================================================================
+ * ALTERNATIVES CONSIDERED
+ * ============================================================================
+ *
+ * A. Middleware-based routing (intercept all commands):
+ *    Rejected — synthesis is the exception, not the rule. A middleware
+ *    pattern would add overhead to every command, including the majority
+ *    that are SYNTHESIS_FORBIDDEN.
+ *
+ * B. Prompt templates as external .txt files:
+ *    Rejected — TypeScript functions provide compile-time safety,
+ *    argument validation, and can reference contract types. External
+ *    files would need a runtime loader and lose type safety.
+ *
+ * C. One giant prompt for all subcommands:
+ *    Rejected — each subcommand has unique argument shapes, contract
+ *    schemas, and domain-specific instructions. Specialized prompts
+ *    produce better-structured output.
+ *
+ * ============================================================================
+ * CONSEQUENCES
+ * ============================================================================
+ *
+ * - Every decision-grade subcommand gets exactly one Claude Code call
+ * - Non-decision commands have zero synthesis overhead
+ * - Prompt templates are version-controlled and type-safe
+ * - New decision-grade subcommands require:
+ *   a. ADR-001 COMMAND_REGISTRY entry with SYNTHESIS_REQUIRED/COMMITMENT_GRADE
+ *   b. ADR-006 SYNTHESIS_SCHEMA_MAP entry
+ *   c. A prompt template function in src/synthesis/prompts/
+ *   d. CLI handler integration per the pattern above
+ * - The router is stateless and testable in isolation
+ */
+/**
+ * The decision-grade subcommand set.
+ * This is the canonical list; any subcommand NOT in this set
+ * must NEVER trigger Claude Code invocation.
+ */
+export const DECISION_GRADE_SUBCOMMANDS = new Set([
+    'simulate.create',
+    'simulate.run',
+    'plan.create',
+    'plan.approve',
+    'deploy.preview',
+    'deploy.run',
+    'deploy.rollback',
+    'export.terraform',
+    'export.kubernetes',
+    'export.erp',
+    'policy.create',
+    'policy.edit',
+    'policy.enable',
+    'policy.disable',
+    'policy.dry-run',
+    'quantify.create',
+    'quantify.compare',
+    'erp.surface',
+    'erp.map',
+    'erp.export',
+]);
+//# sourceMappingURL=adr-007-subcommand-synthesis-router.js.map