/**
 * ADR-001: Command Argument Semantics & Synthesis Governance
 *
 * STATUS: Accepted
 * DATE: 2026-01-28
 * AUTHORS: Platform Engineering
 *
 * ============================================================================
 * CONTEXT
 * ============================================================================
 *
 * The Agentics CLI is an enterprise orchestration tool, not a chat interface.
 * Natural language seeds synthesis; IDs resolve persisted manifests.
 * These are categorically different argument types with non-overlapping semantics.
 *
 * Without formal governance:
 * - Users accidentally pass descriptions where IDs are required
 * - Synthesis triggers on read-only or irreversible commands
 * - Help output is ambiguous about what each command expects
 * - Tests cannot be mechanically derived from command specifications
 *
 * ============================================================================
 * DECISION
 * ============================================================================
 *
 * 1. All CLI arguments are formally classified into three types:
 *    ID, NATURAL_LANGUAGE, and SELECTOR.
 *
 * 2. Each command+subcommand declares its exact argument contract.
 *
 * 3. A synthesis governance matrix classifies every command as:
 *    SYNTHESIS_REQUIRED, SYNTHESIS_FORBIDDEN, or COMMITMENT_GRADE.
 *
 * 4. Runtime validation middleware enforces these contracts before dispatch.
 *
 * 5. Help output, tests, and error messages are all derived from this ADR.
 *
 * ============================================================================
 * ALTERNATIVES CONSIDERED
 * ============================================================================
 *
 * A. Loose validation with runtime inference:
 *    Rejected — violates determinism and enterprise-grade predictability.
 *
 * B. Per-command ad-hoc validation:
 *    Rejected — leads to inconsistency, untestable, help drift.
 *
 * C. External YAML/JSON config:
 *    Rejected — TypeScript provides compile-time safety and co-location
 *    with the code it governs.
 *
 * ============================================================================
 * CONSEQUENCES
 * ============================================================================
 *
 * - Every command has one unambiguous semantic meaning
 * - Users cannot accidentally misuse IDs vs natural language
 * - Synthesis is impossible where unsafe
 * - Validation, tests, and help all derive from this file
 * - New commands must register here before they compile
 *
 * ============================================================================
 * CLAUDE-CODE PARITY STATEMENT
 * ============================================================================
 *
 * The Agentics CLI mirrors claude-flow + claude-code behavior:
 * - Deterministic: same inputs always produce same dispatch path
 * - Explicit: no inference, no guessing, no auto-correction
 * - Enterprise-grade: fail fast with instructional errors
 * - Composable: commands are pipeline stages, not chat turns
 */
/**
 * The three argument classes. No other classification exists.
 */
export type ArgumentType = 'ID' | 'NATURAL_LANGUAGE' | 'SELECTOR';
/**
 * Synthesis governance classification for each command.
 */
export type SynthesisClass = 'SYNTHESIS_REQUIRED' | 'SYNTHESIS_FORBIDDEN' | 'COMMITMENT_GRADE';
/**
 * Argument specification for a single positional argument.
 */
export interface ArgumentSpec {
    /** Name used in help output */
    readonly name: string;
    /** Argument type classification */
    readonly type: ArgumentType;
    /** Whether this argument must be provided */
    readonly required: boolean;
    /** Human-readable description for help */
    readonly description: string;
    /** Example value for help output */
    readonly example: string;
}
/**
 * Complete command specification — the atomic unit of the ADR.
 */
export interface CommandSpec {
    /** Full command path, e.g. "simulate create" */
    readonly command: string;
    /** Primary command name */
    readonly primary: string;
    /** Subcommand name, if any */
    readonly subcommand?: string;
    /** One-line description */
    readonly description: string;
    /** Synthesis governance class */
    readonly synthesis: SynthesisClass;
    /** Ordered positional arguments */
    readonly args: readonly ArgumentSpec[];
    /** Whether this command is irreversible */
    readonly irreversible: boolean;
    /** Whether this command requires confirmation (--force or interactive) */
    readonly requiresConfirmation: boolean;
}
export declare const COMMAND_REGISTRY: readonly CommandSpec[];
/**
 * ADR schema version. Must be bumped when:
 * - MAJOR: argument contracts change in a breaking way
 * - MINOR: new commands are added
 * - PATCH: help text, examples, or descriptions are corrected
 */
export declare const ADR_SCHEMA_VERSION: "1.0.0";
/**
 * Look up a command specification by primary + subcommand.
 * Returns undefined if not registered (which is itself an error).
 */
export declare function lookupCommand(primary: string, subcommand?: string): CommandSpec | undefined;
/**
 * Get all commands for a primary command.
 */
export declare function getSubcommands(primary: string): readonly CommandSpec[];
/**
 * Check if a command allows synthesis.
 */
export declare function isSynthesisAllowed(primary: string, subcommand?: string): boolean;
/**
 * Check if a command is commitment-grade (irreversible + requires confirmation).
 */
export declare function isCommitmentGrade(primary: string, subcommand?: string): boolean;
/**
 * Classify a raw string argument into its detected type.
 */
export declare function classifyArgument(value: string): ArgumentType;
/**
 * Validate that a given argument matches its expected type.
 * Returns null if valid, or an error message if invalid.
 */
export declare function validateArgument(value: string, expected: ArgumentSpec): string | null;
//# sourceMappingURL=adr-command-semantics.d.ts.map