ai-engineering-loop 1.11.1 → 1.13.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 (102) hide show
  1. package/.agents/skills/animate/RECIPES.md +324 -0
  2. package/.agents/skills/animate/SKILL.md +207 -0
  3. package/.agents/skills/animate-expo/RECIPES.md +385 -0
  4. package/.agents/skills/animate-expo/SKILL.md +263 -0
  5. package/.agents/skills/animation-vocabulary/SKILL.md +181 -0
  6. package/.agents/skills/apple-design/SKILL.md +290 -0
  7. package/.agents/skills/ask-sonner/API.md +64 -0
  8. package/.agents/skills/ask-sonner/SKILL.md +88 -0
  9. package/.agents/skills/emil-design-eng/SKILL.md +674 -0
  10. package/.agents/skills/find-animation-opportunities/SKILL.md +140 -0
  11. package/.agents/skills/improve-animations/AUDIT.md +115 -0
  12. package/.agents/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  13. package/.agents/skills/improve-animations/SKILL.md +109 -0
  14. package/.agents/skills/mobile-native/SKILL.md +311 -0
  15. package/.agents/skills/pick-ui-library/SKILL.md +85 -0
  16. package/.agents/skills/prototype/PICKER.md +197 -0
  17. package/.agents/skills/prototype/SKILL.md +98 -0
  18. package/.agents/skills/review-animations/SKILL.md +120 -0
  19. package/.agents/skills/review-animations/STANDARDS.md +187 -0
  20. package/.agents/skills/write-swift/SKILL.md +396 -0
  21. package/.agents/workflows/ai-engineering-loop.md +2 -2
  22. package/.claude/skills/ai-engineering-loop/SKILL.md +3 -3
  23. package/.claude/skills/animate/RECIPES.md +324 -0
  24. package/.claude/skills/animate/SKILL.md +207 -0
  25. package/.claude/skills/animate-expo/RECIPES.md +385 -0
  26. package/.claude/skills/animate-expo/SKILL.md +263 -0
  27. package/.claude/skills/animation-vocabulary/SKILL.md +181 -0
  28. package/.claude/skills/apple-design/SKILL.md +290 -0
  29. package/.claude/skills/ask-sonner/API.md +64 -0
  30. package/.claude/skills/ask-sonner/SKILL.md +88 -0
  31. package/.claude/skills/emil-design-eng/SKILL.md +674 -0
  32. package/.claude/skills/find-animation-opportunities/SKILL.md +140 -0
  33. package/.claude/skills/improve-animations/AUDIT.md +115 -0
  34. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  35. package/.claude/skills/improve-animations/SKILL.md +109 -0
  36. package/.claude/skills/mobile-native/SKILL.md +311 -0
  37. package/.claude/skills/pick-ui-library/SKILL.md +85 -0
  38. package/.claude/skills/prototype/PICKER.md +197 -0
  39. package/.claude/skills/prototype/SKILL.md +98 -0
  40. package/.claude/skills/review-animations/SKILL.md +120 -0
  41. package/.claude/skills/review-animations/STANDARDS.md +187 -0
  42. package/.claude/skills/write-swift/SKILL.md +396 -0
  43. package/.gemini/skills/ai-engineering-loop/SKILL.md +3 -3
  44. package/.gemini/skills/animate/RECIPES.md +324 -0
  45. package/.gemini/skills/animate/SKILL.md +207 -0
  46. package/.gemini/skills/animate-expo/RECIPES.md +385 -0
  47. package/.gemini/skills/animate-expo/SKILL.md +263 -0
  48. package/.gemini/skills/animation-vocabulary/SKILL.md +181 -0
  49. package/.gemini/skills/apple-design/SKILL.md +290 -0
  50. package/.gemini/skills/ask-sonner/API.md +64 -0
  51. package/.gemini/skills/ask-sonner/SKILL.md +88 -0
  52. package/.gemini/skills/emil-design-eng/SKILL.md +674 -0
  53. package/.gemini/skills/find-animation-opportunities/SKILL.md +140 -0
  54. package/.gemini/skills/improve-animations/AUDIT.md +115 -0
  55. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  56. package/.gemini/skills/improve-animations/SKILL.md +109 -0
  57. package/.gemini/skills/mobile-native/SKILL.md +311 -0
  58. package/.gemini/skills/pick-ui-library/SKILL.md +85 -0
  59. package/.gemini/skills/prototype/PICKER.md +197 -0
  60. package/.gemini/skills/prototype/SKILL.md +98 -0
  61. package/.gemini/skills/review-animations/SKILL.md +120 -0
  62. package/.gemini/skills/review-animations/STANDARDS.md +187 -0
  63. package/.gemini/skills/write-swift/SKILL.md +396 -0
  64. package/.grok/skills/ai-engineering-loop/SKILL.md +3 -3
  65. package/.grok/skills/animate/RECIPES.md +324 -0
  66. package/.grok/skills/animate/SKILL.md +207 -0
  67. package/.grok/skills/animate-expo/RECIPES.md +385 -0
  68. package/.grok/skills/animate-expo/SKILL.md +263 -0
  69. package/.grok/skills/animation-vocabulary/SKILL.md +181 -0
  70. package/.grok/skills/apple-design/SKILL.md +290 -0
  71. package/.grok/skills/ask-sonner/API.md +64 -0
  72. package/.grok/skills/ask-sonner/SKILL.md +88 -0
  73. package/.grok/skills/emil-design-eng/SKILL.md +674 -0
  74. package/.grok/skills/find-animation-opportunities/SKILL.md +140 -0
  75. package/.grok/skills/improve-animations/AUDIT.md +115 -0
  76. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  77. package/.grok/skills/improve-animations/SKILL.md +109 -0
  78. package/.grok/skills/mobile-native/SKILL.md +311 -0
  79. package/.grok/skills/pick-ui-library/SKILL.md +85 -0
  80. package/.grok/skills/prototype/PICKER.md +197 -0
  81. package/.grok/skills/prototype/SKILL.md +98 -0
  82. package/.grok/skills/review-animations/SKILL.md +120 -0
  83. package/.grok/skills/review-animations/STANDARDS.md +187 -0
  84. package/.grok/skills/write-swift/SKILL.md +396 -0
  85. package/README.md +13 -1
  86. package/README.npm.md +2 -1
  87. package/THIRD_PARTY_NOTICES.md +10 -0
  88. package/agents/third-party/emilkowalski-skills/LICENSE +21 -0
  89. package/bin/ai-engineering-loop.js +158 -9
  90. package/core/artifact-gates.md +32 -1
  91. package/core/runtime-safety.md +2 -1
  92. package/core/verification-loop.md +6 -0
  93. package/lib/agent-artifacts.js +250 -0
  94. package/lib/claimed-vs-reality.js +134 -0
  95. package/lib/doctor.js +12 -0
  96. package/lib/safe-context.js +62 -4
  97. package/lib/sync-hosts.js +97 -3
  98. package/lib/verification-recorder.js +224 -0
  99. package/lib/workflow-runtime.js +26 -1
  100. package/package.json +2 -1
  101. package/policies/review-budget.md +1 -1
  102. package/schemas/verification.schema.json +2 -2
