ai-engineering-loop 1.0.0

package/examples/mobile-app/offline-sync-queue/review-findings.md

@@ -0,0 +1,30 @@
+# Adversarial Review Findings: Offline Sync Queue
+
+## 1. Review Summary
+- **Reviewer**: Devil's Advocate Agent (Profile: `mobile-app`)
+- **Active Review Domains**: Offline Sync, Lifecycle, Permissions, Battery/Network Hygiene
+- **Total Findings**: 1
+- **Blocking (SEV-1/2)**: 1
+
+---
+
+## 2. Findings Ledger
+
+### Finding ERR-001: Missing unhandled SQLite disk full exception handling
+- **Severity**: `HIGH` (SEV-2)
+- **Category**: `Error Handling & Persistence`
+- **Location**: `lib/core/sync/sqlite_mutation_store.dart:45-56`
+- **Evidence**:
+  ```dart
+  await _db.insert('mutation_queue', item.toMap());
+  ```
+- **Problem**:
+  If the device filesystem runs out of storage space (common on low-end inspection tablets), `_db.insert()` throws an unhandled `DatabaseException` that bubbles up and crashes the UI layer, preventing the user from navigating or seeing an alert.
+- **Impact**:
+  App crash on disk full errors with uninformative logs.
+- **Recommendation**:
+  Wrap write operations in domain-specific `StorageException` handling and surface a user-friendly "Device Storage Low" snackbar notification.
+- **Confidence**: `HIGH`
+- **Status**: `TRIAGED_VALID`
+- **Resolution**:
+  Maker Agent wrapped repository writes in `try/catch (DatabaseException)` with fallback error telemetry and added unit test `should throw StorageFullException gracefully when disk is full`.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ai-engineering-loop",
+  "version": "1.0.0",
+  "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
+  "main": "bin/ai-engineering-loop.js",
+  "bin": {
+    "ai-engineering-loop": "bin/ai-engineering-loop.js"
+  },
+  "scripts": {
+    "init": "node bin/ai-engineering-loop.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egagofur/ai-engineering-loop.git"
+  },
+  "keywords": [
+    "ai-agents",
+    "agentic-workflow",
+    "software-engineering",
+    "devils-advocate",
+    "verification",
+    "autonomous-agents",
+    "antigravity"
+  ],
+  "author": "Ega Gofur",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/egagofur/ai-engineering-loop/issues"
+  },
+  "homepage": "https://github.com/egagofur/ai-engineering-loop#readme"
+}

package/policies/discovery-safety-policy.md

@@ -0,0 +1,51 @@
+# Discovery Safety Policy Specification
+
+## 1. Principle & Core Rule
+
+Project initialization and context discovery is a **read-mostly, non-destructive operation**.
+
+Its sole objective is to inspect repository topology, manifests, and architecture to generate or update `.ai-engineering-loop/`. It must never alter production application code or compromise security.
+
+---
+
+## 2. Strictly Prohibited Actions During Discovery
+
+An agent executing project initialization MUST NEVER:
+
+```mermaid
+flowchart TD
+    Init[Discovery & Initialization Phase] --> Prohibited[STRICTLY PROHIBITED ACTIONS]
+    
+    Prohibited --> P1[1. Secret Leakage: Never inspect .env, tokens, credentials, private keys]
+    Prohibited --> P2[2. Code Mutation: Never modify application code, config, or tests]
+    Prohibited --> P3[3. File Deletion: Never delete any files in the repository]
+    Prohibited --> P4[4. Git Mutations: Never commit, create branches, or push during init]
+    Prohibited --> P5[5. Disruptive Commands: Never run database migrations or destructive scripts]
+```
+
+### 1. Secret & Credential Inspection
+- **Prohibited Files**: `.env`, `.env.local`, `.env.production`, `id_rsa`, `*.pem`, `*.key`, `credentials.json`, `secrets.yaml`, `.netrc`.
+- **Permitted Files**: `.env.example`, `.env.sample`, `config.example.json` (template files containing no real secret values).
+- **Rule**: If an agent inadvertently reads a file containing API keys or database passwords, it is **strictly forbidden** from copying or referencing those values in `.ai-engineering-loop/`.
+
+### 2. Application Code Mutation
+- The agent must not edit `src/`, `apps/`, `packages/`, or any configuration files outside of `.ai-engineering-loop/` during the initialization stage.
+
+### 3. File Deletion
+- The agent must not delete any files, directories, or caches during discovery.
+
+### 4. Git Mutations
+- The agent must not execute `git commit`, `git checkout -b`, `git push`, or `git reset` during initialization. Git commands are strictly restricted to read-only inspection (`git status`, `git log -n 5`, `git remote -v`).
+
+### 5. Disruptive Commands
+- The agent must not execute live database migrations (`prisma migrate dev`, `alembic upgrade head`) or destructive test cleanup scripts during discovery.
+
+---
+
+## 3. Permitted Actions During Discovery
+
+The only actions authorized during project initialization are:
+
+1. **Read-Only Inspection**: Reading repository directories, file trees, package manifests, configuration files, and documentation.
+2. **Writing Context Files**: Creating or updating markdown files strictly within `<workspace-root>/.ai-engineering-loop/`.
+3. **Informational Git Queries**: Running `git status`, `git remote -v`, and `git log -n 5 --stat`.

