ai-engineering-loop 2.1.0 → 2.3.0

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 (108) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  7. package/.claude/agents/judge.md +5 -2
  8. package/.grok/agents/judge.md +5 -2
  9. package/CHANGELOG.md +46 -0
  10. package/agents/maker.md +1 -1
  11. package/agents/shared/judge.body.md +5 -2
  12. package/bin/ai-engineering-loop.js +303 -77
  13. package/core/definition-of-done.md +2 -2
  14. package/core/escalation-policy.md +1 -1
  15. package/core/goal-contract.md +1 -1
  16. package/core/iteration-policy.md +2 -1
  17. package/core/judge-policy.md +10 -4
  18. package/core/local-workflow-studio.md +12 -7
  19. package/core/orchestration-model.md +8 -7
  20. package/core/repo-config-schema.md +2 -2
  21. package/core/runtime-safety.md +3 -3
  22. package/lib/auto-update.js +8 -14
  23. package/lib/claimed-vs-reality.js +2 -2
  24. package/lib/cli-args.js +3 -1
  25. package/lib/docs.js +1 -1
  26. package/lib/doctor.js +0 -6
  27. package/lib/escalation.js +1 -1
  28. package/lib/fsutil.js +88 -0
  29. package/lib/gates.js +69 -27
  30. package/lib/generate-workflow.js +0 -29
  31. package/lib/goal-runtime.js +3 -2
  32. package/lib/guard-hooks.js +26 -7
  33. package/lib/guard.js +100 -10
  34. package/lib/hosts/doctor.js +1 -5
  35. package/lib/impact-map.js +4 -9
  36. package/lib/jsonl-ledger.js +104 -0
  37. package/lib/learn.js +4 -9
  38. package/lib/loop-groups.js +0 -25
  39. package/lib/migrations.js +1 -5
  40. package/lib/no-progress.js +119 -0
  41. package/lib/node-evidence.js +873 -0
  42. package/lib/orchestration.js +5 -361
  43. package/lib/personal-workflow.js +1 -1
  44. package/lib/quick.js +152 -0
  45. package/lib/receipt.js +1 -5
  46. package/lib/recipe-builder.js +3 -35
  47. package/lib/recipe-graph.js +2 -63
  48. package/lib/recipe.js +2 -4
  49. package/lib/review-ingest.js +116 -0
  50. package/lib/run-abandon.js +2 -1
  51. package/lib/run-checkout.js +8 -13
  52. package/lib/run-compaction.js +4 -12
  53. package/lib/run-interactions.js +16 -71
  54. package/lib/run-lifecycle.js +25 -77
  55. package/lib/run-state.js +68 -17
  56. package/lib/run-watcher.js +11 -14
  57. package/lib/runtime-files.js +45 -1
  58. package/lib/safe-context.js +17 -6
  59. package/lib/sandbox.js +2 -1
  60. package/lib/smart-context.js +3 -13
  61. package/lib/spawn-command.js +94 -0
  62. package/lib/studio-layout.js +2 -8
  63. package/lib/studio-runtime.js +2 -1
  64. package/lib/studio-server.js +25 -5
  65. package/lib/tier.js +36 -10
  66. package/lib/user-state.js +2 -17
  67. package/lib/verification-lanes.js +115 -0
  68. package/lib/verification-recorder.js +110 -22
  69. package/lib/workflow-runtime.js +7 -4
  70. package/package.json +1 -2
  71. package/policies/review-budget.md +1 -1
  72. package/studio/app.js +734 -132
  73. package/studio/index.html +13 -4
  74. package/studio/styles.css +75 -20
  75. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  76. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  77. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  78. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  79. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  80. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  81. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  82. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  83. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  84. package/.claude/skills/animate/RECIPES.md +0 -324
  85. package/.claude/skills/animate/SKILL.md +0 -207
  86. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  87. package/.claude/skills/animate-expo/SKILL.md +0 -263
  88. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  89. package/.claude/skills/apple-design/SKILL.md +0 -290
  90. package/.claude/skills/ask-sonner/API.md +0 -64
  91. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  92. package/.claude/skills/backend-development/SKILL.md +0 -272
  93. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  94. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  95. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  96. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  97. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  98. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  99. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  100. package/.claude/skills/improve-animations/SKILL.md +0 -109
  101. package/.claude/skills/mobile-native/SKILL.md +0 -311
  102. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  103. package/.claude/skills/prototype/PICKER.md +0 -197
  104. package/.claude/skills/prototype/SKILL.md +0 -98
  105. package/.claude/skills/review-animations/SKILL.md +0 -120
  106. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  107. package/.claude/skills/write-swift/SKILL.md +0 -396
  108. package/lib/intern-catalog.js +0 -53