@@ -1,5 +1,138 @@
1
1
  'use strict';
2
2
 
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { getCurrentRun, loadRun } = require('./run-state.js');
7
+
8
+ function claimedVsRealityError(message, code = 'CLAIMED_VS_REALITY_FAILED') {
9
+ const error = new Error(message);
10
+ error.code = code;
11
+ return error;
12
+ }
13
+
14
+ function markdownCell(value) {
15
+ return String(value ?? '')
16
+ .replace(/\|/g, '/')
17
+ .replace(/\s+/g, ' ')
18
+ .trim();
19
+ }
20
+
21
+ function frozenGoal(rootDir, run) {
22
+ const artifact = run.artifacts?.goalContract;
23
+ if (!artifact?.path || !artifact.sha256) {
24
+ throw claimedVsRealityError('The Goal Contract has not passed the Goal gate.', 'GOAL_NOT_FROZEN');
25
+ }
26
+ const root = fs.realpathSync(rootDir);
27
+ const goalPath = path.resolve(root, artifact.path);
28
+ const relative = path.relative(root, goalPath);
29
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
30
+ throw claimedVsRealityError('Frozen Goal Contract path escapes the repository.', 'UNSAFE_GOAL_PATH');
31
+ }
32
+ assertNoSymlinkPath(root, goalPath);
33
+ const stat = fs.lstatSync(goalPath);
34
+ if (!stat.isFile() || stat.isSymbolicLink()) {
35
+ throw claimedVsRealityError('Frozen Goal Contract must be a regular file.', 'UNSAFE_GOAL_PATH');
36
+ }
37
+ const content = fs.readFileSync(goalPath);
38
+ const hash = crypto.createHash('sha256').update(content).digest('hex');
39
+ if (hash !== artifact.sha256) {
40
+ throw claimedVsRealityError('Frozen Goal Contract changed after its gate.', 'STALE_GOAL');
41
+ }
42
+ let goal;
43
+ try {
44
+ goal = JSON.parse(content.toString('utf8'));
45
+ } catch (cause) {
46
+ throw claimedVsRealityError(`Frozen Goal Contract is invalid JSON: ${cause.message}`, 'INVALID_GOAL');
47
+ }
48
+ if (goal.runId !== run.runId || !Array.isArray(goal.acceptanceCriteria) || goal.acceptanceCriteria.length === 0) {
49
+ throw claimedVsRealityError('Frozen Goal Contract has no criteria for this Run.', 'INVALID_GOAL');
50
+ }
51
+ return goal;
52
+ }
53
+
54
+ function assertNoSymlinkPath(root, targetPath) {
55
+ const relative = path.relative(root, targetPath);
56
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
57
+ throw claimedVsRealityError('Output path must stay inside the repository.', 'UNSAFE_OUTPUT_PATH');
58
+ }
59
+ let current = root;
60
+ for (const segment of relative.split(path.sep).filter(Boolean)) {
61
+ current = path.join(current, segment);
62
+ try {
63
+ if (fs.lstatSync(current).isSymbolicLink()) {
64
+ throw claimedVsRealityError(`Repository path crosses a symlink: ${path.relative(root, current)}`, 'UNSAFE_PATH');
65
+ }
66
+ } catch (cause) {
67
+ if (cause.code === 'ENOENT') return;
68
+ throw cause;
69
+ }
70
+ }
71
+ }
72
+
73
+ function renderClaimedVsRealityTemplate(goal) {
74
+ const lines = [
75
+ '# Claimed vs Reality',
76
+ '',
77
+ '> Generated from the frozen Goal Contract. Fill Claimed and Reality only after implementation and verification. Reality must cite observed command output; this template is not verification evidence.',
78
+ '',
79
+ '| AC | Claimed | Reality from command log |',
80
+ '|---|---|---|'
81
+ ];
82
+ for (const criterion of goal.acceptanceCriteria) {
83
+ const evidence = markdownCell(criterion.evidenceRequired);
84
+ const failures = (criterion.failureCases || []).map(markdownCell).filter(Boolean).join('; ');
85
+ const description = [
86
+ `${criterion.id}: ${markdownCell(criterion.statement)}`,
87
+ evidence ? `Evidence: ${evidence}` : '',
88
+ failures ? `Failure cases: ${failures}` : ''
89
+ ].filter(Boolean).join(' — ');
90
+ lines.push(`| ${markdownCell(description)} | | |`);
91
+ }
92
+ return `${lines.join('\n')}\n`;
93
+ }
94
+
95
+ function createClaimedVsRealityTemplate(rootDir, { runId, outputPath } = {}) {
96
+ const run = runId ? loadRun(rootDir, runId) : getCurrentRun(rootDir);
97
+ if (!run) throw claimedVsRealityError('No current Run. Pass --run <id>.', 'NO_CURRENT_RUN');
98
+ const goal = frozenGoal(rootDir, run);
99
+ const root = fs.realpathSync(rootDir);
100
+ const requestedPath = outputPath || '.ai-engineering-loop/tasks/claimed-vs-reality.md';
101
+ if (path.isAbsolute(requestedPath)) {
102
+ throw claimedVsRealityError('Output path must be repository-relative.', 'UNSAFE_OUTPUT_PATH');
103
+ }
104
+ const filePath = path.resolve(root, requestedPath);
105
+ const relative = path.relative(root, filePath);
106
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
107
+ throw claimedVsRealityError('Output path must stay inside the repository.', 'UNSAFE_OUTPUT_PATH');
108
+ }
109
+ assertNoSymlinkPath(root, path.dirname(filePath));
110
+ fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
111
+ const realParent = fs.realpathSync(path.dirname(filePath));
112
+ if (realParent !== root && !realParent.startsWith(`${root}${path.sep}`)) {
113
+ throw claimedVsRealityError('Output path escapes the repository through a symlink.', 'UNSAFE_OUTPUT_PATH');
114
+ }
115
+ let descriptor;
116
+ try {
117
+ descriptor = fs.openSync(filePath, 'wx', 0o600);
118
+ } catch (cause) {
119
+ if (cause.code === 'EEXIST') {
120
+ throw claimedVsRealityError(
121
+ `Refusing to overwrite ${relative}. Choose --output <new-file> to preserve existing evidence.`,
122
+ 'OUTPUT_EXISTS'
123
+ );
124
+ }
125
+ throw cause;
126
+ }
127
+ try {
128
+ fs.writeFileSync(descriptor, renderClaimedVsRealityTemplate(goal));
129
+ fs.fsyncSync(descriptor);
130
+ } finally {
131
+ fs.closeSync(descriptor);
132
+ }
133
+ return { runId: run.runId, path: relative.split(path.sep).join('/') };
134
+ }
135
+
3
136
  function parseClaimedVsReality(markdown) {
4
137
  const rows = [];
5
138
  if (!markdown || !String(markdown).trim()) return { rows };
@@ -32,6 +165,7 @@ function readyForDa(markdown) {
32
165
  }
33
166
 
34
167
  module.exports = {
168
+ createClaimedVsRealityTemplate,
35
169
  parseClaimedVsReality,
36
170
  readyForDa
37
171
  };
package/lib/doctor.js CHANGED
@@ -9,16 +9,28 @@ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
9
9
  const REQUIRED_HOST_ASSETS = [
10
10
  '.claude/skills/ai-engineering-loop/SKILL.md',
11
11
  '.claude/skills/backend-development/SKILL.md',
12
+ '.claude/skills/emil-design-eng/SKILL.md',
13
+ '.claude/skills/animate/SKILL.md',
14
+ '.claude/skills/review-animations/SKILL.md',
12
15
  '.claude/agents/devil-advocate.md',
13
16
  '.claude/agents/judge.md',
14
17
  '.grok/skills/ai-engineering-loop/SKILL.md',
15
18
  '.grok/skills/backend-development/SKILL.md',
19
+ '.grok/skills/emil-design-eng/SKILL.md',
20
+ '.grok/skills/animate/SKILL.md',
21
+ '.grok/skills/review-animations/SKILL.md',
16
22
  '.grok/agents/devil-advocate.md',
17
23
  '.grok/agents/judge.md',
18
24
  '.gemini/skills/ai-engineering-loop/SKILL.md',
19
25
  '.gemini/skills/backend-development/SKILL.md',
26
+ '.gemini/skills/emil-design-eng/SKILL.md',
27
+ '.gemini/skills/animate/SKILL.md',
28
+ '.gemini/skills/review-animations/SKILL.md',
20
29
  '.agents/workflows/ai-engineering-loop.md',
21
30
  '.agents/skills/backend-development/SKILL.md',
31
+ '.agents/skills/emil-design-eng/SKILL.md',
32
+ '.agents/skills/animate/SKILL.md',
33
+ '.agents/skills/review-animations/SKILL.md',
22
34
  '.agents/devil-advocate.md',
23
35
  '.agents/judge.md'
24
36
  ];
@@ -35,9 +35,11 @@ const SENSITIVE_NAMES = [
35
35
  /\.(?:pem|key|p12|pfx|jks)$/i
36
36
  ];
37
37
 
38
- function contextError(message, code = 'UNSAFE_CONTEXT') {
38
+ function contextError(message, code = 'UNSAFE_CONTEXT', details = [], budget = null) {
39
39
  const err = new Error(message);
40
40
  err.code = code;
41
+ if (details.length) err.details = details;
42
+ if (budget) err.budget = budget;
41
43
  return err;
42
44
  }
43
45
 
@@ -95,10 +97,15 @@ function redactSecrets(input) {
95
97
  replace(/\bAKIA[A-Z0-9]{16}\b/g, 'aws-access-key', '[REDACTED AWS ACCESS KEY]');
96
98
  replace(/\bsk-(?:live-|test-)?[A-Za-z0-9_-]{8,}\b/g, 'api-token', '[REDACTED API TOKEN]');
97
99
  replace(
98
- /(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|secret|password|authorization)\b\s*[:=]\s*["']?)([^"'\s,;]+)/gi,
100
+ /(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|token|secret|password|authorization)\b\s*[:=]\s*["']?)([^"'\s,;]+)/gi,
99
101
  'key-value-secret',
100
102
  (_match, prefix) => `${prefix}[REDACTED]`
101
103
  );
104
+ replace(
105
+ /(^|[^\w-])(--?(?:api[_-]?key|access[_-]?token|auth[_-]?token|token|secret|password|authorization)\s+)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi,
106
+ 'key-value-secret',
107
+ (_match, boundary, prefix) => `${boundary}${prefix}[REDACTED]`
108
+ );
102
109
 
103
110
  return { text, categories: [...categories].sort() };
104
111
  }
@@ -149,6 +156,7 @@ function createContextPack(rootDir, { runId, stage, files, profile } = {}) {
149
156
  }
150
157
 
151
158
  const entries = [];
159
+ const budgetEntries = [];
152
160
  let totalBytes = 0;
153
161
  let estimatedTokens = 0;
154
162
  for (const requested of uniqueFiles) {
@@ -157,17 +165,67 @@ function createContextPack(rootDir, { runId, stage, files, profile } = {}) {
157
165
  if (raw.includes(0)) throw contextError(`Binary context is blocked: ${requested}`, 'BINARY_CONTEXT');
158
166
 
159
167
  const remaining = limits.maxTotalBytes - totalBytes;
160
- if (remaining <= 0) throw contextError(`${stage} context exceeds its byte budget`, 'CONTEXT_BYTE_LIMIT');
168
+ if (remaining <= 0) {
169
+ const budget = {
170
+ stage,
171
+ reviewProfile,
172
+ maxTotalBytes: limits.maxTotalBytes,
173
+ requestedBytes: totalBytes + raw.length,
174
+ files: [...budgetEntries, {
175
+ path: safe.relative,
176
+ sourceBytes: raw.length,
177
+ includedBytes: 0,
178
+ estimatedTokens: 0,
179
+ truncated: true
180
+ }]
181
+ };
182
+ throw contextError(
183
+ `${stage} context exceeds its byte budget (${limits.maxTotalBytes.toLocaleString()}-byte limit; ${budget.requestedBytes.toLocaleString()} requested)`,
184
+ 'CONTEXT_BYTE_LIMIT',
185
+ budget.files.map((entry) =>
186
+ `${entry.path}: ${entry.estimatedTokens.toLocaleString()} estimated tokens, ${entry.includedBytes.toLocaleString()}/${entry.sourceBytes.toLocaleString()} bytes included`
187
+ ),
188
+ budget
189
+ );
190
+ }
161
191
  const allowedBytes = Math.min(raw.length, limits.maxFileBytes, remaining);
162
192
  const source = raw.subarray(0, allowedBytes).toString('utf8');
163
193
  const redacted = redactSecrets(source);
164
194
  const tokens = estimateTokens(redacted.text);
165
195
  if (estimatedTokens + tokens > limits.maxEstimatedTokens) {
166
- throw contextError(`${stage} context exceeds its estimated token budget`, 'CONTEXT_TOKEN_LIMIT');
196
+ const files = [...budgetEntries, {
197
+ path: safe.relative,
198
+ sourceBytes: raw.length,
199
+ includedBytes: allowedBytes,
200
+ estimatedTokens: tokens,
201
+ truncated: allowedBytes < raw.length
202
+ }];
203
+ const budget = {
204
+ stage,
205
+ reviewProfile,
206
+ maxEstimatedTokens: limits.maxEstimatedTokens,
207
+ requestedTokens: estimatedTokens + tokens,
208
+ files
209
+ };
210
+ throw contextError(
211
+ `${stage} context exceeds its estimated token budget (${limits.maxEstimatedTokens.toLocaleString()}-token limit; ${budget.requestedTokens.toLocaleString()} requested)`,
212
+ 'CONTEXT_TOKEN_LIMIT',
213
+ files.map((entry) =>
214
+ `${entry.path}: ${entry.estimatedTokens.toLocaleString()} estimated tokens, ${entry.includedBytes.toLocaleString()}/${entry.sourceBytes.toLocaleString()} bytes included${entry.truncated ? ' (truncated)' : ''}`
215
+ ),
216
+ budget
217
+ );
167
218
  }
168
219
 
169
220
  totalBytes += allowedBytes;
170
221
  estimatedTokens += tokens;
222
+ budgetEntries.push({
223
+ path: safe.relative,
224
+ sourceBytes: raw.length,
225
+ includedBytes: allowedBytes,
226
+ estimatedTokens: tokens,
227
+ truncated: allowedBytes < raw.length
228
+ });
171
229
  entries.push({
172
230
  path: safe.relative,
173
231
  sourceSha256: sha256(raw),
package/lib/sync-hosts.js CHANGED
@@ -30,6 +30,38 @@ const BACKEND_SKILL_FILES = [
30
30
  'references/security-checklist.md'
31
31
  ];
32
32
 
33
+ const EMIL_KOWALSKI_SKILLS = Object.freeze([
34
+ 'animate',
35
+ 'animate-expo',
36
+ 'animation-vocabulary',
37
+ 'apple-design',
38
+ 'ask-sonner',
39
+ 'emil-design-eng',
40
+ 'find-animation-opportunities',
41
+ 'improve-animations',
42
+ 'mobile-native',
43
+ 'pick-ui-library',
44
+ 'prototype',
45
+ 'review-animations',
46
+ 'write-swift'
47
+ ]);
48
+
49
+ const EMIL_KOWALSKI_SKILL_FILES = Object.freeze({
50
+ animate: ['SKILL.md', 'RECIPES.md'],
51
+ 'animate-expo': ['SKILL.md', 'RECIPES.md'],
52
+ 'animation-vocabulary': ['SKILL.md'],
53
+ 'apple-design': ['SKILL.md'],
54
+ 'ask-sonner': ['SKILL.md', 'API.md'],
55
+ 'emil-design-eng': ['SKILL.md'],
56
+ 'find-animation-opportunities': ['SKILL.md'],
57
+ 'improve-animations': ['SKILL.md', 'AUDIT.md', 'PLAN-TEMPLATE.md'],
58
+ 'mobile-native': ['SKILL.md'],
59
+ 'pick-ui-library': ['SKILL.md'],
60
+ prototype: ['SKILL.md', 'PICKER.md'],
61
+ 'review-animations': ['SKILL.md', 'STANDARDS.md'],
62
+ 'write-swift': ['SKILL.md']
63
+ });
64
+
33
65
  function backendSkillFiles(srcRoot, destRoot, { grokSkillOverlay = false } = {}) {
34
66
  return BACKEND_SKILL_FILES.map((file) => ({
35
67
  src: path.posix.join(srcRoot, file),
@@ -39,6 +71,17 @@ function backendSkillFiles(srcRoot, destRoot, { grokSkillOverlay = false } = {})
39
71
  }));
40
72
  }
41
73
 
74
+ function emilKowalskiSkillFiles(srcRoot, destRoot, { grokSkillOverlay = false } = {}) {
75
+ return EMIL_KOWALSKI_SKILLS.flatMap((skill) => (
76
+ EMIL_KOWALSKI_SKILL_FILES[skill].map((file) => ({
77
+ src: path.posix.join(srcRoot, skill, file),
78
+ dest: path.join(destRoot, skill, file),
79
+ mode: 'upsert',
80
+ ...(grokSkillOverlay && file === 'SKILL.md' ? { grokSkillOverlay: true } : {})
81
+ }))
82
+ ));
83
+ }
84
+
42
85
  function hostFileMap(home) {
43
86
  const claude = path.join(home, '.claude');
44
87
  const grok = path.join(home, '.grok');
@@ -51,6 +94,7 @@ function hostFileMap(home) {
51
94
  files: [
52
95
  { src: '.claude/skills/ai-engineering-loop/SKILL.md', dest: path.join(claude, 'skills/ai-engineering-loop/SKILL.md'), mode: 'upsert' },
53
96
  ...backendSkillFiles('.claude/skills/backend-development', path.join(claude, 'skills/backend-development')),
97
+ ...emilKowalskiSkillFiles('.claude/skills', path.join(claude, 'skills')),
54
98
  { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(claude, 'skills/task-impact-inquiry/SKILL.md'), mode: 'upsert' },
55
99
  { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(claude, 'skills/generate-adapter/SKILL.md'), mode: 'upsert' },
56
100
  { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(claude, 'skills/generate-workflow/SKILL.md'), mode: 'upsert' },
@@ -65,6 +109,7 @@ function hostFileMap(home) {
65
109
  files: [
66
110
  { src: '.grok/skills/ai-engineering-loop/SKILL.md', dest: path.join(grok, 'skills/ai-engineering-loop/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
67
111
  ...backendSkillFiles('.grok/skills/backend-development', path.join(grok, 'skills/backend-development'), { grokSkillOverlay: true }),
112
+ ...emilKowalskiSkillFiles('.grok/skills', path.join(grok, 'skills'), { grokSkillOverlay: true }),
68
113
  { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(grok, 'skills/task-impact-inquiry/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
69
114
  { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(grok, 'skills/generate-adapter/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
70
115
  { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(grok, 'skills/generate-workflow/SKILL.md'), mode: 'upsert', grokSkillOverlay: true },
@@ -79,6 +124,7 @@ function hostFileMap(home) {
79
124
  files: [
80
125
  { src: '.gemini/skills/ai-engineering-loop/SKILL.md', dest: path.join(gemini, 'config/skills/ai-engineering-loop/SKILL.md'), mode: 'upsert' },
81
126
  ...backendSkillFiles('.gemini/skills/backend-development', path.join(gemini, 'config/skills/backend-development')),
127
+ ...emilKowalskiSkillFiles('.gemini/skills', path.join(gemini, 'config/skills')),
82
128
  { src: 'adapters/dot/skills/task-impact-inquiry/SKILL.md', dest: path.join(gemini, 'config/skills/task-impact-inquiry/SKILL.md'), mode: 'upsert' },
83
129
  { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(gemini, 'config/skills/generate-adapter/SKILL.md'), mode: 'upsert' },
84
130
  { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(gemini, 'config/skills/generate-workflow/SKILL.md'), mode: 'upsert' }
@@ -89,6 +135,7 @@ function hostFileMap(home) {
89
135
  root: agents,
90
136
  files: [
91
137
  ...backendSkillFiles('.agents/skills/backend-development', path.join(agents, 'skills/backend-development')),
138
+ ...emilKowalskiSkillFiles('.agents/skills', path.join(agents, 'skills')),
92
139
  { src: '.agents/devil-advocate.md', dest: path.join(agents, 'devil-advocate.md'), mode: 'upsert' },
93
140
  { src: '.agents/judge.md', dest: path.join(agents, 'judge.md'), mode: 'upsert' },
94
141
  { src: '.agents/workflows/ai-engineering-loop.md', dest: path.join(agents, 'workflows/ai-engineering-loop.md'), mode: 'upsert' }
@@ -126,6 +173,28 @@ function isSymlink(dest) {
126
173
  }
127
174
  }
128
175
 
176
+ function findSymlinkAncestor(home, destination) {
177
+ const homePath = path.resolve(home);
178
+ const destinationPath = path.resolve(destination);
179
+ const relative = path.relative(homePath, destinationPath);
180
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
181
+
182
+ let current = homePath;
183
+ const candidates = [];
184
+ for (const segment of relative.split(path.sep).filter(Boolean)) {
185
+ current = path.join(current, segment);
186
+ candidates.push(current);
187
+ }
188
+ for (const candidate of candidates) {
189
+ try {
190
+ if (fs.lstatSync(candidate).isSymbolicLink()) return candidate;
191
+ } catch (error) {
192
+ if (error.code !== 'ENOENT') throw error;
193
+ }
194
+ }
195
+ return null;
196
+ }
197
+
129
198
  function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } = {}) {
130
199
  const results = [];
131
200
  for (const group of hostFileMap(home)) {
@@ -146,8 +215,14 @@ function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } =
146
215
  results.push({ ...item, action: 'skip', reason: 'src-missing' });
147
216
  continue;
148
217
  }
149
- if (isSymlink(file.dest)) {
150
- results.push({ ...item, action: 'skip', reason: 'symlink' });
218
+ const symlinkPath = findSymlinkAncestor(home, file.dest);
219
+ if (symlinkPath) {
220
+ const isDestinationSymlink = path.resolve(symlinkPath) === path.resolve(file.dest);
221
+ results.push({
222
+ ...item,
223
+ action: 'skip',
224
+ reason: isDestinationSymlink ? 'symlink' : 'symlink-ancestor'
225
+ });
151
226
  continue;
152
227
  }
153
228
  if (file.mode === 'update-if-exists' && !destExists(file.dest)) {
@@ -175,8 +250,25 @@ function applyHostSync({ packageRoot: root = packageRoot(), home = homeDir(), dr
175
250
  continue;
176
251
  }
177
252
  if (!dryRun) {
253
+ if (findSymlinkAncestor(home, item.dest)) {
254
+ applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
255
+ continue;
256
+ }
178
257
  fs.mkdirSync(path.dirname(item.dest), { recursive: true });
179
- fs.writeFileSync(item.dest, item.content);
258
+ if (findSymlinkAncestor(home, item.dest)) {
259
+ applied.push({ ...item, action: 'skip', reason: 'symlink-ancestor', content: undefined });
260
+ continue;
261
+ }
262
+ const flags = fs.constants.O_WRONLY
263
+ | fs.constants.O_CREAT
264
+ | fs.constants.O_TRUNC
265
+ | (fs.constants.O_NOFOLLOW || 0);
266
+ const descriptor = fs.openSync(item.dest, flags, 0o600);
267
+ try {
268
+ fs.writeFileSync(descriptor, item.content);
269
+ } finally {
270
+ fs.closeSync(descriptor);
271
+ }
180
272
  }
181
273
  applied.push({ ...item, content: undefined, dryRun });
182
274
  }
@@ -217,6 +309,8 @@ module.exports = {
217
309
  packageRoot,
218
310
  homeDir,
219
311
  applyGrokSkillOverlay,
312
+ EMIL_KOWALSKI_SKILLS,
313
+ EMIL_KOWALSKI_SKILL_FILES,
220
314
  hostFileMap,
221
315
  planHostSync,
222
316
  applyHostSync,
@@ -0,0 +1,224 @@
1
+ 'use strict';
2
+
3
+ const { spawn } = require('child_process');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const {
7
+ atomicWriteJson,
8
+ getCurrentRun,
9
+ getGitRevision,
10
+ loadRun,
11
+ runsDir
12
+ } = require('./run-state.js');
13
+ const { hashFile } = require('./gates.js');
14
+ const { redactHomePaths, redactSecrets } = require('./safe-context.js');
15
+ const { writeVerificationSummary } = require('./verification-summary.js');
16
+
17
+ const MAX_CAPTURE_BYTES = 256 * 1024;
18
+ const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
19
+ const MAX_TIMEOUT_MS = 60 * 60 * 1000;
20
+ const KILL_GRACE_MS = 2_000;
21
+
22
+ function recorderError(message, code = 'VERIFICATION_RECORD_FAILED') {
23
+ const error = new Error(message);
24
+ error.code = code;
25
+ return error;
26
+ }
27
+
28
+ function resolveRun(rootDir, runId) {
29
+ if (runId) return loadRun(rootDir, runId);
30
+ const current = getCurrentRun(rootDir);
31
+ if (!current) throw recorderError('No current Run. Pass --run <id> or start a Run first.', 'NO_CURRENT_RUN');
32
+ return current;
33
+ }
34
+
35
+ function validateRecordingRequest({ command, args, timeoutMs, shell }) {
36
+ if (typeof command !== 'string' || !command.trim() || command.includes('\0')) {
37
+ throw recorderError('Provide an executable after `--`, for example `verification record -- npm test`.', 'INVALID_COMMAND');
38
+ }
39
+ if (!Array.isArray(args) || args.some((argument) => typeof argument !== 'string' || argument.includes('\0'))) {
40
+ throw recorderError('Command arguments must be strings without NUL characters.', 'INVALID_COMMAND');
41
+ }
42
+ if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
43
+ throw recorderError(`Timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`, 'INVALID_TIMEOUT');
44
+ }
45
+ if (shell && args.length > 0) {
46
+ throw recorderError('With --shell, pass one quoted command string after `--`; shell argument arrays are intentionally unsupported.', 'INVALID_COMMAND');
47
+ }
48
+ }
49
+
50
+ function resolveDiff(rootDir, run) {
51
+ const artifact = run.artifacts?.diff;
52
+ if (!artifact?.path || !artifact.sha256) {
53
+ throw recorderError('Maker evidence is not gated yet. Run `gate maker` before recording verification.', 'MAKER_NOT_GATED');
54
+ }
55
+ const root = fs.realpathSync(rootDir);
56
+ const absolute = path.resolve(root, artifact.path);
57
+ const relative = path.relative(root, absolute);
58
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
59
+ throw recorderError('The gated Maker diff path escapes the repository.', 'UNSAFE_DIFF_PATH');
60
+ }
61
+ const stat = fs.lstatSync(absolute);
62
+ if (!stat.isFile() || stat.isSymbolicLink() || hashFile(absolute) !== artifact.sha256) {
63
+ throw recorderError('The gated Maker diff is missing, unsafe, or changed. Re-run the Maker gate.', 'STALE_DIFF');
64
+ }
65
+ return artifact.sha256;
66
+ }
67
+
68
+ function readExistingBundle(filePath, { runId, gitRevision, diffHash }) {
69
+ if (!fs.existsSync(filePath)) {
70
+ return { schemaVersion: 1, runId, gitRevision, diffHash, commands: [] };
71
+ }
72
+ let bundle;
73
+ try {
74
+ bundle = JSON.parse(fs.readFileSync(filePath, 'utf8'));
75
+ } catch (cause) {
76
+ throw recorderError(`Existing verification.json is invalid: ${cause.message}`, 'INVALID_VERIFICATION');
77
+ }
78
+ if (
79
+ bundle.schemaVersion !== 1
80
+ || bundle.runId !== runId
81
+ || bundle.gitRevision !== gitRevision
82
+ || bundle.diffHash !== diffHash
83
+ || !Array.isArray(bundle.commands)
84
+ ) {
85
+ throw recorderError(
86
+ 'Existing verification.json belongs to another Run, revision, or Maker diff. Reconcile it before recording more commands.',
87
+ 'STALE_VERIFICATION'
88
+ );
89
+ }
90
+ return bundle;
91
+ }
92
+
93
+ function captureStream(stream) {
94
+ const chunks = [];
95
+ let bytes = 0;
96
+ let truncated = false;
97
+ stream.on('data', (chunk) => {
98
+ const remaining = MAX_CAPTURE_BYTES - bytes;
99
+ if (remaining <= 0) {
100
+ truncated = true;
101
+ return;
102
+ }
103
+ const captured = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
104
+ chunks.push(captured);
105
+ bytes += captured.length;
106
+ if (captured.length < chunk.length) truncated = true;
107
+ });
108
+ return {
109
+ value: () => Buffer.concat(chunks).toString('utf8'),
110
+ truncated: () => truncated
111
+ };
112
+ }
113
+
114
+ function displayCommand(command, args) {
115
+ const sensitiveArgument = /^--?(?:api[-_]?key|access[-_]?token|auth[-_]?token|token|password|secret|authorization)$/i;
116
+ let redactNext = false;
117
+ const safeParts = [command, ...args].map((part) => {
118
+ if (redactNext) {
119
+ redactNext = false;
120
+ return '[REDACTED ARGUMENT]';
121
+ }
122
+ if (sensitiveArgument.test(part)) {
123
+ redactNext = true;
124
+ return part;
125
+ }
126
+ return redactHomePaths(redactSecrets(part).text);
127
+ });
128
+ const rendered = safeParts
129
+ .map((part) => (/\s|["']/u.test(part) ? JSON.stringify(part) : part))
130
+ .join(' ');
131
+ return redactHomePaths(redactSecrets(rendered).text);
132
+ }
133
+
134
+ function runCommand(command, args, { cwd, timeoutMs, shell }) {
135
+ return new Promise((resolve) => {
136
+ const started = new Date();
137
+ let timedOut = false;
138
+ let launchError = null;
139
+ let forceKillTimer = null;
140
+ const child = spawn(command, shell ? [] : args, {
141
+ cwd,
142
+ env: process.env,
143
+ shell: Boolean(shell),
144
+ stdio: ['ignore', 'pipe', 'pipe']
145
+ });
146
+ const stdout = captureStream(child.stdout);
147
+ const stderr = captureStream(child.stderr);
148
+
149
+ const timeout = setTimeout(() => {
150
+ timedOut = true;
151
+ child.kill('SIGTERM');
152
+ forceKillTimer = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS);
153
+ forceKillTimer.unref?.();
154
+ }, timeoutMs);
155
+ timeout.unref?.();
156
+
157
+ child.once('error', (error) => {
158
+ launchError = error;
159
+ });
160
+ child.once('close', (code, signal) => {
161
+ clearTimeout(timeout);
162
+ if (forceKillTimer) clearTimeout(forceKillTimer);
163
+ const finished = new Date();
164
+ const rawStdout = stdout.value();
165
+ const rawStderr = launchError ? launchError.message : stderr.value();
166
+ const stdoutValue = redactHomePaths(redactSecrets(rawStdout).text);
167
+ const stderrValue = redactHomePaths(redactSecrets(rawStderr).text);
168
+ resolve({
169
+ command: displayCommand(command, args),
170
+ executionIdentity: `pid:${child.pid || process.pid}`,
171
+ startTime: started.toISOString(),
172
+ endTime: finished.toISOString(),
173
+ durationMs: Math.max(0, finished.getTime() - started.getTime()),
174
+ exitCode: launchError ? 127 : (timedOut ? (code ?? 124) : (code ?? 1)),
175
+ signal: signal || null,
176
+ timeoutStatus: timedOut ? 'TIMED_OUT' : 'COMPLETED',
177
+ stdout: stdoutValue || '(no stdout)',
178
+ stdoutWasEmpty: stdoutValue.length === 0,
179
+ stderr: stderrValue,
180
+ stdoutTruncated: stdout.truncated(),
181
+ stderrTruncated: stderr.truncated(),
182
+ ...(launchError ? { launchError: true } : {}),
183
+ ...(timedOut ? { summary: `Command timed out after ${timeoutMs} ms.` } : {})
184
+ });
185
+ });
186
+ });
187
+ }
188
+
189
+ async function recordVerificationCommand(rootDir, {
190
+ runId,
191
+ command,
192
+ args = [],
193
+ shell = false,
194
+ timeoutMs = DEFAULT_TIMEOUT_MS
195
+ } = {}) {
196
+ validateRecordingRequest({ command, args, timeoutMs, shell });
197
+ const run = resolveRun(rootDir, runId);
198
+ if (run.artifacts?.verification) {
199
+ throw recorderError('Verification has already passed its gate. Do not mutate gated evidence; start a new verification iteration instead.', 'VERIFICATION_ALREADY_GATED');
200
+ }
201
+
202
+ const diffHash = resolveDiff(rootDir, run);
203
+ const gitRevision = getGitRevision(rootDir);
204
+ const filePath = path.join(runsDir(rootDir), run.runId, 'verification.json');
205
+ const bundle = readExistingBundle(filePath, { runId: run.runId, gitRevision, diffHash });
206
+ const result = await runCommand(command, args, { cwd: rootDir, timeoutMs, shell });
207
+ bundle.commands.push(result);
208
+ atomicWriteJson(filePath, bundle);
209
+
210
+ const summary = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
211
+ return {
212
+ runId: run.runId,
213
+ path: path.relative(rootDir, filePath).split(path.sep).join('/'),
214
+ command: result,
215
+ summary
216
+ };
217
+ }
218
+
219
+ module.exports = {
220
+ DEFAULT_TIMEOUT_MS,
221
+ MAX_CAPTURE_BYTES,
222
+ MAX_TIMEOUT_MS,
223
+ recordVerificationCommand
224
+ };