package/policies/evidence-policy.md

@@ -0,0 +1,70 @@
+# Evidence Policy Specification
+
+## 1. Principle & Core Law
+
+The foundational premise of the AI Engineering Loop is:
+
+> **Claims without verifiable evidence are invalid.**
+
+An agent may not state that code is functional, bug-free, optimized, or ready for merge based on assumption or conversational confidence. Every positive and negative claim throughout the loop must be substantiated by demonstrable proof.
+
+---
+
+## 2. The Evidence Hierarchy
+
+Evidence is ranked in order of reliability and truth value:
+
+```mermaid
+flowchart TD
+    E1[Level 1: Deterministic Machine Execution<br>Unit tests, CLI exit codes, compiler output]
+    E2[Level 2: Concrete Codebase Artifacts<br>Actual file contents, git commit history, schema files]
+    E3[Level 3: Adversarial Code Diffs<br>Exact before/after reproduction snippets]
+    E4[Level 4: Theoretical / Analytical Deduction<br>Reasoning through architectural implications]
+    E5[Level 5: Unsupported Assertion<br>'Looks correct', 'Should work fine' - REJECTED]
+
+    E1 --> E2 --> E3 --> E4 -.-> E5
+```
+
+### Level 1: Deterministic Machine Execution (Highest Proof)
+- Automated unit/integration test results with full test names, assertions, and exit codes.
+- Compiler / typechecker outputs (`tsc --noEmit`, `cargo check`).
+- Linter execution reports with zero errors.
+- Real-time build artifacts and exit statuses.
+
+### Level 2: Concrete Codebase Artifacts
+- Direct citations of existing repository files, functions, database schemas, and configuration keys with explicit file paths and line ranges.
+- Git commit logs (`git log -n 5 -p`) and git blame history proving past behavior.
+
+### Level 3: Adversarial Code Diffs
+- Concrete code diffs demonstrating an edge case or proposing a surgical fix.
+
+### Level 4: Analytical Deduction
+- Structured logical deduction mapping user workflows to code paths. Acceptable for brainstorming and initial analysis, but must be validated by Level 1 or Level 2 before completion.
+
+### Level 5: Unsupported Assertions (Strictly Prohibited)
+- Vague statements of confidence (*"I am confident this fixes the problem"*).
+- Claiming a test passed without running the command.
+- Assuming an API exists without checking `node_modules` or codebase imports.
+- **Action**: The Judge Agent automatically invalidates any finding or completion claim backed only by Level 5 assertions.
+
+---
+
+## 3. Evidence Requirements for Common Agent Claims
+
+| Claim Type | Mandatory Evidence Required | Prohibited Substitute |
+|---|---|---|
+| **"Bug is fixed"** | Reproducing test that previously failed now passes with exit code 0. | "The logic was corrected." |
+| **"No regressions"** | Full test suite execution log showing 0 failures. | "I only touched a single function." |
+| **"Type safe"** | `tsc --noEmit` / compiler run output with 0 errors. | "I added type annotations." |
+| **"Review finding is invalid (Halu)"** | File path & line showing the suggested API does not exist or behavior is intentional. | "I disagree with the reviewer." |
+| **"Acceptance criteria AC-X met"** | Test function name & assertion specifically targeting AC-X. | "Implemented according to spec." |
+
+---
+
+## 4. Evidentiary Audit Trail
+
+Every artifact created during the engineering loop (Goal Contract, Maker Log, Review Findings, Judge Verdict) must maintain an unbroken chain of evidence:
+
+1. **Exact Commands Run**: Included in verbatim code blocks.
+2. **Standard Output / Error Logs**: Verbatim output snippets without truncation of error counts.
+3. **Traceable File Links**: Every cited file must use clickable format (`file:///path/to/file#L1-L10`).