@@ -17,7 +17,6 @@
17
17
  * and must NEVER be used as the Devil's Advocate or Judge.
18
18
  */
19
19
 
20
- const crypto = require('crypto');
21
20
  const fs = require('fs');
22
21
  const path = require('path');
23
22
 
@@ -66,219 +65,12 @@ const EXECUTION_MODE_ALIASES = {
66
65
  ARTIFACT_ISOLATED_REVIEW: 'CONTEXT_ISOLATION_ONLY'
67
66
  };
68
67
 
69
- const GROK_FORBIDDEN_REVIEW_TYPES = [
70
- 'caveman:cavecrew-reviewer',
71
- 'caveman:cavecrew-builder',
72
- 'caveman:cavecrew-investigator',
73
- 'explore',
74
- 'plan'
75
- ];
76
-
77
68
  function resolveExecutionModeId(modeId) {
78
69
  if (!modeId) return 'UNAVAILABLE';
79
70
  return EXECUTION_MODE_ALIASES[modeId] || modeId;
80
71
  }
81
-
82
- /**
83
- * 2. Standardized Capability Evidence Factory with 3-Stage Lifecycle
84
- */
85
- function createCapabilityEvidence({
86
- mechanism,
87
- classification,
88
- configurationSupported = false,
89
- invocationAvailable = false,
90
- executionProven = false,
91
- available = false,
92
- commandOrApi = null,
93
- result = null,
94
- executionIdentity = null,
95
- conversationId = null,
96
- parentConversationId = null,
97
- childConversationId = null,
98
- childModelResponse = null,
99
- modelExecutionProven = false,
100
- independentContextProven = false,
101
- historyInherited = null,
102
- isDocumentationOnly = false,
103
- isBrowserAutomationOnly = false,
104
- reason = null,
105
- timestamp = new Date().toISOString()
106
- }) {
107
- if (!mechanism || !classification) {
108
- throw new Error('Capability evidence must include mechanism and classification');
109
- }
110
-
111
- const modelExecuted = Boolean(modelExecutionProven || (childModelResponse && executionIdentity));
112
- const fullyProven = Boolean(executionProven || (modelExecuted && childConversationId && independentContextProven));
113
-
114
- return {
115
- mechanism,
116
- classification,
117
- configurationSupported: Boolean(configurationSupported),
118
- invocationAvailable: Boolean(invocationAvailable),
119
- executionProven: fullyProven,
120
- available: Boolean(available || fullyProven),
121
- commandOrApi,
122
- result,
123
- executionIdentity,
124
- conversationId,
125
- parentConversationId,
126
- childConversationId,
127
- childModelResponse,
128
- modelExecutionProven: modelExecuted,
129
- independentContextProven: Boolean(independentContextProven),
130
- historyInherited,
131
- isDocumentationOnly: Boolean(isDocumentationOnly),
132
- isBrowserAutomationOnly: Boolean(isBrowserAutomationOnly),
133
- reason,
134
- timestamp
135
- };
136
- }
137
-
138
72
  /**
139
- * 3. Evaluate whether a capability candidate satisfies execution proof
140
- */
141
- function isCapabilityProvenForMode(evidence, targetModeId) {
142
- if (!evidence) {
143
- return false;
144
- }
145
-
146
- // Reject non-agent capabilities (such as IPC send-message)
147
- if (
148
- evidence.classification === 'NOT_AN_AGENT_EXECUTION_CAPABILITY' ||
149
- evidence.classification === 'IPC_MESSAGE_DISPATCH'
150
- ) {
151
- return false;
152
- }
153
-
154
- // Reject browser automation tools (browser_subagent is NOT an LLM subagent)
155
- if (evidence.isBrowserAutomationOnly || evidence.classification === 'BROWSER_AUTOMATION_TOOL') {
156
- return false;
157
- }
158
-
159
- // Reject compressed review presets that do not emit the Finding Ledger schema
160
- if (
161
- evidence.classification === 'GROK_COMPRESSED_REVIEW_PRESET' ||
162
- GROK_FORBIDDEN_REVIEW_TYPES.includes(evidence.mechanism) ||
163
- GROK_FORBIDDEN_REVIEW_TYPES.includes(evidence.commandOrApi)
164
- ) {
165
- return false;
166
- }
167
-
168
- // Reject documentation-only or configuration-only claims
169
- if (evidence.isDocumentationOnly || (evidence.configurationSupported && !evidence.executionProven)) {
170
- if (targetModeId !== 'CONTEXT_ISOLATION_ONLY') {
171
- return false;
172
- }
173
- }
174
-
175
- // Modes requiring true independent LLM execution
176
- if (
177
- targetModeId === 'TRUE_INDEPENDENT_AGENT' ||
178
- targetModeId === 'ISOLATED_AGENT_INSTANCE' ||
179
- targetModeId === 'FRESH_PROCESS_AGENT'
180
- ) {
181
- // Must satisfy all 4 pillars of execution proof:
182
- const hasChildSession = Boolean(evidence.childConversationId || targetModeId === 'FRESH_PROCESS_AGENT');
183
- const hasModelResponse = Boolean(evidence.modelExecutionProven || evidence.childModelResponse);
184
- const hasExecIdentity = Boolean(evidence.executionIdentity);
185
- const hasCleanContext = Boolean(evidence.independentContextProven && evidence.historyInherited !== true);
186
-
187
- if (!evidence.executionProven && !(hasChildSession && hasModelResponse && hasExecIdentity && hasCleanContext)) {
188
- return false;
189
- }
190
- }
191
-
192
- // Context isolation mode requires verified artifact boundary
193
- if (targetModeId === 'CONTEXT_ISOLATION_ONLY') {
194
- return evidence.available === true;
195
- }
196
-
197
- return true;
198
- }
199
-
200
- /**
201
- * 4. Deterministic Execution Mode Selection
202
- * Evaluates registry strictly in priority order:
203
- * 1. TRUE_INDEPENDENT_AGENT
204
- * 2. ISOLATED_AGENT_INSTANCE
205
- * 3. FRESH_PROCESS_AGENT
206
- * 4. CONTEXT_ISOLATION_ONLY
207
- * 5. UNAVAILABLE
208
- */
209
- function selectExecutionMode(capabilityRegistry = {}) {
210
- const {
211
- nativeSubagent,
212
- sdkAgent,
213
- headlessProcessAgent,
214
- artifactIsolation
215
- } = capabilityRegistry;
216
-
217
- // Priority 1: True Native Independent Sub-Agent
218
- if (isCapabilityProvenForMode(nativeSubagent, 'TRUE_INDEPENDENT_AGENT')) {
219
- return EXECUTION_MODES.TRUE_INDEPENDENT_AGENT;
220
- }
221
-
222
- // Priority 2: Programmatic SDK Agent Instance
223
- if (isCapabilityProvenForMode(sdkAgent, 'ISOLATED_AGENT_INSTANCE')) {
224
- return EXECUTION_MODES.ISOLATED_AGENT_INSTANCE;
225
- }
226
-
227
- // Priority 3: Headless Subprocess Agent
228
- if (isCapabilityProvenForMode(headlessProcessAgent, 'FRESH_PROCESS_AGENT')) {
229
- return EXECUTION_MODES.FRESH_PROCESS_AGENT;
230
- }
231
-
232
- // Priority 4: Guaranteed Fallback - Context Isolation Only
233
- if (isCapabilityProvenForMode(artifactIsolation, 'CONTEXT_ISOLATION_ONLY')) {
234
- return EXECUTION_MODES.CONTEXT_ISOLATION_ONLY;
235
- }
236
-
237
- // Priority 5: Unavailable
238
- return EXECUTION_MODES.UNAVAILABLE;
239
- }
240
-
241
- /**
242
- * 5. Build Clean-Slate Artifact Isolation Barrier
243
- */
244
- function buildReviewContextBarrier({
245
- goalContract,
246
- gitDiff,
247
- verificationLogs,
248
- projectContext,
249
- activeIteration = 1,
250
- priorFindingSignatures = []
251
- }) {
252
- if (!goalContract || !gitDiff) {
253
- throw new Error('Goal contract and git diff are mandatory for review barrier');
254
- }
255
-
256
- return {
257
- iteration: activeIteration,
258
- diffHash: crypto.createHash('sha256').update(gitDiff).digest('hex').slice(0, 16),
259
- goalContract: {
260
- objective: goalContract.objective,
261
- acceptanceCriteria: goalContract.acceptanceCriteria || [],
262
- technicalConstraints: goalContract.technicalConstraints || [],
263
- outOfScope: goalContract.outOfScope || []
264
- },
265
- projectContext: {
266
- profile: projectContext?.profile || 'standard',
267
- architecture: projectContext?.architecture || '',
268
- conventions: projectContext?.conventions || '',
269
- verificationCommands: projectContext?.verificationCommands || ''
270
- },
271
- gitDiff: gitDiff.trim(),
272
- verificationLogs: {
273
- exitCode: verificationLogs?.exitCode ?? 0,
274
- summary: verificationLogs?.summary || 'Deterministic checks passed 100%'
275
- },
276
- priorFindingSignatures: [...priorFindingSignatures]
277
- };
278
- }
279
-
280
- /**
281
- * 6. Validate Verification Evidence Contract
73
+ * 2. Validate Verification Evidence Contract
282
74
  */
