ai-engineering-loop 1.0.19 → 1.1.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 (94) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +7 -3
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +13 -7
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +13 -7
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +13 -7
  5. package/README.md +26 -3
  6. package/SECURITY.md +23 -0
  7. package/SUPPORT.md +28 -0
  8. package/adapters/dot/README.md +12 -8
  9. package/adapters/dot/gitlab.md +29 -5
  10. package/adapters/dot/multi-branch.md +47 -68
  11. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +6 -8
  12. package/adapters/github/pull-request.md +15 -0
  13. package/adapters/gitlab/merge-request.md +15 -0
  14. package/adapters/standard/README.md +1 -0
  15. package/bin/ai-engineering-loop.js +255 -3
  16. package/core/artifact-gates.md +49 -0
  17. package/evals/README.md +35 -0
  18. package/evals/cases/01-stale-verification.json +17 -0
  19. package/evals/cases/02-vague-verification.json +16 -0
  20. package/evals/cases/03-missing-ac-evidence.json +17 -0
  21. package/evals/cases/04-hallucinated-citation.json +17 -0
  22. package/evals/cases/05-prompt-injection.json +17 -0
  23. package/evals/cases/06-source-secret.json +16 -0
  24. package/evals/cases/07-log-secret.json +16 -0
  25. package/evals/cases/08-symlink-escape.json +16 -0
  26. package/evals/cases/09-authorization-bypass.json +16 -0
  27. package/evals/cases/10-payment-idempotency.json +16 -0
  28. package/evals/cases/11-concurrent-update.json +16 -0
  29. package/evals/cases/12-swallowed-error.json +16 -0
  30. package/evals/cases/13-happy-path-only.json +17 -0
  31. package/evals/cases/14-invalid-finding-axis.json +16 -0
  32. package/evals/cases/15-blocker-without-alternative.json +16 -0
  33. package/evals/cases/16-unsupported-pass.json +17 -0
  34. package/evals/cases/17-soft-standard.json +16 -0
  35. package/evals/cases/18-iteration-ceiling.json +17 -0
  36. package/evals/cases/19-safe-documentation-change.json +17 -0
  37. package/evals/cases/20-valid-boundary-feature.json +18 -0
  38. package/lib/doctor.js +98 -0
  39. package/lib/escalation.js +192 -0
  40. package/lib/evaluation.js +137 -0
  41. package/lib/gates.js +315 -0
  42. package/lib/orchestration.js +5 -1
  43. package/lib/run-state.js +221 -0
  44. package/lib/safe-context.js +191 -0
  45. package/lib/sync-hosts.js +6 -5
  46. package/package.json +12 -9
  47. package/policies/model-escalation.md +41 -0
  48. package/schemas/delivery.schema.json +14 -0
  49. package/schemas/finding-ledger.schema.json +27 -0
  50. package/schemas/goal-contract.schema.json +32 -0
  51. package/schemas/verdict.schema.json +17 -0
  52. package/schemas/verification.schema.json +32 -0
  53. package/docs/antigravity-feasibility.md +0 -92
  54. package/docs/claude-code-feasibility.md +0 -80
  55. package/docs/grok-cli-feasibility.md +0 -99
  56. package/docs/migration-plan.md +0 -70
  57. package/examples/backend-api/payment-idempotency/README.md +0 -33
  58. package/examples/backend-api/payment-idempotency/goal-contract.md +0 -33
  59. package/examples/backend-api/payment-idempotency/judge-verdict.md +0 -28
  60. package/examples/backend-api/payment-idempotency/review-findings.md +0 -50
  61. package/examples/dot/status-display/README.md +0 -23
  62. package/examples/dot/status-display/delivery-report.md +0 -41
  63. package/examples/dot/status-display/goal-contract.md +0 -46
  64. package/examples/dot/status-display/judge-verdict.md +0 -44
  65. package/examples/dot/status-display/review-findings.md +0 -63
  66. package/examples/initialization/README.md +0 -19
  67. package/examples/initialization/discovery-trace.md +0 -63
  68. package/examples/initialization/generated-context.md +0 -110
  69. package/examples/mobile-app/offline-sync-queue/README.md +0 -33
  70. package/examples/mobile-app/offline-sync-queue/goal-contract.md +0 -32
  71. package/examples/mobile-app/offline-sync-queue/judge-verdict.md +0 -27
  72. package/examples/mobile-app/offline-sync-queue/review-findings.md +0 -30
  73. package/scripts/init.sh +0 -106
  74. package/templates/repo-config/adapter.md +0 -11
  75. package/templates/repo-config/adr-readme.md +0 -33
  76. package/templates/repo-config/architecture.md +0 -15
  77. package/templates/repo-config/claude-permissions.json +0 -10
  78. package/templates/repo-config/config.md +0 -11
  79. package/templates/repo-config/conventions.md +0 -16
  80. package/templates/repo-config/glossary.md +0 -18
  81. package/templates/repo-config/lessons.md +0 -8
  82. package/templates/repo-config/verification.md +0 -13
  83. package/templates/repo-config/workflow.md +0 -25
  84. package/tests/capability-selection.test.js +0 -207
  85. package/tests/claimed-vs-reality.test.js +0 -27
  86. package/tests/generate-adapter.test.js +0 -80
  87. package/tests/generate-workflow.test.js +0 -180
  88. package/tests/grok-runtime.test.js +0 -201
  89. package/tests/intern-catalog.test.js +0 -72
  90. package/tests/living-context.test.js +0 -61
  91. package/tests/no-company-leak.test.js +0 -82
  92. package/tests/orchestration.test.js +0 -368
  93. package/tests/skill-host-compat.test.js +0 -406
  94. package/tests/sync-hosts.test.js +0 -168
