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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/dist/adapters/base-adapter.d.ts +117 -0
  2. package/dist/adapters/base-adapter.d.ts.map +1 -1
  3. package/dist/adapters/base-adapter.js +143 -0
  4. package/dist/adapters/base-adapter.js.map +1 -1
  5. package/dist/auth/identity-resolver.d.ts +21 -0
  6. package/dist/auth/identity-resolver.d.ts.map +1 -0
  7. package/dist/auth/identity-resolver.js +68 -0
  8. package/dist/auth/identity-resolver.js.map +1 -0
  9. package/dist/auth/index.d.ts +2 -0
  10. package/dist/auth/index.d.ts.map +1 -1
  11. package/dist/auth/index.js +2 -0
  12. package/dist/auth/index.js.map +1 -1
  13. package/dist/auth/role-permissions.d.ts +12 -0
  14. package/dist/auth/role-permissions.d.ts.map +1 -0
  15. package/dist/auth/role-permissions.js +43 -0
  16. package/dist/auth/role-permissions.js.map +1 -0
  17. package/dist/cli/index.js +139 -134
  18. package/dist/cli/index.js.map +1 -1
  19. package/dist/commands/erp.d.ts.map +1 -1
  20. package/dist/commands/erp.js +62 -0
  21. package/dist/commands/erp.js.map +1 -1
  22. package/dist/commands/login.d.ts.map +1 -1
  23. package/dist/commands/login.js +25 -0
  24. package/dist/commands/login.js.map +1 -1
  25. package/dist/commands/logout.d.ts.map +1 -1
  26. package/dist/commands/logout.js +4 -1
  27. package/dist/commands/logout.js.map +1 -1
  28. package/dist/commands/plan.d.ts.map +1 -1
  29. package/dist/commands/plan.js +6 -5
  30. package/dist/commands/plan.js.map +1 -1
  31. package/dist/commands/simulate.d.ts.map +1 -1
  32. package/dist/commands/simulate.js +57 -1
  33. package/dist/commands/simulate.js.map +1 -1
  34. package/dist/commands/whoami.d.ts +4 -0
  35. package/dist/commands/whoami.d.ts.map +1 -1
  36. package/dist/commands/whoami.js +22 -5
  37. package/dist/commands/whoami.js.map +1 -1
  38. package/dist/contracts/adr-002-operational-enforcement.d.ts +684 -0
  39. package/dist/contracts/adr-002-operational-enforcement.d.ts.map +1 -0
  40. package/dist/contracts/adr-002-operational-enforcement.js +671 -0
  41. package/dist/contracts/adr-002-operational-enforcement.js.map +1 -0
  42. package/dist/contracts/adr-003-governance-architecture.d.ts +766 -0
  43. package/dist/contracts/adr-003-governance-architecture.d.ts.map +1 -0
  44. package/dist/contracts/adr-003-governance-architecture.js +773 -0
  45. package/dist/contracts/adr-003-governance-architecture.js.map +1 -0
  46. package/dist/contracts/adr-004-enterprise-integration-memory.d.ts +1150 -0
  47. package/dist/contracts/adr-004-enterprise-integration-memory.d.ts.map +1 -0
  48. package/dist/contracts/adr-004-enterprise-integration-memory.js +1158 -0
  49. package/dist/contracts/adr-004-enterprise-integration-memory.js.map +1 -0
  50. package/dist/contracts/adr-005-system-coherence-drift-self-governance.d.ts +1393 -0
  51. package/dist/contracts/adr-005-system-coherence-drift-self-governance.d.ts.map +1 -0
  52. package/dist/contracts/adr-005-system-coherence-drift-self-governance.js +1371 -0
  53. package/dist/contracts/adr-005-system-coherence-drift-self-governance.js.map +1 -0
  54. package/dist/contracts/adr-006-claude-code-synthesis-runner.d.ts +196 -0
  55. package/dist/contracts/adr-006-claude-code-synthesis-runner.d.ts.map +1 -0
  56. package/dist/contracts/adr-006-claude-code-synthesis-runner.js +177 -0
  57. package/dist/contracts/adr-006-claude-code-synthesis-runner.js.map +1 -0
  58. package/dist/contracts/adr-007-subcommand-synthesis-router.d.ts +273 -0
  59. package/dist/contracts/adr-007-subcommand-synthesis-router.d.ts.map +1 -0
  60. package/dist/contracts/adr-007-subcommand-synthesis-router.js +226 -0
  61. package/dist/contracts/adr-007-subcommand-synthesis-router.js.map +1 -0
  62. package/dist/contracts/adr-008-synthesis-artifact-persistence.d.ts +323 -0
  63. package/dist/contracts/adr-008-synthesis-artifact-persistence.d.ts.map +1 -0
  64. package/dist/contracts/adr-008-synthesis-artifact-persistence.js +184 -0
  65. package/dist/contracts/adr-008-synthesis-artifact-persistence.js.map +1 -0
  66. package/dist/contracts/adr-command-semantics.d.ts +150 -0
  67. package/dist/contracts/adr-command-semantics.d.ts.map +1 -0
  68. package/dist/contracts/adr-command-semantics.js +984 -0
  69. package/dist/contracts/adr-command-semantics.js.map +1 -0
  70. package/dist/contracts/index.d.ts +5 -0
  71. package/dist/contracts/index.d.ts.map +1 -1
  72. package/dist/contracts/index.js +16 -0
  73. package/dist/contracts/index.js.map +1 -1
  74. package/dist/enterprise/index.d.ts +16 -0
  75. package/dist/enterprise/index.d.ts.map +1 -0
  76. package/dist/enterprise/index.js +17 -0
  77. package/dist/enterprise/index.js.map +1 -0
  78. package/dist/enterprise/integration-registry.d.ts +73 -0
  79. package/dist/enterprise/integration-registry.d.ts.map +1 -0
  80. package/dist/enterprise/integration-registry.js +252 -0
  81. package/dist/enterprise/integration-registry.js.map +1 -0
  82. package/dist/enterprise/lineage.d.ts +73 -0
  83. package/dist/enterprise/lineage.d.ts.map +1 -0
  84. package/dist/enterprise/lineage.js +218 -0
  85. package/dist/enterprise/lineage.js.map +1 -0
  86. package/dist/gates/argument-guard.d.ts +39 -0
  87. package/dist/gates/argument-guard.d.ts.map +1 -0
  88. package/dist/gates/argument-guard.js +180 -0
  89. package/dist/gates/argument-guard.js.map +1 -0
  90. package/dist/gates/index.d.ts +5 -0
  91. package/dist/gates/index.d.ts.map +1 -1
  92. package/dist/gates/index.js +7 -0
  93. package/dist/gates/index.js.map +1 -1
  94. package/dist/gates/lineage-gate.d.ts +55 -0
  95. package/dist/gates/lineage-gate.d.ts.map +1 -0
  96. package/dist/gates/lineage-gate.js +127 -0
  97. package/dist/gates/lineage-gate.js.map +1 -0
  98. package/dist/mcp/mcp-server.d.ts +35 -0
  99. package/dist/mcp/mcp-server.d.ts.map +1 -0
  100. package/dist/mcp/mcp-server.js +692 -0
  101. package/dist/mcp/mcp-server.js.map +1 -0
  102. package/dist/modules/help-renderer.d.ts +25 -0
  103. package/dist/modules/help-renderer.d.ts.map +1 -0
  104. package/dist/modules/help-renderer.js +163 -0
  105. package/dist/modules/help-renderer.js.map +1 -0
  106. package/dist/modules/index.d.ts +1 -0
  107. package/dist/modules/index.d.ts.map +1 -1
  108. package/dist/modules/index.js +1 -0
  109. package/dist/modules/index.js.map +1 -1
  110. package/dist/runtime/claude-code-runner.d.ts +93 -0
  111. package/dist/runtime/claude-code-runner.d.ts.map +1 -0
  112. package/dist/runtime/claude-code-runner.js +588 -0
  113. package/dist/runtime/claude-code-runner.js.map +1 -0
  114. package/dist/runtime/index.d.ts +5 -0
  115. package/dist/runtime/index.d.ts.map +1 -0
  116. package/dist/runtime/index.js +5 -0
  117. package/dist/runtime/index.js.map +1 -0
  118. package/dist/server/index.d.ts +2 -0
  119. package/dist/server/index.d.ts.map +1 -1
  120. package/dist/server/index.js +16 -1
  121. package/dist/server/index.js.map +1 -1
  122. package/dist/server/routes/identity.d.ts +9 -0
  123. package/dist/server/routes/identity.d.ts.map +1 -0
  124. package/dist/server/routes/identity.js +100 -0
  125. package/dist/server/routes/identity.js.map +1 -0
  126. package/dist/server/routes/index.d.ts +2 -0
  127. package/dist/server/routes/index.d.ts.map +1 -1
  128. package/dist/server/routes/index.js +2 -0
  129. package/dist/server/routes/index.js.map +1 -1
  130. package/dist/server/routes/lineage.d.ts +15 -0
  131. package/dist/server/routes/lineage.d.ts.map +1 -0
  132. package/dist/server/routes/lineage.js +128 -0
  133. package/dist/server/routes/lineage.js.map +1 -0
  134. package/dist/synthesis/artifact-writer.d.ts +62 -0
  135. package/dist/synthesis/artifact-writer.d.ts.map +1 -0
  136. package/dist/synthesis/artifact-writer.js +603 -0
  137. package/dist/synthesis/artifact-writer.js.map +1 -0
  138. package/dist/synthesis/index.d.ts +7 -0
  139. package/dist/synthesis/index.d.ts.map +1 -0
  140. package/dist/synthesis/index.js +7 -0
  141. package/dist/synthesis/index.js.map +1 -0
  142. package/dist/synthesis/prompts/index.d.ts +50 -0
  143. package/dist/synthesis/prompts/index.d.ts.map +1 -0
  144. package/dist/synthesis/prompts/index.js +502 -0
  145. package/dist/synthesis/prompts/index.js.map +1 -0
  146. package/dist/synthesis/router.d.ts +70 -0
  147. package/dist/synthesis/router.d.ts.map +1 -0
  148. package/dist/synthesis/router.js +346 -0
  149. package/dist/synthesis/router.js.map +1 -0
  150. package/dist/types/index.d.ts +132 -0
  151. package/dist/types/index.d.ts.map +1 -1
  152. package/dist/utils/identity-store.d.ts +31 -0
  153. package/dist/utils/identity-store.d.ts.map +1 -0
  154. package/dist/utils/identity-store.js +97 -0
  155. package/dist/utils/identity-store.js.map +1 -0
  156. package/dist/utils/index.d.ts +2 -0
  157. package/dist/utils/index.d.ts.map +1 -1
  158. package/dist/utils/index.js +1 -0
  159. package/dist/utils/index.js.map +1 -1
  160. package/package.json +1 -1
