ai-engineering-loop 1.0.0

package/examples/backend-api/payment-idempotency/README.md

@@ -0,0 +1,33 @@
+# Reference Example: Backend API Payment Idempotency & Race Condition Fix
+
+## 1. Scenario Overview
+
+This walkthrough demonstrates the **AI Engineering Loop** operating in a **Backend API** repository (`backend-api` profile) with standard GitHub adapter integration.
+
+### The Problem
+A Go/PostgreSQL payment processing microservice experienced double-spend vulnerabilities when users clicked the payment confirmation button multiple times in rapid succession. The database updated account balances without transactional row-level locks or idempotency key uniqueness checks.
+
+---
+
+## 2. Dynamic Context Resolution
+
+```text
+Engine: AI Engineering Loop Core
+Profile: profiles/backend-api.md
+Repo Config: payment-service/.ai-engineering-loop/ (Go 1.22, pgx, GitHub Adapter)
+Task: Implement atomic idempotency key validation and SELECT FOR UPDATE row locking
+```
+
+---
+
+## 3. Walkthrough Artifacts
+
+1. **[Goal Contract (`goal-contract.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/backend-api/payment-idempotency/goal-contract.md)**:
+   - AC-1: Idempotency-Key header mandatory on POST `/api/v1/payments/charge`.
+   - AC-2: Atomic reservation using PostgreSQL `INSERT ... ON CONFLICT DO NOTHING`.
+   - AC-3: Concurrent requests for same user wallet serialized with `SELECT ... FOR UPDATE`.
+2. **[Adversarial Review Findings (`review-findings.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/backend-api/payment-idempotency/review-findings.md)**:
+   - Devil's Advocate activates `backend-api` rules (concurrency, database atomicity).
+   - Flags missing rollback on external gateway timeout (`ERR-001`).
+3. **[Judge Verdict (`judge-verdict.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/backend-api/payment-idempotency/judge-verdict.md)**:
+   - Evaluates parallel test execution (`go test -race ./...`), verifies concurrency safety, and issues `PASS` verdict.

package/examples/backend-api/payment-idempotency/goal-contract.md

@@ -0,0 +1,33 @@
+# Goal Contract: Payment Idempotency & Concurrency Lock
+
+## 1. Objective
+Eliminate double-spending and balance corruption in the `payment-service` by enforcing mandatory `Idempotency-Key` headers, database transaction isolation, and row-level wallet locks.
+
+## 2. Business Outcome & User Lifecycle Impact
+- **Customers**: Guaranteed never to be charged twice for identical checkout operations regardless of network retries or multiple clicks.
+- **Finance**: 100% auditability and balance ledger integrity.
+
+## 3. Acceptance Criteria (AC)
+- [ ] **AC-1**: Reject `POST /api/v1/payments/charge` with HTTP 400 if `Idempotency-Key` header is missing or empty.
+- [ ] **AC-2**: Idempotency records stored atomically with 24-hour expiration window. Duplicate requests return cached original response with `X-Cache: HIT`.
+- [ ] **AC-3**: User wallet balance updates serialized via `SELECT balance, version FROM wallets WHERE id = $1 FOR UPDATE`.
+- [ ] **AC-4**: Zero race conditions detected under 50 simultaneous parallel requests.
+
+## 4. Technical Constraints
+- Maintain Go 1.22 standard library and `github.com/jackc/pgx/v5`.
+- No distributed Redis locks unless DB transactions prove insufficient.
+- Zero breaking changes to response JSON schemas.
+
+## 5. Out of Scope
+- Modifying refund or settlement batch jobs.
+
+## 6. Verification Requirements
+- **Unit & Race Tests**: `go test -race -v -count=1 ./internal/payment/...`
+- **Lint**: `golangci-lint run ./...`
+- **Build**: `go build -o /dev/null ./cmd/server`
+
+## 7. Definition of Done (DoD)
+- [ ] AC-1 through AC-4 verified via automated race test suites.
+- [ ] Deterministic verification 100% green.
+- [ ] Devil's Advocate review conducted with 0 open SEV-1/2 findings.
+- [ ] Judge issues PASS verdict.

package/examples/backend-api/payment-idempotency/judge-verdict.md

@@ -0,0 +1,28 @@
+# Judge Evaluation Report: Payment Idempotency
+
+## 1. Executive Verdict
+- **Verdict**: `PASS`
+- **Iteration**: `Iteration 2 of 3`
+- **Confidence**: `HIGH`
+
+---
+
+## 2. Deterministic Verification Audit
+
+| Check | Command Executed | Raw Result | Status |
+|---|---|---|:---:|
+| **Race Tests** | `go test -race -v ./internal/payment/...` | `PASS: TestConcurrentPaymentDeductions (50 goroutines). 0 race warnings. ok 2.18s` | ✅ PASS |
+| **Idempotency Suite**| `go test -v ./internal/payment/idempotency_test.go` | `PASS: TestIdempotencyDuplicateRequestReturnsCached. ok 0.42s` | ✅ PASS |
+| **Linter** | `golangci-lint run ./...` | `0 issues found.` | ✅ PASS |
+| **Build** | `go build -o /dev/null ./cmd/server` | `Exit code 0.` | ✅ PASS |
+
+---
+
+## 3. Finding Triage Audit
+- **CONC-001 (Critical - Dangling DB Transaction)**: Resolved with `defer tx.Rollback(ctx)`. Verified by timeout test suite. **Status: RESOLVED & VERIFIED**.
+
+---
+
+## 4. Hand-off
+The Definition of Done has been completely satisfied.
+**Authorized next action**: Hand off to configured GitHub Adapter for Pull Request generation.

package/examples/backend-api/payment-idempotency/review-findings.md

@@ -0,0 +1,50 @@
+# Adversarial Review Findings: Payment Idempotency
+
+## 1. Review Summary
+- **Reviewer**: Devil's Advocate Agent (Profile: `backend-api`)
+- **Active Review Domains**: Auth, Database Transactions, Concurrency/Race, N+1, API Contracts
+- **Total Findings**: 1
+- **Blocking (SEV-1/2)**: 1
+
+---
+
+## 2. Findings Ledger
+
+### Finding CONC-001: Missing transaction rollback when external payment gateway times out
+- **Severity**: `CRITICAL` (SEV-1)
+- **Category**: `Concurrency & Error Handling`
+- **Location**: `internal/payment/service.go:88-102`
+- **Evidence**:
+  ```go
+  tx, _ := s.db.Begin(ctx)
+  wallet.Deduct(amount)
+  resp, err := s.gatewayClient.Charge(ctx, req)
+  if err != nil {
+      return nil, err // Exits without tx.Rollback(ctx)
+  }
+  tx.Commit(ctx)
+  ```
+- **Problem**:
+  If the external payment gateway call returns a timeout or network error, the function exits early without invoking `tx.Rollback(ctx)`. In Go `pgx`, the connection remains locked in a dangling transaction until connection pool cleanup, and the user's wallet balance stays locked.
+- **Impact**:
+  Connection pool exhaustion and locked wallet accounts during network blips.
+- **Recommendation**:
+  ```diff
+  tx, err := s.db.Begin(ctx)
+  if err != nil {
+      return nil, err
+  }
+  + defer tx.Rollback(ctx)
+  
+  wallet.Deduct(amount)
+  resp, err := s.gatewayClient.Charge(ctx, req)
+  if err != nil {
+      return nil, err
+  }
+  - tx.Commit(ctx)
+  + return resp, tx.Commit(ctx)
+  ```
+- **Confidence**: `HIGH`
+- **Status**: `TRIAGED_VALID`
+- **Resolution**:
+  Maker Agent implemented `defer tx.Rollback(ctx)` and verified with a unit test simulating gateway timeout.

package/examples/dot/attendance-confirmation/README.md

@@ -0,0 +1,22 @@
+# Reference Example: Attendance Confirmation Status Fix
+
+## 1. Context & Scenario
+
+This reference walkthrough demonstrates how a complex real-world bug in the DOT ecosystem moves through the complete **AI Engineering Loop** and is subsequently delivered via the **DOT Delivery Adapter**.
+
+### The Problem
+In the Dotify employee portal, attendance confirmation cards displayed an incorrect status (`"PENDING"`) for employees working overtime or on weekends, even when all underlying time logs had already been approved or rejected. Furthermore, non-normal hours employees (shift workers) had their records mistakenly treated under standard 9-to-5 rules.
+
+---
+
+## 2. Walkthrough Stages & Artifacts
+
+1. **[Stage 1: Goal Contract (`goal-contract.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/dot/attendance-confirmation/goal-contract.md)**:
+   - Formalized objective, acceptance criteria (normal hours, weekends, non-normal hours, null values), and verification plan.
+2. **[Stage 2: Adversarial Review & Triage (`review-findings.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/dot/attendance-confirmation/review-findings.md)**:
+   - Independent Devil's Advocate review flagging a timezone offset bug (`COR-001`) and an invalid nitpick (`MAINT-001`).
+   - Maker Agent triage and surgical resolution.
+3. **[Stage 3: Judge Evaluation & Verdict (`judge-verdict.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/dot/attendance-confirmation/judge-verdict.md)**:
+   - Audit of unit test results, typecheck logs, finding resolutions, and issuance of `PASS` verdict.
+4. **[Stage 4: DOT Delivery Pipeline (`delivery-report.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/dot/attendance-confirmation/delivery-report.md)**:
+   - Creation of GitLab Issue #307, base MR !946, multi-branch propagation to `staging` (!947) and `develop` (!948), Coreview bot triage, and automated Mattermost channel notification.

package/examples/dot/attendance-confirmation/delivery-report.md

@@ -0,0 +1,51 @@
+# DOT Delivery Report: Attendance Confirmation Fix
+
+## 1. Summary of Delivery Actions
+
+Upon receiving the `PASS` verdict from the Judge Agent, the DOT Delivery Adapter executed the following release actions:
+
+1. **GitLab Issue Created**: [Issue #307 - [BE] [Attendance] Fix Attendance Confirmation Display Status](https://gitlab.dot.co.id/dot-system/dotify-new/-/issues/307).
+2. **Primary MR Created**: [MR !946 targeting `main`](https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/946).
+3. **Multi-Branch Cherry-Pick**:
+   - [MR !947 targeting `staging`](https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/947).
+   - [MR !948 targeting `develop`](https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/948).
+4. **Coreview Bot Triage**:
+   - Comments fetched on MR !948. Zero blocking comments found.
+5. **Mattermost Notification**:
+   - Resolved repository `dot-system/dotify-new` to channel `"internal-dotify"`.
+   - Dispatched Markdown report via MCP `mattermost_send_message` with `from: "AI Agent"`.
+
+---
+
+## 2. GitLab Links
+
+| Artifact | Branch | Link |
+|---|---|---|
+| **GitLab Issue** | — | `[Issue #307](https://gitlab.dot.co.id/dot-system/dotify-new/-/issues/307)` |
+| **Merge Request DEV** | `develop` | `[MR !948](https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/948)` |
+| **Merge Request STAGING** | `staging` | `[MR !947](https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/947)` |
+| **Merge Request MAIN** | `main` | `[MR !946](https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/946)` |
+
+---
+
+## 3. Dispatched Mattermost Notification
+
+```text
+[MR DEV] https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/948
+Changes log 
+- Include user.type.hasNormalHours and timeEntities.overtimeNote in attendanceConfirmationPagination Prisma query.
+- Create resolveAttendanceConfirmationDisplayStatus utility to properly evaluate hasPendingTimeEntities by checking overtimeNote, isWeekend, duration > 8, non-normal hours employees, and null statuses.
+- Add comprehensive unit tests in src/server/attendance-confirmations/utils/resolve-display-status.test.ts covering all status permutations.
+
+[MR STAGING] https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/947
+Changes log 
+- Include user.type.hasNormalHours and timeEntities.overtimeNote in attendanceConfirmationPagination Prisma query.
+- Create resolveAttendanceConfirmationDisplayStatus utility to properly evaluate hasPendingTimeEntities by checking overtimeNote, isWeekend, duration > 8, non-normal hours employees, and null statuses.
+- Add comprehensive unit tests in src/server/attendance-confirmations/utils/resolve-display-status.test.ts covering all status permutations.
+
+[MR MAIN] https://gitlab.dot.co.id/dot-system/dotify-new/-/merge_requests/946
+Changes log 
+- Include user.type.hasNormalHours and timeEntities.overtimeNote in attendanceConfirmationPagination Prisma query.
+- Create resolveAttendanceConfirmationDisplayStatus utility to properly evaluate hasPendingTimeEntities by checking overtimeNote, isWeekend, duration > 8, non-normal hours employees, and null statuses.
+- Add comprehensive unit tests in src/server/attendance-confirmations/utils/resolve-display-status.test.ts covering all status permutations.
+```

package/examples/dot/attendance-confirmation/goal-contract.md

@@ -0,0 +1,39 @@
+# Goal Contract: Attendance Confirmation Display Status Fix
+
+## 1. Objective
+Fix the incorrect calculation of attendance confirmation display statuses across list and pagination endpoints when time entities contain overtime notes, weekend logs, non-normal hours employees, or null record states.
+
+## 2. Business Outcome & User Lifecycle Impact
+- **Employees**: View accurate confirmation statuses (APPROVED, REJECTED, NEED_APPROVAL) reflecting their true attendance record.
+- **Managers / Reviewers**: Stop receiving false-positive pending approval notifications for already-settled weekend logs.
+- **HR & Payroll**: Accurate cumulative duration calculations for payroll export.
+
+## 3. Acceptance Criteria (AC)
+- [ ] **AC-1**: If an employee has `hasNormalHours = true` and `duration <= 8` on a standard weekday without overtime notes, display status must resolve to `APPROVED` or `NEED_APPROVAL` strictly based on clock-in/out presence.
+- [ ] **AC-2**: If `overtimeNote` exists or `duration > 8` or `isWeekend = true`, evaluate pending status across all associated `timeEntities`.
+- [ ] **AC-3**: Non-normal hours employees (`user.type.hasNormalHours = false`) must not be evaluated under 8-hour weekday thresholds.
+- [ ] **AC-4**: Null or missing time entity collections must default safely to `APPROVED` without throwing runtime `TypeError`.
+- [ ] **AC-5**: Backward compatibility of the tRPC/REST response contract must be strictly preserved.
+
+## 4. Technical Constraints
+- Preserve existing Prisma query schemas in `attendanceConfirmationPagination`.
+- Centralize logic in a pure, testable utility function: `resolveAttendanceConfirmationDisplayStatus`.
+- No new external runtime dependencies (use existing `dayjs` and `lodash` packages).
+- 0 TypeScript compiler errors on `tsc --noEmit`.
+
+## 5. Out of Scope
+- Modifying the UI frontend component layouts in `dotify-new/web`.
+- Database schema migrations or alter table statements.
+- Changing payroll export report generation scripts.
+
+## 6. Verification Requirements
+- **Unit Tests**: Comprehensive Jest test suite in `src/server/attendance-confirmations/utils/resolve-display-status.test.ts` covering 100% of branches.
+- **Typecheck**: `npx tsc --noEmit` exits with 0.
+- **Linter**: `npx eslint --fix` on modified files with 0 errors.
+- **Regression**: Run entire test suite: `npx jest --testPathIgnorePatterns="dotify-api"`.
+
+## 7. Definition of Done (DoD)
+- [ ] All AC-1 through AC-5 proven by unit tests.
+- [ ] Deterministic verification passes 100%.
+- [ ] Devil's Advocate review conducted with 0 unresolved blocking findings.
+- [ ] Judge issues PASS verdict.

package/examples/dot/attendance-confirmation/judge-verdict.md

@@ -0,0 +1,43 @@
+# Judge Evaluation Report: Attendance Confirmation Fix
+
+## 1. Executive Verdict
+- **Verdict**: `PASS`
+- **Iteration**: `Iteration 2 of 3`
+- **Confidence**: `HIGH`
+
+---
+
+## 2. Deterministic Verification Audit
+
+| Check | Command Executed | Raw Result | Status |
+|---|---|---|:---:|
+| **Unit Tests** | `npx jest src/server/attendance-confirmations/utils/resolve-display-status.test.ts` | `Tests: 12 passed, 12 total. Snapshots: 0. Time: 1.42s` | ✅ PASS |
+| **Full Suite** | `npx jest --testPathIgnorePatterns="dotify-api"` | `Test Suites: 48 passed, 48 total. Tests: 382 passed.` | ✅ PASS |
+| **TypeScript** | `npx tsc --noEmit` | `Exit code 0. Zero errors.` | ✅ PASS |
+| **Linter** | `npx eslint --fix src/server/attendance-confirmations/**` | `0 errors, 0 warnings found.` | ✅ PASS |
+
+---
+
+## 3. Goal Contract Compliance Audit
+
+| Criterion | Verified By Test / Artifact | Result |
+|---|---|:---:|
+| **AC-1**: Normal hours weekday calculation | `resolve-display-status.test.ts > normal hours` | ✅ PASS |
+| **AC-2**: Weekend & duration > 8 handling | `resolve-display-status.test.ts > weekend overtime` | ✅ PASS |
+| **AC-3**: Non-normal hours employee rules | `resolve-display-status.test.ts > shift worker` | ✅ PASS |
+| **AC-4**: Null & undefined timeEntities safety | `resolve-display-status.test.ts > null safety` | ✅ PASS |
+| **AC-5**: API Contract Preservation | `tRPC router typecheck` | ✅ PASS |
+
+---
+
+## 4. Finding Triage Audit
+
+- **COR-001 (High - Null Safety)**: Maker applied null coalescing in Iteration 2. Verified via fresh test execution. **Status: RESOLVED & VERIFIED**.
+- **MAINT-001 (Low - Factory Suggestion)**: Overridden by Judge as invalid speculative nitpick. **Status: DISMISSED / INVALID**.
+
+---
+
+## 5. Formal Conclusion & Hand-off
+
+The Definition of Done has been 100% satisfied with reproducible evidence.
+**Authorized next action**: Proceed to [DOT Delivery Adapter](file:///Users/egagofur/Development/work/ai-engineering-loop/adapters/dot/README.md) for GitLab MR generation, multi-branch cherry-picking, Coreview triage, and Mattermost notification.

package/examples/dot/attendance-confirmation/review-findings.md

@@ -0,0 +1,57 @@
+# Adversarial Review Findings & Triage: Attendance Confirmation Fix
+
+## 1. Review Summary
+
+- **Reviewer**: Devil's Advocate Agent
+- **Target Branch**: `main...fix/attendance-confirmation-status`
+- **Total Findings**: 2
+- **Blocking (SEV-1/2)**: 1
+- **Non-Blocking / Invalid**: 1
+
+---
+
+## 2. Findings Ledger
+
+### Finding COR-001: Missing null safety when iterating `timeEntities`
+- **Severity**: `HIGH` (SEV-2)
+- **Category**: `Correctness`
+- **Location**: `src/server/attendance-confirmations/utils/resolve-display-status.ts:34-41`
+- **Evidence**:
+  ```typescript
+  const hasPending = confirmation.timeEntities.some(
+    (entity) => entity.status === "NEED_APPROVAL"
+  );
+  ```
+- **Problem**:
+  If `confirmation.timeEntities` is `null` or `undefined` (which occurs for historical attendance records prior to migration v2.4), calling `.some()` throws a runtime `TypeError: Cannot read properties of undefined (reading 'some')`.
+- **Impact**:
+  Crashing pagination API for employees with legacy historical attendance records.
+- **Recommendation**:
+  ```diff
+  - const hasPending = confirmation.timeEntities.some(
+  + const hasPending = (confirmation.timeEntities ?? []).some(
+      (entity) => entity.status === "NEED_APPROVAL"
+    );
+  ```
+- **Confidence**: `HIGH`
+- **Status**: `TRIAGED_VALID`
+- **Resolution**:
+  Maker Agent applied optional chaining and null coalescing `(confirmation.timeEntities ?? [])` and added unit test case `should return APPROVED when timeEntities is null or undefined` in `resolve-display-status.test.ts`.
+
+---
+
+### Finding MAINT-001: Suggestion to convert helper into an abstract factory class
+- **Severity**: `LOW` (SEV-4)
+- **Category**: `Maintainability`
+- **Location**: `src/server/attendance-confirmations/utils/resolve-display-status.ts:1-50`
+- **Evidence**:
+  Utility is authored as a pure exported function `export function resolveAttendanceConfirmationDisplayStatus(...)`.
+- **Problem**:
+  Reviewer claimed that an object-oriented Strategy/Factory pattern would allow swapping attendance status calculators in the future.
+- **Impact**:
+  None. Pure functions are more testable, tree-shakeable, and align with current repository conventions.
+- **Recommendation**: Refactor to `class AttendanceStatusCalculatorFactory`.
+- **Confidence**: `LOW`
+- **Status**: `TRIAGED_INVALID`
+- **Triage Reason**:
+  Dismissed as speculative overengineering. Repository architecture uses functional utilities with tRPC. Adding a class factory violates Technical Constraint: *"Produce minimal, surgical changes without speculative abstractions."*

package/examples/initialization/README.md

@@ -0,0 +1,19 @@
+# Reference Example: Automatic Project Initialization & Discovery
+
+## 1. Overview & Scenario
+
+This walkthrough demonstrates how the **AI Engineering Loop** automatically initializes an unconfigured full-stack TypeScript and Go monorepo (`acme-platform`) that contains **zero** existing `.ai-engineering-loop/` configuration.
+
+### The Codebase State:
+- **Repository**: `acme-corp/acme-platform`
+- **Existing Config**: `pnpm-workspace.yaml`, `turbo.json`, `apps/web/package.json` (Next.js), `apps/api/go.mod` (Go/Gin), `packages/ui/`
+- **Initial Status**: No `.ai-engineering-loop/` folder present.
+
+---
+
+## 2. Walkthrough Artifacts
+
+1. **[Discovery Execution Trace (`discovery-trace.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/initialization/discovery-trace.md)**:
+   - Full 5-pass log of directory inspection, manifest parsing, script discovery, architecture tracing, and second-pass quality check.
+2. **[Generated Context Artifacts (`generated-context.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/initialization/generated-context.md)**:
+   - The exact evidence-based `.ai-engineering-loop/` files generated automatically by the agent without user intervention.

package/examples/initialization/discovery-trace.md

@@ -0,0 +1,63 @@
+# Discovery Execution Trace: `acme-platform`
+
+## 1. Trigger & Initial Detection
+
+```text
+[ENGINE] Initializing workspace in /workspaces/acme-platform
+[ENGINE] Checking for .ai-engineering-loop/... NOT FOUND.
+[ENGINE] Triggering State B: Autonomous Project Initialization & Discovery.
+```
+
+---
+
+## 2. The 5-Pass Discovery Log
+
+### Pass 1: Topology & Workspace Inspection
+- `list_dir /workspaces/acme-platform`:
+  - `apps/` (contains `web/`, `api/`)
+  - `packages/` (contains `ui/`, `database/`, `shared/`)
+  - `pnpm-workspace.yaml` (detected `pnpm` monorepo)
+  - `turbo.json` (detected Turborepo pipeline)
+- **Profile Binding**: Bound [`profiles/monorepo.md`](file:///Users/egagofur/Development/work/ai-engineering-loop/profiles/monorepo.md).
+
+### Pass 2: Manifests & Verification Commands Discovery
+- Parsed `package.json` (root):
+  - `"test"`: `"turbo run test"`
+  - `"typecheck"`: `"turbo run typecheck"`
+  - `"lint"`: `"turbo run lint"`
+  - `"build"`: `"turbo run build"`
+- Parsed `apps/api/go.mod`:
+  - Go 1.22, Gin framework, pgx
+- Extracted Commands:
+  - Unit Tests: `pnpm test` (or `pnpm --filter @acme/web test` for focused web)
+  - Typecheck: `pnpm typecheck`
+  - Linter: `pnpm lint`
+  - Build: `pnpm build`
+
+### Pass 3: Architecture & Invariant Mapping
+- **Presentation**: Next.js 14 App Router in `apps/web/src/app`, Gin REST API in `apps/api/cmd/server`.
+- **Data Access**: PostgreSQL + Prisma in `packages/database`.
+- **Shared UI**: Tailwind + Radix UI in `packages/ui`.
+- **Boundaries**: `packages/ui` and `packages/database` are shared dependencies; `apps/web` must not import `apps/api` internal code.
+
+### Pass 4: Observed Conventions Extraction
+- File naming: `kebab-case` throughout `apps/web` and `packages/ui`.
+- Error handling: Go API returns `{"error": {"code": "...", "message": "..."}}`.
+- Git remote: `origin -> https://github.com/acme-corp/acme-platform.git`.
+- Adapter: Bound GitHub Adapter.
+
+### Pass 5: Second-Pass Context Quality Audit
+- Evidence check: 100% of claims attributed to files.
+- Secret check: `.env` and `.env.local` skipped; `.env.example` verified safe. Zero leaked credentials.
+- Conciseness check: 180 total lines generated across `.ai-engineering-loop/`.
+- Status: **PASSED QUALITY AUDIT**.
+
+---
+
+## 3. Completion & Hand-off
+
+```text
+[ENGINE] Generated .ai-engineering-loop/ (config.md, architecture.md, conventions.md, verification.md, adapter.md)
+[ENGINE] Project Context successfully initialized!
+[ENGINE] Proceeding to Goal Contract formulation...
+```

package/examples/initialization/generated-context.md

@@ -0,0 +1,110 @@
+# Generated Context Artifacts: `acme-platform`
+
+Below are the exact 5 files generated automatically inside `/workspaces/acme-platform/.ai-engineering-loop/`:
+
+---
+
+## 1. `.ai-engineering-loop/config.md`
+
+```markdown
+# Project Configuration
+
+## Metadata
+- **project_name**: "acme-platform"
+- **project_profile**: "monorepo" # Archetype bound from profiles/monorepo.md
+- **languages**:
+  - TypeScript 5.4 (Node.js 20.x)
+  - Go 1.22
+- **frameworks**:
+  - Next.js 14 (App Router)
+  - Gin Web Framework
+  - Prisma ORM
+- **package_manager**: "pnpm" (Turborepo workspace)
+- **default_base_branch**: "main"
+
+## Evidence
+- Topology: `pnpm-workspace.yaml`, `turbo.json`
+- Apps: `apps/web/package.json`, `apps/api/go.mod`
+- Shared: `packages/ui/package.json`, `packages/database/prisma/schema.prisma`
+```
+
+---
+
+## 2. `.ai-engineering-loop/architecture.md`
+
+```markdown
+# Project Architecture
+
+## System Overview
+Full-stack monorepo featuring a Next.js 14 web application, a Go backend API service, and shared UI/database packages.
+
+## Applications & Packages
+- `apps/web`: Next.js 14 frontend client rendering UI.
+- `apps/api`: Go Gin REST service handling payments and user records.
+- `packages/ui`: Shared React/Tailwind component library.
+- `packages/database`: Centralized Prisma client and database schemas.
+
+## Boundary Invariants
+- `packages/ui` must not import backend API logic.
+- `apps/web` must not connect directly to the database; it queries `apps/api` via REST.
+- Shared packages must maintain zero cyclic dependencies.
+
+## Evidence & Confidence
+- Observed from: `apps/`, `packages/`, `turbo.json`
+- Confidence: HIGH
+```
+
+---
+
+## 3. `.ai-engineering-loop/conventions.md`
+
+```markdown
+# Project Conventions
+
+## Code Standards
+- File naming: `kebab-case` for TypeScript components and Go files.
+- Test placement: Colocated `*.test.tsx` in `apps/web`; `*_test.go` in `apps/api`.
+- Design tokens: Use Tailwind utility classes with colors defined in `packages/ui/tailwind.config.js`.
+
+## Forbidden Anti-Patterns
+- Zero `any` types in TypeScript packages.
+- Zero unchecked error returns in Go (`if err != nil` is mandatory).
+- Do not commit or hardcode environment URLs.
+```
+
+---
+
+## 4. `.ai-engineering-loop/verification.md`
+
+```markdown
+# Project Verification Commands
+
+## Workspace Package Manager
+pnpm (Turborepo)
+
+## Commands
+- **test_unit**: `pnpm test`
+- **test_scoped**: `pnpm --filter <package-name> test`
+- **typecheck**: `pnpm typecheck`
+- **lint**: `pnpm lint`
+- **build**: `pnpm build`
+
+## Required Verification by Scope
+- **Web changes**: `pnpm --filter @acme/web test` and `pnpm --filter @acme/web typecheck`.
+- **API changes**: `cd apps/api && go test -v ./...` and `golangci-lint run`.
+- **Database changes**: `pnpm --filter @acme/database test`.
+```
+
+---
+
+## 5. `.ai-engineering-loop/adapter.md`
+
+```markdown
+# Project Delivery Adapter Configuration
+
+## Delivery Pipeline
+- **adapter_type**: "github"
+- **repository**: "acme-corp/acme-platform"
+- **default_target_branch**: "main"
+- **ci_workflows**: GitHub Actions (`.github/workflows/ci.yml`)
+```

package/examples/mobile-app/offline-sync-queue/README.md

@@ -0,0 +1,33 @@
+# Reference Example: Mobile App Offline Sync Queue
+
+## 1. Scenario Overview
+
+This walkthrough demonstrates the **AI Engineering Loop** operating in a **Mobile Application** repository (`mobile-app` profile) for a field survey application built in Flutter / SQLite.
+
+### The Problem
+Field inspectors working in remote areas without cellular coverage experienced loss of submitted inspection forms when the application was closed or terminated by the OS before regaining an internet connection.
+
+---
+
+## 2. Dynamic Context Resolution
+
+```text
+Engine: AI Engineering Loop Core
+Profile: profiles/mobile-app.md
+Repo Config: inspector-app/.ai-engineering-loop/ (Flutter 3.22, sqflite, Riverpod)
+Task: Implement persistent offline SQLite mutation queue with exponential backoff sync
+```
+
+---
+
+## 3. Walkthrough Artifacts
+
+1. **[Goal Contract (`goal-contract.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/mobile-app/offline-sync-queue/goal-contract.md)**:
+   - AC-1: All form submissions persist immediately to local SQLite `mutation_queue` table before network dispatch.
+   - AC-2: Background sync engine triggers on network restoration with exponential backoff.
+   - AC-3: OS suspension / app kill must not drop un-synced items.
+2. **[Adversarial Review Findings (`review-findings.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/mobile-app/offline-sync-queue/review-findings.md)**:
+   - Devil's Advocate activates `mobile-app` rules (offline persistence, lifecycle, battery).
+   - Flags missing disk write error handling when device storage is full (`PERF-001`).
+3. **[Judge Verdict (`judge-verdict.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/examples/mobile-app/offline-sync-queue/judge-verdict.md)**:
+   - Audits Flutter unit & mock network tests, verifies 100% pass, and issues `PASS` verdict.

package/examples/mobile-app/offline-sync-queue/goal-contract.md

@@ -0,0 +1,32 @@
+# Goal Contract: Offline Mutation Queue & Sync Engine
+
+## 1. Objective
+Implement an offline-first transactional queue in SQLite that captures user inspection submissions locally and synchronizes reliably with the cloud API upon network reconnection.
+
+## 2. Business Outcome & User Lifecycle Impact
+- **Field Inspectors**: Can complete and save survey reports anywhere with zero risk of data loss.
+- **Operations**: Automatic background upload with zero manual re-entry.
+
+## 3. Acceptance Criteria (AC)
+- [ ] **AC-1**: Submissions write to local SQLite `mutation_queue` with status `PENDING` before network attempt.
+- [ ] **AC-2**: Connectivity changes trigger FIFO queue processing with max 3 retry attempts per item.
+- [ ] **AC-3**: Simulated app kill during background sync resumes cleanly upon next launch.
+- [ ] **AC-4**: Zero data loss under intermittent network flapping (3G/offline transitions).
+
+## 4. Technical Constraints
+- Flutter 3.22, Dart 3.4, `sqflite` for local DB, `connectivity_plus` for network state.
+- Pure Dart logic for sync manager with zero direct UI widget dependencies.
+
+## 5. Out of Scope
+- Modifying survey form UI layout or camera image capture compression.
+
+## 6. Verification Requirements
+- **Unit & Mock Tests**: `flutter test test/core/sync/offline_queue_test.dart`
+- **Static Analysis**: `dart analyze`
+- **Build Check**: `flutter build bundle`
+
+## 7. Definition of Done (DoD)
+- [ ] All AC-1 through AC-4 proven via unit & repository test suites.
+- [ ] Static analysis 0 issues.
+- [ ] Devil's Advocate review conducted with 0 unresolved blocking findings.
+- [ ] Judge issues PASS verdict.

package/examples/mobile-app/offline-sync-queue/judge-verdict.md

@@ -0,0 +1,27 @@
+# Judge Evaluation Report: Offline Sync Queue
+
+## 1. Executive Verdict
+- **Verdict**: `PASS`
+- **Iteration**: `Iteration 2 of 3`
+- **Confidence**: `HIGH`
+
+---
+
+## 2. Deterministic Verification Audit
+
+| Check | Command Executed | Raw Result | Status |
+|---|---|---|:---:|
+| **Unit & Sync Tests** | `flutter test test/core/sync/` | `00:04 +18: All tests passed!` | ✅ PASS |
+| **Static Analysis** | `dart analyze` | `No issues found! (ran in 1.8s)` | ✅ PASS |
+| **Asset Bundle** | `flutter build bundle` | `Bundle built successfully.` | ✅ PASS |
+
+---
+
+## 3. Finding Triage Audit
+- **ERR-001 (High - SQLite Disk Full Crash)**: Resolved by wrapping insert operations with domain exception handlers and fallback telemetry. **Status: RESOLVED & VERIFIED**.
+
+---
+
+## 4. Hand-off
+All Definition of Done criteria are satisfied.
+**Authorized next action**: Proceed to designated mobile release pipeline.