@@ -0,0 +1,191 @@
1
+ 'use strict';
2
+
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
7
+
8
+ const STAGE_LIMITS = Object.freeze({
9
+ maker: Object.freeze({ maxFiles: 12, maxFileBytes: 32_000, maxTotalBytes: 96_000, maxEstimatedTokens: 24_000 }),
10
+ 'devil-advocate': Object.freeze({ maxFiles: 8, maxFileBytes: 16_000, maxTotalBytes: 64_000, maxEstimatedTokens: 16_000 }),
11
+ judge: Object.freeze({ maxFiles: 3, maxFileBytes: 12_000, maxTotalBytes: 32_000, maxEstimatedTokens: 8_000 })
12
+ });
13
+
14
+ const SENSITIVE_NAMES = [
15
+ /^\.env(?:\.|$)/i,
16
+ /^\.npmrc$/i,
17
+ /^\.netrc$/i,
18
+ /^credentials(?:\.json)?$/i,
19
+ /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?$/i,
20
+ /\.(?:pem|key|p12|pfx|jks)$/i
21
+ ];
22
+
23
+ function contextError(message, code = 'UNSAFE_CONTEXT') {
24
+ const err = new Error(message);
25
+ err.code = code;
26
+ return err;
27
+ }
28
+
29
+ function inside(parent, child) {
30
+ const relative = path.relative(parent, child);
31
+ return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
32
+ }
33
+
34
+ function isSensitivePath(relativePath) {
35
+ const segments = relativePath.split(/[\\/]/);
36
+ if (segments.includes('.git') || segments.includes('node_modules')) return true;
37
+ return segments.some((segment) => SENSITIVE_NAMES.some((pattern) => pattern.test(segment)));
38
+ }
39
+
40
+ function resolveSafeRepoFile(rootDir, relativePath) {
41
+ if (!relativePath || path.isAbsolute(relativePath)) {
42
+ throw contextError(`Context path must be repository-relative: ${relativePath || '(empty)'}`);
43
+ }
44
+ const root = fs.realpathSync(rootDir);
45
+ const requested = path.resolve(root, relativePath);
46
+ if (!inside(root, requested)) throw contextError(`Context path escapes the repository: ${relativePath}`);
47
+ const normalized = path.relative(root, requested);
48
+ if (isSensitivePath(normalized)) throw contextError(`Sensitive context path is blocked: ${relativePath}`);
49
+
50
+ let real;
51
+ try {
52
+ real = fs.realpathSync(requested);
53
+ } catch (cause) {
54
+ throw contextError(`Context file is unavailable: ${relativePath} (${cause.message})`, 'CONTEXT_FILE_MISSING');
55
+ }
56
+ if (!inside(root, real)) throw contextError(`Context symlink escapes the repository: ${relativePath}`);
57
+ const stat = fs.statSync(real);
58
+ if (!stat.isFile()) throw contextError(`Context path is not a file: ${relativePath}`);
59
+ return { absolute: real, relative: path.relative(root, real).split(path.sep).join('/') };
60
+ }
61
+
62
+ function redactSecrets(input) {
63
+ let text = String(input || '');
64
+ const categories = new Set();
65
+ const replace = (pattern, category, replacement) => {
66
+ text = text.replace(pattern, (...args) => {
67
+ categories.add(category);
68
+ return typeof replacement === 'function' ? replacement(...args) : replacement;
69
+ });
70
+ };
71
+
72
+ replace(
73
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
74
+ 'private-key',
75
+ '[REDACTED PRIVATE KEY]'
76
+ );
77
+ replace(/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, 'bearer-token', 'Bearer [REDACTED]');
78
+ replace(/\bgithub_pat_[A-Za-z0-9_]{12,}\b/g, 'github-token', '[REDACTED GITHUB TOKEN]');
79
+ replace(/\bgh[pousr]_[A-Za-z0-9]{12,}\b/g, 'github-token', '[REDACTED GITHUB TOKEN]');
80
+ replace(/\bAKIA[A-Z0-9]{16}\b/g, 'aws-access-key', '[REDACTED AWS ACCESS KEY]');
81
+ replace(/\bsk-(?:live-|test-)?[A-Za-z0-9_-]{8,}\b/g, 'api-token', '[REDACTED API TOKEN]');
82
+ replace(
83
+ /(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|secret|password|authorization)\b\s*[:=]\s*["']?)([^"'\s,;]+)/gi,
84
+ 'key-value-secret',
85
+ (_match, prefix) => `${prefix}[REDACTED]`
86
+ );
87
+
88
+ return { text, categories: [...categories].sort() };
89
+ }
90
+
91
+ function sha256(content) {
92
+ return crypto.createHash('sha256').update(content).digest('hex');
93
+ }
94
+
95
+ function estimateTokens(text) {
96
+ return Math.ceil(String(text || '').length / 4);
97
+ }
98
+
99
+ function resolveRun(rootDir, runId) {
100
+ if (runId) return loadRun(rootDir, runId);
101
+ const current = getCurrentRun(rootDir);
102
+ if (!current) throw contextError('No current run. Start one before building context.', 'NO_CURRENT_RUN');
103
+ return current;
104
+ }
105
+
106
+ function createContextPack(rootDir, { runId, stage, files } = {}) {
107
+ const limits = STAGE_LIMITS[stage];
108
+ if (!limits) {
109
+ throw contextError(`Unknown context stage: ${stage}. Use ${Object.keys(STAGE_LIMITS).join('|')}`, 'UNKNOWN_CONTEXT_STAGE');
110
+ }
111
+ const run = resolveRun(rootDir, runId);
112
+ const uniqueFiles = [...new Set((files || []).map((file) => String(file).trim()).filter(Boolean))];
113
+ if (uniqueFiles.length === 0) throw contextError('At least one context file is required', 'EMPTY_CONTEXT');
114
+ if (uniqueFiles.length > limits.maxFiles) {
115
+ throw contextError(`${stage} context allows at most ${limits.maxFiles} files`, 'CONTEXT_FILE_LIMIT');
116
+ }
117
+
118
+ const entries = [];
119
+ let totalBytes = 0;
120
+ let estimatedTokens = 0;
121
+ for (const requested of uniqueFiles) {
122
+ const safe = resolveSafeRepoFile(rootDir, requested);
123
+ const raw = fs.readFileSync(safe.absolute);
124
+ if (raw.includes(0)) throw contextError(`Binary context is blocked: ${requested}`, 'BINARY_CONTEXT');
125
+
126
+ const remaining = limits.maxTotalBytes - totalBytes;
127
+ if (remaining <= 0) throw contextError(`${stage} context exceeds its byte budget`, 'CONTEXT_BYTE_LIMIT');
128
+ const allowedBytes = Math.min(raw.length, limits.maxFileBytes, remaining);
129
+ const source = raw.subarray(0, allowedBytes).toString('utf8');
130
+ const redacted = redactSecrets(source);
131
+ const tokens = estimateTokens(redacted.text);
132
+ if (estimatedTokens + tokens > limits.maxEstimatedTokens) {
133
+ throw contextError(`${stage} context exceeds its estimated token budget`, 'CONTEXT_TOKEN_LIMIT');
134
+ }
135
+
136
+ totalBytes += allowedBytes;
137
+ estimatedTokens += tokens;
138
+ entries.push({
139
+ path: safe.relative,
140
+ sourceSha256: sha256(raw),
141
+ sourceBytes: raw.length,
142
+ includedBytes: allowedBytes,
143
+ estimatedTokens: tokens,
144
+ truncated: allowedBytes < raw.length,
145
+ redactions: redacted.categories,
146
+ content: redacted.text
147
+ });
148
+ }
149
+
150
+ const pack = {
151
+ schemaVersion: 1,
152
+ runId: run.runId,
153
+ stage,
154
+ createdAt: new Date().toISOString(),
155
+ transcriptInherited: false,
156
+ limits,
157
+ totalBytes,
158
+ estimatedTokens,
159
+ entries
160
+ };
161
+ const packPath = path.join(runsDir(rootDir), run.runId, 'context', `${stage}.json`);
162
+ atomicWriteJson(packPath, pack);
163
+ return {
164
+ pack,
165
+ path: path.relative(rootDir, packPath).split(path.sep).join('/')
166
+ };
167
+ }
168
+
169
+ function contextPackSummary(result) {
170
+ return {
171
+ schemaVersion: result.pack.schemaVersion,
172
+ runId: result.pack.runId,
173
+ stage: result.pack.stage,
174
+ path: result.path,
175
+ files: result.pack.entries.length,
176
+ totalBytes: result.pack.totalBytes,
177
+ estimatedTokens: result.pack.estimatedTokens,
178
+ redactions: result.pack.entries.reduce((sum, entry) => sum + entry.redactions.length, 0),
179
+ truncatedFiles: result.pack.entries.filter((entry) => entry.truncated).length
180
+ };
181
+ }
182
+
183
+ module.exports = {
184
+ STAGE_LIMITS,
185
+ isSensitivePath,
186
+ resolveSafeRepoFile,
187
+ redactSecrets,
188
+ estimateTokens,
189
+ createContextPack,
190
+ contextPackSummary
191
+ };
package/lib/sync-hosts.js CHANGED
@@ -14,12 +14,13 @@ function homeDir(env = process.env) {
14
14
  }
15
15
 
16
16
  function applyGrokSkillOverlay(content) {
17
- const match = content.match(/^---\n([\s\S]*?)\n---\n/);
18
- if (!match) return content;
17
+ const normalized = String(content).replace(/\r\n?/g, '\n');
18
+ const match = normalized.match(/^---\n([\s\S]*?)\n---\n/);
19
+ if (!match) return normalized;
19
20
  const yaml = match[1];
20
- if (/^user-invocable:\s*true\s*$/m.test(yaml)) return content;
21
+ if (/^user-invocable:\s*true\s*$/m.test(yaml)) return normalized;
21
22
  const nextYaml = `${yaml.replace(/\s*$/, '')}\nuser-invocable: true`;
22
- return `---\n${nextYaml}\n---\n${content.slice(match[0].length)}`;
23
+ return `---\n${nextYaml}\n---\n${normalized.slice(match[0].length)}`;
23
24
  }
24
25
 
25
26
  function hostFileMap(home) {
@@ -133,7 +134,7 @@ function planHostSync({ packageRoot: root = packageRoot(), home = homeDir() } =
133
134
  results.push({ ...item, action: 'skip', reason: 'not-installed' });
134
135
  continue;
135
136
  }
136
- let content = fs.readFileSync(srcAbs, 'utf8');
137
+ let content = fs.readFileSync(srcAbs, 'utf8').replace(/\r\n?/g, '\n');
137
138
  if (file.grokSkillOverlay) content = applyGrokSkillOverlay(content);
138
139
  if (destExists(file.dest) && fs.readFileSync(file.dest, 'utf8') === content) {
139
140
  results.push({ ...item, action: 'current' });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.0.19",
3
+ "version": "1.1.0",
4
4
  "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
5
5
  "main": "bin/ai-engineering-loop.js",
6
6
  "bin": {
@@ -14,11 +14,8 @@
14
14
  "policies/",
15
15
  "profiles/",
16
16
  "adapters/",
17
- "templates/",
18
- "examples/",
19
- "docs/",
20
- "tests/",
21
- "scripts/",
17
+ "schemas/",
18
+ "evals/",
22
19
  ".agents/",
23
20
  ".grok/",
24
21
  ".gemini/skills/",
@@ -26,12 +23,18 @@
26
23
  ".claude/commands/",
27
24
  ".claude/skills/",
28
25
  "LICENSE",
29
- "README.md",
30
- "README.npm.md"
26
+ "SECURITY.md",
27
+ "SUPPORT.md",
28
+ "README.md"
31
29
  ],
32
30
  "scripts": {
33
31
  "init": "node bin/ai-engineering-loop.js",
34
- "test": "node --test tests/*.test.js"
32
+ "test": "node --test",
33
+ "doctor": "node bin/ai-engineering-loop.js doctor",
34
+ "eval": "node bin/ai-engineering-loop.js eval"
35
+ },
36
+ "engines": {
37
+ "node": ">=18"
35
38
  },
36
39
  "repository": {
37
40
  "type": "git",
@@ -0,0 +1,41 @@
1
+ # Model Escalation Policy
2
+
3
+ Cheap models are the default Maker, Devil's Advocate, and Judge. Required workflow stages never disappear when the model tier changes.
4
+
5
+ The objective is not to prevent every model error. Unsupported output must fail a deterministic gate, and repeated uncertainty must move to a stronger reviewer.
6
+
7
+ ## Deterministic routing
8
+
9
+ Use `CHEAP_MODEL` when all evidence is current, context is complete, and no high-risk path changed.
10
+
11
+ Require `STRONG_MODEL` when any of these signals exist:
12
+
13
+ - Authentication, authorization, payment, billing, database migration, infrastructure, cryptography, or secret-handling paths changed.
14
+ - The model emitted two invalid structured artifacts.
15
+ - A finding cites a path that does not exist.
16
+ - Verification is flaky.
17
+ - A stage context pack was truncated.
18
+ - A critical acceptance criterion remains `UNKNOWN`.
19
+ - Devil's Advocate and Judge disagree about a blocking finding.
20
+
21
+ Require `HUMAN` when:
22
+
23
+ - The iteration ceiling is reached.
24
+ - A credential or evaluation canary reached model-visible output.
25
+
26
+ Diff size alone is not a risk classification. A one-line authorization change can require stronger review.
27
+
28
+ ## Verdict metadata
29
+
30
+ Judge writes `modelTier` in `verdict.json`:
31
+
32
+ ```json
33
+ {
34
+ "modelTier": "CHEAP_MODEL",
35
+ "humanApproved": false
36
+ }
37
+ ```
38
+
39
+ `ai-engineering-loop gate judge` computes the required tier. A lower tier may safely issue `ESCALATE`, but it cannot issue `PASS` when stronger review is required.
40
+
41
+ Run `ai-engineering-loop escalation --json` before spawning Judge to select the minimum acceptable tier. Do not invent a provider or model slug; resolve the tier through the active host's model catalog.
@@ -0,0 +1,14 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/delivery.schema.json",
4
+ "title": "AI Engineering Loop Delivery Record",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "runId", "destination", "summary"],
7
+ "properties": {
8
+ "schemaVersion": { "const": 1 },
9
+ "runId": { "type": "string", "minLength": 1 },
10
+ "destination": { "type": "string", "minLength": 1 },
11
+ "summary": { "type": "string", "minLength": 1 }
12
+ },
13
+ "additionalProperties": true
14
+ }
@@ -0,0 +1,27 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/finding-ledger.schema.json",
4
+ "title": "AI Engineering Loop Finding Ledger",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "runId", "diffHash", "findings"],
7
+ "properties": {
8
+ "schemaVersion": { "const": 1 },
9
+ "runId": { "type": "string", "minLength": 1 },
10
+ "diffHash": { "type": "string", "minLength": 1 },
11
+ "findings": {
12
+ "type": "array",
13
+ "items": {
14
+ "type": "object",
15
+ "required": ["id", "location", "failureScenario", "evidence", "severity", "validity", "disposition"],
16
+ "properties": {
17
+ "axis": { "enum": ["spec", "standards"] },
18
+ "severity": { "enum": ["BLOCKER", "HIGH", "MEDIUM", "LOW"] },
19
+ "validity": { "enum": ["VALID", "INVALID"] },
20
+ "disposition": { "enum": ["STRONG", "ACCEPTABLE", "WEAK"] }
21
+ },
22
+ "additionalProperties": true
23
+ }
24
+ }
25
+ },
26
+ "additionalProperties": true
27
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/goal-contract.schema.json",
4
+ "title": "AI Engineering Loop Goal Contract",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "runId", "objective", "acceptanceCriteria"],
7
+ "properties": {
8
+ "schemaVersion": { "const": 1 },
9
+ "runId": { "type": "string", "minLength": 1 },
10
+ "objective": { "type": "string", "minLength": 1 },
11
+ "acceptanceCriteria": {
12
+ "type": "array",
13
+ "minItems": 1,
14
+ "items": {
15
+ "type": "object",
16
+ "required": ["id", "statement", "evidenceRequired", "failureCases"],
17
+ "properties": {
18
+ "id": { "type": "string", "pattern": "^AC-[0-9]+$" },
19
+ "statement": { "type": "string", "minLength": 1 },
20
+ "evidenceRequired": { "type": "string", "minLength": 1 },
21
+ "failureCases": {
22
+ "type": "array",
23
+ "minItems": 1,
24
+ "items": { "type": "string", "minLength": 1 }
25
+ }
26
+ },
27
+ "additionalProperties": true
28
+ }
29
+ }
30
+ },
31
+ "additionalProperties": true
32
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/verdict.schema.json",
4
+ "title": "AI Engineering Loop Judge Verdict",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "runId", "verdict", "reason", "action"],
7
+ "properties": {
8
+ "schemaVersion": { "const": 1 },
9
+ "runId": { "type": "string", "minLength": 1 },
10
+ "verdict": { "enum": ["PASS", "ITERATE", "ESCALATE"] },
11
+ "reason": { "type": "string", "minLength": 1 },
12
+ "action": { "type": "string", "minLength": 1 },
13
+ "modelTier": { "enum": ["CHEAP_MODEL", "STRONG_MODEL", "HUMAN"] },
14
+ "humanApproved": { "type": "boolean" }
15
+ },
16
+ "additionalProperties": true
17
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/egagofur/ai-engineering-loop/schemas/verification.schema.json",
4
+ "title": "AI Engineering Loop Verification Evidence",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "runId", "gitRevision", "diffHash", "commands"],
7
+ "properties": {
8
+ "schemaVersion": { "const": 1 },
9
+ "runId": { "type": "string", "minLength": 1 },
10
+ "gitRevision": { "type": "string", "minLength": 1 },
11
+ "diffHash": { "type": "string", "minLength": 1 },
12
+ "commands": {
13
+ "type": "array",
14
+ "minItems": 1,
15
+ "items": {
16
+ "type": "object",
17
+ "required": ["command", "executionIdentity", "startTime", "endTime", "exitCode", "stdout", "timeoutStatus"],
18
+ "properties": {
19
+ "command": { "type": "string", "minLength": 1 },
20
+ "executionIdentity": { "type": "string", "minLength": 1 },
21
+ "startTime": { "type": "string", "minLength": 1 },
22
+ "endTime": { "type": "string", "minLength": 1 },
23
+ "exitCode": { "const": 0 },
24
+ "stdout": { "type": "string", "minLength": 1 },
25
+ "timeoutStatus": { "const": "COMPLETED" }
26
+ },
27
+ "additionalProperties": true
28
+ }
29
+ }
30
+ },
31
+ "additionalProperties": true
32
+ }
@@ -1,92 +0,0 @@
1
- # Antigravity Sub-Agent Feasibility & Execution Strategy
2
-
3
- ## 1. Executive Summary
4
-
5
- This document evaluates the practical feasibility of executing the **AI Engineering Loop** (Maker, Devil's Advocate, Judge) inside the **Google Antigravity IDE / Agentic Platform**, addressing runtime capabilities, context segregation, token economics, and persistence.
6
-
7
- ---
8
-
9
- ## 2. Analysis of the 8 Core Questions
10
-
11
- ```mermaid
12
- flowchart TD
13
- Main[Antigravity Primary Agent / Planner] -->|Spawn / Invoke| SubDA[Sub-Agent / Persona: Devil's Advocate]
14
- Main -->|Spawn / Invoke| SubJD[Sub-Agent / Persona: Judge]
15
-
16
- SubDA -->|Reads Same Workspace & Git Diff| Repo[(Workspace Files & Git)]
17
- SubDA -->|Returns Finding Ledger| Main
18
-
19
- Main -->|Evaluates with Judge Policy| SubJD
20
- SubJD -->|Returns PASS / ITERATE / ESCALATE| Main
21
-
22
- Main -->|Persists State Artifacts| BrainDir[(brain/<conversation_id>/)]
23
- ```
24
-
25
- ### 1. Can Antigravity summon independent sub-agents?
26
- - **Status**: **YES**.
27
- - **Mechanism**: Antigravity natively supports agentic delegation through sub-agents (e.g. `invoke_subagent` / `browser_subagent` / background tasks). Sub-agents execute with their own independent message loops, instructions, and tool sets.
28
- - **Alternative / Fallback**: If subagent spawning is constrained in a single-agent CLI mode, Antigravity agents can execute **Context-Switched Multi-Turn Personas** by clearing operational context, adopting strict role instructions, and evaluating the isolated `git diff`.
29
-
30
- ### 2. Can the main agent pass context to a sub-agent?
31
- - **Status**: **YES**.
32
- - **Mechanism**: The spawning task payload allows passing:
33
- - The [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
34
- - Target base branch name (`main`, `develop`).
35
- - Active iteration index and finding ledger history.
36
-
37
- ### 3. Can the sub-agent inspect the same repository?
38
- - **Status**: **YES**.
39
- - **Mechanism**: Sub-agents share the active workspace root (`/Users/.../ai-engineering-loop`). They have access to `view_file`, `grep_search`, `list_dir`, and `run_command` (`git diff`, `git log`, `npx jest`, etc.).
40
-
41
- ### 4. Can the sub-agent return structured findings?
42
- - **Status**: **YES**.
43
- - **Mechanism**: The sub-agent is instructed to output strictly formatted YAML/Markdown compliant with the [Finding Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/finding-policy.md). Upon task completion, the structured output is delivered directly back into the primary agent's context.
44
-
45
- ### 5. Can the main agent consume those findings?
46
- - **Status**: **YES**.
47
- - **Mechanism**: The primary agent parses the returned Finding Ledger, updates the iteration state artifact, and feeds the findings into the [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md).
48
-
49
- ### 6. Can the loop be repeated automatically?
50
- - **Status**: **YES**.
51
- - **Mechanism**: Antigravity's autonomous loop executes sequentially until the Judge outputs `PASS` or triggers `ESCALATE`. The loop does not require human intervention between iterations unless an escalation trigger is activated.
52
-
53
- ### 7. Can iteration state be persisted?
54
- - **Status**: **YES**.
55
- - **Mechanism**: Antigravity provides a dedicated per-conversation artifact directory:
56
- `<appDataDir>/brain/<conversation-id>/`
57
- The loop persists:
58
- - `goal_contract.md`
59
- - `iteration_ledger.json` (finding signatures, iteration index, diff hashes)
60
- - `verification_logs.txt`
61
- - `judge_verdict.md`
62
-
63
- ### 8. What are the practical token/context limitations?
64
- - **Analysis**:
65
- - Full codebase context in every prompt leads to context bloat and degraded attention.
66
- - **Optimization Strategy**:
67
- - Write `git diff` to `.ai-engineering-loop/tasks/current.diff` and pass that path.
68
- - Devil's Advocate: at most 8 tool calls; skip css/generated; no git log; wait (no background).
69
- - Judge: at most 4 tool calls; ledger + Goal Contract only; fact-check cited locations; wait.
70
- - Do not use `browser_subagent` as a reviewer.
71
- - If `invoke_subagent` is missing, use CONTEXT_ISOLATION_ONLY with the same budgets. See `policies/review-budget.md` and `.agents/`.
72
-
73
- ---
74
-
75
- ## 3. Recommended Execution Modes in Antigravity
76
-
77
- | Dimension | Mode A: Native Sub-Agents (Recommended) | Mode B: Persona Context Switching |
78
- |---|---|---|
79
- | **Context Isolation** | 100% Isolated context window | Sequential turns within single context |
80
- | **Cognitive Bias** | Zero author bias (clean slate) | Low bias if context is scoped to diff |
81
- | **Token Overhead** | Minimal (sub-agent starts fresh) | Moderate (context grows across turns) |
82
- | **Implementation Complexity** | Requires subagent invocation tool | Works natively in standard chat turn |
83
- | **Antigravity Fit** | Ideal for complex multi-file features | Ideal for quick, surgical fixes |
84
-
85
- ---
86
-
87
- ## 4. Implementation Roadmap for Antigravity Skill
88
-
89
- To deploy this workflow as an Antigravity Custom Skill (e.g. `skills/ai-engineering-loop/SKILL.md`):
90
- 1. Package the core loop into an executable skill definition with YAML frontmatter.
91
- 2. Provide slash command shortcuts (e.g. `/loop:start`, `/loop:review`).
92
- 3. Bind the DOT Adapter as an opt-in release plugin when working inside DOT repositories.
@@ -1,80 +0,0 @@
1
- # Claude Code Feasibility and Kiro Request Safety
2
-
3
- ## 1. Problem
4
-
5
- Claude Code users (including Kiro-backed models such as `kiro/claude-sonnet-5`) hit:
6
-
7
- ```
8
- API Error: 400 [kiro/claude-sonnet-5] [400]:
9
- {"message":"Improperly formed request.","reason":"REQUEST_BODY_INVALID"}
10
- ```
11
-
12
- Kiro's `generateAssistantResponse` rejects request bodies that Claude Code will happily send. Two skill-side causes were confirmed:
13
-
14
- 1. **Extra tool keys.** The shared skill told the model to call `spawn_subagent` with `capability_mode`, `isolation`, and `resume_from`. Claude Code's Task/Agent schema does not have those fields. Proxies that validate additionalProperties fail with `REQUEST_BODY_INVALID`.
15
- 2. **Hostile markup in the injected skill.** Mermaid (`<br>`, nested `{braces}`), LaTeX (`$\rightarrow$`), and folded YAML descriptions inflate and corrupt the system/skill payload Kiro receives.
16
-
17
- This is separate from 9router bugs that reject any Anthropic `system` field. Those need a router fix. The skill must still not add extra invalid keys or markup.
18
-
19
- ## 2. Claude Code mapping
20
-
21
- | Loop role | Claude Code type | Task keys allowed |
22
- |---|---|---|
23
- | Orchestrator / Maker | parent session | n/a |
24
- | Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt`, `run_in_background: false` |
25
- | Judge | `judge` (fallback `general-purpose`) | same; wait for DA first |
26
-
27
- Parent must write `git diff` to a file and pass that path. DA budget: 8 tool calls, skip css/generated, no git log. Do not leave DA running in the background.
28
-
29
- Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`, `isolation`, `background`) on Claude Code.
30
-
31
- Repo files:
32
-
33
- - `.claude/skills/ai-engineering-loop/SKILL.md`
34
- - `.claude/agents/devil-advocate.md`
35
- - `.claude/agents/judge.md`
36
- - `.claude/commands/ai-engineering-loop.md`
37
-
38
- ## 3. Mode selection
39
-
40
- | Condition | Mode |
41
- |---|---|
42
- | Task/Agent tool present, child result returned | `TRUE_INDEPENDENT_AGENT` |
43
- | No subagent tool | `CONTEXT_ISOLATION_ONLY` |
44
-
45
- ## 4. Second 400 path: auto-mode Bash classifier
46
-
47
- A later failure looks like this:
48
-
49
- ```
50
- Error: kr/claude-sonnet-5 is temporarily unavailable, so auto mode
51
- cannot determine the safety of Bash right now.
52
- API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
53
- ```
54
-
55
- Read/Grep still work. The first Bash that needs the auto-mode safety classifier (`npm run typecheck`, `npm test`) is sent to Kiro. When that classifier request is invalid or the model is down, Claude Code retries and Kiro returns 400.
56
-
57
- Mitigations shipped in the skill:
58
-
59
- 1. `allowed-tools` pre-approves `Bash(npm run *)`, `Bash(npm test *)`, `Bash(npx *)`, `Bash(git *)` so those commands skip the classifier when the skill or slash command is active.
60
- 2. The skill tells the model not to retry Bash/Write after a classifier or 400 failure.
61
- 3. Project allow rules (copy into `.claude/settings.local.json`):
62
-
63
- ```json
64
- {
65
- "permissions": {
66
- "allow": [
67
- "Bash(npm run *)",
68
- "Bash(npm test *)",
69
- "Bash(npx *)",
70
- "Bash(git *)"
71
- ]
72
- }
73
- }
74
- ```
75
-
76
- If 400 still happens on a fresh session with no Bash yet, it is the 9router `system` field bug, not this package.
77
-
78
- ## 5. What stays in Grok-only files
79
-
80
- Grok spawn details live in `.grok/skills/ai-engineering-loop/SKILL.md`. Claude Code must not load that file as its skill. Claude Code discovers `.claude/` first.