ai-engineering-loop 1.0.0

package/core/iteration-policy.md

@@ -0,0 +1,108 @@
+# Iteration Policy Specification
+
+## 1. Overview & Objectives
+
+The **Iteration Policy** governs autonomous retry loops within the AI Engineering Loop. When deterministic tests fail or the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) identifies valid blocking findings, the system initiates an **autonomous iteration cycle**.
+
+The objective of this policy is to enable **reliable self-correction** while strictly guarding against infinite loops, cognitive drift, and resource exhaustion.
+
+---
+
+## 2. Iteration Limits & Configuration
+
+```text
+DEFAULT_MAX_ITERATIONS = 3
+MIN_ITERATIONS = 1
+MAX_ALLOWED_CEILING = 5
+```
+
+- **Default Cap**: An engineering run is allotted a maximum of **3 iterations** by default.
+- **Configurability**: Projects or workflows may configure `MAX_ITERATIONS` between 1 and 5 in their runtime configuration or Goal Contract.
+- **Hard Ceiling**: Under no circumstances may an agent loop beyond 5 iterations without human re-authorization.
+
+---
+
+## 3. The Autonomous Iteration Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> GoalContract: Initialize
+    GoalContract --> MakerExecute: Iteration = 1
+    
+    state "Iteration Loop" as Loop {
+        MakerExecute --> DeterministicChecks
+        DeterministicChecks --> MakerFix: Deterministic Fail
+        MakerFix --> DeterministicChecks
+        
+        DeterministicChecks --> DevilsAdvocate: Deterministic Pass
+        DevilsAdvocate --> JudgeEvaluation
+        
+        JudgeEvaluation --> PassState: Verdict = PASS
+        JudgeEvaluation --> MakerIterate: Verdict = ITERATE\n(Iteration < MAX_ITERATIONS)
+        MakerIterate --> DeterministicChecks
+        
+        JudgeEvaluation --> EscalateState: Verdict = ESCALATE\n(Iteration >= MAX_ITERATIONS or Stalled)
+    }
+    
+    PassState --> [*]: Hand off to Adapter
+    EscalateState --> [*]: Pause for Human
+```
+
+### Iteration State Machine Steps
+
+1. **Cycle Start (Iteration $K$)**:
+   - Increments iteration counter $K \leftarrow K + 1$.
+   - Verifies $K \le \text{MAX\_ITERATIONS}$. If $K > \text{MAX\_ITERATIONS}$, immediately triggers `ESCALATE`.
+2. **Maker Refinement**:
+   - The [Maker Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/maker.md) receives the prior iteration's triaged findings and Judge directives.
+   - Maker applies targeted code fixes and updates test suites.
+3. **Deterministic Re-verification**:
+   - All tests, typecheck, lint, and build checks are re-executed from scratch.
+4. **Adversarial Differential Review**:
+   - The [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) evaluates the updated diff against previously raised findings and checks for new regressions.
+5. **Judge Evaluation & Progression**:
+   - The [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) compares findings from Iteration $K$ with Iteration $K-1$.
+   - If progress is verified and all criteria met $\rightarrow$ `PASS`.
+   - If new valid findings emerge but progress is demonstrated $\rightarrow$ `ITERATE` (if $K < \text{MAX\_ITERATIONS}$).
+   - If repeated findings or no progress detected $\rightarrow$ `ESCALATE`.
+
+---
+
+## 4. Finding State Transitions
+
+Every finding generated during iteration must progress through an explicit state lifecycle:
+
+```mermaid
+stateDiagram-v2
+    [*] --> NEW: Discovered by Reviewer
+    NEW --> TRIAGED_VALID: Verified with evidence
+    NEW --> TRIAGED_INVALID: Disproved with evidence
+    NEW --> TRIAGED_UNCERTAIN: Ambiguous requirement
+    
+    TRIAGED_VALID --> RESOLVED: Fixed by Maker
+    RESOLVED --> VERIFIED: Re-tested & confirmed by DA/Judge
+    
+    TRIAGED_INVALID --> CLOSED: Retained in log as false positive
+    TRIAGED_UNCERTAIN --> ESCALATED: Requires human clarification
+```
+
+| State | Definition | Next Permissible Action |
+|---|---|---|
+| `NEW` | Discovered by Devil's Advocate in current iteration | Judge / Maker triages against repository facts |
+| `TRIAGED_VALID` | Confirmed real technical or contractual defect | Maker must apply code/test fix |
+| `TRIAGED_INVALID` | Confirmed false positive / non-applicable suggestion | Closed; documented with explanation |
+| `TRIAGED_UNCERTAIN` | Unclear business rule or contradictory requirement | Escalated to human user |
+| `RESOLVED` | Maker has applied code fix and passing test | Re-evaluated by Devil's Advocate & Judge |
+| `VERIFIED` | Confirmed completely resolved by Judge | Marked complete |
+
+---
+
+## 5. Iteration State Preservation
+
+To maintain continuity across sub-agent calls or tool invocations, each iteration MUST update a standardized state record containing:
+
+1. **Current Iteration Number** ($K / N$).
+2. **Active Finding Ledger**: Complete list of all findings with their current state.
+3. **Cumulative Code Diff**: Total changes relative to base branch.
+4. **Deterministic Run Results**: Exit codes and timestamped test outcomes.
+5. **No-Progress Hash**: Signatures of active findings for stagnation detection.

package/core/judge-policy.md

@@ -0,0 +1,123 @@
+# Judge Policy Specification
+
+## 1. Overview & Role Definition
+
+The **Judge Agent** is the impartial arbiter of the AI Engineering Loop. In traditional workflows, either the author approves its own code (optimistic bias) or a reviewer blocks changes arbitrarily (nitpicking/hallucination).
+
+The Judge Agent evaluates the complete matrix of:
+1. The original [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
+2. The surgical code implementation & diff.
+3. The raw [Deterministic Verification](file:///Users/egagofur/Development/work/ai-engineering-loop/core/verification-loop.md) outputs (tests, typecheck, lint, build).
+4. The [Devil's Advocate Review Findings](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) and Author's evidence/triage.
+5. The [Iteration & No-Progress State](file:///Users/egagofur/Development/work/ai-engineering-loop/core/iteration-policy.md).
+
+```mermaid
+flowchart TD
+    GC[Goal Contract] --> Judge[Judge Agent]
+    Diff[Implementation Diff] --> Judge
+    DV[Deterministic Logs] --> Judge
+    DA[Devil's Advocate Findings] --> Judge
+    
+    Judge --> Decision{Evaluate Rules}
+    
+    Decision -->|All ACs Met, Tests Green, Findings Resolved| PASS[Verdict: PASS]
+    Decision -->|Valid Blocking Findings & Iterations Remaining| ITERATE[Verdict: ITERATE]
+    Decision -->|Stalled / Max Iterations / High Risk| ESCALATE[Verdict: ESCALATE]
+```
+
+---
+
+## 2. Evidence Evaluation Rules
+
+The Judge does NOT blindly accept claims from either the Maker or the Devil's Advocate. Every statement is scrutinized according to the following evidentiary rules:
+
+### Rule 1: Deterministic Precedence
+If any deterministic check (unit tests, TypeScript compilation, linter, build) failed or was not executed, the Judge **CANNOT** issue a `PASS` verdict.
+
+### Rule 2: Rejection of Unsubstantiated Nitpicks
+A Devil's Advocate finding that:
+- Relies on personal aesthetic preference (e.g. *"variable names could be shorter"*),
+- Suggests speculative future-proofing abstractions not requested in the Goal Contract, or
+- Misunderstands existing repository conventions,
+must be declared **`INVALID`** by the Judge and discarded from blocking the build.
+
+### Rule 3: Strict Severity Thresholds
+- **SEV-1 (Critical)** and **SEV-2 (High)** findings: Must be resolved in code with passing tests before a `PASS` verdict can be granted.
+- **SEV-3 (Medium)** and **SEV-4 (Low)** findings: May be accepted into an action items backlog if they do not violate any Acceptance Criteria in the Goal Contract.
+
+### Rule 4: Verification of Author Triage
+If the Maker Agent claims a finding is `INVALID` (e.g. *"The suggested API does not exist"*), the Judge verifies this claim against the repository before accepting the dismissal.
+
+---
+
+## 3. Verdict Computation Logic
+
+```text
+FUNCTION ComputeVerdict(Contract, Diff, DeterministicLogs, Findings, IterationState):
+    IF DeterministicLogs.HasFailures() THEN
+        RETURN ITERATE(reason="Deterministic verification gates failed")
+    END IF
+
+    IF IterationState.IsStalled() OR IterationState.CurrentIteration >= IterationState.MaxIterations THEN
+        IF Findings.HasUnresolvedBlocking() THEN
+            RETURN ESCALATE(reason="Max iterations reached with unresolved blocking findings")
+        END IF
+    END IF
+
+    IF Contract.ViolatesConstraints(Diff) THEN
+        RETURN ESCALATE(reason="Implementation violated technical constraints or modified out-of-scope files")
+    END IF
+
+    UnresolvedBlocking = Findings.GetUnresolved(severity IN [SEV_1, SEV_2])
+    
+    IF UnresolvedBlocking.Count == 0 THEN
+        IF Contract.AllAcceptanceCriteriaVerified(DeterministicLogs) THEN
+            RETURN PASS(summary="All criteria satisfied and verified with proof")
+        ELSE
+            RETURN ITERATE(reason="Missing deterministic proof for specific Acceptance Criteria")
+        END IF
+    ELSE
+        RETURN ITERATE(reason="Unresolved blocking findings exist", findings=UnresolvedBlocking)
+    END IF
+```
+
+---
+
+## 4. Standardized Judge Verdict Report
+
+Every evaluation concludes with a formal **Judge Verdict Artifact**:
+
+```markdown
+# ⚖️ Judge Evaluation Report
+
+## 1. Executive Verdict
+- **Verdict**: `[PASS | ITERATE | ESCALATE]`
+- **Iteration**: `[K of N]`
+- **Confidence**: `[HIGH | MEDIUM | LOW]`
+
+## 2. Deterministic Verification Audit
+| Gate | Command | Result | Status |
+|---|---|---|:---:|
+| Unit Tests | `npx jest --testPathIgnorePatterns="integration"` | 14 passed, 0 failed | ✅ PASS |
+| Static Types | `npx tsc --noEmit` | Exit code 0 | ✅ PASS |
+| Linter | `npx eslint --fix <files>` | 0 errors, 0 warnings | ✅ PASS |
+| Build | `npm run build` | Exit code 0 | ✅ PASS |
+
+## 3. Goal Contract Compliance Audit
+| Acceptance Criterion | Verification Method | Status |
+|---|---|:---:|
+| AC-1: Correct attendance status calculation | `resolve-display-status.test.ts` | ✅ PASS |
+| AC-2: Weekend & non-normal hours edge cases | `resolve-display-status.test.ts:L45` | ✅ PASS |
+| AC-3: Backward compatibility preserved | Integration test suite | ✅ PASS |
+
+## 4. Finding Triage & Resolution Matrix
+| ID | Severity | Category | Reviewer Finding | Triage Status | Resolution Proof |
+|---|---|---|---|:---:|---|
+| COR-001 | HIGH | Correctness | Missing null check on overtimeNote | `VALID` | Fixed in `service.ts:L32`; tested in `service.test.ts` |
+| SEC-001 | LOW | Security | Suggest sanitizing display status | `INVALID` | Display status is an enum internally generated, not user input |
+
+## 5. Directives for Next Step
+[If PASS: Hand off to Delivery Adapter.]
+[If ITERATE: Explicit, numbered instructions for the Maker Agent.]
+[If ESCALATE: Actionable human decision points.]
+```

package/core/project-initialization.md

@@ -0,0 +1,97 @@
+# Project Initialization & Context Discovery Specification
+
+## 1. Overview & Core Philosophy
+
+The AI Engineering Loop enforces a clean architectural separation between **Deterministic Context Bootstrap** and **Agent Intelligence**:
+
+> **"The CLI bootstraps and validates repository context. The AI Agent reasons over that context to execute the engineering lifecycle."**
+
+```mermaid
+flowchart TD
+    subgraph CLI [DETERMINISTIC CLI BOOTSTRAP: init / status / refresh]
+        Discover[Repository Discovery Engine] --> ContextGen[Generate .ai-engineering-loop/]
+        ContextGen --> Validate[Context Validation Engine]
+    end
+
+    Validate --> ContextDir[(.ai-engineering-loop/ Ground Truth)]
+
+    subgraph Agent [AI AGENT INTELLIGENCE: run]
+        ContextDir --> GoalContract[Stage 1: Goal Contract]
+        GoalContract --> RCA[Stage 2: Root Cause Analysis]
+        RCA --> Plan[Stage 3: Implementation Plan]
+        Plan --> Maker[Stage 4: Maker Agent: Code & Tests]
+        Maker --> Verify{Stage 5: Deterministic Verification}
+        Verify -->|Pass| DA[Stage 6: Devil's Advocate Review]
+        DA --> Judge[Stage 7: Judge Evaluation]
+        Judge -->|PASS| Adapter[Stage 8: Delivery Pipeline]
+    end
+```
+
+---
+
+## 2. Operation Separation: `init` vs `run`
+
+### The `init` Operation
+- **Purpose**: Discovers repository characteristics, extracts manifest scripts, binds archetype profiles, and generates `.ai-engineering-loop/`.
+- **Command**: `npx ai-engineering-loop init` (or `/ai-engineering-loop init`).
+- **Boundaries**:
+  - `init` **MUST NOT** edit application code, write business logic, author unit tests, or run adversarial reviews.
+  - `init` **MUST NOT** commit to git, change branches, push to remotes, or open PRs.
+  - The only permitted file writes are within `<workspace-root>/.ai-engineering-loop/`.
+- **Idempotency**: Running `init` repeatedly is safe. If context is already complete and valid, `init` is a non-destructive no-op.
+
+---
+
+### The `run` Operation
+- **Purpose**: Consumes the ground truth in `.ai-engineering-loop/` to solve a specific user task.
+- **Command**: `npx ai-engineering-loop run` (or `/ai-engineering-loop [task]`).
+- **Boundaries**:
+  - The Agent reads `.ai-engineering-loop/` (triggering auto-init if missing).
+  - Formulates the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
+  - Performs Root Cause Analysis (RCA) and Implementation Planning.
+  - Executes surgical diffs, runs deterministic test suites, conducts independent adversarial review via the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md), and obtains certification from the [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md).
+
+---
+
+## 3. Dual-State Initialization Flow
+
+```text
+State A (Context Exists):
+Inspect Health ──▶ Detect Drift ──▶ Selectively Refresh Stale Sections ──▶ Load
+
+State B (Context Missing):
+Inspect Topology ──▶ Manifests/Commands ──▶ Inferred Profile ──▶ Generate .ai-engineering-loop/ ──▶ Validate
+```
+
+---
+
+## 4. The 5-Pass Discovery Engine
+
+1. **Pass 1 (Topology & Profile)**:
+   - Identifies if Monorepo (`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `Cargo.toml [workspace]`, `go.work`) or Single Application.
+   - Binds archetype profile: `web-app` | `backend-api` | `mobile-app` | `library` | `monorepo`.
+2. **Pass 2 (Manifests & Verification Commands)**:
+   - Reads `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`.
+   - Extracts exact CLI scripts: `test_unit`, `test_all`, `typecheck`, `lint`, `build`, `e2e`.
+3. **Pass 3 (Architecture & Invariants)**:
+   - Maps ingress (controllers/routers/views), domain services, and database layers.
+   - Sets boundary invariant rules.
+4. **Pass 4 (Conventions & Documentation)**:
+   - Identifies observed naming conventions, test file placement, error patterns.
+   - Cross-checks existing docs (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`, `AGENTS.md`) without blindly trusting contradictions.
+5. **Pass 5 (Safety Audit & File Generation)**:
+   - Strictly ignores private credentials (`.env`, `.env.local`, `.pem`, tokens, API keys).
+   - Generates `.ai-engineering-loop/` (`config.md`, `architecture.md`, `conventions.md`, `verification.md`, `adapter.md`).
+
+---
+
+## 5. Version Control Recommendation
+
+Because `.ai-engineering-loop/` represents the shared ground truth of a repository's engineering conventions, it is **strongly recommended to commit `.ai-engineering-loop/` to version control**:
+
+```bash
+git add .ai-engineering-loop
+git commit -m "chore: initialize AI Engineering Loop context"
+```
+
+This allows all team members and future AI agent sessions to share identical context without redundant discovery cycles.

package/core/repo-config-schema.md

@@ -0,0 +1,72 @@
+# Repository Configuration Schema (`.ai-engineering-loop/`)
+
+## 1. Overview & Purpose
+
+The `.ai-engineering-loop/` directory serves as the **Living Project Context** for autonomous agents working in a repository:
+
+```text
+<target-repository>/
+└── .ai-engineering-loop/
+    ├── metadata.json       # Baseline tracking, git revisions, & manifest hashes
+    ├── config.md           # Basic project metadata, type, and stack
+    ├── architecture.md     # System architecture, layers, & boundaries
+    ├── conventions.md      # Code standards, patterns, & forbidden practices
+    ├── verification.md     # Exact CLI verification commands
+    └── adapter.md          # Configured delivery pipeline & CI/CD tools
+```
+
+---
+
+## 2. File Specifications
+
+### 1. `metadata.json` — Context Baseline & Drift Tracking
+Maintains lightweight state for instant drift detection:
+- `contextVersion`: Schema version (e.g. `"1.0.0"`).
+- `generatedAt`: ISO timestamp of initial generation.
+- `repositoryRevision`: Full git commit SHA corresponding to this context baseline.
+- `projectProfile`: Active archetype profile (`web-app`, `backend-api`, `mobile-app`, `library`, `monorepo`).
+- `manifestChecksums`: Hash map of manifest files (`package.json`, `go.mod`, `Cargo.toml`).
+- `lastReconciliation`: Timestamp, trigger, and impact of the last update.
+
+### 2. `config.md` — Project Identity & Metadata
+- `project_name`: Name of the repository / service.
+- `project_profile`: Bound profile archetype.
+- `languages`: Primary languages and versions.
+- `frameworks`: Core runtime frameworks.
+- `package_manager`: Detected package manager (`pnpm`, `npm`, `yarn`, `bun`, `cargo`, `go`, `poetry`).
+- `default_base_branch`: Primary target branch (`main`, `master`, `develop`).
+- `observed_evidence`: File paths used to infer project identity.
+
+### 3. `architecture.md` — System Design & Boundaries
+- **Presentation / Ingress**: UI components, API routers, controllers.
+- **Application / Domain**: Services, business logic actions, use cases.
+- **Data Access**: Repositories, ORMs, query builders, cache stores.
+- **Infrastructure / Integrations**: External third-party APIs, message brokers, queues.
+- **Critical Boundaries**: Rules regarding circular dependencies and forbidden layer leaps.
+- **Evidence & Confidence**: Observed directories and confidence rating (`HIGH`, `MEDIUM`, `LOW`).
+
+### 4. `conventions.md` — Engineering Standards & Invariants
+- **Design System / UI Tokens**: Approved token sets, component libraries.
+- **Naming Conventions**: File naming (`kebab-case`, `PascalCase`), interface naming, test file suffixes.
+- **Error Handling Patterns**: Standard error classes, result types, domain exceptions.
+- **Forbidden Anti-Patterns**: Explicit list of banned practices.
+
+### 5. `verification.md` — Deterministic Commands
+- `test_unit`: Command for focused unit testing.
+- `test_all`: Command for full regression suite.
+- `typecheck`: Command for static typechecking (`tsc --noEmit`, `mypy`).
+- `lint`: Command for linting with auto-fix.
+- `build`: Command for production bundle / binary compilation.
+- `e2e`: (Optional) End-to-end / browser test command.
+
+### 6. `adapter.md` — Delivery Pipeline Configuration
+- `adapter_type`: Configured adapter (`dot`, `github`, `gitlab`, `standard`).
+- `remote_repository`: Git remote repository slug.
+- `default_target_branch`: Base target branch.
+- `ci_provider`: Detected CI engine (GitHub Actions, GitLab CI).
+
+---
+
+## 3. Version Control Recommendation
+
+It is strongly recommended to **commit the `.ai-engineering-loop/` directory (including `metadata.json`) to git**. This ensures all developers and AI agent sessions share consistent, up-to-date repository context without repeated re-discovery overhead.

package/core/verification-loop.md

@@ -0,0 +1,97 @@
+# Verification Loop Specification
+
+## 1. Overview
+
+The **Verification Loop** is the dual-layer validation engine of the AI Engineering Loop. It guarantees that code is not merely claimed to be functional by its author, but is rigorously tested via **machine-checkable deterministic gates** and scrutinized by **independent adversarial inspection**.
+
+```mermaid
+flowchart TD
+    Start([Implementation Diff]) --> D1[Deterministic Gate 1: Unit & Integration Tests]
+    D1 -->|Fail| MakerFix[Return to Maker: Fix Logic]
+    D1 -->|Pass| D2[Deterministic Gate 2: Typecheck & Compiler]
+    
+    D2 -->|Fail| MakerFix
+    D2 -->|Pass| D3[Deterministic Gate 3: Linter & Format]
+    
+    D3 -->|Fail| MakerFix
+    D3 -->|Pass| D4[Deterministic Gate 4: Build / Packaging]
+    
+    D4 -->|Fail| MakerFix
+    D4 -->|Pass| Adversarial[Adversarial Gate: Devil's Advocate Layered Review]
+    
+    Adversarial --> JudgeEval[Judge Agent: Evidence Evaluation]
+    JudgeEval -->|ITERATE| MakerFix
+    JudgeEval -->|ESCALATE| Escalate([Human Escalation])
+    JudgeEval -->|PASS| Done([Definition of Done Satisfied])
+```
+
+---
+
+## 2. Dynamic Command Discovery
+
+The exact commands executed for each deterministic gate are resolved dynamically according to [Configuration Precedence](file:///Users/egagofur/Development/work/ai-engineering-loop/core/configuration-precedence.md):
+
+1. Read `.ai-engineering-loop/verification.md` from the target repository if present.
+2. If missing, fall back to the defaults of the bound [Project Profile](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/README.md) (`web-app`, `backend-api`, `mobile-app`, `library`, `monorepo`).
+3. If profile is unspecified, infer commands from repository manifests (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`).
+
+---
+
+## 3. Layer 1: Deterministic Verification
+
+Deterministic verification consists of machine-executed commands producing binary (`PASS` / `FAIL`) or structured outputs. 
+
+An agent is **strictly prohibited** from proceeding to adversarial review if any deterministic gate fails.
+
+### The 4 Deterministic Gates
+
+#### Gate 1: Unit & Regression Tests
+- **Objective**: Prove correctness of new logic and ensure zero regressions.
+- **Criteria**: 100% exit code `0`, zero test failures, zero unexpected skipped tests.
+- **Rules**:
+  - Tests must cover happy paths, null/undefined safety, empty inputs, boundary conditions, and error branches.
+  - Test assertions must be strict (e.g. checking specific return values, error types, and state mutations, not merely `toBeDefined()`).
+
+#### Gate 2: Static Typing & Compilation
+- **Objective**: Prove mathematical type safety and schema conformance.
+- **Criteria**: Zero compiler / typechecker errors across the codebase or affected workspaces (e.g. `tsc --noEmit`, `mypy`, `cargo check`).
+
+#### Gate 3: Code Standards & Linting
+- **Objective**: Guarantee zero static analysis rule violations and formatting hygiene.
+- **Criteria**: Zero linter errors on touched files (e.g. `eslint`, `ruff`, `golangci-lint`, `dart analyze`).
+
+#### Gate 4: Build & Packaging
+- **Objective**: Ensure the project compiles, bundles, or packages without missing assets or circular dependencies.
+- **Criteria**: Build command completes with exit code `0`.
+
+---
+
+## 4. Layer 2: Adversarial Verification (Devil's Advocate)
+
+Once all deterministic gates pass, the code diff is submitted to the **Devil's Advocate Agent**.
+
+### Purpose
+Deterministic tests only test what the author *thought* to test. The Devil's Advocate exists to discover what the author *forgot*, *assumed*, or *misunderstood*.
+
+### Scope of Review
+The Devil's Advocate reviews strictly the git diff against the target base branch:
+```bash
+git diff <base-branch>...HEAD
+```
+
+### Layered Review Rules
+Review domains are dynamically assembled based on the active **Project Profile** and **Repository Invariants** (see [Devil's Advocate Specification](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md)), ensuring only substantive, relevant topics are evaluated.
+
+---
+
+## 5. Verification Evidence Protocol
+
+All claims of verification must be accompanied by **reproducible evidence**:
+
+1. **Command Executed**: Full CLI command line string.
+2. **Exit Code**: Exact status code returned.
+3. **Execution Output**: Raw relevant output snippet showing test pass counts, typecheck logs, or lint results.
+4. **Acceptance Criteria Mapping**: Explicit mapping showing which test corresponds to which AC from the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
+
+> [!CAUTION]
+> Statements such as *"I have manually verified that this works"* or *"The tests should pass"* without command outputs are invalid and will be rejected by the Judge Agent.

package/docs/antigravity-feasibility.md

@@ -0,0 +1,90 @@
+# Antigravity Sub-Agent Feasibility & Execution Strategy
+
+## 1. Executive Summary
+
+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.
+
+---
+
+## 2. Analysis of the 8 Core Questions
+
+```mermaid
+flowchart TD
+    Main[Antigravity Primary Agent / Planner] -->|Spawn / Invoke| SubDA[Sub-Agent / Persona: Devil's Advocate]
+    Main -->|Spawn / Invoke| SubJD[Sub-Agent / Persona: Judge]
+    
+    SubDA -->|Reads Same Workspace & Git Diff| Repo[(Workspace Files & Git)]
+    SubDA -->|Returns Finding Ledger| Main
+    
+    Main -->|Evaluates with Judge Policy| SubJD
+    SubJD -->|Returns PASS / ITERATE / ESCALATE| Main
+    
+    Main -->|Persists State Artifacts| BrainDir[(brain/<conversation_id>/)]
+```
+
+### 1. Can Antigravity summon independent sub-agents?
+- **Status**: **YES**.
+- **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.
+- **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`.
+
+### 2. Can the main agent pass context to a sub-agent?
+- **Status**: **YES**.
+- **Mechanism**: The spawning task payload allows passing:
+  - The [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
+  - Target base branch name (`main`, `develop`).
+  - Active iteration index and finding ledger history.
+
+### 3. Can the sub-agent inspect the same repository?
+- **Status**: **YES**.
+- **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.).
+
+### 4. Can the sub-agent return structured findings?
+- **Status**: **YES**.
+- **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.
+
+### 5. Can the main agent consume those findings?
+- **Status**: **YES**.
+- **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).
+
+### 6. Can the loop be repeated automatically?
+- **Status**: **YES**.
+- **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.
+
+### 7. Can iteration state be persisted?
+- **Status**: **YES**.
+- **Mechanism**: Antigravity provides a dedicated per-conversation artifact directory:
+  `<appDataDir>/brain/<conversation-id>/`
+  The loop persists:
+  - `goal_contract.md`
+  - `iteration_ledger.json` (finding signatures, iteration index, diff hashes)
+  - `verification_logs.txt`
+  - `judge_verdict.md`
+
+### 8. What are the practical token/context limitations?
+- **Analysis**:
+  - Full codebase context in every prompt leads to context bloat and degraded attention.
+  - **Optimization Strategy**:
+    - Pass only the `Goal Contract` + `git diff <base>...HEAD` to the Devil's Advocate, not the entire conversation history.
+    - Retain finding signatures and summaries rather than full raw chat transcripts.
+    - Run deterministic checks with summarized test output (failing tests in detail, passing suites as totals).
+
+---
+
+## 3. Recommended Execution Modes in Antigravity
+
+| Dimension | Mode A: Native Sub-Agents (Recommended) | Mode B: Persona Context Switching |
+|---|---|---|
+| **Context Isolation** | 100% Isolated context window | Sequential turns within single context |
+| **Cognitive Bias** | Zero author bias (clean slate) | Low bias if context is scoped to diff |
+| **Token Overhead** | Minimal (sub-agent starts fresh) | Moderate (context grows across turns) |
+| **Implementation Complexity** | Requires subagent invocation tool | Works natively in standard chat turn |
+| **Antigravity Fit** | Ideal for complex multi-file features | Ideal for quick, surgical fixes |
+
+---
+
+## 4. Implementation Roadmap for Antigravity Skill
+
+To deploy this workflow as an Antigravity Custom Skill (e.g. `skills/ai-engineering-loop/SKILL.md`):
+1. Package the core loop into an executable skill definition with YAML frontmatter.
+2. Provide slash command shortcuts (e.g. `/loop:start`, `/loop:review`).
+3. Bind the DOT Adapter as an opt-in release plugin when working inside DOT repositories.

package/docs/migration-plan.md

@@ -0,0 +1,70 @@
+# Migration Plan: Legacy 8-Phase Workflow to AI Engineering Loop
+
+## 1. Overview & Migration Objectives
+
+The legacy `dot-dev-workflow` established a strong 8-phase engineering foundation across DOT codebases. However, it tightly coupled generic engineering principles (root cause analysis, surgical diffs, unit testing, static typing) with company-specific delivery tooling (GitLab, `glab`, `@coreview-bot`, Mattermost).
+
+This migration plan maps every single phase of the legacy workflow into the new modular architecture, ensuring that **zero engineering rigor is lost** while achieving complete platform independence.
+
+---
+
+## 2. Comprehensive Phase-by-Phase Mapping
+
+```mermaid
+flowchart TD
+    subgraph LegacyWorkflow [Legacy 8-Phase Workflow]
+        L1[Phase 1: Root Cause Analysis]
+        L2[Phase 2: Collaborative Alignment]
+        L3[Phase 3: Surgical Code Fix]
+        L4[Phase 4: Unit Testing]
+        L5[Phase 5: Typecheck & Build]
+        L6[Phase 6: Multi-Branch glab MRs]
+        L7[Phase 7: @coreview-bot Triage]
+        L8[Phase 8: Mattermost Report]
+    end
+
+    subgraph NewArchitecture [AI Engineering Loop + DOT Adapter]
+        GC[core/goal-contract.md]
+        MA[agents/maker.md]
+        VL[core/verification-loop.md]
+        DA[agents/devil-advocate.md]
+        JD[agents/judge.md]
+        AD_GL[adapters/dot/gitlab.md]
+        AD_MB[adapters/dot/multi-branch.md]
+        AD_CV[adapters/dot/coreview.md]
+        AD_MM[adapters/dot/mattermost.md]
+    end
+
+    L1 --> MA
+    L2 --> GC
+    L3 --> MA
+    L4 --> VL
+    L5 --> VL
+    L6 --> AD_GL & AD_MB
+    L7 --> DA & AD_CV
+    L8 --> AD_MM
+```
+
+---
+
+## 3. Detailed Mapping Matrix
+
+| Legacy Phase | New Architecture Placement | Action (`Keep / Modify / Move / Remove`) | Detailed Rationale |
+|---|---|:---:|---|
+| **Phase 1: Comprehensive Code & Root Cause Analysis** | `agents/maker.md` & `core/goal-contract.md` | **MODIFY & KEEP** | End-to-end data tracing, git history examination (`git log -n 5 -p`), and blind spot identification are preserved in the Maker Agent. The output feeds directly into formalizing the Goal Contract. |
+| **Phase 2: Collaborative Alignment & Brainstorming** | `core/goal-contract.md` | **MODIFY & KEEP** | Upgraded from informal conversational alignment to a binding, machine-verifiable [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md) containing explicit Acceptance Criteria, constraints, and out-of-scope declarations. |
+| **Phase 3: Surgical & Clean Code Fixing** | `agents/maker.md` & `core/definition-of-done.md` | **KEEP** | Preserves core quality rules: smallest coherent diff, zero dead code, zero speculative abstractions, adhering to existing architectural conventions and design tokens. |
+| **Phase 4: Unit Testing & Boundary Coverage** | `core/verification-loop.md` (Gate 1) & `agents/maker.md` | **KEEP** | Retains 100% test pass requirement, boundary condition testing, null/undefined safety, and edge-case permutations as Deterministic Gate 1. |
+| **Phase 5: Build & Type Safety Verification** | `core/verification-loop.md` (Gates 2, 3, 4) | **KEEP** | Retains `tsc --noEmit` and `eslint --fix` as mandatory machine-checked gates that must pass prior to review. |
+| **Phase 6: Multi-Branch MR & Issue Card via `glab` CLI** | `adapters/dot/gitlab.md` & `adapters/dot/multi-branch.md` | **MOVE TO ADAPTER** | Moved out of generic core into the DOT Adapter. The core loop remains platform-agnostic, while DOT adapter encapsulates `glab issue create`, `glab mr create`, and cherry-picking to `staging` and `develop`. |
+| **Phase 7: Automated Bot Review Triage (`@coreview-bot`)** | `agents/devil-advocate.md` (Internal) + `adapters/dot/coreview.md` (External) | **SPLIT & MOVE** | The concept of adversarial review is promoted to the generic core as the internal [Devil's Advocate Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) (runs *before* opening MR). The external `@coreview-bot` triage (`VALID` vs `HALU`) is moved to `adapters/dot/coreview.md` (runs *after* opening MR). |
+| **Phase 8: Mattermost Markdown Report & Auto-Send via MCP** | `adapters/dot/mattermost.md` | **MOVE TO ADAPTER** | Moved out of generic core into the DOT Adapter. Preserves channel mapping lookup (`mattermost-channel-mapping.json`), fallback prompt, and MCP `mattermost_send_message` dispatch with `from: "AI Agent"`. |
+
+---
+
+## 4. Key Improvements over Legacy Workflow
+
+1. **Elimination of Self-Certification**: In the legacy workflow, the same agent that wrote code decided it was done. In the new architecture, only the independent [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) can grant a `PASS` verdict.
+2. **Pre-MR Adversarial Inspection**: Flaws are caught and fixed locally via the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) *before* publishing PRs/MRs to remote repositories.
+3. **No-Progress & Escalation Circuit Breakers**: Bounded iterations (`MAX_ITERATIONS = 3`) and [No-Progress Detection](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/no-progress-policy.md) prevent runaway loops and thrashing.
+4. **Pluggable Architecture**: The same generic core loop can now be used with GitHub, Bitbucket, Jira, Linear, or Slack simply by swapping adapters.