ai-engineering-loop 1.0.4 → 1.0.6

package/lib/orchestration.js

@@ -11,9 +11,15 @@
  * 3. Artifact isolation is strictly reported as CONTEXT_ISOLATION_ONLY (Independent LLM execution: NOT PROVEN).
  * 4. browser_subagent is browser automation and must NOT be classified as an LLM subagent.
  * 5. agentapi send-message is an IPC communication capability and must NEVER activate agent execution.
+ * 6. grok spawn_subagent is a true independent child session (own context, no parent transcript)
+ *    when a child id and model response are captured. GROK_SUBAGENTS=0 disables invocation.
+ * 7. caveman:cavecrew-reviewer is a compressed code-review preset with a different output schema
+ *    and must NEVER be used as the Devil's Advocate or Judge.
  */
 
 const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
 
 // 1. Standard 5 Execution Modes
 const EXECUTION_MODES = {
@@ -49,6 +55,30 @@ const EXECUTION_MODES = {
   }
 };
 
+/**
+ * Skill / agent-spec aliases. The skill historically used NATIVE_SUBAGENT etc.
+ * Canonical runtime IDs remain the 5 EXECUTION_MODES keys.
+ */
+const EXECUTION_MODE_ALIASES = {
+  NATIVE_SUBAGENT: 'TRUE_INDEPENDENT_AGENT',
+  SDK_AGENT: 'ISOLATED_AGENT_INSTANCE',
+  HEADLESS_SUBPROCESS: 'FRESH_PROCESS_AGENT',
+  ARTIFACT_ISOLATED_REVIEW: 'CONTEXT_ISOLATION_ONLY'
+};
+
+const GROK_FORBIDDEN_REVIEW_TYPES = [
+  'caveman:cavecrew-reviewer',
+  'caveman:cavecrew-builder',
+  'caveman:cavecrew-investigator',
+  'explore',
+  'plan'
+];
+
+function resolveExecutionModeId(modeId) {
+  if (!modeId) return 'UNAVAILABLE';
+  return EXECUTION_MODE_ALIASES[modeId] || modeId;
+}
+
 /**
  * 2. Standardized Capability Evidence Factory with 3-Stage Lifecycle
  */
@@ -126,6 +156,15 @@ function isCapabilityProvenForMode(evidence, targetModeId) {
     return false;
   }
 