package/policies/finding-policy.md

@@ -0,0 +1,102 @@
+# Finding Policy Specification
+
+## 1. Purpose
+
+The **Finding Policy** defines the standardized schema, severity definitions, categories, and lifecycle states for all issues identified by review agents (such as the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) or external review bots).
+
+A standardized finding schema ensures that:
+1. Every criticism is actionable, localized, and backed by evidence.
+2. Review findings can be parsed, hashed, and tracked across autonomous iterations.
+3. The [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) can evaluate findings objectively without subjective ambiguity.
+
+---
+
+## 2. Standardized Finding Schema
+
+Every finding MUST be structured according to the following specification:
+
+```yaml
+id: "<CATEGORY_PREFIX>-<3_DIGIT_NUMBER>" # e.g. COR-001, SEC-002, PERF-001
+title: "<Short, descriptive summary of the problem>"
+severity: "<CRITICAL | HIGH | MEDIUM | LOW | INFO>"
+category: "<Correctness | ErrorHandling | Security | Concurrency | Performance | Maintainability | TestingGaps>"
+location:
+  file: "<Relative file path>"
+  startLine: <Integer>
+  endLine: <Integer>
+evidence: "<Exact code snippet, command output, or trace exhibiting the flaw>"
+problem: "<Detailed technical explanation of what is wrong>"
+impact: "<Concrete operational, business, or runtime consequence>"
+recommendation: "<Actionable suggestion and concrete code diff showing the fix>"
+confidence: "<HIGH | MEDIUM | LOW>"
+status: "<NEW | TRIAGED_VALID | TRIAGED_INVALID | TRIAGED_UNCERTAIN | RESOLVED | VERIFIED>"
+triageReason: "<Required when status is TRIAGED_INVALID or TRIAGED_UNCERTAIN>"
+```
+
+---
+
+## 3. Severity Matrix & Definitions
+
+| Severity Level | Definition | Impact on Build / Loop |
+|---|---|---|
+| **`CRITICAL` (SEV-1)** | Complete system crash, remote code execution, severe data corruption, authentication bypass, or massive data loss. | **BLOCKING**: Hard block. Must be resolved immediately; cannot pass DoD. |
+| **`HIGH` (SEV-2)** | Core business logic defect, unhandled null exception on primary user path, IDOR/authorization gap, or significant performance regression. | **BLOCKING**: Must be resolved before `PASS` verdict. |
+| **`MEDIUM` (SEV-3)** | Edge-case logic failure, missing error telemetry, suboptimal query with limited dataset, or unhandled rare boundary condition. | **NON-BLOCKING**: Can pass DoD if documented in backlog, unless directly violating an Acceptance Criterion. |
+| **`LOW` (SEV-4)** | Minor maintainability issue, non-critical testing gap, minor code duplication, or naming ambiguity. | **ADVISORY**: Does not block completion. |
+| **`INFO` (SEV-5)** | Informational observation, architectural note, or praise for a well-designed pattern. | **INFORMATIONAL**: No action required. |
+
+---
+
+## 4. Review Categories
+
+Findings are categorized under one of the 7 standard domains:
+
+1. **`Correctness` (`COR`)**: Functional bugs, logic errors, type mismatches, inverted conditionals, timezone bugs, calculation errors.
+2. **`ErrorHandling` (`ERR`)**: Swallowed errors, unhandled rejections, missing fallbacks, crashing async boundaries.
+3. **`Security` (`SEC`)**: Injection, broken auth/access control, secret exposure, sensitive data logging, unsanitized inputs.
+4. **`Concurrency` (`CONC`)**: Race conditions, un-synchronized shared memory, non-atomic database operations, thread safety issues.
+5. **`Performance` (`PERF`)**: N+1 queries, memory leaks, unbounded array loops, unindexed filters, heavy synchronous blocking operations.
+6. **`Maintainability` (`MAINT`)**: High coupling, breaking existing architecture, anti-patterns, dead code, circular dependencies.
+7. **`TestingGaps` (`TEST`)**: Untested boundary conditions, weak/tautological assertions, missing negative test cases.
+
+---
+
+## 5. Finding Status & Validity Rules
+
+Review findings are hypotheses, not absolute truths. Every finding exists in one of the following states:
+
+- **`NEW`**: Initial discovery by reviewer.
+- **`TRIAGED_VALID`**: Author and Judge confirm that the defect is real and violates technical or contract requirements. Must be fixed by Maker.
+- **`TRIAGED_INVALID` (False Positive / "Halu")**: Author demonstrates with evidence that the reviewer's concern is factually incorrect, based on an API that does not exist, or flags intentional/designed behavior.
+- **`TRIAGED_UNCERTAIN`**: Ambiguous requirement where the codebase documentation is silent or contradictory. Triggers escalation.
+- **`RESOLVED`**: Maker has applied code fix and passing test suite.
+- **`VERIFIED`**: Devil's Advocate and Judge re-evaluated and confirmed the issue is fully solved.
+
+---
+
+## 6. Concrete Example
+
+```yaml
+id: "COR-001"
+title: "Unsafe timezone conversion in attendance clock-in calculation"
+severity: "HIGH"
+category: "Correctness"
+location:
+  file: "src/server/attendance/utils/calculate-duration.ts"
+  startLine: 28
+  endLine: 34
+evidence: |
+  const checkInHour = new Date(record.clockIn).getHours();
+problem: |
+  Using Date.prototype.getHours() extracts the local server timezone hour instead of converting to the employee's designated timezone (e.g. Asia/Jakarta).
+impact: |
+  Employees clocking in between 00:00 and 07:00 UTC will be marked as late or absent depending on the server hosting region.
+recommendation: |
+  Use timezone-aware date parsing with dayjs/date-fns-tz:
+  ```diff
+  - const checkInHour = new Date(record.clockIn).getHours();
+  + const checkInHour = dayjs(record.clockIn).tz(userTimezone).hour();
+  ```
+confidence: "HIGH"
+status: "TRIAGED_VALID"
+```

