ai-engineering-loop 1.0.4 → 1.0.6

package/README.md

@@ -1,17 +1,152 @@
 # AI Engineering Loop
 
+<div align="center">
+
 [![NPM Version](https://img.shields.io/npm/v/ai-engineering-loop.svg?color=cb3837)](https://www.npmjs.com/package/ai-engineering-loop)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
+[![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
+[![Release](https://img.shields.io/badge/release-v1.0.6-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
+
+**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
+
+*Featuring living project context, strict verification evidence contracts, 3-stage capability lifecycle registry, and dual-axis Judge evaluation.*
+
+[Overview](#overview--philosophy) • [Runtime Capability Registry](#runtime-capability-registry--execution-modes) • [Verification Evidence](#verification-evidence-contract) • [CLI Commands](#cli-interface--commands) • [Grok CLI](#grok-cli-integration) • [Claude Code](#claude-code-integration) • [Antigravity](#antigravity-agent-integration) • [Lifecycle](#lifecycle-stages) • [Architecture](#architecture--5-layer-configuration) • [Project Profiles](#project-profiles) • [Repository Structure](#repository-structure) • [Reference Examples](#reference-examples) • [Contributing](#contributing)
+
+</div>
+
+---
+
+## Overview & Philosophy
 
-**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents.**
+The AI Engineering Loop enforces clean architectural separation across three core layers:
 
-Features living project context, strict verification evidence contracts, 3-stage capability lifecycle registry, and dual-axis Judge evaluation.
+```mermaid
+flowchart TD
+    Start([User Task in Workspace]) --> PreCheck{Pre-Task Drift Check: metadata.json}
+    
+    PreCheck -->|Context Missing| AutoInit[Stage 0: Bootstrap .ai-engineering-loop/]
+    PreCheck -->|Drift Detected| Reconcile[Stage 0: Reconcile Drifted Context]
+    PreCheck -->|Context Fresh| GC[Stage 1: Goal Contract: Explicit Acceptance Criteria]
+    
+    AutoInit --> GC
+    Reconcile --> GC
+    
+    subgraph CoreEngine [AI ENGINEERING OPERATING SYSTEM]
+        GC --> RCA[Stage 2: Root Cause Analysis]
+        RCA --> Plan[Stage 3: Implementation Plan]
+        Plan --> MA[Stage 4: Maker Agent: Surgical Diff & Tests]
+        MA --> DV{Stage 5: Deterministic Verification<br>Evidence Contract: Exit Code 0 & Full Logs}
+        
+        DV -->|Fail| MA
+        DV -->|Pass| DA[Stage 6: Devil's Advocate Review<br>Capability Registry & Artifact Barrier]
+        
+        DA --> JD[Stage 7: Judge Agent: Impartial Magistrate<br>Validity + Severity Decision Matrix]
+    end
+    
+    JD -->|VALID BLOCKER / HIGH: ITERATE| MA
+    JD -->|INVALID: Dismissed / VALID LOW: Tradeoff| CheckDoD{All ACs Verified?}
+    
+    CheckDoD -->|Yes: PASS| ImpactEval{Post-Task Context Impact Assessment}
+    ImpactEval -->|NONE: Typo, UI tweak| Adapter[Stage 8: Delivery Adapter: GitLab / GitHub]
+    ImpactEval -->|TARGETED: Dep/route changed| PartialRefresh[Surgical Context Update] --> Adapter
+    ImpactEval -->|MAJOR: Framework migration| FullRefresh[Full Context Reconciliation] --> Adapter
+    
+    Adapter --> TargetRepo[(Target Repository)]
+```
 
 ---
 
-## ⚡ Quick Start
+## Runtime Capability Registry & Execution Modes
+
+The system maintains a strict distinction between **Configuration Support**, **Invocation Availability**, and **Execution Proof**:
+
+```text
+┌───────────────────────────┐     ┌───────────────────────────┐     ┌───────────────────────────┐
+│  CONFIGURATION_SUPPORTED  │ ──> │   INVOCATION_AVAILABLE    │ ──> │     EXECUTION_PROVEN      │
+│  (Config is recognized)   │     │ (Callable tool is active) │     │ (Child LLM response seen) │
+└───────────────────────────┘     └───────────────────────────┘     └───────────────────────────┘
+```
+
+### 5 Standard Execution Modes (Deterministic Priority):
+
+| Priority | Mode Name | Requires Independent LLM Execution? | Condition for Selection |
+|:---:|---|:---:|---|
+| **1** | **`TRUE_INDEPENDENT_AGENT`** | **YES** | Child session exists **AND** actual model response is captured **AND** context is independent. |
+| **2** | **`ISOLATED_AGENT_INSTANCE`** | **YES** | Programmatic SDK agent instance with verified independent model execution. |
+| **3** | **`FRESH_PROCESS_AGENT`** | **YES** | Separate OS process successfully executes an LLM agent with fresh context. |
+| **4** | **`CONTEXT_ISOLATION_ONLY`** | **NO** | Clean-Slate Artifact Isolation Barrier in same session (100% prompt history excluded on disk). |
+| **5** | **`UNAVAILABLE`** | **NO** | No review execution mechanism is available. |
+
+### Truthful Reporting Disclosure:
+When `CONTEXT_ISOLATION_ONLY` is selected, the report strictly produces:
+```text
+Execution Mode: CONTEXT_ISOLATION_ONLY
+Independent LLM Execution: NOT PROVEN
+Native Subagent Invocation: UNAVAILABLE
+Review Method: Clean-Slate Artifact Isolation Barrier
+```
+
+---
+
+## Verification Evidence Contract
+
+A verification `PASS` is strictly invalid without concrete execution evidence. The system categorically rejects vague statements such as *"command was launched"* or *"test appears to have passed"*.
+
+### Mandatory Execution Proof:
+- **`command`**: Exact CLI string executed.
+- **`executionIdentity`**: PID, execution hash, or system execution identifier.
+- **`startTime` & `endTime`**: Documented execution duration.
+- **`exitCode`**: Must be `0`.
+- **`stdout` & `stderr`**: Raw machine logs captured.
+- **`timeoutStatus`**: Must be `"COMPLETED"`.
+- **`testCounts`**: Explicit counts of passed, failed, and skipped tests.
+- **`assertionEvidence`**: Specific assertion proof matching the active Goal Contract's Acceptance Criteria.
+
+---
+
+## Dual-Axis Finding Model & Judge Decision Matrix
+
+The Devil's Advocate categorizes findings along separate **Validity**, **Severity**, and **Disposition** axes:
+
+```json
+{
+  "id": "DA-01",
+  "topic": "correctness",
+  "validity": "VALID",
+  "severity": "BLOCKER",
+  "disposition": "STRONG",
+  "location": "src/services/payment.ts#L42-L58",
+  "acceptanceCriteria": "AC-2",
+  "failureScenario": "Under concurrent traffic, duplicate rows are inserted before the lock is acquired.",
+  "evidence": "Missing SELECT FOR UPDATE in findByPaymentKey query.",
+  "concreteAlternativeDiff": "```diff\n- const tx = await findByKey(key);\n+ const tx = await findByKeyWithLock(key, { mode: 'FOR UPDATE' });\n```"
+}
+```
+
+### Judge Decision Matrix:
+- **`VALID + BLOCKER / HIGH`** $\rightarrow$ **`ITERATE`** (Maker must apply concrete fix diff and add regression tests).
+- **`VALID + MEDIUM / LOW`** $\rightarrow$ **`ACCEPT / TRADEOFF`** (Merged; documented as acceptable tradeoff in MR notes).
+- **`INVALID`** $\rightarrow$ **`DISMISS`** (Reviewer hallucination disproven by code; cannot block delivery; signature recorded).
+
+*Reviewer disposition (`STRONG`, `ACCEPTABLE`, `WEAK`) never overrides factual evidence.*
+
+---
 
-You can initialize and manage `.ai-engineering-loop/` context directly using `npx`:
+## Living Project Context
+
+The `.ai-engineering-loop/` directory is **Living Context**, not a static wiki generated once.
+
+1. **Post-Task Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
+2. **Context Baseline (`metadata.json`)**: Tracks `repositoryRevision` (git commit SHA) and `manifestChecksums` for instant Level 0 (0ms) drift verification.
+3. **Strict Context Isolation**: Decouples living project context from ephemeral task logs and loop execution states.
+
+---
+
+## CLI Interface & Commands
+
+The CLI package is published on NPM as [`ai-engineering-loop`](https://www.npmjs.com/package/ai-engineering-loop) and operates against the current working directory.
 
 ```bash
 # Bootstrap .ai-engineering-loop/ context from repository discovery
@@ -29,28 +164,153 @@ npx ai-engineering-loop run
 
 ---
 
-## 🚀 Key Architectural Features
+## Grok CLI Integration
+
+Grok CLI is a first-class host. `spawn_subagent` is a real independent child session (own context, no parent transcript unless `resume_from` is set). After a child id and model response are captured, the registry selects **`TRUE_INDEPENDENT_AGENT`**.
+
+| Loop role | Grok `subagent_type` | Spawn rules |
+|---|---|---|
+| Orchestrator / Maker | parent session | Parent stays the orchestrator (Grok nesting depth is 1) |
+| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `capability_mode: execute`, omit `resume_from` |
+| Judge | `judge` (fallback `general-purpose`) | Sibling of DA, never nested under DA |
+
+Do **not** use `caveman:cavecrew-reviewer` as Devil's Advocate or Judge — its output schema is not the Finding Ledger.
+
+Repo-local Grok files:
+
+- `.grok/agents/devil-advocate.md` / `.grok/agents/judge.md`
+- `.grok/skills/ai-engineering-loop/SKILL.md`
+- `.grok/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
+
+Fallback: `GROK_SUBAGENTS=0` or `--disallowed-tools Agent` → `CONTEXT_ISOLATION_ONLY`, disclosed as such. Optional process fallback: `grok -p` → `FRESH_PROCESS_AGENT` only after a model response is captured.
+
+See [docs/grok-cli-feasibility.md](docs/grok-cli-feasibility.md).
+
+---
+
+## Claude Code Integration
+
+Claude Code is a first-class host. Use the **Task** (or **Agent**) tool with **only** `subagent_type`, `description`, and `prompt`.
+
+Do **not** pass Grok keys (`spawn_subagent`, `capability_mode`, `isolation`, `resume_from`). Extra keys are the usual cause of:
+
+```
+API Error: 400 [kiro/claude-sonnet-5] REQUEST_BODY_INVALID
+```
+
+| Loop role | Claude Code `subagent_type` | Task keys |
+|---|---|---|
+| Orchestrator / Maker | parent session | n/a |
+| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+| Judge | `judge` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+
+Repo-local Claude Code files:
 
-1. **Living Project Context**: Tracks baseline git SHA and manifest checksums in `metadata.json` for 0ms drift verification and post-task impact assessment (`NONE`, `TARGETED`, `MAJOR`).
-2. **Deterministic Verification Evidence Contract**: Rejects vague assertions ("command was launched"); strictly requires CLI exit code 0, machine logs, and assertion proofs.
-3. **Runtime Capability Registry (3-Stage Lifecycle)**:
-   $$\text{CONFIGURATION\_SUPPORTED} \longrightarrow \text{INVOCATION\_AVAILABLE} \longrightarrow \text{EXECUTION\_PROVEN}$$
-   Prevents misleading claims of multi-agent execution by requiring proven child session model execution.
-4. **Dual-Axis Finding Model & Judge Matrix**:
-   - `VALID + BLOCKER/HIGH` → `ITERATE`
-   - `VALID + MEDIUM/LOW` → `ACCEPT / TRADEOFF`
-   - `INVALID` → `DISMISS`
+- `.claude/agents/devil-advocate.md` / `.claude/agents/judge.md`
+- `.claude/skills/ai-engineering-loop/SKILL.md`
+- `.claude/commands/ai-engineering-loop.md` → `/ai-engineering-loop`
+
+See [docs/claude-code-feasibility.md](docs/claude-code-feasibility.md).
 
 ---
 
-## 📖 Full Documentation & Specifications
+## Antigravity Agent Integration
+
+When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
 
-For complete specifications, agent role definitions, project profiles, and reference walkthroughs, visit the GitHub repository:
+- **`/ai-engineering-loop init`**: Initialize project context only (non-destructive bootstrap).
+- **`/ai-engineering-loop status`**: Check repository context health & baseline freshness.
+- **`/ai-engineering-loop refresh`**: Reconcile drifted context files non-destructively.
+- **`/ai-engineering-loop [task description]`**: Execute the full 8-stage engineering lifecycle with pre-task drift gate and post-task impact assessment.
 
-👉 **[https://github.com/egagofur/ai-engineering-loop](https://github.com/egagofur/ai-engineering-loop)**
+On Grok CLI the same slash command is provided by `.grok/commands/ai-engineering-loop.md` and runs Devil's Advocate / Judge as native subagents.
+
+---
+
+## Repository Structure
+
+```text
+ai-engineering-loop/
+│
+├── README.md                           # Operating system overview & architecture
+├── LICENSE                             # MIT Open Source License
+├── package.json                        # CLI package manifest
+│
+├── bin/                                # CLI execution entrypoints
+│   └── ai-engineering-loop.js          # npx executable CLI (init, status, refresh, run)
+│
+├── lib/                                # Core orchestration & decision engine
+│   └── orchestration.js                # 3-stage capability registry, barrier builder, Judge engine
+│
+├── tests/                              # Deterministic test suites
+│   ├── capability-selection.test.js    # Unit tests for capability lifecycle & truthful selection
+│   ├── orchestration.test.js           # Tests for isolation, Finding schema, Judge matrix
+│   └── grok-runtime.test.js            # Grok spawn_subagent mapping, aliases, forbidden types
+│
+├── .grok/                              # Grok CLI host adapter
+│   ├── agents/devil-advocate.md        # Native DA subagent type
+│   ├── agents/judge.md                 # Native Judge subagent type
+│   ├── skills/ai-engineering-loop/     # Grok skill (spawn protocol)
+│   └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
+│
+├── .claude/                            # Claude Code host adapter (Kiro-safe)
+│   ├── agents/devil-advocate.md        # Task subagent type
+│   ├── agents/judge.md                 # Task subagent type
+│   ├── skills/ai-engineering-loop/     # Claude skill (Task keys only)
+│   └── commands/ai-engineering-loop.md # /ai-engineering-loop slash command
+│
+├── core/                               # Generic engineering loop specifications
+│   ├── orchestration-model.md          # 3-stage capability lifecycle & execution priority
+│   ├── project-initialization.md       # Auto-discovery & initialization lifecycle
+│   ├── context-refresh-policy.md       # Progressive drift hierarchy & living baseline
+│   ├── context-impact-assessment.md    # Post-task impact assessment (NONE, TARGETED, MAJOR)
+│   ├── goal-contract.md                # Task contract schema & acceptance criteria
+│   ├── verification-loop.md            # Dual-layer verification & Evidence Contract
+│   ├── definition-of-done.md           # 5 pillars of Done & rejection triggers
+│   ├── iteration-policy.md             # Bounded autonomous loop (MAX_ITERATIONS = 3)
+│   ├── escalation-policy.md            # Deterministic human escalation triggers
+│   ├── judge-policy.md                 # Evaluation rules, triage audit, & verdicts
+│   ├── configuration-precedence.md     # 5-layer precedence & conflict resolution
+│   └── repo-config-schema.md           # Schema for target repo .ai-engineering-loop/
+│
+├── profiles/                           # Project archetype profiles
+│   ├── README.md                       # Profile catalog & auto-detection rules
+│   ├── web-app.md                      # Frontend web applications
+│   ├── backend-api.md                  # Backend APIs & microservices
+│   ├── mobile-app.md                   # Native & cross-platform mobile apps
+│   ├── library.md                      # Reusable SDKs & shared packages
+│   └── monorepo.md                     # Multi-package monorepo workspaces
+│
+├── agents/                             # Triad agent role specifications
+│   ├── maker.md                        # Maker agent: surgical diffs & unit tests
+│   ├── devil-advocate.md               # Adversarial reviewer: dual-axis finding ledger & diffs
+│   └── judge.md                        # Judge agent: impartial magistrate on Validity + Severity
+│
+├── policies/                           # Operational schemas & algorithms
+│   ├── discovery-safety-policy.md      # Secret protection & non-destructive discovery rules
+│   ├── finding-policy.md               # Dual-axis finding schema & severity matrix
+│   ├── evidence-policy.md              # 5-level evidence hierarchy & Verification Evidence Contract
+│   └── no-progress-policy.md           # Finding signature hashing & stagnation detection
+│
+├── adapters/                           # Pluggable delivery pipelines
+│   └── dot/                            # DOT Indonesia delivery adapter
+│       ├── README.md                   # DOT adapter overview
+│       ├── gitlab.md                   # glab CLI, issue cards, & MR generation
+│       ├── multi-branch.md             # main / staging / develop cherry-pick propagation
+│       ├── coreview.md                 # @coreview-bot external review triage (Valid vs Halu)
+│       └── mattermost.md               # Channel mapping & MCP dispatch (from: "AI Agent")
+│
+└── templates/                          # Starter templates for target repositories
+    └── repo-config/                    # Ready-to-copy .ai-engineering-loop/ files
+        ├── config.md                   # Project identity & profile binding
+        ├── architecture.md             # Layers & boundary invariants
+        ├── conventions.md              # Code standards & forbidden patterns
+        ├── verification.md             # CLI test/lint/build commands
+        └── adapter.md                  # Configured release pipeline
+```
 
 ---
 
-## 📄 License
+## License
 
-MIT © [Ega Gofur](https://github.com/egagofur)
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

package/README.npm.md

@@ -36,6 +36,17 @@ npx ai-engineering-loop run
 2. **Living Project Context**: Tracks repository revisions and manifest checksums in `metadata.json` for instant drift detection.
 3. **Multi-Agent Triad**: Coordinates **Maker** (surgical diffs & tests), **Devil's Advocate** (independent adversarial review), and **Judge** (impartial evaluation & PASS certification).
 4. **Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
+5. **Grok CLI host**: Native `spawn_subagent` for Devil's Advocate and Judge (`TRUE_INDEPENDENT_AGENT`). Disabled by `GROK_SUBAGENTS=0`.
+
+---
+
+## Grok CLI
+
+Inside a Grok TUI session, `/ai-engineering-loop` uses repo-local `.grok/agents/` types. Devil's Advocate and Judge spawn as sibling children (`capability_mode: execute`, no `resume_from`). Do not use `caveman:cavecrew-reviewer` as the loop reviewer.
+
+## Claude Code
+
+Inside Claude Code, `/ai-engineering-loop` uses `.claude/agents/` types via the **Task** tool. Pass only `subagent_type`, `description`, and `prompt`. Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`) — extra keys cause Kiro `REQUEST_BODY_INVALID`.
 
 ---
 

package/agents/devil-advocate.md

@@ -12,12 +12,16 @@ The **Devil's Advocate** is an independent adversarial reviewer. Its sole purpos
 
 ## 2. Review Execution Modes
 
-The Devil's Advocate executes under one of 4 runtime modes depending on platform capabilities:
+The Devil's Advocate executes under one of 4 runtime modes depending on platform capabilities.
 
-1. **`NATIVE_SUBAGENT`**: Genuine independent sub-agent session spawned by host runtime.
-2. **`SDK_AGENT`**: Programmatic Python SDK agent instance with isolated memory.
-3. **`HEADLESS_SUBPROCESS`**: Fresh subprocess agent spawned via CLI.
-4. **`ARTIFACT_ISOLATED_REVIEW`**: Clean-Slate Artifact Barrier in single-agent session (*strictly labeled: isolated review context, not independent agent execution*).
+Canonical ids are listed first; skill aliases are in parentheses.
+
+1. **`TRUE_INDEPENDENT_AGENT`** (`NATIVE_SUBAGENT`): Genuine independent child session.
+   - **Grok CLI**: `spawn_subagent` with `subagent_type: "devil-advocate"` (fallback `"general-purpose"`), `capability_mode: "execute"`, `isolation: "none"`, **omit** `resume_from`. Agent definition: `.grok/agents/devil-advocate.md`.
+   - Do **not** use `caveman:cavecrew-reviewer` (compressed review schema, not a Finding Ledger).
+2. **`ISOLATED_AGENT_INSTANCE`** (`SDK_AGENT`): Programmatic SDK agent instance with isolated memory.
+3. **`FRESH_PROCESS_AGENT`** (`HEADLESS_SUBPROCESS`): Fresh OS process such as `grok -p` after a model response is captured.
+4. **`CONTEXT_ISOLATION_ONLY`** (`ARTIFACT_ISOLATED_REVIEW`): Clean-Slate Artifact Barrier in single-agent session (*strictly labeled: isolated review context, not independent agent execution*).
 
 ---
 

package/agents/judge.md

@@ -4,6 +4,8 @@
 
 The **Judge Agent** is the final decision-maker of the AI Engineering Loop. It serves as an impartial magistrate that evaluates the complete evidence pipeline (Contract, Diff, Deterministic Verification Logs, and Devil's Advocate findings) to determine whether the iteration should **PASS**, **ITERATE**, or **ESCALATE**.
 
+On **Grok CLI**, the parent orchestrator spawns the Judge with `spawn_subagent` (`subagent_type: "judge"`, fallback `"general-purpose"`), `capability_mode: "execute"`, and **no** `resume_from`. Agent definition: `.grok/agents/judge.md`. The Judge is a sibling of the Devil's Advocate, never its child (Grok nesting depth is 1).
+
 ```mermaid
 flowchart LR
     Inputs[Goal Contract + Diff + Test Logs + Review Findings] --> Judge[Judge Agent]

package/bin/ai-engineering-loop.js

@@ -15,7 +15,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 
-const VERSION = '1.0.2';
+const VERSION = '1.0.6';
 const CWD = process.cwd();
 const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
 
@@ -553,6 +553,15 @@ function handleRefresh() {
   handleStatus();
 }
 
+function detectGrokHost() {
+  try {
+    const { detectGrokRuntime } = require('../lib/orchestration.js');
+    return detectGrokRuntime(process.env, fs);
+  } catch (e) {
+    return null;
+  }
+}
+
 // Command: run
 function handleRun() {
   log.info('AI Engineering Loop — Task Execution Entrypoint (run)');
@@ -564,6 +573,8 @@ function handleRun() {
     handleStatus();
   }
 
+  const grok = detectGrokHost();
+
   console.log('\n------------------------------------------------------------');
   log.bold('AI Agent Ready:');
   console.log('1. Formulate Goal Contract (core/goal-contract.md)');
@@ -574,6 +585,34 @@ function handleRun() {
   console.log('6. Judge Agent evaluates DoD and issues PASS verdict');
   console.log('7. Context Impact Assessment (NONE / TARGETED / MAJOR)');
   console.log('8. Delivery Adapter creates MR/PR');
+
+  if (grok && grok.host === 'grok-cli') {
+    console.log('------------------------------------------------------------');
+    log.bold('Grok CLI host:');
+    console.log(`- Binary: ${grok.grokBin || 'detected'}`);
+    console.log(`- spawn_subagent: ${grok.invocationAvailable ? 'INVOCATION_AVAILABLE' : 'UNAVAILABLE'}`);
+    console.log(`- Execution proven: no (requires child subagent_id + model response)`);
+    if (grok.invocationAvailable) {
+      console.log('- Devil\'s Advocate: spawn_subagent type=devil-advocate capability_mode=execute (no resume_from)');
+      console.log('- Judge: spawn_subagent type=judge capability_mode=execute (sibling, not nested)');
+      console.log('- Forbidden types: caveman:cavecrew-reviewer, explore, plan');
+    } else {
+      console.log(`- Fallback: CONTEXT_ISOLATION_ONLY (${grok.reason})`);
+    }
+    console.log('- Skill: .grok/skills/ai-engineering-loop/SKILL.md');
+  }
+
+  const claudeSkill = path.join(CWD, '.claude', 'skills', 'ai-engineering-loop', 'SKILL.md');
+  const claudeAgent = path.join(CWD, '.claude', 'agents', 'devil-advocate.md');
+  if (fs.existsSync(claudeSkill) || fs.existsSync(claudeAgent)) {
+    console.log('------------------------------------------------------------');
+    log.bold('Claude Code host:');
+    console.log('- Subagent tool: Task (or Agent). Keys allowed: subagent_type, description, prompt');
+    console.log('- Devil\'s Advocate: Task subagent_type=devil-advocate');
+    console.log('- Judge: Task subagent_type=judge (sibling, not nested)');
+    console.log('- Do not pass spawn_subagent, capability_mode, isolation, resume_from (Kiro 400 REQUEST_BODY_INVALID)');
+    console.log('- Skill: .claude/skills/ai-engineering-loop/SKILL.md');
+  }
   console.log('------------------------------------------------------------\n');
 }
 

package/core/orchestration-model.md

@@ -69,6 +69,26 @@ The system categorically rejects the following as proof of independent LLM execu
 
 ---
 
+## 4b. Grok CLI Empirical Discovery Record
+
+| Investigated Surface | Tested Command / API | Classification | Status & Result |
+|---|---|---|---|
+| **Grok CLI binary** | `~/.grok/bin/grok` | `CONFIGURATION_SUPPORTED` | Installed (`grok 1.0.5+`). Not execution proof. |
+| **Native subagent tool** | `spawn_subagent` | `INVOCATION_AVAILABLE` | Enabled by default. Disabled by `GROK_SUBAGENTS=0` or `--disallowed-tools Agent`. |
+| **Child session** | `subagent_id` + child model response, `resume_from` omitted | `EXECUTION_PROVEN` → `TRUE_INDEPENDENT_AGENT` | Own context window; parent transcript is not inherited. |
+| **Project agent types** | `.grok/agents/devil-advocate.md`, `.grok/agents/judge.md` | `CONFIGURATION_SUPPORTED` | Prefer these types; fall back to `general-purpose` with the spec prepended. |
+| **Headless process** | `grok -p` | `FRESH_PROCESS_AGENT` | Only after the process prints a model response. |
+| **Cavecrew reviewer** | `caveman:cavecrew-reviewer` | `GROK_COMPRESSED_REVIEW_PRESET` | **Rejected** as Devil's Advocate / Judge (wrong output schema). |
+| **Maker resume** | `spawn_subagent(resume_from=maker)` | tainted history | **Rejected**. DA and Judge must spawn fresh. |
+| **Artifact barrier** | `buildReviewContextBarrier()` | `CONTEXT_ISOLATION_ONLY` | Fallback when spawn is disabled. |
+
+### Architectural Conclusion:
+> *"Grok CLI spawn_subagent is a true independent child session. Select TRUE_INDEPENDENT_AGENT only after a child id and model response are captured without resume_from. Binary presence and agent markdown are never sufficient."*
+
+See [docs/grok-cli-feasibility.md](../docs/grok-cli-feasibility.md).
+
+---
+
 ## 5. Truthful Reporting Output
 
 When `CONTEXT_ISOLATION_ONLY` is selected, the report generator strictly produces:

package/docs/claude-code-feasibility.md

@@ -0,0 +1,45 @@
+# Claude Code Feasibility and Kiro Request Safety
+
+## 1. Problem
+
+Claude Code users (including Kiro-backed models such as `kiro/claude-sonnet-5`) hit:
+
+```
+API Error: 400 [kiro/claude-sonnet-5] [400]:
+{"message":"Improperly formed request.","reason":"REQUEST_BODY_INVALID"}
+```
+
+Kiro's `generateAssistantResponse` rejects request bodies that Claude Code will happily send. Two skill-side causes were confirmed:
+
+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`.
+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.
+
+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.
+
+## 2. Claude Code mapping
+
+| Loop role | Claude Code type | Task keys allowed |
+|---|---|---|
+| Orchestrator / Maker | parent session | n/a |
+| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+| Judge | `judge` (fallback `general-purpose`) | `subagent_type`, `description`, `prompt` |
+
+Do not pass Grok keys (`spawn_subagent`, `capability_mode`, `resume_from`, `isolation`, `background`) on Claude Code.
+
+Repo files:
+
+- `.claude/skills/ai-engineering-loop/SKILL.md`
+- `.claude/agents/devil-advocate.md`
+- `.claude/agents/judge.md`
+- `.claude/commands/ai-engineering-loop.md`
+
+## 3. Mode selection
+
+| Condition | Mode |
+|---|---|
+| Task/Agent tool present, child result returned | `TRUE_INDEPENDENT_AGENT` |
+| No subagent tool | `CONTEXT_ISOLATION_ONLY` |
+
+## 4. What stays in Grok-only files
+
+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.

package/docs/grok-cli-feasibility.md

@@ -0,0 +1,99 @@
+# Grok CLI Feasibility & Execution Strategy
+
+## 1. Executive Summary
+
+Grok CLI (verified `grok 1.0.5`) is a **first-class host** for the AI Engineering Loop. Unlike Antigravity standalone mode, Grok exposes `spawn_subagent` as a real independent child session: own context window, no parent transcript unless `resume_from` is set, and a captured `subagent_id` plus model response.
+
+When those evidence fields are present, the capability registry **must** select `TRUE_INDEPENDENT_AGENT` (skill alias: `NATIVE_SUBAGENT`).
+
+```text
+Parent (Maker + orchestrator)
+  ├─ spawn_subagent type=devil-advocate  → Finding Ledger
+  └─ spawn_subagent type=judge           → PASS | ITERATE | ESCALATE
+```
+
+Children cannot spawn children (depth 1). The parent therefore remains the orchestrator.
+
+---
+
+## 2. Empirical Discovery Record
+
+| Surface | Tested command / API | Classification | Result |
+|---|---|---|---|
+| Grok CLI binary | `~/.grok/bin/grok` (`grok 1.0.5`) | `CONFIGURATION_SUPPORTED` | Installed and authenticated in TUI sessions |
+| Native child session | `spawn_subagent` | `INVOCATION_AVAILABLE` | Enabled by default; disabled only when `GROK_SUBAGENTS=0` or `--disallowed-tools Agent` |
+| Child execution | child `subagent_id` + model response | `EXECUTION_PROVEN` | Proven only after the child returns; binary presence is not proof |
+| Project agents | `.grok/agents/devil-advocate.md`, `.grok/agents/judge.md` | `CONFIGURATION_SUPPORTED` | Registered as `subagent_type` values |
+| Skill + slash command | `.grok/skills/ai-engineering-loop/`, `.grok/commands/ai-engineering-loop.md` | `CONFIGURATION_SUPPORTED` | Grok discovers repo-local skills and command markdown |
+| Headless child | `grok -p "..."` | `FRESH_PROCESS_AGENT` | Valid fallback **after** stdout contains a model response |
+| Compressed reviewer | `caveman:cavecrew-reviewer` | `GROK_COMPRESSED_REVIEW_PRESET` | **Rejected** — output schema is `path:line: emoji severity`, not the Finding Ledger |
+| Browser tools | `browser_*` | `BROWSER_AUTOMATION_TOOL` | Not an LLM reviewer |
+| `resume_from` Maker | `spawn_subagent(resume_from=makerId)` | tainted history | **Rejected** — inherits Maker transcript |
+
+### What is NOT execution proof on Grok
+
+1. `~/.grok/bin/grok` existing on disk
+2. `.grok/agents/*.md` being discoverable
+3. Subagents being enabled in `config.toml`
+4. A persona named "reviewer" without a child response
+5. Cavecrew reviewer output that looks like a review
+
+---
+
+## 3. Mapping Loop Roles → Grok Types
+
+| Loop role | Grok `subagent_type` | `capability_mode` | `isolation` | `resume_from` |
+|---|---|---|---|---|
+| Orchestrator / Maker | parent session (or `general-purpose` if parent is orchestrator-only) | `all` | `none` | n/a |
+| Devil's Advocate | `devil-advocate` (fallback `general-purpose`) | `execute` | `none` | **omit** |
+| Judge | `judge` (fallback `general-purpose`) | `execute` | `none` | **omit** |
+
+`execute` allows git/read/search and forbids source edits. Do not use `read-only` if the child needs `git diff`. Do not use `worktree` isolation: DA and Judge must see the Maker working tree.
+
+`description` prefixes `[devil-advocate]` and `[judge]` so the Grok TUI labels the child correctly when falling back to `general-purpose`.
+
+---
+
+## 4. Artifact Barrier (still required)
+
+Grok children do not inherit parent chat, but they do receive compacted `AGENTS.md` / project instructions. That is acceptable (project context, not Maker thoughts).
+
+Still write artifacts to disk and pass **paths**, not Maker narration:
+
+- Goal Contract
+- git diff file
+- verification log (command, exit code, stdout, test counts)
+- `.ai-engineering-loop/`
+
+---
+
+## 5. Disable / fallback matrix
+
+| Condition | Selected mode |
+|---|---|
+| `spawn_subagent` available, child response captured, no `resume_from` | `TRUE_INDEPENDENT_AGENT` |
+| `spawn_subagent` missing, `grok -p` returns a model response | `FRESH_PROCESS_AGENT` |
+| `GROK_SUBAGENTS=0` or `--disallowed-tools Agent` | `CONTEXT_ISOLATION_ONLY` |
+| No grok, no spawn, no headless | `UNAVAILABLE` or artifact barrier if the same session can still read the diff |
+
+---
+
+## 6. Answers to the eight host questions
+
+1. **Independent sub-agents?** Yes — `spawn_subagent`, own context window.
+2. **Pass context?** Yes — prompt + on-disk artifacts. Do not pass Maker chat.
+3. **Same repository?** Yes — `isolation: none` shares the workspace.
+4. **Structured findings?** Yes — DA agent contract is Finding Ledger JSON.
+5. **Parent consume findings?** Yes — child summary returns to parent; Judge spawn gets the ledger.
+6. **Repeat the loop?** Yes — parent iterates; each DA/Judge spawn is fresh (no `resume_from`).
+7. **Persist state?** Yes — files under `.ai-engineering-loop/` and task artifact paths. Grok also keeps session logs under `~/.grok/sessions/`.
+8. **Token limits?** Pass artifact paths, not full transcripts. Do not dump Maker reasoning into the DA prompt.
+
+---
+
+## 7. Practical limits on Grok CLI
+
+- **Depth 1**: a DA child cannot spawn a Judge. Parent must spawn both.
+- **Plan mode**: a write-capable child is not gated by the parent's plan-mode lock. Keep DA/Judge on `capability_mode: execute` (no writes) so they cannot edit source while the parent is in plan mode.
+- **Headless `--disallowed-tools Agent`**: kills native review. Disclose `CONTEXT_ISOLATION_ONLY`.
+- **Cavecrew**: useful for cheap locate/review, **not** for this loop's Judge input.