ai-engineering-loop 1.0.0

package/core/configuration-precedence.md

@@ -0,0 +1,102 @@
+# Configuration Precedence & Resolution Engine
+
+## 1. Overview & Core Principle
+
+To support multiple repositories, varied tech stacks, and disparate team conventions without fragmenting or forking the generic core, the AI Engineering Loop implements a **5-Layer Configuration Hierarchy**.
+
+The core principle of configuration resolution is:
+
+> **The more specific layer refines or overrides the broader layer, provided it does not violate immutable safety boundaries.**
+
+```mermaid
+flowchart TD
+    Init[LIFECYCLE STAGE 0: Project Initialization & Discovery] --> Res[Dynamic Configuration Hierarchy]
+    
+    subgraph Layers [5-LAYER HIERARCHY]
+        L1[Layer 1: GLOBAL ENVIRONMENT<br>Host safety ceilings, execution timeouts, max iteration cap]
+        L2[Layer 2: ENGINEERING CORE<br>Contract-driven loop, deterministic precedence, DoD, triad roles]
+        L3[Layer 3: PROJECT TYPE PROFILE<br>Archetype defaults: web-app, backend-api, mobile-app, library, monorepo]
+        L4[Layer 4: REPOSITORY LOCAL CONFIG<br>.ai-engineering-loop/ auto-discovered or loaded]
+        L5[Layer 5: TASK CONTRACT<br>Goal contract for current execution run]
+
+        L1 --> L2 --> L3 --> L4 --> L5
+    end
+```
+
+---
+
+## 2. The 5 Hierarchy Layers
+
+### Layer 1: Global Environment
+- **Authority**: System / Host Platform (Antigravity IDE, CLI environment).
+- **Scope**: Hard safety constraints (e.g. `ABSOLUTE_MAX_ITERATIONS = 5`, maximum command timeout = 10m, safe file path boundaries).
+- **Overridability**: **Immutable**. Cannot be overridden by downstream layers.
+
+### Layer 2: Engineering Core (`core/`)
+- **Authority**: AI Engineering Operating System specification.
+- **Scope**: Mandatory engineering invariants:
+  - No code changes without a formalized [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
+  - Deterministic checks must pass 100% before adversarial review.
+  - Review findings require reproducible evidence (Level 1–3) to be valid.
+  - Only the [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) can issue a `PASS` verdict.
+- **Overridability**: Invariant. Downstream layers cannot skip verification or eliminate agent roles.
+
+### Layer 3: Project Type Profile (`profiles/`)
+- **Authority**: Archetype profiles (`web-app`, `backend-api`, `mobile-app`, `library`, `monorepo`).
+- **Scope**: Tech stack defaults:
+  - Relevant review domains for Devil's Advocate (e.g. activating database transaction reviews for APIs, responsive UI checks for web apps).
+  - Typical testing patterns (e.g. Jest/Vitest for web, pytest/go test for backend, XCTest/Espresso for mobile).
+- **Overridability**: Overridden by explicit repository-local configuration.
+
+### Layer 4: Repository-Local Configuration (`.ai-engineering-loop/`)
+- **Authority**: Target repository checked-in or auto-initialized files.
+- **Scope**: Repository-specific ground truth:
+  - Exact test/lint/typecheck commands in `verification.md`.
+  - Layer definitions in `architecture.md`.
+  - Architectural constraints and forbidden patterns in `conventions.md`.
+  - Configured delivery adapter (DOT, GitHub, GitLab) in `adapter.md`.
+- **Auto-Discovery**: Automatically generated if missing via [Project Initialization](file:///Users/egagofur/Development/work/ai-engineering-loop/core/project-initialization.md).
+- **Overridability**: Overrides Layer 3 defaults for this specific codebase.
+
+### Layer 5: Task Contract
+- **Authority**: Current execution request / prompt.
+- **Scope**: Task-specific Acceptance Criteria (AC-1..N), out-of-scope boundaries, and temporary overrides.
+- **Overridability**: Scoped strictly to the active task run.
+
+---
+
+## 3. Precedence Resolution Algorithm
+
+When the engine executes a task, it resolves configuration keys using the following lookup order:
+
+```python
+def resolve_config_key(key: str, context: ExecutionContext) -> Any:
+    # 1. Task Contract (highest priority for task-scoped values)
+    if context.task_contract.has(key):
+        return context.task_contract.get(key)
+
+    # 2. Repository Local Configuration (.ai-engineering-loop/)
+    if context.repo_config.has(key):
+        return context.repo_config.get(key)
+
+    # 3. Project Type Profile (profiles/<type>.md)
+    if context.profile.has(key):
+        return context.profile.get(key)
+
+    # 4. Engineering Core Defaults
+    if context.core_defaults.has(key):
+        return context.core_defaults.get(key)
+
+    # 5. Global Environment Safety
+    return context.global_env.get(key)
+```
+
+---
+
+## 4. Conflict Resolution & Escalation Rules
+
+1. **Refinement vs Contradiction**:
+   - *Refinement (Allowed)*: Profile says "Run unit tests"; Repo config specifies `pnpm run test:unit`. $\rightarrow$ Valid refinement.
+   - *Contradiction (Escalate)*: Core requires deterministic verification; Task contract requests skipping tests to merge faster. $\rightarrow$ **Forbidden**. The engine rejects the override and flags a policy violation.
+2. **Unresolvable Contradictions**:
+   - If repository configuration directly contradicts an established platform invariant (e.g. a command requires root sudo or drops protected tables), the system halts and triggers [Human Escalation](file:///Users/egagofur/Development/work/ai-engineering-loop/core/escalation-policy.md).

package/core/context-impact-assessment.md

@@ -0,0 +1,127 @@
+# Context Impact Assessment Specification
+
+## 1. Overview & Core Philosophy
+
+In the AI Engineering Loop, project context (`.ai-engineering-loop/`) is a **Living Knowledge Base** that reflects the current engineering reality of the repository.
+
+However, performing an expensive full-repository re-analysis after every completed task introduces unnecessary overhead and latency. Most software changes (e.g. fixing a UI bug, tweaking validation logic, or adding a test) do **not** alter the project's architecture, conventions, or build commands.
+
+The **Context Impact Assessment** is a lightweight, evidence-based evaluation executed immediately after a task reaches a **Judge `PASS`** verdict, determining whether and how `.ai-engineering-loop/` should be updated before closing the session.
+
+```mermaid
+flowchart TD
+    JudgePass([Judge Agent: PASS Verdict]) --> Assess[Context Impact Assessment]
+    
+    Assess --> Level{Determine Impact Level}
+    
+    Level -->|NONE| Skip[No Context Update Required<br>Task Finished]
+    Level -->|TARGETED| Partial[Surgical Update of Affected Files<br>Update metadata.json Baseline]
+    Level -->|MAJOR| Full[Full Reconciliation Pass<br>Update metadata.json Baseline]
+    
+    Skip --> End([Session Complete])
+    Partial --> End
+    Full --> End
+```
+
+---
+
+## 2. The 3 Context Impact Levels
+
+```text
+┌─────────────────┬──────────────────────────────────────────┬─────────────────────────────┐
+│ Impact Level    │ Task Characteristics                     │ System Action               │
+├─────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
+│ NONE            │ Isolated bugfix, UI tweak, test-only,   │ NO-OP (Skip refresh)        │
+│ (80-90% tasks)  │ small refactor preserving architecture.  │                             │
+├─────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
+│ TARGETED        │ Manifest scripts changed, new module,    │ Surgically reconcile only   │
+│ (10-15% tasks)  │ new team invariant, new CI config.       │ affected files in context.  │
+├─────────────────┼──────────────────────────────────────────┼─────────────────────────────┤
+│ MAJOR           │ Framework migration, database redesign,  │ Full repository context     │
+│ (< 5% tasks)    │ monorepo restructuring, auth overhaul.   │ reconciliation pass.        │
+└─────────────────┴──────────────────────────────────────────┴─────────────────────────────┘
+```
+
+---
+
+## 3. Impact Level Classification Matrix
+
+### Level 1: `NONE` (No Action)
+- **Criteria**:
+  - The task diff only touches existing function bodies, templates, styles, or test files.
+  - Zero new external dependencies or build scripts introduced.
+  - Directory hierarchy and layer boundaries remain unchanged.
+- **Examples**:
+  - Fixing a typo or styling bug in `src/components/Button.tsx`.
+  - Fixing an off-by-one error in `src/utils/date.ts`.
+  - Adding edge-case unit tests to `user.service.spec.ts`.
+- **Action**: Output `Context Impact: NONE`. Do not modify `.ai-engineering-loop/`.
+
+---
+
+### Level 2: `TARGETED` (Surgical Reconciliation)
+- **Criteria**:
+  - A specific dimension of project knowledge has become stale due to the diff.
+- **Mapping by File / Diff Signal**:
+
+| Changed Area in Task Diff | Stale Context File | Targeted Action |
+|---|---|---|
+| `package.json` / `go.mod` scripts modified | `verification.md`, `config.md` | Update test/build/lint command entries |
+| New folder in `src/modules/` or `apps/` | `architecture.md` | Add module summary and boundary notes |
+| New global error class or lint rule added | `conventions.md` | Document new pattern or forbidden rule |
+| `.gitlab-ci.yml` / `.github/workflows` edited | `adapter.md` | Update CI/CD workflow references |
+
+- **Action**: Reconcile *only* the affected markdown file(s) and update `metadata.json` baseline.
+
+---
+
+### Level 3: `MAJOR` (Full Context Reconciliation)
+- **Criteria**:
+  - The diff introduces a paradigm shift in how the codebase compiles, runs, or organizes architecture.
+- **Examples**:
+  - Migrating from Next.js Pages Router to App Router.
+  - Converting a single repository into a Turborepo/pnpm monorepo.
+  - Migrating ORM from TypeORM to Prisma or replacing REST with tRPC.
+  - Introducing a complete OAuth2 / JWT authentication architecture.
+- **Action**: Execute full 5-pass reconciliation, update all relevant `.ai-engineering-loop/` files, and establish a new baseline in `metadata.json`.
+
+---
+
+## 4. Devil's Advocate & Judge Drift Interaction
+
+During task review, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) may discover that the codebase has drifted from the documented architecture:
+
+> *Example Review Finding*: "The implementation assumes `user-service` connects directly to Postgres, but the codebase has migrated to an asynchronous event queue in `src/events/`."
+
+### Triage Protocol:
+1. The **Devil's Advocate** flags the discrepancy in its Finding Ledger.
+2. The **Judge Agent** evaluates the finding:
+   - If `VALID`: The Judge flags an active architectural drift.
+   - Upon task completion, the Context Impact Assessment automatically triggers a `TARGETED` or `MAJOR` refresh of `architecture.md` to capture the new reality.
+   - If `INVALID` (e.g. reviewer hallucination), no context update occurs.
+
+---
+
+## 5. Output Reporting Protocol
+
+Every completed engineering run concludes with a **Context Impact Summary**:
+
+### Example: Impact Level NONE
+```text
+Project Context Assessment
+- Impact Level: NONE
+- Reason: Surgical bugfix in src/services/attendance.ts preserved existing architecture and commands.
+- Action: Context refresh SKIPPED (context is CURRENT).
+```
+
+### Example: Impact Level TARGETED
+```text
+Project Context Assessment
+- Impact Level: TARGETED
+- Reason: Added Redis client and caching layer in src/infrastructure/cache.ts.
+- Affected Context Files:
+  - architecture.md (added Cache Layer boundary)
+  - config.md (added Redis dependency)
+- Action: Surgically updated architecture.md and config.md.
+- Baseline: Updated to commit a1b2c3d.
+```

package/core/context-refresh-policy.md

@@ -0,0 +1,116 @@
+# Context Refresh & Living Baseline Policy
+
+## 1. Overview & Core Laws
+
+The **Context Refresh Policy** defines how the AI Engineering Loop maintains living synchronization between `.ai-engineering-loop/` and the underlying repository without unnecessary computation.
+
+### Three Fundamental Invariants:
+1. **Reconciliation, Not Destruction**: Refresh never deletes `.ai-engineering-loop/` or wipes manual developer notes. It reconciles existing context against current repository facts.
+2. **Progressive Cost**: Drift detection uses cheap signals (Level 0) before performing deeper inspections (Levels 1–3).
+3. **Strict Context Isolation**:
+   - **Project Context (`.ai-engineering-loop/`)**: Shared, living architectural rules and verification commands.
+   - **Task Context**: Ephemeral task contracts, specific diff scopes, and temporary session data.
+   - **Loop State**: Transient retry counters, test outputs, and finding signatures.
+   *Task execution histories and conversational chat transcripts are NEVER dumped into `.ai-engineering-loop/`.*
+
+---
+
+## 2. Context Baseline Metadata (`metadata.json`)
+
+To enable deterministic, instant drift checks without requiring a database, the `.ai-engineering-loop/` directory maintains a lightweight `metadata.json` baseline:
+
+```json
+{
+  "contextVersion": "1.0.0",
+  "generatedAt": "2026-08-25T10:00:00Z",
+  "repositoryRevision": "7f8b9a1c2d3e...",
+  "projectProfile": "backend-api",
+  "manifestChecksums": {
+    "package.json": "a3f5b2c1...",
+    "go.mod": "e9b8c7d6..."
+  },
+  "lastReconciliation": {
+    "timestamp": "2026-08-25T10:00:00Z",
+    "trigger": "init",
+    "impact": "INITIAL_BOOTSTRAP"
+  }
+}
+```
+
+---
+
+## 3. Progressive Multi-Level Drift Detection Hierarchy
+
+Drift detection ascends through four progressively detailed levels:
+
+```mermaid
+flowchart TD
+    Start([Check Context Freshness]) --> L0[Level 0: Cheap Signal Comparison<br>git rev-parse HEAD & manifest checksums]
+    
+    L0 -->|Match: Zero Diff| Current([Status: CURRENT<br>Cost: 0ms])
+    L0 -->|Mismatch: Change Detected| L1[Level 1: Inspect Touched Files<br>git diff --name-only baseline..HEAD]
+    
+    L1 -->|Only Non-Architectural Files| Current
+    L1 -->|Manifest or Boundary Files Touched| L2[Level 2: Targeted Context Analysis]
+    
+    L2 -->|Surgical Change| SurgReconcile[Surgically Update Affected Files]
+    L2 -->|Structural / Paradigm Shift| L3[Level 3: Full Context Reconciliation]
+    
+    SurgReconcile --> UpdateMeta[Update metadata.json Baseline] --> Done([Context Synchronized])
+    L3 --> UpdateMeta --> Done
+```
+
+### Level 0: Instant Cheap Signal Comparison (Cost: ~0ms)
+- Compare current `git rev-parse HEAD` and manifest hashes (`package.json`, `go.mod`, etc.) against `metadata.json`.
+- If identical $\rightarrow$ status is **`CURRENT`**. Stop immediately.
+
+### Level 1: Touched File Scope Inspection (Cost: ~50ms)
+- If HEAD has advanced (e.g. other developers merged commits), inspect touched file paths via `git diff --name-only <baseline>..HEAD`.
+- If all changed files are isolated application logic, styles, or tests (e.g. `src/views/Profile.vue`, `src/utils/math.ts`) $\rightarrow$ status is **`CURRENT`**.
+
+### Level 2: Targeted Context Analysis (Cost: ~200ms)
+- If manifests, top-level directory layouts, or CI workflows were touched, re-read those specific files and reconcile only the corresponding markdown files (`verification.md`, `architecture.md`, `adapter.md`).
+
+### Level 3: Full Repository Context Reconciliation (Cost: ~1-2s)
+- Triggered only when major structural shifts occur (e.g. monorepo workspace addition, framework migration). Re-runs full 5-pass discovery.
+
+---
+
+## 4. Pre-Task Drift Gate
+
+Before starting any task, the engine executes the Pre-Task Drift Gate:
+
+```text
+Load Project Context
+       ↓
+Level 0 / Level 1 Drift Check
+       ↓
+┌────────────────────────────────────────┐
+│ CURRENT                                │
+│ → Proceed directly to Goal Contract    │
+│                                        │
+│ STALE (Drift Detected)                 │
+│ → Reconcile affected context files     │
+│ → Update baseline metadata             │
+│ → Proceed to Goal Contract             │
+└────────────────────────────────────────┘
+```
+
+This guarantees that an AI agent never writes code using outdated build commands or obsolete architectural assumptions.
+
+---
+
+## 5. Scheduled Maintenance / Heartbeat
+
+- **Role**: A secondary safety net catching external repository modifications (e.g. external PRs merged without the loop).
+- **Protocol**: Executes Level 0/Level 1 drift detection periodically (e.g. every 12h or 24h).
+- **Rule**: If Level 0/1 detects no material changes, it **STOPS immediately**. It NEVER performs a full re-analysis simply because a timer fired.
+
+---
+
+## 6. Anti-Infinite-Loop Safeguard
+
+To prevent circular update loops (`Task -> Refresh -> Context Changes -> Refresh -> ...`):
+1. Every refresh operation concludes by updating `metadata.json` to the current repository revision (`repositoryRevision = git rev-parse HEAD`).
+2. Setting the new baseline guarantees that subsequent Level 0 checks evaluate to `CURRENT`.
+3. The refresh engine is strictly **idempotent**: running `refresh` multiple times on unchanged code produces 0 file modifications and terminates with *"Context is already current"*.

package/core/definition-of-done.md

@@ -0,0 +1,79 @@
+# Definition of Done (DoD) Specification
+
+## 1. Principle & Definition
+
+The **Definition of Done (DoD)** is the objective, non-negotiable threshold that must be satisfied before any task can be declared complete, merged, or handed off to downstream delivery pipelines.
+
+The core question answered by the DoD is not:
+> *"Does the agent believe it solved the problem?"*
+
+The DoD answers:
+> **"Has the system provided verifiable proof satisfying all technical and business criteria?"**
+
+---
+
+## 2. The 5 Pillars of Done
+
+To achieve a `DONE` status, an engineering task must satisfy all five pillars without exception:
+
+```mermaid
+flowchart LR
+    P1[1. Contract Satisfaction] --> DoD{DEFINITION OF DONE}
+    P2[2. Deterministic Verification] --> DoD
+    P3[3. Code & Diff Quality] --> DoD
+    P4[4. Adversarial Consensus] --> DoD
+    P5[5. Judge Certified PASS] --> DoD
+```
+
+### Pillar 1: Contract Satisfaction
+- 100% of Acceptance Criteria defined in the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md) are demonstrably met.
+- Zero out-of-scope files or unauthorized modules were modified.
+- All technical constraints (e.g. backward compatibility, no unapproved dependencies) are preserved.
+
+### Pillar 2: Deterministic Verification
+- **Unit & Regression Tests**: 100% passing tests (0 failures, 0 errors, 0 unresolved broken suites).
+- **Static Typing / Compilation**: 0 type errors (e.g. `tsc --noEmit` exits with `0`).
+- **Linting & Code Formatting**: 0 lint errors on modified files.
+- **Build / Packaging**: Project builds successfully without warnings treated as errors.
+
+### Pillar 3: Code & Diff Quality
+- **Surgical Diff**: Smallest coherent diff that completely resolves the issue.
+- **Architecture Preservation**: Adheres to existing repository patterns, naming conventions, and layer boundaries.
+- **Zero Placeholders**: No stubbed functions, empty `catch` blocks, speculative `TODO` comments, or orphaned dead code.
+- **Null & Boundary Safety**: Explicit handling of `null`, `undefined`, empty collections, and error paths.
+
+### Pillar 4: Adversarial Consensus
+- Independent [Devil's Advocate Review](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) has been executed across all 6 core review domains.
+- **Zero Unresolved Blocking Findings**: No open `SEV-1 (Critical)` or `SEV-2 (High)` findings.
+- **Evidence-Based Triage**: Every raised finding has been formally triaged with reproducible evidence as `VALID` (and resolved in code) or `INVALID` (with technical proof of why it is a false positive).
+
+### Pillar 5: Judge Certified PASS
+- The [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) has evaluated the complete execution trace, verified the evidence, confirmed no-progress limits were not violated, and issued a signed `PASS` verdict.
+
+---
+
+## 3. DoD Verification Checklist
+
+Every iteration concluding in a `PASS` verdict must produce a DoD verification table:
+
+| Checklist Item | Required Standard | Status | Evidence Reference |
+|---|---|:---:|---|
+| Acceptance Criteria AC-1..N | 100% satisfied | ✅ | Unit test file & assertion links |
+| Test Suite Execution | 0 failures, 0 errors | ✅ | Test command output log |
+| Typecheck / Compiler | Exit code 0 | ✅ | Typecheck log |
+| Linter | 0 errors on diff | ✅ | Linter log |
+| Build Check | Exit code 0 | ✅ | Build command log |
+| Adversarial Review | Completed across 6 topics | ✅ | Review findings artifact |
+| Blocking Findings (Sev 1/2)| 0 unresolved | ✅ | Triage summary table |
+| Judge Verdict | PASS | ✅ | Judge evaluation report |
+
+---
+
+## 4. Rejection Criteria
+
+An engineering run MUST be rejected and flagged as `FAIL` or `BLOCKED` if any of the following occur:
+
+1. **Unverified Claims**: The agent states that a test passed or feature works without providing command outputs or test code.
+2. **Post-Hoc Goal Shifting**: Modifying Acceptance Criteria to match buggy behavior instead of fixing the bug.
+3. **Suppressed Errors**: Adding `@ts-ignore`, `eslint-disable`, empty catch blocks, or skipping tests to force a green build.
+4. **Unresolved Critical Findings**: Attempting to declare completion while a `SEV-1` or `SEV-2` finding from the Devil's Advocate remains open.

package/core/escalation-policy.md

@@ -0,0 +1,99 @@
+# Escalation Policy Specification
+
+## 1. Principle & Core Philosophy
+
+The primary objective of the AI Engineering Loop is:
+
+> **Reliable Autonomy, NOT Maximum Autonomy at All Costs.**
+
+An autonomous agent that attempts to push through deep architectural ambiguities, unresolvable test regressions, or unverified business rules creates significant technical debt and risk.
+
+The **Escalation Policy** defines deterministic thresholds where autonomous iteration MUST immediately halt and hand off control to a human engineer with an actionable, evidence-backed report.
+
+---
+
+## 2. Mandatory Escalation Triggers
+
+An agent MUST trigger Human Escalation when any of the following conditions are met:
+
+```mermaid
+flowchart TD
+    E1[1. Max Iterations Reached] --> Escalate([TRIGGER HUMAN ESCALATION])
+    E2[2. No-Progress / Stalled Loop Detected] --> Escalate
+    E3[3. Contradictory / Impossible Requirements] --> Escalate
+    E4[4. Destructive / High-Risk Operations] --> Escalate
+    E5[5. Unresolvable Agent Disagreement] --> Escalate
+    E6[6. Irreproducible Failure] --> Escalate
+```
+
+### Trigger 1: Maximum Iterations Reached
+- **Condition**: The system has completed `MAX_ITERATIONS` (default: 3) and unresolved blocking findings (`SEV-1` or `SEV-2`) still persist.
+- **Rationale**: Prolonged retries indicate either an incorrect fundamental strategy or a hidden architectural obstacle.
+
+### Trigger 2: No-Progress / Stagnation Detected
+- **Condition**: Two consecutive iterations produce identical or semantically equivalent finding signatures without demonstrable code convergence (see [No-Progress Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/no-progress-policy.md)).
+- **Rationale**: Prevents thrashing where the agent modifies code without resolving the underlying flaw.
+
+### Trigger 3: Contradictory or Inconsistent Acceptance Criteria
+- **Condition**: Satisfying Criterion A mathematically or logically violates Criterion B, or the Goal Contract contradicts an established database or platform invariant.
+- **Rationale**: Agents must not invent business compromises without stakeholder input.
+
+### Trigger 4: High-Risk / Destructive Operations
+- **Condition**: The fix requires dropping production database columns, bypassing authentication/authorization layers, modifying global build pipelines, or upgrading major core dependencies.
+- **Rationale**: High blast-radius architectural changes require human authorization.
+
+### Trigger 5: Irreproducible Failure
+- **Condition**: The agent is unable to reproduce the reported bug deterministically after exhaustive environment inspection and logging.
+- **Rationale**: Prevents speculative fixes for phantom issues.
+
+### Trigger 6: Unresolvable Triad Disagreement
+- **Condition**: The Maker Agent and Devil's Advocate Agent present mutually incompatible, evidence-backed arguments regarding architecture or domain rules, and the Judge cannot definitively resolve it from existing codebase artifacts.
+- **Rationale**: Domain-level business tradeoffs belong to product owners and human engineers.
+
+---
+
+## 3. Human Escalation Report Protocol
+
+When escalating, the agent must NEVER output a generic message like *"I am stuck."*
+
+Instead, it must render an **Actionable Escalation Report** following this structured template:
+
+```markdown
+# ⚠️ Human Escalation Triggered
+
+## 1. Escalation Reason
+**Trigger**: [e.g. Trigger 2: No-Progress / Stalled Loop Detected]
+**Iteration**: [e.g. Iteration 3 of 3]
+
+## 2. Summary of Attempted Solutions
+- **Iteration 1**: [What was tried, what failed]
+- **Iteration 2**: [What was modified, what remained unresolved]
+- **Iteration 3**: [Current diff and exact blocker]
+
+## 3. Core Technical Blocker
+[Precise explanation of why the agent cannot proceed autonomously. Include code locations, conflicting constraints, or missing domain knowledge.]
+
+## 4. Active Findings Ledger
+| Finding ID | Severity | Category | Location | State | Summary |
+|---|---|---|---|---|---|
+| SEC-001 | HIGH | Security | `src/auth/guard.ts:42` | TRIAGED_VALID | IDOR risk when tenant ID is omitted |
+
+## 5. Specific Decision Required from Human
+[State 2-3 concrete options for the human to choose from, or a focused question]:
+- **Option A**: [Description of architectural option A and tradeoffs]
+- **Option B**: [Description of architectural option B and tradeoffs]
+
+## 6. Current Workspace State
+- **Branch**: `<current-working-branch>`
+- **Uncommitted Changes**: [Clean / Stashed / In-flight diff]
+- **Deterministic Test Status**: [Passing / Failing with command logs]
+```
+
+---
+
+## 4. Resumption Protocol
+
+Once the human engineer provides guidance or amends the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md):
+1. The iteration counter is reset: $K \leftarrow 1$.
+2. The agent incorporates the human's decision into the Goal Contract constraints.
+3. The loop resumes at the **Maker Agent** phase with clean validation.

package/core/goal-contract.md

@@ -0,0 +1,88 @@
+# Goal Contract Specification
+
+## 1. Purpose & Core Philosophy
+
+The **Goal Contract** is the immutable anchor of the AI Engineering Loop. An autonomous coding agent must never begin implementation on ambiguous prompts, loose descriptions, or conversational requests without first formalizing an explicit contract.
+
+The Goal Contract establishes:
+- **What** problem is being solved.
+- **Why** it matters to the business or user lifecycle.
+- **How** success is measured deterministically.
+- **Where** the boundaries are set (preventing scope creep).
+- **When** the work is strictly considered complete.
+
+---
+
+## 2. Mandatory Contract Schema
+
+Every Goal Contract MUST adhere to the following schema in Markdown or structured YAML:
+
+```markdown
+# Goal Contract: [Short Title / Feature / Bugfix ID]
+
+## 1. Objective
+[Concise 1-2 sentence description of the technical deliverable.]
+
+## 2. Business Outcome & User Lifecycle Impact
+[Explain what changes for the real-world actor (e.g. Employee, Admin, Customer, System). Describe the before/after lifecycle state transition.]
+
+## 3. Acceptance Criteria (AC)
+- [ ] AC-1: [Exact, testable statement with expected outcome]
+- [ ] AC-2: [Exact, testable statement with expected outcome]
+- [ ] AC-3: [Edge case or boundary behavior explicitly specified]
+
+## 4. Technical Constraints
+- [Architecture]: [Preserve existing patterns, layer boundaries, dependency conventions]
+- [API / Schema]: [No breaking changes to existing contracts or database schemas]
+- [Scope of Diff]: [Smallest coherent change; zero speculative abstractions; zero dead code]
+- [Dependencies]: [Do not introduce external packages without explicit justification]
+
+## 5. Out of Scope
+- [Explicitly list what the agent MUST NOT touch or refactor during this task]
+
+## 6. Verification Requirements
+- **Unit Tests**: [Target files, boundary cases, and minimum expected coverage]
+- **Static Analysis**: [Typecheck command, linter command, schema validation command]
+- **Build / Packaging**: [Build command or bundling check]
+- **Runtime / Integration**: [Manual smoke test steps or integration test command]
+
+## 7. Definition of Done (DoD)
+- [ ] All Acceptance Criteria (AC-1 through AC-N) verified with automated tests.
+- [ ] 100% pass on all deterministic verification commands (0 errors, 0 warnings where enforced).
+- [ ] Independent Devil's Advocate review completed with 0 unresolved blocking findings (SEV-1 / SEV-2).
+- [ ] All review findings triaged with evidence (VALID, INVALID, UNCERTAIN).
+- [ ] Judge Agent issues a formal PASS verdict.
+```
+
+---
+
+## 3. Contract Lifecycle & Immutability Rules
+
+1. **Pre-Implementation Freezing**:
+   - The Goal Contract is authored and frozen *before* any production code edits.
+   - If the task is ambiguous, the agent must refine the contract with the user before touching code.
+2. **Immutability During Iteration**:
+   - Neither the Maker Agent nor the Devil's Advocate Agent may alter Acceptance Criteria during an iteration loop to make tests pass or bypass critique.
+3. **Contract Amendments**:
+   - If during implementation a fundamental contradiction or impossible requirement is discovered, the agent must trigger **Human Escalation**. Only a human user may amend the Goal Contract.
+
+---
+
+## 4. Verification Mapping
+
+Every single item listed under `Acceptance Criteria` must map to at least one concrete verification method:
+
+| Acceptance Criterion | Primary Verification | Fallback Verification |
+|---|---|---|
+| Logic / Computation / Parsing | Automated Unit Test | Deterministic script execution |
+| Type Safety / Schema Integrity | Compiler / Typechecker | Schema validator (`tsc`, `zod`, etc.) |
+| Regression Protection | Existing Test Suite | End-to-end integration test |
+| Visual / Interface State | Component / Snapshot / E2E Test | Exact DOM / State inspection |
+
+---
+
+## 5. Anti-Patterns to Avoid
+
+- **The Vague Contract**: "Make authentication work better." (Invalid: lacks testable acceptance criteria).
+- **The Missing Constraint**: Failing to declare out-of-scope files, leading to arbitrary refactoring of adjacent legacy modules.
+- **The Self-Serving Goal**: Modifying acceptance criteria post-hoc when tests fail rather than fixing the underlying implementation.