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

package/dist/contracts/adr-008-synthesis-artifact-persistence.js

@@ -0,0 +1,184 @@
+/**
+ * ADR-008: Synthesis Artifact Persistence & Platform Handoff
+ *
+ * STATUS: Proposed
+ * DATE: 2026-02-07
+ * AUTHORS: Platform Engineering
+ * DEPENDS-ON: ADR-006 (Runner), ADR-007 (Router), ADR-004 (Enterprise Integration)
+ *
+ * ============================================================================
+ * CONTEXT
+ * ============================================================================
+ *
+ * After Claude Code synthesis produces a contract-validated JSON object
+ * (ADR-006 + ADR-007), two things must happen:
+ *
+ * 1. The result must be handed off to the platform (agentics-dev-platform)
+ *    for execution, persistence, and governance tracking.
+ *
+ * 2. Local artifacts must be written for `agentics inspect` to read,
+ *    providing an offline audit trail.
+ *
+ * Currently, artifacts are stored by the Ruvector-backed platform adapters
+ * (src/adapters/base-adapter.ts:643-1089) and local CRUD files live in
+ * .agentics/{command}s/ (e.g., .agentics/simulations/). The executive
+ * synthesis tool writes a decision-summary.md but nothing else.
+ *
+ * This ADR defines the persistence contract for synthesis runs.
+ *
+ * ============================================================================
+ * DECISION
+ * ============================================================================
+ *
+ * 1. A new module `src/synthesis/artifact-writer.ts` handles local persistence.
+ *
+ * 2. After every successful synthesis + platform handoff, the following
+ *    artifacts are written:
+ *
+ *    ```
+ *    ~/.agentics/runs/<run-id>/
+ *    ├── manifest.json         # Run metadata (IDs, timing, command, schema)
+ *    ├── claude_output.json    # Raw Claude Code output (validated JSON)
+ *    ├── platform_receipt.json # Platform API response (IDs, status)
+ *    └── prompt.txt            # The exact prompt sent to Claude Code
+ *    ```
+ *
+ * 3. The manifest.json structure:
+ *    ```typescript
+ *    interface RunManifest {
+ *      run_id: string;
+ *      plan_id?: string;        // If a plan was created
+ *      deploy_id?: string;      // If a deployment was created
+ *      command: string;
+ *      subcommand: string;
+ *      synthesis_class: SynthesisClass;
+ *      contract_schema: string;
+ *      model: string;
+ *      duration_ms: number;
+ *      created_at: string;
+ *      seed: number;
+ *      user_id: string;
+ *      org_id: string;
+ *      trace_id: string;
+ *      artifacts: string[];     // Relative paths to sibling files
+ *    }
+ *    ```
+ *
+ * 4. Platform handoff flow:
+ *    a. Synthesis router returns SynthesisResult<T>
+ *    b. The command handler passes the data to the existing platform adapter
+ *       (PlannerAdapter, RunnerAdapter, etc.)
+ *    c. The platform responds with IDs and status
+ *    d. Artifact writer persists all three files atomically
+ *    e. IDs are printed to stdout
+ *
+ * 5. The artifact writer is idempotent: writing the same run-id twice
+ *    overwrites the previous artifacts (latest wins).
+ *
+ * 6. `agentics inspect run <run-id>` will be enhanced to read from
+ *    `~/.agentics/runs/<run-id>/manifest.json` when the run is not
+ *    found in the platform (offline inspection).
+ *
+ * ============================================================================
+ * ID GENERATION
+ * ============================================================================
+ *
+ * Every synthesis run produces:
+ * - run_id: `run-{uuid}` — unique per invocation
+ * - plan_id: `plan-{uuid}` — if the command creates a plan
+ * - deploy_id: `deploy-{uuid}` — if the command creates a deployment
+ *
+ * These are generated BEFORE calling Claude Code (so they can be embedded
+ * in the prompt for determinism) and then used as the canonical identifiers
+ * throughout the pipeline.
+ *
+ * ============================================================================
+ * STORAGE PATH
+ * ============================================================================
+ *
+ * Base directory: `~/.agentics/runs/`
+ * Override: `AGENTICS_RUNS_DIR` environment variable
+ *
+ * This is separate from the existing `.agentics/simulations/` and
+ * `.agentics/plans/` directories, which store CRUD records. The `runs/`
+ * directory stores synthesis-specific artifacts.
+ *
+ * ============================================================================
+ * FILE PERMISSIONS
+ * ============================================================================
+ *
+ * All files written with mode 0o600 (owner read/write only), matching
+ * the existing credentials.ts pattern (src/utils/credentials.ts:38-39).
+ *
+ * ============================================================================
+ * PLATFORM RECEIPT
+ * ============================================================================
+ *
+ * The platform_receipt.json captures the downstream response:
+ *
+ * ```typescript
+ * interface PlatformReceipt {
+ *   success: boolean;
+ *   platform_id: string;       // ID assigned by platform
+ *   platform_type: string;     // e.g., "PlanReference", "SimulationReference"
+ *   status: string;            // e.g., "created", "queued", "completed"
+ *   timestamp: string;
+ *   trace_id: string;
+ *   error?: string;            // If platform call failed
+ * }
+ * ```
+ *
+ * ============================================================================
+ * WIRING INTO CLI DISPATCH
+ * ============================================================================
+ *
+ * The integration modifies the command handlers in src/cli/index.ts.
+ * For each decision-grade subcommand:
+ *
+ * ```
+ * BEFORE (current):
+ *   parse args → validate gates → call command executor → print output
+ *                                                       → fire-and-forget synthesis
+ *
+ * AFTER (ADR-008):
+ *   parse args → validate gates → synthesis router (Claude Code)
+ *                                → call command executor (with synthesis data)
+ *                                → persist artifacts
+ *                                → print IDs to stdout
+ * ```
+ *
+ * The key change: synthesis happens BEFORE the platform call, not after.
+ * Claude Code produces the structured plan/intent/config, which is then
+ * sent to the platform for execution.
+ *
+ * ============================================================================
+ * ALTERNATIVES CONSIDERED
+ * ============================================================================
+ *
+ * A. Store artifacts in the platform only (no local files):
+ *    Rejected — offline inspection is a hard requirement. Users must be
+ *    able to audit synthesis results without platform connectivity.
+ *
+ * B. Store artifacts in the existing .agentics/{command}s/ directories:
+ *    Rejected — synthesis artifacts are cross-cutting (a simulation run
+ *    may reference a plan). A dedicated `runs/` directory with run-id
+ *    as the organizing key is cleaner.
+ *
+ * C. Use a SQLite database for local storage:
+ *    Rejected — JSON files are simpler, greppable, and don't require
+ *    additional dependencies. The volume is low (one run per command).
+ *
+ * ============================================================================
+ * CONSEQUENCES
+ * ============================================================================
+ *
+ * - Every synthesis run is fully auditable locally
+ * - The prompt sent to Claude Code is preserved for debugging
+ * - Platform receipts provide end-to-end traceability
+ * - `agentics inspect run <run-id>` works offline
+ * - The runs/ directory grows linearly; no automatic cleanup (user manages)
+ * - New decision-grade subcommands automatically get artifact persistence
+ *   if they follow the synthesis router integration pattern
+ */
+export {};
+//# sourceMappingURL=adr-008-synthesis-artifact-persistence.js.map

package/dist/contracts/adr-008-synthesis-artifact-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-008-synthesis-artifact-persistence.js","sourceRoot":"","sources":["../../src/contracts/adr-008-synthesis-artifact-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqLG"}

package/dist/contracts/adr-command-semantics.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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

package/dist/contracts/adr-command-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-command-semantics.d.ts","sourceRoot":"","sources":["../../src/contracts/adr-command-semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAMH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,kBAAkB,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,CAAC;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAMD,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAi0BzC,CAAC;AAMX;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAG,OAAgB,CAAC;AAMnD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAU3F;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAEtE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAIhF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAI/E;AAUD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CA0B5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAgBrF"}