package/policies/no-progress-policy.md

@@ -0,0 +1,92 @@
+# No-Progress Policy Specification
+
+## 1. Overview & Objective
+
+A major risk in autonomous AI agent loops is **thrashing (stagnation)**: the agent modifies code repeatedly across iterations without actually resolving the underlying defect, oscillating between two broken states, or generating the same unresolved findings repeatedly.
+
+The **No-Progress Policy** defines an algorithmic mechanism to detect stagnation early and halt the loop with a [Human Escalation](file:///Users/egagofur/Development/work/ai-engineering-loop/core/escalation-policy.md) rather than wasting tokens and computational cycles.
+
+```mermaid
+flowchart LR
+    Iter1[Iteration 1: Finding A] --> Iter2[Iteration 2: Finding A]
+    Iter2 --> Detect{No-Progress Detector}
+    Detect -->|Signatures Match & No Code Progress| Halt([ABORT LOOP ──▶ ESCALATE])
+    Detect -->|Demonstrated Progress / New Resolved State| Continue([CONTINUE LOOP])
+```
+
+---
+
+## 2. Finding Signature Hashing
+
+To detect recurring findings objectively across iterations, each active finding is assigned a **Finding Signature**:
+
+$$\text{Signature} = \text{Hash}\Big(\text{Category} + \text{File Location} + \text{Core Problem Concept}\Big)$$
+
+### Signature Formula Components:
+1. **Category**: One of `Correctness`, `Security`, `ErrorHandling`, etc.
+2. **Normalized Location**: File path and functional block (e.g. `src/server/attendance/service.ts:calculateDuration`).
+3. **Core Issue Key**: Normalized problem keywords (e.g. `timezone-conversion-utc`, `null-pointer-overtime-note`, `missing-auth-tenant-id`).
+
+---
+
+## 3. Stagnation Detection Criteria
+
+Stagnation is detected if any of the following rules evaluate to `TRUE`:
+
+### Criterion 1: Identical Unresolved Finding Across 2 Consecutive Iterations
+- If Iteration $K$ produces an unresolved blocking finding with the exact same Signature as Iteration $K-1$, AND the Maker Agent's diff did not change the underlying logic block.
+
+### Criterion 2: Oscillating Diffs (Ping-Pong State)
+- If the diff generated in Iteration $K$ reverts the codebase back to the state of Iteration $K-2$.
+
+### Criterion 3: Persistent Deterministic Failure
+- If the exact same unit test or compiler error fails in Iteration $K$ after the Maker Agent attempted a fix in Iteration $K-1$.
+
+### Criterion 4: Scope Divergence / Thrashing
+- If the Maker Agent modifies more than $3\times$ the number of lines or files compared to Iteration 1 without resolving the original Acceptance Criteria (indicating uncontrolled thrashing).
+
+---
+
+## 4. Operational Algorithm
+
+```python
+def check_stagnation(
+    current_iteration: int,
+    iteration_history: list[IterationRecord]
+) -> tuple[bool, str]:
+    if current_iteration < 2:
+        return False, "Initial iteration"
+
+    prev_record = iteration_history[current_iteration - 2]
+    curr_record = iteration_history[current_iteration - 1]
+
+    # Check 1: Recurring blocking finding signatures
+    prev_blocking = {f.signature for f in prev_record.unresolved_blocking_findings}
+    curr_blocking = {f.signature for f in curr_record.unresolved_blocking_findings}
+
+    recurring = prev_blocking.intersection(curr_blocking)
+    if recurring and curr_record.diff_hash == prev_record.diff_hash:
+        return True, f"Identical unresolved findings {recurring} with no effective diff progress"
+
+    # Check 2: Ping-Pong reversion
+    if current_iteration >= 3:
+        two_back_record = iteration_history[current_iteration - 3]
+        if curr_record.diff_hash == two_back_record.diff_hash:
+            return True, "Oscillating diff detected (reverted to state from 2 iterations ago)"
+
+    # Check 3: Identical deterministic failure
+    if (curr_record.deterministic_errors == prev_record.deterministic_errors and 
+        len(curr_record.deterministic_errors) > 0):
+        return True, f"Deterministic check failed with identical errors across iterations: {curr_record.deterministic_errors}"
+
+    return False, "Progress verified"
+```
+
+---
+
+## 5. Escalation Action
+
+When `check_stagnation` returns `True`:
+1. The Judge Agent immediately sets the verdict to **`ESCALATE`**.
+2. Autonomous iteration stops.
+3. The agent generates the standardized [Human Escalation Report](file:///Users/egagofur/Development/work/ai-engineering-loop/core/escalation-policy.md) highlighting the recurring signature and exact blocking contradiction.

package/profiles/README.md

@@ -0,0 +1,42 @@
+# Project Profiles Specification
+
+## 1. Purpose & Core Concept
+
+A **Project Profile** describes the engineering characteristics, verification expectations, common risk areas, and active review domains of a broad software archetype without modifying the generic core engineering loop.
+
+```mermaid
+flowchart TD
+    Core[AI Engineering Loop Core] --> Selector{Resolve Project Profile}
+    
+    Selector --> P1[profiles/web-app.md]
+    Selector --> P2[profiles/backend-api.md]
+    Selector --> P3[profiles/mobile-app.md]
+    Selector --> P4[profiles/library.md]
+    Selector --> P5[profiles/monorepo.md]
+    
+    P1 & P2 & P3 & P4 & P5 --> CustomContext[Contextualized Maker, Reviewer & Verifier]
+```
+
+---
+
+## 2. Standard Profile Catalog
+
+| Profile | Target Archetype | Primary Verification Focus | Active Review Domains |
+|---|---|---|---|
+| **[`web-app`](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/web-app.md)** | Single-Page Apps, SSR/SSG websites, Admin Portals | DOM rendering, browser responsiveness, bundle size, CSS/tokens | Responsive layout, accessibility (a11y), client state, Core Web Vitals |
+| **[`backend-api`](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/backend-api.md)** | REST / GraphQL / gRPC Microservices, Background Workers | Unit tests, database migrations, schema contracts | Auth/Authz, SQL injection, concurrency, transactions, API contracts |
+| **[`mobile-app`](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/mobile-app.md)** | iOS, Android, React Native, Flutter | Platform builds, simulator smoke tests, widget tests | Offline sync, device permissions, lifecycle transitions, network resilience |
+| **[`library`](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/library.md)** | Reusable SDKs, packages, shared utilities | Broad runtime compatibility, zero external dependencies | Public API stability, semver breaking changes, bundle tree-shaking |
+| **[`monorepo`](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/monorepo.md)** | Turborepo, Nx, Lerna, Yarn/pnpm Workspaces | Workspace scope tests, affected package compilation | Cross-package boundaries, circular dependencies, dependency isolation |
+
+---
+
+## 3. Profile Discovery & Binding
+
+1. **Explicit Binding**: Declared in `<repo>/.ai-engineering-loop/config.md` via `project_profile: <name>`.
+2. **Implicit Auto-Detection**: If `.ai-engineering-loop/` is absent, the engine inspects repository manifest files:
+   - `flutter.yaml` / `ios/` / `android/` $\rightarrow$ `mobile-app`
+   - `turbo.json` / `nx.json` / `pnpm-workspace.yaml` $\rightarrow$ `monorepo`
+   - `next.config.js` / `vite.config.ts` / `index.html` $\rightarrow$ `web-app`
+   - `Dockerfile` / `go.mod` / `requirements.txt` $\rightarrow$ `backend-api`
+   - `rollup.config.js` / `tsup.config.ts` / `"main": "dist/..."` $\rightarrow$ `library`

package/profiles/backend-api.md

@@ -0,0 +1,64 @@
+# Project Profile: `backend-api`
+
+## 1. Profile Definition
+
+- **Archetype**: Backend Services, REST / tRPC / GraphQL / gRPC APIs, Microservices, Background Workers (Node.js/TypeScript, Go, Python, Java, Rust, Elixir).
+- **Core Environment**: Server runtimes, databases (PostgreSQL, MySQL, MongoDB, Redis), message queues (Kafka, RabbitMQ), containerized infrastructure.
+
+---
+
+## 2. Engineering & Architecture Characteristics
+
+- **Layered Clean Architecture**: Strict boundaries between Transport/Controllers $\rightarrow$ Domain Services $\rightarrow$ Data Repositories $\rightarrow$ Infrastructure.
+- **Data Integrity & ACID**: Explicit transaction boundaries for multi-table mutations. Zero partial database writes on mid-operation failures.
+- **Idempotency**: Critical endpoints (e.g. payment, billing, order placement) must implement idempotent processing via unique request tokens or database unique constraints.
+- **API Contract Discipline**: Strict schema validation on input payloads and response shapes (`zod`, `pydantic`, `protobuf`).
+
+---
+
+## 3. Verification Expectations
+
+When working in a `backend-api` repository, deterministic verification should prioritize:
+
+1. **Unit & Domain Tests**: Fast, isolated tests of domain services and calculation logic.
+2. **Integration / DB Tests**: Real or test-container database tests validating transaction rollbacks, unique constraints, and foreign key integrity.
+3. **Static Typing / Linting**: `tsc --noEmit`, `golangci-lint`, `ruff`, `mypy`.
+4. **Schema Contract Validation**: Verifying that OpenAPI / GraphQL / protobuf contracts have not broken backwards compatibility.
+5. **Database Migration Checks**: Dry-run migration execution and rollback tests.
+
+---
+
+## 4. Active Review Domains for Devil's Advocate
+
+When reviewing diffs in a `backend-api` project, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) activates these targeted checks:
+
+```mermaid
+flowchart LR
+    DA[Devil's Advocate] --> R1[1. Authorization & Tenant Isolation]
+    DA --> R2[2. Database Transactions & Atomicity]
+    DA --> R3[3. Concurrency & Race Conditions]
+    DA --> R4[4. Query Performance & N+1 Loops]
+    DA --> R5[5. API Contract Backwards Compatibility]
+    DA --> R6[6. Input Validation & Injection]
+```
+
+### 1. Authorization & Tenant Isolation (IDOR)
+- Does the endpoint verify that the requesting user has access to the requested entity (`tenant_id` / `org_id` / `user_id` check), or does it blindly trust IDs supplied in the request body/path?
+
+### 2. Database Transactions & Atomicity
+- If multiple database writes occur in one business operation, are they wrapped inside an explicit database transaction with rollback on error?
+
+### 3. Concurrency & Race Conditions
+- Can two concurrent requests for the same user cause double spending, duplicate voucher redemptions, or negative inventory balances?
+- Are optimistic locks (e.g. `version` column) or database-level row locks (`SELECT FOR UPDATE`) used where necessary?
+
+### 4. Query Performance & N+1 Loops
+- Are relational queries executing queries in a loop (`for item in items: db.query(...)`) instead of using joins or batch fetching (`IN (...)` / dataloaders)?
+- Are new `WHERE` or `ORDER BY` filters supported by database indexes?
+
+### 5. API Contract Compatibility
+- Does the change remove or rename an existing response field that could break existing mobile or web clients in production?
+
+### 6. Input Validation & Injection
+- Are inputs validated using schema parsers before reaching domain logic?
+- Are database queries constructed safely via parameterization?

package/profiles/library.md

@@ -0,0 +1,51 @@
+# Project Profile: `library`
+
+## 1. Profile Definition
+
+- **Archetype**: Reusable SDKs, Shared Packages, npm/PyPI/crates/Go modules, Open Source Libraries.
+- **Core Environment**: Diverse downstream host runtimes, varied Node/browser versions, zero assumption about host application architecture.
+
+---
+
+## 2. Engineering & Architecture Characteristics
+
+- **Semantic Versioning & Public API Stability**: Strict adherence to SemVer. Zero breaking changes on exported function signatures or interfaces in minor/patch releases.
+- **Minimal Dependencies**: Extreme reluctance to introduce third-party transitive dependencies. Prefer native standard libraries.
+- **Tree-Shaking & Bundle Efficiency**: Clean ES Module / CommonJS dual packaging, side-effect free declarations (`"sideEffects": false`).
+- **Comprehensive TypeScript Declarations**: Exported `.d.ts` definitions with complete JSDoc annotations and strong generics.
+
+---
+
+## 3. Verification Expectations
+
+1. **Compatibility Matrix Testing**: Unit tests executed across multiple runtime versions (e.g. Node 18, 20, 22).
+2. **API Surface & Type Tests**: Type-level regression tests (e.g. `tsd`, `expect-type`) ensuring type inference remains intact for consumers.
+3. **Packaging & Export Tests**: Build tools (`tsup`, `rollup`, `pkgroll`) verifying that output bundles export all expected entrypoints.
+4. **Zero-Dependency Audit**: Dependency vulnerability and size audit.
+
+---
+
+## 4. Active Review Domains for Devil's Advocate
+
+When reviewing diffs in a `library` project, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) activates these targeted checks:
+
+```mermaid
+flowchart LR
+    DA[Devil's Advocate] --> R1[1. Public API Breaking Changes]
+    DA --> R2[2. Unwanted Dependency Bloat]
+    DA --> R3[3. Cross-Runtime Compatibility]
+    DA --> R4[4. Tree-Shaking & Side-Effects]
+    DA --> R5[5. Type Inference Regressions]
+```
+
+### 1. Public API Breaking Changes
+- Does modifying this parameter or return type break existing consumers who update within the same major version?
+
+### 2. Unwanted Dependency Bloat
+- Is a new dependency being pulled in for something that could be written in 10 lines of standard library code?
+
+### 3. Cross-Runtime Compatibility
+- Does the code rely on Node.js-specific globals (`process`, `Buffer`, `fs`) in a package intended to also run in browser or edge runtimes (Cloudflare Workers, Deno)?
+
+### 4. Tree-Shaking & Side-Effects
+- Does importing a single utility from the package accidentally cause the entire library to be bundled by Webpack/Vite?