+  // Reject compressed review presets that do not emit the Finding Ledger schema
+  if (
+    evidence.classification === 'GROK_COMPRESSED_REVIEW_PRESET' ||
+    GROK_FORBIDDEN_REVIEW_TYPES.includes(evidence.mechanism) ||
+    GROK_FORBIDDEN_REVIEW_TYPES.includes(evidence.commandOrApi)
+  ) {
+    return false;
+  }
+
   // Reject documentation-only or configuration-only claims
   if (evidence.isDocumentationOnly || (evidence.configurationSupported && !evidence.executionProven)) {
     if (targetModeId !== 'CONTEXT_ISOLATION_ONLY') {
@@ -376,7 +415,142 @@ function computeJudgeVerdict({
 }
 
 /**
- * 9. Truthful Review Report Generator
+ * 9. Detect Grok CLI as a host runtime.
+ * Presence of the grok binary is CONFIGURATION_SUPPORTED.
+ * GROK_SUBAGENTS=0 means invocation is disabled even if grok is installed.
+ * Execution is never proven from detection alone.
+ */
+function detectGrokRuntime(env = process.env, fsApi = fs) {
+  const grokHome = env.GROK_HOME || path.join(env.HOME || env.USERPROFILE || '', '.grok');
+  const grokBinCandidates = [
+    env.GROK_BIN,
+    path.join(grokHome, 'bin', 'grok'),
+    path.join(grokHome, 'bin', 'agent')
+  ].filter(Boolean);
+
+  const grokBin = grokBinCandidates.find((candidate) => {
+    try {
+      return fsApi.existsSync(candidate);
+    } catch (e) {
+      return false;
+    }
+  }) || null;
+
+  const grokPresent = Boolean(grokBin);
+  const subagentsDisabled = env.GROK_SUBAGENTS === '0';
+  const invocationAvailable = grokPresent && !subagentsDisabled;
+
+  let reason;
+  if (!grokPresent) {
+    reason = 'Grok CLI binary not found under GROK_HOME/bin';
+  } else if (subagentsDisabled) {
+    reason = 'GROK_SUBAGENTS=0 disables spawn_subagent; fall back to CONTEXT_ISOLATION_ONLY or grok -p';
+  } else {
+    reason = 'Grok CLI present; spawn_subagent is the native independent-agent tool (enabled by default)';
+  }
+
+  return {
+    host: grokPresent ? 'grok-cli' : 'unknown',
+    grokHome,
+    grokBin,
+    configurationSupported: grokPresent,
+    invocationAvailable,
+    executionProven: false,
+    subagentsDisabled,
+    commandOrApi: 'spawn_subagent',
+    headlessCommand: 'grok -p',
+    reason
+  };
+}
+
+/**
+ * 10. Build capability evidence for Grok spawn_subagent.
+ * Independent context is proven only when the child did not resume a Maker transcript.
+ */
+function createGrokCapabilityEvidence({
+  invocationAvailable = false,
+  executionProven = false,
+  childConversationId = null,
+  childModelResponse = null,
+  executionIdentity = null,
+  independentContextProven = false,
+  historyInherited = null,
+  resumeFrom = null,
+  reason = null
+} = {}) {
+  const resumedMaker = Boolean(resumeFrom);
+  const inherited = historyInherited === true || resumedMaker;
+  const modelExecuted = Boolean(executionProven || childModelResponse);
+  const fullyProven = Boolean(
+    modelExecuted &&
+      childConversationId &&
+      executionIdentity &&
+      independentContextProven &&
+      !inherited
+  );
+
+  return createCapabilityEvidence({
+    mechanism: 'grok-spawn_subagent',
+    classification: fullyProven
+      ? 'TRUE_INDEPENDENT_AGENT'
+      : invocationAvailable
+        ? 'INVOCATION_AVAILABLE'
+        : 'CONFIGURATION_SUPPORTED_WITHOUT_INVOCATION_TOOL',
+    configurationSupported: true,
+    invocationAvailable: Boolean(invocationAvailable),
+    executionProven: fullyProven,
+    available: Boolean(invocationAvailable || fullyProven),
+    commandOrApi: 'spawn_subagent',
+    childConversationId,
+    childModelResponse,
+    executionIdentity,
+    modelExecutionProven: modelExecuted,
+    independentContextProven: Boolean(independentContextProven && !inherited),
+    historyInherited: inherited ? true : historyInherited,
+    reason: reason || (resumedMaker
+      ? 'resume_from inherits the source transcript; Devil\'s Advocate and Judge must spawn fresh'
+      : null)
+  });
+}
+
+/**
+ * 11. Grok spawn plan for Devil's Advocate / Judge.
+ * Parent orchestrator spawns children; children must not spawn children (depth 1).
+ * Never pass resume_from. Never use cavecrew-reviewer (wrong output schema).
+ */
+function buildGrokReviewSpawnPlan({
+  role,
+  iteration = 1,
+  artifactPaths = {}
+} = {}) {
+  if (role !== 'devil-advocate' && role !== 'judge') {
+    throw new Error('Grok review spawn role must be devil-advocate or judge');
+  }
+
+  return {
+    tool: 'spawn_subagent',
+    subagent_type: role,
+    fallback_subagent_type: 'general-purpose',
+    description: role === 'judge'
+      ? `[judge] evaluate iteration ${iteration}`
+      : `[devil-advocate] review iteration ${iteration}`,
+    background: false,
+    capability_mode: 'execute',
+    isolation: 'none',
+    resume_from: null,
+    forbidden_types: [...GROK_FORBIDDEN_REVIEW_TYPES],
+    artifactPaths: {
+      goalContract: artifactPaths.goalContract || null,
+      gitDiff: artifactPaths.gitDiff || null,
+      verificationLogs: artifactPaths.verificationLogs || null,
+      projectContext: artifactPaths.projectContext || '.ai-engineering-loop/',
+      findingLedger: artifactPaths.findingLedger || null
+    }
+  };
+}
+
+/**
+ * 12. Truthful Review Report Generator
  * Enforces mandatory reporting headers and strictly prevents misleading phrasing.
  */
 function formatExecutionReport({ selectedMode, capabilityRegistry = {} }) {
@@ -398,6 +572,9 @@ function formatExecutionReport({ selectedMode, capabilityRegistry = {} }) {
 
 module.exports = {
   EXECUTION_MODES,
+  EXECUTION_MODE_ALIASES,
+  GROK_FORBIDDEN_REVIEW_TYPES,
+  resolveExecutionModeId,
   createCapabilityEvidence,
   isCapabilityProvenForMode,
   selectExecutionMode,
@@ -405,5 +582,8 @@ module.exports = {
   validateVerificationEvidence,
   validateFindingLedger,
   computeJudgeVerdict,
-  formatExecutionReport
+  formatExecutionReport,
+  detectGrokRuntime,
+  createGrokCapabilityEvidence,
+  buildGrokReviewSpawnPlan
 };

package/package.json

@@ -1,11 +1,30 @@
 {
   "name": "ai-engineering-loop",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
   "main": "bin/ai-engineering-loop.js",
   "bin": {
     "ai-engineering-loop": "bin/ai-engineering-loop.js"
   },
+  "files": [
+    "bin/",
+    "lib/",
+    "core/",
+    "agents/",
+    "policies/",
+    "profiles/",
+    "adapters/",
+    "templates/",
+    "examples/",
+    "docs/",
+    "tests/",
+    "scripts/",
+    ".grok/",
+    ".claude/",
+    "LICENSE",
+    "README.md",
+    "README.npm.md"
+  ],
   "scripts": {
     "init": "node bin/ai-engineering-loop.js",
     "test": "node --test tests/*.test.js"
@@ -21,7 +40,10 @@
     "devils-advocate",
     "verification",
     "autonomous-agents",
-    "antigravity"
+    "antigravity",
+    "grok",
+    "claude-code",
+    "subagents"
   ],
   "author": "Ega Gofur",
   "license": "MIT",

package/tests/grok-runtime.test.js

@@ -0,0 +1,201 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const {
+  EXECUTION_MODES,
+  EXECUTION_MODE_ALIASES,
+  GROK_FORBIDDEN_REVIEW_TYPES,
+  resolveExecutionModeId,
+  createCapabilityEvidence,
+  selectExecutionMode,
+  detectGrokRuntime,
+  createGrokCapabilityEvidence,
+  buildGrokReviewSpawnPlan,
+  formatExecutionReport
+} = require('../lib/orchestration.js');
+
+function fakeFs(existingPaths) {
+  return {
+    existsSync: (p) => existingPaths.includes(p)
+  };
+}
+
+test('Grok spawn_subagent with full execution proof selects TRUE_INDEPENDENT_AGENT', () => {
+  const nativeSubagent = createGrokCapabilityEvidence({
+    invocationAvailable: true,
+    childConversationId: 'grok-child-da-01',
+    childModelResponse: 'Finding ledger JSON emitted',
+    executionIdentity: 'spawn_subagent:grok-child-da-01',
+    independentContextProven: true,
+    historyInherited: false
+  });
+
+  const selected = selectExecutionMode({
+    nativeSubagent,
+    artifactIsolation: createCapabilityEvidence({
+      mechanism: 'clean-slate-artifact-barrier',
+      classification: 'CONTEXT_ISOLATION_ONLY',
+      available: true
+    })
+  });
+
+  assert.strictEqual(selected.id, EXECUTION_MODES.TRUE_INDEPENDENT_AGENT.id);
+  assert.strictEqual(selected.isIndependentExecutionProven, true);
+  assert.strictEqual(nativeSubagent.commandOrApi, 'spawn_subagent');
+});
+
+test('GROK_SUBAGENTS=0 disables invocation even when grok binary exists', () => {
+  const grokBin = '/tmp/fake-grok-home/bin/grok';
+  const runtime = detectGrokRuntime(
+    { GROK_HOME: '/tmp/fake-grok-home', GROK_SUBAGENTS: '0', HOME: '/tmp' },
+    fakeFs([grokBin])
+  );
+
+  assert.strictEqual(runtime.host, 'grok-cli');
+  assert.strictEqual(runtime.configurationSupported, true);
+  assert.strictEqual(runtime.invocationAvailable, false);
+  assert.strictEqual(runtime.executionProven, false);
+  assert.match(runtime.reason, /GROK_SUBAGENTS=0/);
+
+  const selected = selectExecutionMode({
+    nativeSubagent: createGrokCapabilityEvidence({
+      invocationAvailable: runtime.invocationAvailable,
+      reason: runtime.reason
+    }),
+    artifactIsolation: createCapabilityEvidence({
+      mechanism: 'clean-slate-artifact-barrier',
+      classification: 'CONTEXT_ISOLATION_ONLY',
+      available: true
+    })
+  });
+
+  assert.strictEqual(selected.id, EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id);
+});
+
+test('Grok binary present with default subagents maps to INVOCATION_AVAILABLE, not execution proven', () => {
+  const grokBin = '/tmp/fake-grok-home/bin/grok';
+  const runtime = detectGrokRuntime(
+    { GROK_HOME: '/tmp/fake-grok-home', HOME: '/tmp' },
+    fakeFs([grokBin])
+  );
+
+  assert.strictEqual(runtime.invocationAvailable, true);
+  assert.strictEqual(runtime.executionProven, false);
+
+  const evidence = createGrokCapabilityEvidence({
+    invocationAvailable: true
+  });
+
+  const selected = selectExecutionMode({
+    nativeSubagent: evidence,
+    artifactIsolation: createCapabilityEvidence({
+      mechanism: 'clean-slate-artifact-barrier',
+      classification: 'CONTEXT_ISOLATION_ONLY',
+      available: true
+    })
+  });
+
+  assert.strictEqual(evidence.classification, 'INVOCATION_AVAILABLE');
+  assert.strictEqual(selected.id, EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id);
+});
+
+test('resume_from Maker transcript cannot activate TRUE_INDEPENDENT_AGENT', () => {
+  const tainted = createGrokCapabilityEvidence({
+    invocationAvailable: true,
+    childConversationId: 'grok-child-resume',
+    childModelResponse: 'I remember the Maker rationale',
+    executionIdentity: 'spawn_subagent:resume',
+    independentContextProven: true,
+    resumeFrom: 'maker-subagent-id'
+  });
+
+  const selected = selectExecutionMode({
+    nativeSubagent: tainted,
+    artifactIsolation: createCapabilityEvidence({
+      mechanism: 'clean-slate-artifact-barrier',
+      classification: 'CONTEXT_ISOLATION_ONLY',
+      available: true
+    })
+  });
+
+  assert.strictEqual(tainted.historyInherited, true);
+  assert.strictEqual(selected.id, EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id);
+});
+
+test('caveman:cavecrew-reviewer cannot serve as Devil\'s Advocate', () => {
+  const compressed = createCapabilityEvidence({
+    mechanism: 'caveman:cavecrew-reviewer',
+    classification: 'GROK_COMPRESSED_REVIEW_PRESET',
+    available: true,
+    invocationAvailable: true,
+    executionProven: true,
+    childConversationId: 'cave-1',
+    executionIdentity: 'cave-1',
+    childModelResponse: 'path:line: 🔴 BLOCKER: bug. fix it.',
+    modelExecutionProven: true,
+    independentContextProven: true
+  });
+
+  const selected = selectExecutionMode({
+    nativeSubagent: compressed,
+    artifactIsolation: createCapabilityEvidence({
+      mechanism: 'clean-slate-artifact-barrier',
+      classification: 'CONTEXT_ISOLATION_ONLY',
+      available: true
+    })
+  });
+
+  assert.strictEqual(selected.id, EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id);
+  assert.ok(GROK_FORBIDDEN_REVIEW_TYPES.includes('caveman:cavecrew-reviewer'));
+});
+
+test('Skill aliases resolve to canonical execution mode ids', () => {
+  assert.strictEqual(resolveExecutionModeId('NATIVE_SUBAGENT'), 'TRUE_INDEPENDENT_AGENT');
+  assert.strictEqual(resolveExecutionModeId('SDK_AGENT'), 'ISOLATED_AGENT_INSTANCE');
+  assert.strictEqual(resolveExecutionModeId('HEADLESS_SUBPROCESS'), 'FRESH_PROCESS_AGENT');
+  assert.strictEqual(resolveExecutionModeId('ARTIFACT_ISOLATED_REVIEW'), 'CONTEXT_ISOLATION_ONLY');
+  assert.strictEqual(EXECUTION_MODE_ALIASES.NATIVE_SUBAGENT, EXECUTION_MODES.TRUE_INDEPENDENT_AGENT.id);
+});
+
+test('Grok DA/Judge spawn plan is fresh, execute-only, and forbids compressed review types', () => {
+  const da = buildGrokReviewSpawnPlan({
+    role: 'devil-advocate',
+    iteration: 2,
+    artifactPaths: { goalContract: 'goal.md', gitDiff: 'diff.patch' }
+  });
+
+  assert.strictEqual(da.tool, 'spawn_subagent');
+  assert.strictEqual(da.subagent_type, 'devil-advocate');
+  assert.strictEqual(da.fallback_subagent_type, 'general-purpose');
+  assert.strictEqual(da.description, '[devil-advocate] review iteration 2');
+  assert.strictEqual(da.background, false);
+  assert.strictEqual(da.capability_mode, 'execute');
+  assert.strictEqual(da.isolation, 'none');
+  assert.strictEqual(da.resume_from, null);
+  assert.ok(da.forbidden_types.includes('caveman:cavecrew-reviewer'));
+  assert.strictEqual(da.artifactPaths.goalContract, 'goal.md');
+
+  const judge = buildGrokReviewSpawnPlan({ role: 'judge', iteration: 2 });
+  assert.strictEqual(judge.subagent_type, 'judge');
+  assert.strictEqual(judge.description, '[judge] evaluate iteration 2');
+  assert.strictEqual(judge.resume_from, null);
+});
+
+test('buildGrokReviewSpawnPlan rejects unknown roles', () => {
+  assert.throws(
+    () => buildGrokReviewSpawnPlan({ role: 'caveman:cavecrew-reviewer' }),
+    /must be devil-advocate or judge/
+  );
+});
+
+test('Grok proven spawn report discloses independent execution', () => {
+  const report = formatExecutionReport({
+    selectedMode: EXECUTION_MODES.TRUE_INDEPENDENT_AGENT,
+    capabilityRegistry: {
+      nativeSubagent: { invocationAvailable: true }
+    }
+  });
+
+  assert.match(report, /Execution Mode: TRUE_INDEPENDENT_AGENT/);
+  assert.match(report, /Independent LLM Execution: PROVEN/);
+  assert.match(report, /Native Subagent Invocation: AVAILABLE/);
+});

package/tests/skill-host-compat.test.js

@@ -0,0 +1,68 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+function readRepo(rel) {
+  return fs.readFileSync(path.join(ROOT, rel), 'utf8');
+}
+
+function parseFrontmatter(content, label) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+  assert.ok(match, `${label} is missing YAML frontmatter`);
+  const fm = match[1];
+  assert.match(fm, /^name:\s*[a-z0-9-]+$/m, `${label} name must be kebab-case`);
+  assert.match(fm, /^description:\s+\S/m, `${label} description must be a single-line value`);
+  assert.doesNotMatch(fm, /^description:\s*>-?/m, `${label} must not use folded YAML description`);
+  const desc = fm.split('\n').find((line) => line.startsWith('description:'));
+  assert.ok(desc.length <= 500, `${label} description exceeds 500 chars (${desc.length})`);
+  return { fm, body: content.slice(match[0].length) };
+}
+
+test('Claude Code skill is Kiro-safe: no mermaid, latex, HTML breaks, or Grok tool keys', () => {
+  const content = readRepo('.claude/skills/ai-engineering-loop/SKILL.md');
+  parseFrontmatter(content, 'claude skill');
+
+  assert.doesNotMatch(content, /```mermaid/);
+  assert.doesNotMatch(content, /\$\\/);
+  assert.doesNotMatch(content, /<br\s*\/?>/i);
+  assert.doesNotMatch(content, /spawn_subagent/);
+  assert.doesNotMatch(content, /capability_mode/);
+  assert.doesNotMatch(content, /resume_from/);
+  assert.match(content, /\bTask\b/);
+  assert.match(content, /subagent_type/);
+  assert.match(content, /devil-advocate/);
+  assert.match(content, /\bjudge\b/);
+});
+
+test('Claude Code agents exist with Claude tool names and Finding Ledger / verdict contracts', () => {
+  const da = readRepo('.claude/agents/devil-advocate.md');
+  const judge = readRepo('.claude/agents/judge.md');
+  parseFrontmatter(da, 'devil-advocate agent');
+  parseFrontmatter(judge, 'judge agent');
+
+  assert.match(da, /^tools:\s*Read, Grep, Glob, Bash$/m);
+  assert.match(judge, /^tools:\s*Read, Grep, Glob, Bash$/m);
+  assert.doesNotMatch(da, /spawn_subagent|capability_mode|resume_from/);
+  assert.doesNotMatch(judge, /spawn_subagent|capability_mode|resume_from/);
+  assert.match(da, /Finding Ledger/);
+  assert.match(judge, /PASS/);
+  assert.match(judge, /ITERATE/);
+  assert.match(judge, /ESCALATE/);
+});
+
+test('Claude Code slash command does not embed Grok spawn keys', () => {
+  const cmd = readRepo('.claude/commands/ai-engineering-loop.md');
+  parseFrontmatter(cmd, 'claude command');
+  assert.doesNotMatch(cmd, /spawn_subagent|capability_mode|resume_from/);
+  assert.match(cmd, /ai-engineering-loop/);
+});
+
+test('Grok skill may use spawn_subagent; Claude skill must not', () => {
+  const grok = readRepo('.grok/skills/ai-engineering-loop/SKILL.md');
+  const claude = readRepo('.claude/skills/ai-engineering-loop/SKILL.md');
+  assert.match(grok, /spawn_subagent/);
+  assert.doesNotMatch(claude, /spawn_subagent/);
+});