283
75
  function validateVerificationEvidence(evidence) {
284
76
  if (!evidence) return { valid: false, reason: 'Evidence object missing' };
@@ -310,7 +102,7 @@ function validateVerificationEvidence(evidence) {
310
102
  }
311
103
 
312
104
  /**
313
- * 7. Validate Finding Ledger Schema
105
+ * 3. Validate Finding Ledger Schema
314
106
  */
315
107
  function validateFindingLedger(ledger) {
316
108
  if (!ledger || !Array.isArray(ledger.findings)) {
@@ -365,7 +157,7 @@ function isBlockingFinding(finding) {
365
157
  }
366
158
 
367
159
  /**
368
- * 8. Compute Judge Verdict based primarily on Validity + Severity, then review axis
160
+ * 4. Compute Judge Verdict based primarily on Validity + Severity, then review axis
369
161
  */
370
162
  function computeJudgeVerdict({
371
163
  goalContract,
@@ -432,7 +224,7 @@ function computeJudgeVerdict({
432
224
  }
433
225
 
434
226
  /**
435
- * 9. Detect Grok CLI as a host runtime.
227
+ * 5. Detect Grok CLI as a host runtime.
436
228
  * Presence of the grok binary is CONFIGURATION_SUPPORTED.
437
229
  * GROK_SUBAGENTS=0 means invocation is disabled even if grok is installed.
438
230
  * Execution is never proven from detection alone.
@@ -484,161 +276,13 @@ function detectGrokRuntime(env = process.env, fsApi = fs) {
484
276
  };
485
277
  }
486
278
 
487
- /**
488
- * 10. Build capability evidence for Grok spawn_subagent.
489
- * Independent context is proven only when the child did not resume a Maker transcript.
490
- */
491
- function createGrokCapabilityEvidence({
492
- invocationAvailable = false,
493
- executionProven = false,
494
- childConversationId = null,
495
- childModelResponse = null,
496
- executionIdentity = null,
497
- independentContextProven = false,
498
- historyInherited = null,
499
- resumeFrom = null,
500
- reason = null
501
- } = {}) {
502
- const resumedMaker = Boolean(resumeFrom);
503
- const inherited = historyInherited === true || resumedMaker;
504
- const modelExecuted = Boolean(executionProven || childModelResponse);
505
- const fullyProven = Boolean(
506
- modelExecuted &&
507
- childConversationId &&
508
- executionIdentity &&
509
- independentContextProven &&
510
- !inherited
511
- );
512
-
513
- return createCapabilityEvidence({
514
- mechanism: 'grok-spawn_subagent',
515
- classification: fullyProven
516
- ? 'TRUE_INDEPENDENT_AGENT'
517
- : invocationAvailable
518
- ? 'INVOCATION_AVAILABLE'
519
- : 'CONFIGURATION_SUPPORTED_WITHOUT_INVOCATION_TOOL',
520
- configurationSupported: true,
521
- invocationAvailable: Boolean(invocationAvailable),
522
- executionProven: fullyProven,
523
- available: Boolean(invocationAvailable || fullyProven),
524
- commandOrApi: 'spawn_subagent',
525
- childConversationId,
526
- childModelResponse,
527
- executionIdentity,
528
- modelExecutionProven: modelExecuted,
529
- independentContextProven: Boolean(independentContextProven && !inherited),
530
- historyInherited: inherited ? true : historyInherited,
531
- reason: reason || (resumedMaker
532
- ? 'resume_from inherits the source transcript; Devil\'s Advocate and Judge must spawn fresh'
533
- : null)
534
- });
535
- }
536
-
537
- /**
538
- * 11. Grok spawn plan for Devil's Advocate / Judge.
539
- * Parent orchestrator spawns children; children must not spawn children (depth 1).
540
- * Never pass resume_from. Never use cavecrew-reviewer (wrong output schema).
541
- */
542
- function buildGrokReviewSpawnPlan({
543
- role,
544
- iteration = 1,
545
- artifactPaths = {}
546
- } = {}) {
547
- if (role !== 'devil-advocate' && role !== 'judge') {
548
- throw new Error('Grok review spawn role must be devil-advocate or judge');
549
- }
550
-
551
- return {
552
- tool: 'spawn_subagent',
553
- subagent_type: role,
554
- fallback_subagent_type: 'general-purpose',
555
- description: role === 'judge'
556
- ? `[judge] evaluate iteration ${iteration}`
557
- : `[devil-advocate] review iteration ${iteration}`,
558
- background: false,
559
- capability_mode: 'execute',
560
- isolation: 'none',
561
- resume_from: null,
562
- forbidden_types: [...GROK_FORBIDDEN_REVIEW_TYPES],
563
- artifactPaths: {
564
- goalContract: artifactPaths.goalContract || null,
565
- gitDiff: artifactPaths.gitDiff || null,
566
- verificationLogs: artifactPaths.verificationLogs || null,
567
- projectContext: artifactPaths.projectContext || '.ai-engineering-loop/',
568
- findingLedger: artifactPaths.findingLedger || null
569
- }
570
- };
571
- }
572
-
573
- /**
574
- * 12. Truthful Review Report Generator
575
- * Enforces mandatory reporting headers and strictly prevents misleading phrasing.
576
- * When a non-independent mode is reported although native subagent invocation
577
- * is AVAILABLE, the Execution Mode line must carry the reason (#57), so the
578
- * header never looks contradictory.
579
- */
580
- const DEFAULT_ISOLATION_REASON = 'subagent available but no reviewer subagent returned its own result';
581
-
582
- function formatExecutionReport({ selectedMode, capabilityRegistry = {}, reason = null }) {
583
- const isContextOnly = selectedMode.id === EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id;
584
- const nativeAvailable = Boolean(capabilityRegistry.nativeSubagent?.invocationAvailable);
585
- const nativeSubagentState = nativeAvailable ? 'AVAILABLE' : 'UNAVAILABLE';
586
- const needsReason = !selectedMode.isIndependentExecutionProven && (nativeAvailable || reason);
587
- const why = String(reason || '').trim() || DEFAULT_ISOLATION_REASON;
588
-
589
- const lines = [
590
- `Execution Mode: ${selectedMode.id}${needsReason ? ` (reason: ${why})` : ''}`,
591
- `Independent LLM Execution: ${selectedMode.isIndependentExecutionProven ? 'PROVEN' : 'NOT PROVEN'}`,
592
- `Native Subagent Invocation: ${nativeSubagentState}`,
593
- `Review Method: ${isContextOnly ? 'Clean-Slate Artifact Isolation Barrier' : selectedMode.label}`
594
- ];
595
-
596
- return lines.join('\n');
597
- }
598
-
599
- /**
600
- * 13. REPORT_ONLY (recipe `audit`) review policy (#57).
601
- * A report-only audit has no Maker diff and no Judge, but its findings still
602
- * benefit from one independent challenge when it is cheap: if the host can
603
- * invoke a native subagent, spawn ONE fresh `devil-advocate` sibling on
604
- * report.json before `gate report` (no Judge, no iteration loop). Otherwise the
605
- * same check runs in-session as CONTEXT_ISOLATION_ONLY with an explicit reason.
606
- */
607
- function reportOnlyReviewPlan(capabilityRegistry = {}) {
608
- const nativeAvailable = Boolean(capabilityRegistry.nativeSubagent?.invocationAvailable);
609
- if (nativeAvailable) {
610
- return {
611
- spawn: 'devil-advocate',
612
- judge: false,
613
- expectedMode: EXECUTION_MODES.TRUE_INDEPENDENT_AGENT.id,
614
- reason: null
615
- };
616
- }
617
- return {
618
- spawn: null,
619
- judge: false,
620
- expectedMode: EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id,
621
- reason: 'no native subagent tool in this session'
622
- };
623
- }
624
-
625
279
  module.exports = {
626
280
  EXECUTION_MODES,
627
281
  EXECUTION_MODE_ALIASES,
628
- GROK_FORBIDDEN_REVIEW_TYPES,
629
282
  resolveExecutionModeId,
630
- createCapabilityEvidence,
631
- isCapabilityProvenForMode,
632
- selectExecutionMode,
633
- buildReviewContextBarrier,
634
283
  validateVerificationEvidence,
635
284
  validateFindingLedger,
636
285
  isBlockingFinding,
637
286
  computeJudgeVerdict,
638
- formatExecutionReport,
639
- reportOnlyReviewPlan,
640
- DEFAULT_ISOLATION_REASON,
641
- detectGrokRuntime,
642
- createGrokCapabilityEvidence,
643
- buildGrokReviewSpawnPlan
287
+ detectGrokRuntime
644
288
  };
@@ -6,6 +6,7 @@
6
6
 
7
7
  const fs = require('fs');
8
8
  const path = require('path');
9
+ const { ACTOR_ID } = require('./fsutil.js');
9
10
  const { redactHomePaths, redactSecrets } = require('./safe-context.js');
10
11
  const {
11
12
  homeDir,
@@ -41,7 +42,6 @@ const SUGGEST_RATIO = 0.8;
41
42
  const RISK_WINDOW = 10;
42
43
  const RISK_COUNT = 4;
43
44
  const LEARNING_MIN = 3;
44
- const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
45
45
  const LEARNING_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
46
46
  const GATE_ID = /^[a-z0-9-]{1,40}$/;
47
47
  const BACKBONE_TYPES = new Set([
package/lib/quick.js ADDED
@@ -0,0 +1,152 @@
1
+ 'use strict';
2
+
3
+ // `quick start|finish`: the T0 path in two calls. Each step is the regular
4
+ // CLI command run as a child process, so every gate behaves exactly as in the
5
+ // long form; quick only removes the hand-written glue between them.
6
+
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+ const { spawnSync } = require('child_process');
10
+ const { extractChangedPaths } = require('./escalation.js');
11
+
12
+ const CLI = path.join(__dirname, '..', 'bin', 'ai-engineering-loop.js');
13
+ const CLAIMED_PATH = '.ai-engineering-loop/tasks/claimed-vs-reality.md';
14
+
15
+ function quickError(message, code, details = []) {
16
+ return Object.assign(new Error(message), { code, details });
17
+ }
18
+
19
+ function invoke(rootDir, args) {
20
+ const result = spawnSync(process.execPath, [CLI, ...args, '--json'], {
21
+ cwd: rootDir,
22
+ env: { ...process.env, AEL_NO_AUTO_UPDATE: '1' },
23
+ encoding: 'utf8',
24
+ maxBuffer: 64 * 1024 * 1024
25
+ });
26
+ const lines = String(result.stdout || '').trim().split('\n');
27
+ let parsed = null;
28
+ for (let index = lines.length - 1; index >= 0 && !parsed; index -= 1) {
29
+ try {
30
+ parsed = JSON.parse(lines.slice(index).join('\n'));
31
+ } catch {
32
+ // keep widening until the trailing JSON document parses
33
+ }
34
+ }
35
+ if (result.status !== 0 || !parsed || parsed.ok === false) {
36
+ const message = parsed?.error || String(result.stderr || result.stdout || 'command failed').trim().split('\n').pop();
37
+ throw quickError(`\`${args.slice(0, 2).join(' ')}\` failed: ${message}`, parsed?.code || 'QUICK_STEP_FAILED', parsed?.details || []);
38
+ }
39
+ return parsed;
40
+ }
41
+
42
+ function oneLine(value, limit = 300) {
43
+ return String(value || '').replace(/\|/g, '/').replace(/\s+/g, ' ').trim().slice(0, limit);
44
+ }
45
+
46
+ function quickGoal(runId, task) {
47
+ return {
48
+ schemaVersion: 1,
49
+ runId,
50
+ objective: oneLine(task, 500),
51
+ acceptanceCriteria: [{
52
+ id: 'AC-1',
53
+ statement: `The change does exactly what the task says: ${oneLine(task, 200)}`,
54
+ evidenceRequired: 'verify command output (exit 0) and the gated diff',
55
+ failureCases: [
56
+ 'files unrelated to the task are changed',
57
+ 'the verification command fails'
58
+ ]
59
+ }],
60
+ derivedBy: 'quick start (T0)'
61
+ };
62
+ }
63
+
64
+ function startQuick(rootDir, { task, mode = null } = {}) {
65
+ if (!String(task || '').trim()) throw quickError('quick start needs a task: quick start "<task>"', 'INVALID_USAGE');
66
+ const run = invoke(rootDir, ['run', '--new', ...(mode ? ['--mode', mode] : []), task]);
67
+ if (run.tier !== 'T0') {
68
+ return {
69
+ ok: true,
70
+ runId: run.runId,
71
+ tier: run.tier,
72
+ quick: false,
73
+ learnings: run.learnings || [],
74
+ next: `Tier ${run.tier} is not trivial; continue the normal loop for Run ${run.runId} (Goal Contract, Maker, verify, review).`
75
+ };
76
+ }
77
+ const runDir = path.join(rootDir, '.ai-engineering-loop', 'runs', run.runId);
78
+ fs.writeFileSync(path.join(runDir, 'goal-contract.json'), `${JSON.stringify(quickGoal(run.runId, task), null, 2)}\n`, { mode: 0o600 });
79
+ const gate = invoke(rootDir, ['gate', 'goal', '--run', run.runId]);
80
+ return {
81
+ ok: true,
82
+ runId: run.runId,
83
+ tier: 'T0',
84
+ quick: true,
85
+ state: gate.state,
86
+ learnings: run.learnings || [],
87
+ next: `Make the change, then: npx ai-engineering-loop quick finish --run ${run.runId}`
88
+ };
89
+ }
90
+
91
+ function writeClaimedVsReality(rootDir, { changedPaths, commands }) {
92
+ const reality = commands
93
+ .map((c) => `\`${oneLine(c.command, 120)}\` exit ${c.exitCode}${c.testCounts ? ` (${c.testCounts.passed ?? '?'} passed, ${c.testCounts.failed ?? 0} failed)` : ''}`)
94
+ .join('; ');
95
+ const claimed = `Changed ${changedPaths.length} file(s): ${changedPaths.slice(0, 10).join(', ')}${changedPaths.length > 10 ? ', …' : ''}`;
96
+ const text = [
97
+ '# Claimed vs Reality',
98
+ '',
99
+ '> Written by `quick finish` from the gated diff and the recorded verification output.',
100
+ '',
101
+ '| AC | Claimed | Reality from command log |',
102
+ '|---|---|---|',
103
+ `| AC-1 | ${oneLine(claimed, 600)} | ${oneLine(reality, 600)} |`,
104
+ ''
105
+ ].join('\n');
106
+ const filePath = path.join(rootDir, CLAIMED_PATH);
107
+ fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
108
+ fs.writeFileSync(filePath, text, { mode: 0o600 });
109
+ return CLAIMED_PATH;
110
+ }
111
+
112
+ function finishQuick(rootDir, { runId, commands = [], shell = false, serial = false, timeoutMs = null } = {}) {
113
+ const runArgs = runId ? ['--run', runId] : [];
114
+ const maker = invoke(rootDir, ['gate', 'maker', '--from-git', ...runArgs]);
115
+ const id = maker.runId;
116
+ if (maker.tier && maker.tier !== 'T0') {
117
+ return {
118
+ ok: false,
119
+ code: 'TIER_RAISED',
120
+ runId: id,
121
+ tier: maker.tier,
122
+ state: maker.state,
123
+ next: `The diff raised the tier to ${maker.tier}. Continue the normal loop: verify --run ${id}, then the Devil's Advocate review.`
124
+ };
125
+ }
126
+ const verify = invoke(rootDir, [
127
+ 'verify', '--run', id,
128
+ ...commands.flatMap((command) => ['--cmd', command]),
129
+ ...(shell ? ['--shell'] : []),
130
+ ...(serial ? ['--serial'] : []),
131
+ ...(timeoutMs ? ['--timeout-ms', String(timeoutMs)] : [])
132
+ ]);
133
+ const diffPath = path.join(rootDir, '.ai-engineering-loop', 'runs', id, 'diff.patch');
134
+ const changedPaths = [...new Set(extractChangedPaths(fs.readFileSync(diffPath, 'utf8')))];
135
+ const claimed = writeClaimedVsReality(rootDir, { changedPaths, commands: verify.commands.map((c) => ({ ...c, testCounts: verify.testCounts })) });
136
+ invoke(rootDir, ['gate', 'review', '--run', id]);
137
+ const judge = invoke(rootDir, ['gate', 'judge', '--run', id]);
138
+ return {
139
+ ok: true,
140
+ runId: id,
141
+ tier: 'T0',
142
+ state: judge.state,
143
+ commands: verify.commands,
144
+ changedPaths,
145
+ claimedVsReality: claimed,
146
+ next: judge.state === 'JUDGED_PASS'
147
+ ? `After the human approves: npx ai-engineering-loop deliver --run ${id} --destination <where> --summary "<text>" --approve --by <name>`
148
+ : `Judge returned ${judge.state}; fix and run quick finish again.`
149
+ };
150
+ }
151
+
152
+ module.exports = { startQuick, finishQuick, quickGoal };
package/lib/receipt.js CHANGED
@@ -6,10 +6,10 @@
6
6
  // `verify-receipt` re-checks all of it, so a reviewer (or CI) can trust the
7
7
  // PR body without re-reading the Run.
8
8
 
9
- const crypto = require('crypto');
10
9
  const fs = require('fs');
11
10
  const path = require('path');
12
11
  const { execFileSync } = require('child_process');
12
+ const { sha256: hashBytes } = require('./fsutil.js');
13
13
  const { getCurrentRun, loadRun, runsDir } = require('./run-state.js');
14
14
  const { canonicalJson, sha256 } = require('./recipe.js');
15
15
  const { parseClaimedVsReality } = require('./claimed-vs-reality.js');
@@ -45,10 +45,6 @@ function resolveRun(rootDir, runId) {
45
45
  return current;
46
46
  }
47
47
 
48
- function hashBytes(buffer) {
49
- return crypto.createHash('sha256').update(buffer).digest('hex');
50
- }
51
-
52
48
  function repoRelative(rootDir, filePath) {
53
49
  return path.relative(rootDir, filePath).split(path.sep).join('/');
54
50
  }
@@ -2,14 +2,10 @@
2
2
 
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
- const crypto = require('crypto');
6
5
  const { NODE_TYPES } = require('./node-registry.js');
7
6
  const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
8
- const {
9
- mergeGraphs,
10
- migrateLegacyRecipe,
11
- planGraphMerge
12
- } = require('./recipe-graph.js');
7
+ const { writePrivateJson } = require('./fsutil.js');
8
+ const { migrateLegacyRecipe } = require('./recipe-graph.js');
13
9
  const {
14
10
  RECIPE_ID,
15
11
  canonicalJson,
@@ -48,14 +44,7 @@ function atomicWriteJson(filePath, value, { replace = false } = {}) {
48
44
  if (!replace && fs.existsSync(filePath)) {
49
45
  throw builderError(`Recipe already exists: ${path.basename(filePath, '.json')}`, 'RECIPE_EXISTS');
50
46
  }
51
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
52
- const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
53
- try {
54
- fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
55
- fs.renameSync(temporary, filePath);
56
- } finally {
57
- try { fs.unlinkSync(temporary); } catch {}
58
- }
47
+ writePrivateJson(filePath, value);
59
48
  }
60
49
 
61
50
  function assertProjectId(rootDir, id) {
@@ -71,25 +60,6 @@ function validateCandidate(recipe) {
71
60
  return result;
72
61
  }
73
62
 
74
- function planRecipeImport(existingRecipe, importedRecipe, operation) {
75
- if (!['replace', 'merge', 'cancel'].includes(operation)) {
76
- throw builderError('Import operation must be replace, merge, or cancel', 'INVALID_IMPORT_OPERATION');
77
- }
78
- validateCandidate(existingRecipe);
79
- validateCandidate(importedRecipe);
80
- if (operation !== 'merge') return { operation, nodeIdMap: {}, edgeIdMap: {} };
81
- return { operation, ...planGraphMerge(existingRecipe, importedRecipe) };
82
- }
83
-
84
- function applyRecipeImport(existingRecipe, importedRecipe, plan) {
85
- if (!plan || !['replace', 'merge', 'cancel'].includes(plan.operation)) {
86
- throw builderError('A valid import preview is required', 'INVALID_IMPORT_PLAN');
87
- }
88
- if (plan.operation === 'cancel') return existingRecipe;
89
- if (plan.operation === 'replace') return migrateLegacyRecipe(importedRecipe);
90
- return mergeGraphs(existingRecipe, importedRecipe, plan);
91
- }
92
-
93
63
  function cloneRecipe(rootDir, sourceId, targetId, { description } = {}) {
94
64
  assertProjectId(rootDir, targetId);
95
65
  const source = loadRecipe(rootDir, sourceId).recipe;
@@ -217,10 +187,8 @@ function diffRecipes(rootDir, leftId, rightId) {
217
187
  }
218
188
 
219
189
  module.exports = {
220
- applyRecipeImport,
221
190
  cloneRecipe,
222
191
  installRecipe,
223
- planRecipeImport,
224
192
  recipeCatalog,
225
193
  inspectRecipe,
226
194
  diffRecipes