package/profiles/mobile-app.md

@@ -0,0 +1,59 @@
+# Project Profile: `mobile-app`
+
+## 1. Profile Definition
+
+- **Archetype**: Native & Cross-Platform Mobile Applications (iOS / Swift, Android / Kotlin, Flutter / Dart, React Native).
+- **Core Environment**: Mobile operating systems (iOS, Android), intermittent network connectivity, constrained memory and battery, background lifecycle states.
+
+---
+
+## 2. Engineering & Architecture Characteristics
+
+- **Offline-First & Resilience**: Expect network loss at any time. State must persist locally (SQLite, Room, CoreData, Hive, WatermelonDB) and synchronize reliably upon reconnection.
+- **Platform Lifecycle Handling**: Gracefully handle backgrounding, app suspension, memory pressure warnings, and foreground resumption.
+- **State Management**: Reactive state architecture (Bloc, Riverpod, Redux, Zustand, Combine, StateFlow) with single source of truth.
+- **Secure Device Storage**: Sensitive credentials (auth tokens, encryption keys) stored in iOS Keychain or Android Keystore / EncryptedSharedPreferences.
+
+---
+
+## 3. Verification Expectations
+
+When working in a `mobile-app` repository, deterministic verification should prioritize:
+
+1. **Unit & Logic Testing**: Pure Dart/Kotlin/Swift unit tests on stores, state notifiers, repository mappers, and sync algorithms.
+2. **Widget & Component Testing**: Testing component rendering, user taps, and navigation state.
+3. **Static Analysis & Typechecks**: `dart analyze`, `flutter test`, `swiftlint`, `ktlint`, `detekt`.
+4. **Native Build Validation**: `flutter build bundle`, `xcodebuild build-for-testing`, `./gradlew assembleDebug`.
+5. **Offline Scenario Simulation**: Unit tests verifying behavior when network repository throws `SocketException` or returns 503.
+
+---
+
+## 4. Active Review Domains for Devil's Advocate
+
+When reviewing diffs in a `mobile-app` project, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) activates these targeted checks:
+
+```mermaid
+flowchart LR
+    DA[Devil's Advocate] --> R1[1. Offline Sync & Conflict Resolution]
+    DA --> R2[2. Platform Lifecycle & State Loss]
+    DA --> R3[3. Permission Rejection Handling]
+    DA --> R4[4. Battery & Network Hygiene]
+    DA --> R5[5. Secure Credential Storage]
+```
+
+### 1. Offline Sync & Conflict Resolution
+- Does the code properly enqueue mutations when offline, or will unsaved user data be lost if the network drops before submit?
+- If the server has a newer version of a record upon sync, does the app have an explicit conflict resolution strategy?
+
+### 2. Platform Lifecycle & State Loss
+- If the operating system kills the app in the background due to memory pressure, does the user return to an empty screen or is essential draft state restored?
+
+### 3. Permission Rejection Handling
+- If the user denies camera, location, or notification permissions, does the app degrade gracefully or enter a crash loop?
+
+### 4. Battery & Network Hygiene
+- Are location listeners, GPS polling, or background timers stopped when the screen is dismissed?
+- Are large images cached appropriately on disk rather than re-downloaded on every scroll?
+
+### 5. Secure Credential Storage
+- Are JWT tokens or API secrets saved in secure hardware-backed storage rather than plain `SharedPreferences` / `UserDefaults`?