@@ -0,0 +1,226 @@
1
+ /**
2
+ * ADR-007: Subcommand-Aware Synthesis Router
3
+ *
4
+ * STATUS: Proposed
5
+ * DATE: 2026-02-07
6
+ * AUTHORS: Platform Engineering
7
+ * DEPENDS-ON: ADR-001 (Command Semantics), ADR-006 (Claude Code Runner)
8
+ *
9
+ * ============================================================================
10
+ * CONTEXT
11
+ * ============================================================================
12
+ *
13
+ * ADR-001 defines a COMMAND_REGISTRY with synthesis governance classifications:
14
+ * - SYNTHESIS_REQUIRED: LLM invocation expected
15
+ * - SYNTHESIS_FORBIDDEN: Must NEVER trigger synthesis
16
+ * - COMMITMENT_GRADE: Requires ID + confirmation + synthesis
17
+ *
18
+ * The current CLI dispatches commands via a monolithic switch statement in
19
+ * src/cli/index.ts. Decision-grade subcommands call their respective
20
+ * command executors (executePlanCreateCommand, executeSimulateRunCommand, etc.)
21
+ * which talk to the platform API. The executive synthesis tool fires as an
22
+ * afterthought (fire-and-forget detached process).
23
+ *
24
+ * What's missing is a routing layer that sits BETWEEN argument parsing and
25
+ * command execution, intercepting decision-grade subcommands to:
26
+ * 1. Construct a subcommand-specific prompt
27
+ * 2. Call Claude Code Runner (ADR-006)
28
+ * 3. Validate the output
29
+ * 4. Feed it into the platform pipeline
30
+ *
31
+ * ============================================================================
32
+ * DECISION
33
+ * ============================================================================
34
+ *
35
+ * 1. A new module `src/synthesis/router.ts` will implement the synthesis
36
+ * routing layer.
37
+ *
38
+ * 2. The router takes a SynthesisRequest:
39
+ * ```typescript
40
+ * interface SynthesisRequest {
41
+ * command: string; // e.g. "simulate"
42
+ * subcommand: string; // e.g. "create"
43
+ * positionalArgs: string[]; // from parsed CLI args
44
+ * options: Record<string, string>;
45
+ * flags: Record<string, boolean>;
46
+ * userContext: {
47
+ * userId: string;
48
+ * orgId: string;
49
+ * traceId: string;
50
+ * };
51
+ * }
52
+ * ```
53
+ *
54
+ * 3. Routing logic:
55
+ * a. Look up (command, subcommand) in ADR-001 COMMAND_REGISTRY
56
+ * b. If synthesis === 'SYNTHESIS_FORBIDDEN', return null immediately
57
+ * c. If synthesis === 'SYNTHESIS_REQUIRED' or 'COMMITMENT_GRADE':
58
+ * i. Generate a run-id (UUID v4)
59
+ * ii. Load the prompt template for this (command, subcommand)
60
+ * iii. Inject arguments, context, run-id, and contract requirements
61
+ * iv. Call ClaudeCodeRunner.invoke()
62
+ * v. Return the validated SynthesisResult
63
+ *
64
+ * 4. SynthesisResult structure:
65
+ * ```typescript
66
+ * interface SynthesisResult<T> {
67
+ * data: T; // Contract-validated output
68
+ * runId: string; // UUID for this synthesis run
69
+ * command: string;
70
+ * subcommand: string;
71
+ * model: string; // Model used
72
+ * durationMs: number;
73
+ * contractSchema: string; // Schema name used for validation
74
+ * }
75
+ * ```
76
+ *
77
+ * 5. The router is a pure function with no side effects beyond calling
78
+ * ClaudeCodeRunner. It does NOT:
79
+ * - Write artifacts (that's ADR-008)
80
+ * - Call the platform API (that's the command executor)
81
+ * - Modify CLI state
82
+ *
83
+ * ============================================================================
84
+ * PROMPT TEMPLATE SYSTEM
85
+ * ============================================================================
86
+ *
87
+ * 1. Templates live in `src/synthesis/prompts/` as exported string constants
88
+ * (not .txt files — TypeScript provides compile-time safety and tree-shaking).
89
+ *
90
+ * 2. Each template is a function: (args: PromptArgs) => string
91
+ *
92
+ * 3. PromptArgs includes:
93
+ * - runId: string
94
+ * - seed: number
95
+ * - command: string
96
+ * - subcommand: string
97
+ * - positionalArgs: string[]
98
+ * - contractSchemaName: string
99
+ * - contractSchemaFields: string (human-readable field list)
100
+ *
101
+ * 4. Every template MUST include:
102
+ * - "Respond ONLY with a JSON object. No prose, no markdown, no explanation."
103
+ * - The exact contract schema name
104
+ * - The run-id and seed
105
+ * - The required fields for the output schema
106
+ *
107
+ * 5. Template naming: `{command}_{subcommand}` (e.g., simulate_create)
108
+ *
109
+ * ============================================================================
110
+ * DECISION-GRADE SUBCOMMAND MATRIX
111
+ * ============================================================================
112
+ *
113
+ * | Command | Subcommand | Synthesis Class | Contract Schema |
114
+ * |-----------|------------|----------------------|------------------|
115
+ * | simulate | create | SYNTHESIS_REQUIRED | simulation |
116
+ * | simulate | run | COMMITMENT_GRADE | simulation |
117
+ * | plan | create | SYNTHESIS_REQUIRED | plan |
118
+ * | plan | approve | COMMITMENT_GRADE | plan |
119
+ * | deploy | preview | SYNTHESIS_REQUIRED | intent |
120
+ * | deploy | run | COMMITMENT_GRADE | intent |
121
+ * | deploy | rollback | COMMITMENT_GRADE | intent |
122
+ * | export | terraform | SYNTHESIS_REQUIRED | export |
123
+ * | export | kubernetes | SYNTHESIS_REQUIRED | export |
124
+ * | export | erp | SYNTHESIS_REQUIRED | export |
125
+ * | policy | create | SYNTHESIS_REQUIRED | base |
126
+ * | policy | edit | SYNTHESIS_REQUIRED | base |
127
+ * | policy | enable | COMMITMENT_GRADE | base |
128
+ * | policy | disable | SYNTHESIS_REQUIRED | base |
129
+ * | policy | dry-run | SYNTHESIS_REQUIRED | base |
130
+ * | quantify | create | SYNTHESIS_REQUIRED | roiReport |
131
+ * | quantify | compare | COMMITMENT_GRADE | roiReport |
132
+ * | erp | surface | SYNTHESIS_REQUIRED | base |
133
+ * | erp | map | SYNTHESIS_REQUIRED | base |
134
+ * | erp | export | SYNTHESIS_REQUIRED | export |
135
+ *
136
+ * All other (command, subcommand) combinations return null from the router.
137
+ *
138
+ * ============================================================================
139
+ * INTEGRATION POINT
140
+ * ============================================================================
141
+ *
142
+ * The router is called from the CLI dispatch in src/cli/index.ts.
143
+ * The integration follows this pattern:
144
+ *
145
+ * ```typescript
146
+ * // In the command handler (e.g., simulate create)
147
+ * const synthesisResult = synthesisRouter.route({
148
+ * command: parsed.command,
149
+ * subcommand: parsed.subcommand,
150
+ * positionalArgs: parsed.positionalArgs,
151
+ * options: parsed.options,
152
+ * flags: parsed.flags,
153
+ * userContext: { userId, orgId, traceId },
154
+ * });
155
+ *
156
+ * if (synthesisResult) {
157
+ * // Decision-grade: use Claude Code output
158
+ * const platformResult = await executeWithSynthesis(synthesisResult);
159
+ * await persistArtifacts(synthesisResult, platformResult);
160
+ * } else {
161
+ * // Non-synthesis: proceed with existing command handler
162
+ * await executeExistingHandler(...);
163
+ * }
164
+ * ```
165
+ *
166
+ * ============================================================================
167
+ * ALTERNATIVES CONSIDERED
168
+ * ============================================================================
169
+ *
170
+ * A. Middleware-based routing (intercept all commands):
171
+ * Rejected — synthesis is the exception, not the rule. A middleware
172
+ * pattern would add overhead to every command, including the majority
173
+ * that are SYNTHESIS_FORBIDDEN.
174
+ *
175
+ * B. Prompt templates as external .txt files:
176
+ * Rejected — TypeScript functions provide compile-time safety,
177
+ * argument validation, and can reference contract types. External
178
+ * files would need a runtime loader and lose type safety.
179
+ *
180
+ * C. One giant prompt for all subcommands:
181
+ * Rejected — each subcommand has unique argument shapes, contract
182
+ * schemas, and domain-specific instructions. Specialized prompts
183
+ * produce better-structured output.
184
+ *
185
+ * ============================================================================
186
+ * CONSEQUENCES
187
+ * ============================================================================
188
+ *
189
+ * - Every decision-grade subcommand gets exactly one Claude Code call
190
+ * - Non-decision commands have zero synthesis overhead
191
+ * - Prompt templates are version-controlled and type-safe
192
+ * - New decision-grade subcommands require:
193
+ * a. ADR-001 COMMAND_REGISTRY entry with SYNTHESIS_REQUIRED/COMMITMENT_GRADE
194
+ * b. ADR-006 SYNTHESIS_SCHEMA_MAP entry
195
+ * c. A prompt template function in src/synthesis/prompts/
196
+ * d. CLI handler integration per the pattern above
197
+ * - The router is stateless and testable in isolation
198
+ */
199
+ /**
200
+ * The decision-grade subcommand set.
201
+ * This is the canonical list; any subcommand NOT in this set
202
+ * must NEVER trigger Claude Code invocation.
203
+ */
204
+ export const DECISION_GRADE_SUBCOMMANDS = new Set([
205
+ 'simulate.create',
206
+ 'simulate.run',
207
+ 'plan.create',
208
+ 'plan.approve',
209
+ 'deploy.preview',
210
+ 'deploy.run',
211
+ 'deploy.rollback',
212
+ 'export.terraform',
213
+ 'export.kubernetes',
214
+ 'export.erp',
215
+ 'policy.create',
216
+ 'policy.edit',
217
+ 'policy.enable',
218
+ 'policy.disable',
219
+ 'policy.dry-run',
220
+ 'quantify.create',
221
+ 'quantify.compare',
222
+ 'erp.surface',
223
+ 'erp.map',
224
+ 'erp.export',
225
+ ]);
226
+ //# sourceMappingURL=adr-007-subcommand-synthesis-router.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adr-007-subcommand-synthesis-router.js","sourceRoot":"","sources":["../../src/contracts/adr-007-subcommand-synthesis-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqMG;AAgFH;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAwB,IAAI,GAAG,CAAC;IACrE,iBAAiB;IACjB,cAAc;IACd,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,YAAY;IACZ,iBAAiB;IACjB,kBAAkB;IAClB,mBAAmB;IACnB,YAAY;IACZ,eAAe;IACf,aAAa;IACb,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,aAAa;IACb,SAAS;IACT,YAAY;CACb,CAAC,CAAC"}
@@ -0,0 +1,323 @@
1
+ /**
2
+ * ADR-008: Synthesis Artifact Persistence & Platform Handoff
3
+ *
4
+ * STATUS: Proposed
5
+ * DATE: 2026-02-07
6
+ * AUTHORS: Platform Engineering
7
+ * DEPENDS-ON: ADR-006 (Runner), ADR-007 (Router), ADR-004 (Enterprise Integration)
8
+ *
9
+ * ============================================================================
10
+ * CONTEXT
11
+ * ============================================================================
12
+ *
13
+ * After Claude Code synthesis produces a contract-validated JSON object
14
+ * (ADR-006 + ADR-007), two things must happen:
15
+ *
16
+ * 1. The result must be handed off to the platform (agentics-dev-platform)
17
+ * for execution, persistence, and governance tracking.
18
+ *
19
+ * 2. Local artifacts must be written for `agentics inspect` to read,
20
+ * providing an offline audit trail.
21
+ *
22
+ * Currently, artifacts are stored by the Ruvector-backed platform adapters
23
+ * (src/adapters/base-adapter.ts:643-1089) and local CRUD files live in
24
+ * .agentics/{command}s/ (e.g., .agentics/simulations/). The executive
25
+ * synthesis tool writes a decision-summary.md but nothing else.
26
+ *
27
+ * This ADR defines the persistence contract for synthesis runs.
28
+ *
29
+ * ============================================================================
30
+ * DECISION
31
+ * ============================================================================
32
+ *
33
+ * 1. A new module `src/synthesis/artifact-writer.ts` handles local persistence.
34
+ *
35
+ * 2. After every successful synthesis + platform handoff, the following
36
+ * artifacts are written:
37
+ *
38
+ * ```
39
+ * ~/.agentics/runs/<run-id>/
40
+ * ├── manifest.json # Run metadata (IDs, timing, command, schema)
41
+ * ├── claude_output.json # Raw Claude Code output (validated JSON)
42
+ * ├── platform_receipt.json # Platform API response (IDs, status)
43
+ * └── prompt.txt # The exact prompt sent to Claude Code
44
+ * ```
45
+ *
46
+ * 3. The manifest.json structure:
47
+ * ```typescript
48
+ * interface RunManifest {
49
+ * run_id: string;
50
+ * plan_id?: string; // If a plan was created
51
+ * deploy_id?: string; // If a deployment was created
52
+ * command: string;
53
+ * subcommand: string;
54
+ * synthesis_class: SynthesisClass;
55
+ * contract_schema: string;
56
+ * model: string;
57
+ * duration_ms: number;
58
+ * created_at: string;
59
+ * seed: number;
60
+ * user_id: string;
61
+ * org_id: string;
62
+ * trace_id: string;
63
+ * artifacts: string[]; // Relative paths to sibling files
64
+ * }
65
+ * ```
66
+ *
67
+ * 4. Platform handoff flow:
68
+ * a. Synthesis router returns SynthesisResult<T>
69
+ * b. The command handler passes the data to the existing platform adapter
70
+ * (PlannerAdapter, RunnerAdapter, etc.)
71
+ * c. The platform responds with IDs and status
72
+ * d. Artifact writer persists all three files atomically
73
+ * e. IDs are printed to stdout
74
+ *
75
+ * 5. The artifact writer is idempotent: writing the same run-id twice
76
+ * overwrites the previous artifacts (latest wins).
77
+ *
78
+ * 6. `agentics inspect run <run-id>` will be enhanced to read from
79
+ * `~/.agentics/runs/<run-id>/manifest.json` when the run is not
80
+ * found in the platform (offline inspection).
81
+ *
82
+ * ============================================================================
83
+ * ID GENERATION
84
+ * ============================================================================
85
+ *
86
+ * Every synthesis run produces:
87
+ * - run_id: `run-{uuid}` — unique per invocation
88
+ * - plan_id: `plan-{uuid}` — if the command creates a plan
89
+ * - deploy_id: `deploy-{uuid}` — if the command creates a deployment
90
+ *
91
+ * These are generated BEFORE calling Claude Code (so they can be embedded
92
+ * in the prompt for determinism) and then used as the canonical identifiers
93
+ * throughout the pipeline.
94
+ *
95
+ * ============================================================================
96
+ * STORAGE PATH
97
+ * ============================================================================
98
+ *
99
+ * Base directory: `~/.agentics/runs/`
100
+ * Override: `AGENTICS_RUNS_DIR` environment variable
101
+ *
102
+ * This is separate from the existing `.agentics/simulations/` and
103
+ * `.agentics/plans/` directories, which store CRUD records. The `runs/`
104
+ * directory stores synthesis-specific artifacts.
105
+ *
106
+ * ============================================================================
107
+ * FILE PERMISSIONS
108
+ * ============================================================================
109
+ *
110
+ * All files written with mode 0o600 (owner read/write only), matching
111
+ * the existing credentials.ts pattern (src/utils/credentials.ts:38-39).
112
+ *
113
+ * ============================================================================
114
+ * PLATFORM RECEIPT
115
+ * ============================================================================
116
+ *
117
+ * The platform_receipt.json captures the downstream response:
118
+ *
119
+ * ```typescript
120
+ * interface PlatformReceipt {
121
+ * success: boolean;
122
+ * platform_id: string; // ID assigned by platform
123
+ * platform_type: string; // e.g., "PlanReference", "SimulationReference"
124
+ * status: string; // e.g., "created", "queued", "completed"
125
+ * timestamp: string;
126
+ * trace_id: string;
127
+ * error?: string; // If platform call failed
128
+ * }
129
+ * ```
130
+ *
131
+ * ============================================================================
132
+ * WIRING INTO CLI DISPATCH
133
+ * ============================================================================
134
+ *
135
+ * The integration modifies the command handlers in src/cli/index.ts.
136
+ * For each decision-grade subcommand:
137
+ *
138
+ * ```
139
+ * BEFORE (current):
140
+ * parse args → validate gates → call command executor → print output
141
+ * → fire-and-forget synthesis
142
+ *
143
+ * AFTER (ADR-008):
144
+ * parse args → validate gates → synthesis router (Claude Code)
145
+ * → call command executor (with synthesis data)
146
+ * → persist artifacts
147
+ * → print IDs to stdout
148
+ * ```
149
+ *
150
+ * The key change: synthesis happens BEFORE the platform call, not after.
151
+ * Claude Code produces the structured plan/intent/config, which is then
152
+ * sent to the platform for execution.
153
+ *
154
+ * ============================================================================
155
+ * ALTERNATIVES CONSIDERED
156
+ * ============================================================================
157
+ *
158
+ * A. Store artifacts in the platform only (no local files):
159
+ * Rejected — offline inspection is a hard requirement. Users must be
160
+ * able to audit synthesis results without platform connectivity.
161
+ *
162
+ * B. Store artifacts in the existing .agentics/{command}s/ directories:
163
+ * Rejected — synthesis artifacts are cross-cutting (a simulation run
164
+ * may reference a plan). A dedicated `runs/` directory with run-id
165
+ * as the organizing key is cleaner.
166
+ *
167
+ * C. Use a SQLite database for local storage:
168
+ * Rejected — JSON files are simpler, greppable, and don't require
169
+ * additional dependencies. The volume is low (one run per command).
170
+ *
171
+ * ============================================================================
172
+ * CONSEQUENCES
173
+ * ============================================================================
174
+ *
175
+ * - Every synthesis run is fully auditable locally
176
+ * - The prompt sent to Claude Code is preserved for debugging
177
+ * - Platform receipts provide end-to-end traceability
178
+ * - `agentics inspect run <run-id>` works offline
179
+ * - The runs/ directory grows linearly; no automatic cleanup (user manages)
180
+ * - New decision-grade subcommands automatically get artifact persistence
181
+ * if they follow the synthesis router integration pattern
182
+ */
183
+ export interface RunManifest {
184
+ readonly run_id: string;
185
+ readonly plan_id?: string;
186
+ readonly deploy_id?: string;
187
+ readonly simulation_id?: string;
188
+ readonly command: string;
189
+ readonly subcommand: string;
190
+ readonly synthesis_class: 'SYNTHESIS_REQUIRED' | 'COMMITMENT_GRADE';
191
+ readonly contract_schema: string;
192
+ readonly model: string;
193
+ readonly duration_ms: number;
194
+ readonly created_at: string;
195
+ readonly seed: number;
196
+ readonly user_id: string;
197
+ readonly org_id: string;
198
+ readonly trace_id: string;
199
+ readonly artifacts: readonly string[];
200
+ }
201
+ export interface PlatformReceipt {
202
+ readonly success: boolean;
203
+ readonly platform_id: string;
204
+ readonly platform_type: string;
205
+ readonly status: string;
206
+ readonly timestamp: string;
207
+ readonly trace_id: string;
208
+ readonly error?: string;
209
+ }
210
+ export interface ArtifactWriterInput {
211
+ readonly manifest: RunManifest;
212
+ readonly claudeOutput: unknown;
213
+ readonly platformReceipt: PlatformReceipt;
214
+ readonly prompt: string;
215
+ }
216
+ /**
217
+ * Result of a successful artifact write operation.
218
+ * Contains the run directory path, file list, checksums, and byte count
219
+ * for verification and diagnostics.
220
+ */
221
+ export interface ArtifactWriteResult {
222
+ /** Absolute path to the run directory */
223
+ readonly runDir: string;
224
+ /** List of artifact filenames written (relative to runDir) */
225
+ readonly filesWritten: readonly string[];
226
+ /** SHA-256 checksums keyed by filename for integrity verification */
227
+ readonly checksums: Readonly<Record<string, string>>;
228
+ /** Total bytes written across all artifact files */
229
+ readonly bytesWritten: number;
230
+ }
231
+ /**
232
+ * Lightweight summary of a synthesis run for listing and filtering.
233
+ * Contains only the fields needed for discovery; use readManifest()
234
+ * to get the full RunManifest.
235
+ */
236
+ export interface RunSummary {
237
+ readonly run_id: string;
238
+ readonly command: string;
239
+ readonly subcommand: string;
240
+ readonly synthesis_class: 'SYNTHESIS_REQUIRED' | 'COMMITMENT_GRADE';
241
+ readonly created_at: string;
242
+ readonly model: string;
243
+ }
244
+ /**
245
+ * Options for listing synthesis runs with filtering and pagination.
246
+ */
247
+ export interface ListRunsOptions {
248
+ /** Maximum number of runs to return */
249
+ readonly limit?: number;
250
+ /** Number of runs to skip (for pagination) */
251
+ readonly offset?: number;
252
+ /** Filter to runs for this command */
253
+ readonly command?: string;
254
+ /** Filter to runs for this subcommand */
255
+ readonly subcommand?: string;
256
+ /** Sort order: true = newest first (default), false = oldest first */
257
+ readonly newestFirst?: boolean;
258
+ }
259
+ /** The four canonical artifact file types in every run directory */
260
+ export type ArtifactFileType = 'manifest' | 'claude_output' | 'platform_receipt' | 'prompt';
261
+ export interface IArtifactWriter {
262
+ /**
263
+ * Write all synthesis artifacts for a run.
264
+ * Creates the run directory and writes all four files atomically
265
+ * (temp-then-rename per file). Idempotent: re-writing the same
266
+ * run-id overwrites previous artifacts.
267
+ *
268
+ * @returns Write result with run directory path, checksums, and byte count
269
+ * @throws CLIError (ECLI-ART-001..003) on invalid input
270
+ * @throws CLIError (ECLI-ART-010..011) on serialization/size errors
271
+ * @throws CLIError (ECLI-ART-020..021) on I/O failures
272
+ */
273
+ write(input: ArtifactWriterInput): ArtifactWriteResult;
274
+ /**
275
+ * Read a run manifest by run-id.
276
+ * @returns The manifest or null if not found or unreadable
277
+ */
278
+ readManifest(runId: string): RunManifest | null;
279
+ /**
280
+ * Read the platform receipt for a run.
281
+ * @returns The receipt or null if not found or unreadable
282
+ */
283
+ readReceipt(runId: string): PlatformReceipt | null;
284
+ /**
285
+ * Read the raw Claude Code output for a run.
286
+ * @returns The parsed JSON output or null if not found or unreadable
287
+ */
288
+ readClaudeOutput(runId: string): unknown;
289
+ /**
290
+ * Read the prompt text that was sent to Claude Code for a run.
291
+ * @returns The prompt string or null if not found or unreadable
292
+ */
293
+ readPrompt(runId: string): string | null;
294
+ /**
295
+ * List synthesis runs with optional filtering and pagination.
296
+ * Reads manifest files from the runs directory, sorted by created_at.
297
+ * @returns Array of run summaries (may be empty if no runs or directory missing)
298
+ */
299
+ listRuns(options?: ListRunsOptions): RunSummary[];
300
+ /**
301
+ * Check if a run exists (has a readable manifest file).
302
+ * Fast stat-based check without reading the full manifest.
303
+ */
304
+ runExists(runId: string): boolean;
305
+ /**
306
+ * Get the base directory for all runs.
307
+ */
308
+ getRunsDir(): string;
309
+ /**
310
+ * Get the absolute path to a specific run's directory.
311
+ * Validates the run-id format and prevents path traversal.
312
+ * @throws CLIError (ECLI-ART-001..002) on invalid run-id
313
+ */
314
+ getRunDir(runId: string): string;
315
+ /**
316
+ * Delete a run and all its artifacts.
317
+ * Removes the entire run directory recursively.
318
+ * @returns true if the run was deleted, false if not found
319
+ * @throws CLIError (ECLI-ART-001..002) on invalid run-id
320
+ */
321
+ deleteRun(runId: string): boolean;
322
+ }
323
+ //# sourceMappingURL=adr-008-synthesis-artifact-persistence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adr-008-synthesis-artifact-persistence.d.ts","sourceRoot":"","sources":["../../src/contracts/adr-008-synthesis-artifact-persistence.ts"],"names":[],"mappings":"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"}