ai-engineering-loop 1.0.1 → 1.0.3

package/README.full.md

@@ -0,0 +1,251 @@
+# 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.3-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) • [Agent Integration](#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
+
+The AI Engineering Loop enforces clean architectural separation across three core layers:
+
+```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)]
+```
+
+---
+
+## 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.*
+
+---
+
+## 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
+npx ai-engineering-loop init
+
+# Check the validity, readiness, and baseline freshness of context
+npx ai-engineering-loop status
+
+# Reconcile drifted context against repository non-destructively
+npx ai-engineering-loop refresh
+
+# Verify context readiness and begin engineering loop
+npx ai-engineering-loop run
+```
+
+---
+
+## Antigravity Agent Integration
+
+When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
+
+- **`/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.
+
+---
+
+## 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
+│
+├── 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
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

package/README.md

@@ -2,62 +2,55 @@
 
 [![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)
-[![GitHub](https://img.shields.io/badge/GitHub-Repository-black.svg)](https://github.com/egagofur/ai-engineering-loop)
 
-**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
+**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents.**
 
-Move beyond linear AI pipelines and optimistic self-evaluation toward contract-driven execution, deterministic machine verification, independent adversarial review, and living project context.
+Features living project context, strict verification evidence contracts, 3-stage capability lifecycle registry, and dual-axis Judge evaluation.
 
 ---
 
-## Quickstart CLI
+## ⚡ Quick Start
 
-Run the CLI in any repository root without global installation:
+You can initialize and manage `.ai-engineering-loop/` context directly using `npx`:
 
 ```bash
-# 1. Bootstrap .ai-engineering-loop/ context from repository discovery
+# Bootstrap .ai-engineering-loop/ context from repository discovery
 npx ai-engineering-loop init
 
-# 2. Check the validity, readiness, and baseline freshness of context
+# Check the validity, readiness, and baseline freshness of context
 npx ai-engineering-loop status
 
-# 3. Reconcile drifted context against repository non-destructively
+# Reconcile drifted context against repository non-destructively
 npx ai-engineering-loop refresh
 
-# 4. Verify context readiness and begin engineering loop
+# Verify context readiness and begin engineering loop
 npx ai-engineering-loop run
 ```
 
 ---
 
-## What It Does
+## 🚀 Key Architectural Features
 
-1. **Zero-Config Discovery (`init`)**: Analyzes repository topology (monorepo vs single app), package manifests (`package.json`, `go.mod`, `Cargo.toml`, etc.), frameworks, and test scripts to generate `.ai-engineering-loop/`.
-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.
+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`
 
 ---
 
-## Antigravity IDE Integration
+## 📖 Full Documentation & Specifications
 
-In Antigravity IDE or compatible agentic platforms, invoke the loop directly in chat:
+For complete specifications, agent role definitions, project profiles, and reference walkthroughs, visit the GitHub repository:
 
-- `/ai-engineering-loop init` — Bootstrap project context only.
-- `/ai-engineering-loop status` — Check context health and living freshness.
-- `/ai-engineering-loop refresh` — Reconcile drifted context files.
-- `/ai-engineering-loop <task>` — Execute the full 8-stage engineering lifecycle.
+👉 **[https://github.com/egagofur/ai-engineering-loop](https://github.com/egagofur/ai-engineering-loop)**
 
 ---
 
-## Complete Documentation & Specifications
+## 📄 License
 
-For the complete architectural specifications, project profiles (`web-app`, `backend-api`, `mobile-app`, `library`, `monorepo`), delivery adapters (GitLab, GitHub, Mattermost), and reference examples:
-
-👉 **[Visit the GitHub Repository](https://github.com/egagofur/ai-engineering-loop)**
-
----
-
-## License
-
-MIT License — see [LICENSE](https://github.com/egagofur/ai-engineering-loop/blob/main/LICENSE) for details.
+MIT © [Ega Gofur](https://github.com/egagofur)

package/agents/devil-advocate.md

@@ -1,111 +1,73 @@
 # Devil's Advocate Agent Specification
 
-## 1. Role & Identity
-
-The **Devil's Advocate Agent** is the independent adversarial reviewer of the AI Engineering Loop. Its mission is to rigorously challenge the implementation, expose unhandled edge cases, question unstated assumptions, and detect architectural, security, and correctness vulnerabilities.
-
-```mermaid
-flowchart TD
-    Diff[Git Diff Against Base] --> DA[Devil's Advocate Agent]
-    GC[Goal Contract] --> DA
-    
-    subgraph LayeredRules [Layered Review Rule Resolution]
-        G[1. Generic Engineering Invariants]
-        P[2. Project Profile Rules e.g. backend-api / web-app]
-        C[3. Repository-Local Invariants .ai-engineering-loop/]
-        T[4. Task-Specific Focus Areas]
-        G --> P --> C --> T
-    end
-    
-    LayeredRules --> DA
-    DA --> FilteredReview[Targeted, Relevant Review Evaluation]
-    FilteredReview --> Findings[Standardized Finding Ledger]
-```
-
----
+## 1. Role Definition & Mandate
 
-## 2. Core Operational Constraints
+The **Devil's Advocate** is an independent adversarial reviewer. Its sole purpose is to find real, substantive flaws in the Maker's code diff before production merge:
 
-1. **Independent Evaluation**:
-   - The Devil's Advocate reviews code from an adversarial perspective. When supported by the host runtime, it should execute as an independent sub-agent or in a segregated context.
-2. **Read-Only / No Direct Code Modification**:
-   - The Devil's Advocate **MUST NOT** directly edit codebase files or apply fixes. Its output is exclusively an evidence-backed **Finding Ledger**.
-3. **Evidence-Backed Criticism Only**:
-   - Every critique must be substantiated with concrete repository facts, line references, or reproducible scenarios.
-4. **Concrete Diffs Required**:
-   - For every substantive problem identified, the Devil's Advocate must provide a concrete code snippet or diff illustrating the recommended fix. Abstract complaints without constructive alternatives are rejected.
+- **Primary Goal**: Detect correctness bugs, unhandled race conditions, missing error paths, auth/security flaws, and test gaps.
+- **Strict Invariant**: The Devil's Advocate is strictly **read-only**. It **NEVER modifies application source code** or git branches.
+- **Concrete Diffs Required**: Every substantive finding must provide a concrete code diff showing the fix, not just an abstract complaint.
 
 ---
 
-## 3. Layered Review Rule Resolution
-
-To prevent noisy or irrelevant reviews, the Devil's Advocate dynamically resolves its active review categories using four layers:
-
-$$\text{Generic Rules} + \text{Project Profile Rules} + \text{Repository Invariants} + \text{Task Concerns}$$
-
-### Layer 1: Generic Review Rules (Always Active)
-1. **Correctness & Logic Integrity**: Bugs, calculation errors, off-by-one errors, broken lifecycle logic.
-2. **Error Handling & Failure Modes**: Swallowed exceptions, unhandled Promise rejections, missing fallbacks.
-3. **Regression Risk**: Breaking existing functionality or altering un-targeted behaviors.
-4. **Maintainability & Architecture**: Violating existing layer boundaries, introducing dead code.
-5. **Testing Gaps**: Untested boundary conditions, weak/tautological assertions.
+## 2. Review Execution Modes
 
-### Layer 2: Project Profile Review Rules (Dynamically Activated)
-- **`web-app` Profile**: UI responsiveness (320px–4k), accessibility (a11y/ARIA), client state lifecycle, Core Web Vitals, XSS/CSRF.
-- **`backend-api` Profile**: IDOR & authorization scopes, database transactions & ACID rollbacks, concurrency locks (`SELECT FOR UPDATE`), N+1 query loops, API contract backwards compatibility.
-- **`mobile-app` Profile**: Offline mutation queuing, OS lifecycle termination & state loss, permission denials, battery/GPS hygiene, secure hardware storage.
-- **`library` Profile**: Semantic versioning & public API breaking changes, dependency bloat, cross-runtime compatibility (Node vs Browser), tree-shaking exports.
-- **`monorepo` Profile**: Cross-package boundary leaps, workspace dependency isolation, circular package dependencies.
+The Devil's Advocate executes under one of 4 runtime modes depending on platform capabilities:
 
-### Layer 3: Repository-Specific Invariants (`.ai-engineering-loop/conventions.md`)
-- Custom team rules (e.g. "All money fields must use BigInt cents", "Use dayjs UTC plugins").
-
-### Layer 4: Task-Specific Focus Areas
-- Specific risk areas declared in the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
+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*).
 
 ---
 
-## 4. Anti-Slop & Anti-Nitpicking Filter
+## 3. Input Barrier (What Reviewer Sees)
 
-To maintain high engineering velocity, the Devil's Advocate is **strictly prohibited** from raising manufactured, trivial, or aesthetic nitpicks:
+The Devil's Advocate receives **only** the objective artifact package:
+- `Goal Contract` (AC-1..N, constraints, out of scope).
+- `Project Context` (`.ai-engineering-loop/`: `architecture.md`, `conventions.md`, `verification.md`).
+- `Pure Git Diff` (`git diff <base>...HEAD`).
+- `Deterministic Verification Logs` (exit code 0 proof).
+- `Prior Finding Signatures`.
 
-❌ **Prohibited Nitpicks**:
-- *"Rename this local variable because I prefer shorter names."*
-- *"We could rewrite this with a complex functional programming pattern."*
-- *"Consider adding a generic factory pattern for future use."*
-- *Checking mobile responsive layout on a backend API PR.*
+*Maker conversational history, intermediate attempts, and author rationalizations are strictly excluded.*
 
-✅ **Mandatory Substantive Findings**:
-- *"Line 42 accesses `user.profile.id` without checking if `profile` is null, causing runtime crash when legacy accounts log in."*
-- *"The query in `get-attendance.ts` loads all 50,000 rows into memory without pagination."*
+---
 
-> [!NOTE]
-> A review that finds **zero issues** is completely acceptable if the implementation is genuinely correct and verified. The agent must never manufacture false criticism to appear diligent.
+## 4. Output Contract: Structured Finding Ledger
+
+The Devil's Advocate outputs a strictly structured Finding Ledger:
+
+```json
+{
+  "iteration": 1,
+  "executionMode": "ARTIFACT_ISOLATED_REVIEW",
+  "diffHash": "437bbfcb",
+  "findings": [
+    {
+      "id": "DA-01",
+      "topic": "correctness",
+      "validity": "VALID",
+      "severity": "BLOCKER",
+      "disposition": "STRONG",
+      "location": "src/services/queue.ts#L45-L60",
+      "acceptanceCriteria": "AC-1",
+      "failureScenario": "When the network disconnects between line 48 and 52, the transaction aborts but the queue message is not acknowledged, creating an unrecoverable poison pill.",
+      "reproduction": "Inject socket disconnect during executePaymentTransaction step.",
+      "evidence": "Observed missing error catch and dead-letter queue routing in queue.ts.",
+      "concreteAlternativeDiff": "```diff\n- queue.process(msg)\n+ try { await queue.process(msg); } catch (err) { await dlq.send(msg, err); }\n```"
+    }
+  ]
+}
+```
 
 ---
 
-## 5. Output Format
-
-The Devil's Advocate must output its review conforming to the [Finding Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/finding-policy.md):
-
-```markdown
-### Round Summary: [Topic Name]
-- **Status**: [Issues Found | Clean]
-- **Findings Count**: [Number]
-
-#### Finding: [ID] - [Short Title]
-- **Severity**: `[CRITICAL | HIGH | MEDIUM | LOW]`
-- **Category**: `[Correctness | Error Handling | Security | Concurrency | Performance | Maintainability | Testing Gaps]`
-- **Location**: `path/to/file.ts:L20-L35`
-- **Evidence**: [Raw code snippet or runtime behavior]
-- **Problem**: [Technical explanation of the defect]
-- **Impact**: [Concrete business or operational consequence]
-- **Recommendation**:
-```diff
-- unsafeFunction(data);
-+ if (data) {
-+   safeFunction(data);
-+ }
-```
-- **Confidence**: `[HIGH | MEDIUM | LOW]`
-```
+## 5. Review Priority & Topics
+
+1. **Correctness & Logic**: Race conditions, unhandled edge cases, data corruption.
+2. **Error Handling & Failure Modes**: Swallowed errors, unhandled promise rejections, missing rollbacks.
+3. **Security & Permissions**: IDOR, auth bypass, unsanitized inputs, credential leakage.
+4. **Concurrency & DB Locking**: Missing transactions, dirty reads, missing row locks.
+5. **Performance**: N+1 queries, memory leaks, excessive allocations.
+6. **Testing Gaps**: Untested failure branches, brittle assertions, missing edge cases.

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.1';
+const VERSION = '1.0.2';
 const CWD = process.cwd();
 const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');