package/profiles/monorepo.md

@@ -0,0 +1,46 @@
+# Project Profile: `monorepo`
+
+## 1. Profile Definition
+
+- **Archetype**: Multi-package workspaces, Turborepo, Nx, Lerna, Cargo workspaces, Go multi-module repositories.
+- **Core Environment**: Shared codebases hosting multiple interdependent apps, services, and shared packages in a single git repository.
+
+---
+
+## 2. Engineering & Architecture Characteristics
+
+- **Workspace Boundaries**: Strict dependency rules between packages (e.g. `packages/ui` must not import `apps/web`; shared packages must only depend on approved core libraries).
+- **Internal Dependency Linking**: Use of `workspace:*` references rather than published npm packages for local development.
+- **Incremental Builds & Task Caching**: Optimized task pipelines where unaffected packages are skipped during verification.
+
+---
+
+## 3. Verification Expectations
+
+1. **Scoped & Affected Testing**: Running tests on touched packages and their direct downstream dependents (e.g. `turbo run test --filter=...[origin/main]`).
+2. **Workspace Typecheck**: Full typecheck across the monorepo root ensuring zero cross-package type breakage.
+3. **Circular Dependency Checks**: Static analysis tools verifying zero circular package graph dependencies (`madge`, `eslint-plugin-import`).
+4. **Boundary Linting**: Linters enforcing architecture tags (e.g. Nx boundaries).
+
+---
+
+## 4. Active Review Domains for Devil's Advocate
+
+When reviewing diffs in a `monorepo` project, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) activates these targeted checks:
+
+```mermaid
+flowchart LR
+    DA[Devil's Advocate] --> R1[1. Cross-Package Boundary Leaps]
+    DA --> R2[2. Circular Dependency Loops]
+    DA --> R3[3. Blast-Radius on Shared Packages]
+    DA --> R4[4. Monorepo Cache Invalidation]
+```
+
+### 1. Cross-Package Boundary Leaps
+- Is a shared package importing code or types from an application-layer package?
+
+### 2. Blast-Radius on Shared Packages
+- If modifying a core utility in `packages/common`, have all consuming applications (`apps/api`, `apps/web`, `apps/mobile`) been verified against breaking changes?
+
+### 3. Circular Dependency Loops
+- Does adding this import introduce a cycle in the monorepo graph?