ai-engineering-loop 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ega Gofur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# AI Engineering Loop
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
+[![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
+[![Release](https://img.shields.io/badge/release-v1.0.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
+[![Status](https://img.shields.io/badge/status-production--ready-success.svg)](https://github.com/egagofur/ai-engineering-loop)
+
+**A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
+
+*Featuring living project context, post-task impact assessment, contract-driven execution, deterministic machine verification, and independent adversarial review.*
+
+[Overview](#overview--philosophy) • [Living Project Context](#living-project-context) • [CLI Commands](#cli-interface--commands) • [Agent Integration](#antigravity-agent-integration) • [Lifecycle](#lifecycle-stages) • [Architecture](#architecture--5-layer-configuration) • [Project Profiles](#project-profiles) • [Repository Structure](#repository-structure) • [Reference Examples](#reference-examples) • [Contributing](#contributing)
+
+</div>
+
+---
+
+## Overview & Philosophy
+
+The AI Engineering Loop enforces a clean architectural separation between **Deterministic Living Context Bootstrap** and **Agent Intelligence**:
+
+> **"The CLI bootstraps, tracks, and validates living context. The AI Agent reasons over that context to execute the engineering lifecycle."**
+
+```mermaid
+flowchart TD
+    Start([User Task in Workspace]) --> PreCheck{Pre-Task Drift Check: metadata.json}
+    
+    PreCheck -->|Context Missing| AutoInit[Stage 0: Bootstrap .ai-engineering-loop/]
+    PreCheck -->|Drift Detected| Reconcile[Stage 0: Reconcile Drifted Context]
+    PreCheck -->|Context Fresh| GC[Stage 1: Goal Contract: Explicit Acceptance Criteria]
+    
+    AutoInit --> GC
+    Reconcile --> GC
+    
+    subgraph CoreEngine [AI ENGINEERING OPERATING SYSTEM]
+        GC --> RCA[Stage 2: Root Cause Analysis]
+        RCA --> Plan[Stage 3: Implementation Plan]
+        Plan --> MA[Stage 4: Maker Agent: Surgical Diff & Tests]
+        MA --> DV{Stage 5: Deterministic Verification}
+        
+        DV -->|Fail| MA
+        DV -->|Pass| DA[Stage 6: Devil's Advocate: Adversarial Review]
+        
+        DA --> JD[Stage 7: Judge Agent: Impartial Magistrate]
+    end
+    
+    JD -->|PASS| ImpactEval{Post-Task Context Impact Assessment}
+    
+    ImpactEval -->|NONE: Typo, UI tweak| Adapter[Stage 8: Delivery Adapter: GitLab / GitHub]
+    ImpactEval -->|TARGETED: Dep/route changed| PartialRefresh[Surgical Context Update] --> Adapter
+    ImpactEval -->|MAJOR: Framework migration| FullRefresh[Full Context Reconciliation] --> Adapter
+    
+    Adapter --> TargetRepo[(Target Repository)]
+```
+
+---
+
+## Living Project Context
+
+The `.ai-engineering-loop/` directory is **Living Context**, not a static wiki generated once.
+
+### 1. Post-Task Context Impact Assessment
+A task reaching `PASS` does **not** blindly trigger a full project refresh. The agent evaluates the impact level:
+- **`NONE` (80–90% of tasks)**: Typo fixes, CSS tweaks, surgical bugfixes preserving architecture $\rightarrow$ Refresh SKIPPED.
+- **`TARGETED` (10–15% of tasks)**: Manifest script change (`verification.md`), new module (`architecture.md`), new CI config (`adapter.md`) $\rightarrow$ Surgically update affected files only.
+- **`MAJOR` (<5% of tasks)**: Framework migration, monorepo restructuring, auth overhaul $\rightarrow$ Full context reconciliation.
+
+### 2. Context Baseline (`metadata.json`)
+Deterministic drift detection without a database:
+- Tracks `repositoryRevision` (git commit SHA), `manifestChecksums`, and `lastReconciliation`.
+- Enables instant **Level 0 (0ms)** drift verification on subsequent agent invocations.
+
+### 3. Strict Context Isolation
+- **Project Context (`.ai-engineering-loop/`)**: Shared, living ground truth of engineering rules and architecture.
+- **Task Context**: Transient task contracts, acceptance criteria, and active diff scope.
+- **Loop State**: Ephemeral finding signatures, iteration counters, and retry attempts.
+
+---
+
+## CLI Interface & Commands
+
+The CLI operates against the current working directory without maintaining a centralized project registry.
+
+```bash
+# Bootstrap .ai-engineering-loop/ context from repository discovery
+npx ai-engineering-loop init
+
+# Check the validity, readiness, and baseline freshness of context
+npx ai-engineering-loop status
+
+# Reconcile drifted context against repository non-destructively
+npx ai-engineering-loop refresh
+
+# Verify context readiness and begin engineering loop
+npx ai-engineering-loop run
+```
+
+### Command Responsibilities:
+
+| Command | Purpose | Expected Writes | Mutates App Code? |
+|---|---|---|:---:|
+| **`init`** | Analyzes repository topology, manifests, and test scripts to generate `.ai-engineering-loop/`. | `.ai-engineering-loop/*` | **NO** |
+| **`status`** | Audits the completeness of context files and checks baseline drift (`CURRENT` / `STALE`). | None | **NO** |
+| **`refresh`** | Re-analyzes manifests and surgically updates drifted sections while preserving human notes. | `.ai-engineering-loop/*` | **NO** |
+| **`run`** | Loads verified context and triggers the AI Agent to execute task engineering. | Governed by Task Scope | By Agent |
+
+---
+
+## Antigravity Agent Integration
+
+When working inside the Antigravity IDE or compatible agentic platforms, you can invoke the loop via slash commands:
+
+- **`/ai-engineering-loop init`**: Initialize project context only (non-destructive bootstrap).
+- **`/ai-engineering-loop status`**: Check repository context health & baseline freshness.
+- **`/ai-engineering-loop refresh`**: Reconcile drifted context files non-destructively.
+- **`/ai-engineering-loop [task description]`**: Execute the full 8-stage engineering lifecycle with pre-task drift gate and post-task impact assessment.
+
+---
+
+## Lifecycle Stages
+
+1. **Stage 0: Living Context & Drift Gate ([`core/project-initialization.md`](core/project-initialization.md), [`core/context-refresh-policy.md`](core/context-refresh-policy.md))**:
+   - Check `metadata.json` baseline. If fresh $\rightarrow$ proceed. If missing or drifted $\rightarrow$ reconcile context.
+2. **Stage 1: Goal Contract ([`core/goal-contract.md`](core/goal-contract.md))**: Formulate explicit, testable Acceptance Criteria.
+3. **Stage 2: Root Cause Analysis**: End-to-end data tracing and git commit history examination.
+4. **Stage 3: Implementation Plan**: Structured diff proposal and test plan.
+5. **Stage 4: Maker Execution ([`agents/maker.md`](agents/maker.md))**: Surgical implementation and test engineering.
+6. **Stage 5: Deterministic Verification ([`core/verification-loop.md`](core/verification-loop.md))**: 100% green pass on tests, typechecks, linters, and builds.
+7. **Stage 6: Devil's Advocate Review ([`agents/devil-advocate.md`](agents/devil-advocate.md))**: Layered adversarial critique with concrete alternative diffs.
+8. **Stage 7: Judge & Impact Assessment ([`agents/judge.md`](agents/judge.md), [`core/context-impact-assessment.md`](core/context-impact-assessment.md))**: Impartial verdict (`PASS`/`ITERATE`/`ESCALATE`) followed by Context Impact Assessment (`NONE`/`TARGETED`/`MAJOR`).
+9. **Stage 8: Delivery Pipeline ([`adapters/`](adapters/))**: Automated PR/MR generation, multi-branch propagation, and notification dispatch.
+
+---
+
+## Architecture & 5-Layer Configuration
+
+The system dynamically resolves configuration and review rules through a cascading 5-layer hierarchy:
+
+$$\text{GLOBAL} \longrightarrow \text{ENGINEERING CORE} \longrightarrow \text{PROJECT TYPE PROFILE} \longrightarrow \text{PROJECT CONFIG (`.ai-engineering-loop/`)} \longrightarrow \text{TASK CONTRACT}$$
+
+1. **GLOBAL**: Host execution safety limits and maximum iteration ceilings (`MAX_ITERATIONS <= 5`).
+2. **ENGINEERING CORE**: Universal loop invariants ([Goal Contract](core/goal-contract.md), [Verification Loop](core/verification-loop.md), [Definition of Done](core/definition-of-done.md)).
+3. **PROJECT TYPE PROFILE ([`profiles/`](profiles/README.md))**: Archetype defaults for web applications, backend APIs, mobile apps, libraries, or monorepos.
+4. **PROJECT CONFIGURATION (`<repo>/.ai-engineering-loop/`)**: Target repository ground truth ([`verification.md`](templates/repo-config/verification.md), [`architecture.md`](templates/repo-config/architecture.md), [`conventions.md`](templates/repo-config/conventions.md)).
+5. **TASK CONTRACT**: Active task-scoped acceptance criteria and diff constraints.
+
+---
+
+## Project Profiles
+
+Profiles define technology-specific characteristics and activate relevant review domains for the Devil's Advocate without modifying the core engine:
+
+| Profile | Specification | Target Tech Stack | Active Review Focus |
+|---|---|---|---|
+| **`web-app`** | [web-app.md](profiles/web-app.md) | Next.js, Remix, Vite, React, Vue | DOM rendering, responsiveness (320px–4k), accessibility (a11y/ARIA), client state, Core Web Vitals |
+| **`backend-api`** | [backend-api.md](profiles/backend-api.md) | Go, Node.js, Python, Java, PostgreSQL | Auth/IDOR, database transactions & ACID rollbacks, concurrency locks (`SELECT FOR UPDATE`), N+1 query loops |
+| **`mobile-app`** | [mobile-app.md](profiles/mobile-app.md) | Flutter, React Native, iOS (Swift), Android (Kotlin) | Offline sync queues, OS lifecycle termination & state loss, permission denials, battery/GPS hygiene |
+| **`library`** | [library.md](profiles/library.md) | npm/PyPI packages, SDKs, crates | SemVer public API stability, zero dependency bloat, cross-runtime compatibility, bundle tree-shaking |
+| **`monorepo`** | [monorepo.md](profiles/monorepo.md) | Turborepo, Nx, Cargo/pnpm workspaces | Cross-package boundaries, circular dependencies, affected scope testing, workspace cache invalidation |
+
+Profile index: [profiles/README.md](profiles/README.md).
+
+---
+
+## Repository Structure
+
+```text
+ai-engineering-loop/
+│
+├── README.md                           # Operating system overview & architecture
+├── LICENSE                             # MIT Open Source License
+├── package.json                        # CLI package manifest
+│
+├── bin/                                # CLI execution entrypoints
+│   └── ai-engineering-loop.js          # npx executable CLI (init, status, refresh, run)
+│
+├── scripts/                            # Shell installers
+│   └── init.sh                         # Convenience one-liner installer
+│
+├── core/                               # Generic engineering loop specifications
+│   ├── project-initialization.md       # Auto-discovery & initialization lifecycle
+│   ├── context-refresh-policy.md       # Progressive drift hierarchy & living baseline
+│   ├── context-impact-assessment.md    # Post-task impact assessment (NONE, TARGETED, MAJOR)
+│   ├── goal-contract.md                # Task contract schema & acceptance criteria
+│   ├── verification-loop.md            # Dual-layer verification lifecycle
+│   ├── definition-of-done.md           # 5 pillars of Done & rejection triggers
+│   ├── iteration-policy.md             # Bounded autonomous loop (MAX_ITERATIONS = 3)
+│   ├── escalation-policy.md            # Deterministic human escalation triggers
+│   ├── judge-policy.md                 # Evaluation rules, triage audit, & verdicts
+│   ├── configuration-precedence.md     # 5-layer precedence & conflict resolution
+│   └── repo-config-schema.md           # Schema for target repo .ai-engineering-loop/
+│
+├── profiles/                           # Project archetype profiles
+│   ├── README.md                       # Profile catalog & auto-detection rules
+│   ├── web-app.md                      # Frontend web applications
+│   ├── backend-api.md                  # Backend APIs & microservices
+│   ├── mobile-app.md                   # Native & cross-platform mobile apps
+│   ├── library.md                      # Reusable SDKs & shared packages
+│   └── monorepo.md                     # Multi-package monorepo workspaces
+│
+├── agents/                             # Triad agent role specifications
+│   ├── maker.md                        # Maker agent: surgical diffs & unit tests
+│   ├── devil-advocate.md               # Adversarial reviewer: layered review rules & concrete diffs
+│   └── judge.md                        # Judge agent: neutral magistrate & verdict computation
+│
+├── policies/                           # Operational schemas & algorithms
+│   ├── discovery-safety-policy.md      # Secret protection & non-destructive discovery rules
+│   ├── finding-policy.md               # Standardized finding schema & severity matrix
+│   ├── evidence-policy.md              # 5-level evidence hierarchy
+│   └── no-progress-policy.md           # Finding signature hashing & stagnation detection
+│
+├── adapters/                           # Pluggable delivery pipelines
+│   └── dot/                            # DOT Indonesia delivery adapter
+│       ├── README.md                   # DOT adapter overview
+│       ├── gitlab.md                   # glab CLI, issue cards, & MR generation
+│       ├── multi-branch.md             # main / staging / develop cherry-pick propagation
+│       ├── coreview.md                 # @coreview-bot external review triage (Valid vs Halu)
+│       └── mattermost.md               # Channel mapping & MCP dispatch (from: "AI Agent")
+│
+├── templates/                          # Starter templates for target repositories
+│   └── repo-config/                    # Ready-to-copy .ai-engineering-loop/ files
+│       ├── config.md                   # Project identity & profile binding
+│       ├── architecture.md             # Layers & boundary invariants
+│       ├── conventions.md              # Code standards & forbidden patterns
+│       ├── verification.md             # CLI test/lint/build commands
+│       └── adapter.md                  # Configured release pipeline
+│
+├── examples/                           # End-to-end multi-archetype reference walkthroughs
+│   ├── initialization/                 # Unconfigured Monorepo auto-discovery trace
+│   ├── dot/attendance-confirmation/    # Scenario A: DOT Web Application bugfix & multi-branch MRs
+│   ├── backend-api/payment-idempotency/# Scenario B: Go/PostgreSQL race condition & idempotency fix
+│   └── mobile-app/offline-sync-queue/  # Scenario C: Flutter/SQLite offline sync queue
+│
+└── docs/                               # Meta-documentation & integration guides
+    ├── migration-plan.md               # 8-phase legacy workflow mapping & rationale
+    └── antigravity-feasibility.md      # Antigravity runtime evaluation & subagent orchestration
+```
+
+---
+
+## Reference Examples
+
+- **[Auto-Initialization Trace](examples/initialization/README.md)**: Demonstrates the step-by-step discovery of an unconfigured TypeScript/Go monorepo.
+- **[Scenario A: DOT Web Application](examples/dot/attendance-confirmation/README.md)**: Resolves an attendance status bug across `main`, `staging`, and `develop` with `@coreview-bot` triage and Mattermost dispatch.
+- **[Scenario B: Backend API Service](examples/backend-api/payment-idempotency/README.md)**: Eliminates double-spend race conditions in Go/PostgreSQL with `SELECT FOR UPDATE` and automated race test suites.
+- **[Scenario C: Mobile Application](examples/mobile-app/offline-sync-queue/README.md)**: Implements an offline SQLite mutation queue in Flutter with network flapping tolerance and state preservation.
+
+---
+
+## Contributing
+
+Contributions, feedback, and new adapter profiles are welcome.
+
+1. Fork the repository (`https://github.com/egagofur/ai-engineering-loop/fork`).
+2. Create your feature branch (`git checkout -b feature/new-adapter`).
+3. Ensure all changes adhere to [core/definition-of-done.md](core/definition-of-done.md).
+4. Open a Pull Request.
+
+---
+
+## License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
+
+---
+
+<div align="center">
+Designed for software engineering teams and autonomous AI coding agents.
+</div>

package/adapters/dot/README.md

@@ -0,0 +1,55 @@
+# DOT Ecosystem Delivery Adapter
+
+## 1. Overview & Architecture
+
+The **DOT Delivery Adapter** connects the generic [AI Engineering Loop](file:///Users/egagofur/Development/work/ai-engineering-loop/README.md) to the specific development infrastructure of **DOT Indonesia**.
+
+The generic engineering loop guarantees that code is correct, verified, and adversarially tested. The DOT adapter is responsible for downstream release engineering, collaboration tools, issue tracking, and multi-environment synchronization.
+
+```mermaid
+flowchart TD
+    subgraph CoreLoop [Generic AI Engineering Loop]
+        PASS([Judge Verdict: PASS])
+    end
+
+    subgraph DOTAdapter [DOT Delivery Pipeline]
+        PASS --> Issue[1. GitLab Issue Card via glab]
+        Issue --> BaseMR[2. Base Merge Request via glab]
+        BaseMR --> MultiBranch[3. Multi-Branch Cherry-Pick: staging & develop]
+        MultiBranch --> CoreviewTriage[4. External @coreview-bot Review Triage]
+        CoreviewTriage --> MattermostDispatch[5. Mattermost Markdown Notification via MCP]
+    end
+```
+
+---
+
+## 2. Adapter Modules
+
+The DOT adapter is organized into four dedicated specification modules:
+
+1. **[GitLab Integration (`gitlab.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/adapters/dot/gitlab.md)**:
+   - CLI automation with `glab`.
+   - Standardized issue card templates with actual vs expected tables and QA testing steps.
+   - Standardized MR descriptions linking issue IDs and change summaries.
+2. **[Multi-Branch Propagation (`multi-branch.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/adapters/dot/multi-branch.md)**:
+   - Multi-environment branching model across `main`, `staging`, and `develop`.
+   - Clean cherry-picking workflow and target-specific test verification.
+3. **[Coreview External Reviewer Triage (`coreview.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/adapters/dot/coreview.md)**:
+   - Ingestion of `@coreview-bot` automated PR comments.
+   - Rigorous evaluation of bot suggestions into `VALID` (fix & propagate) vs `HALU` (false positive pushback).
+4. **[Mattermost Notifications (`mattermost.md`)](file:///Users/egagofur/Development/work/ai-engineering-loop/adapters/dot/mattermost.md)**:
+   - Repository-to-channel resolution using persistent configuration.
+   - MCP `mattermost_send_message` dispatch with mandatory `from: "AI Agent"` attribution.
+   - Environment-tagged Markdown blocks (`[MR DEV]`, `[MR STAGING]`, `[MR MAIN]`).
+
+---
+
+## 3. Separation of Concerns
+
+| Generic Core Responsibility | DOT Adapter Responsibility |
+|---|---|
+| Goal Contract & Acceptance Criteria | GitLab Issue Card drafting |
+| Unit testing, typecheck, lint, build | Running DOT-specific scripts (`npx jest --testPathIgnorePatterns="dotify-api"`) |
+| Internal Devil's Advocate Review | External `@coreview-bot` triage on GitLab MRs |
+| Judge verdict & completion certificate | Multi-environment cherry-picking & branch synchronization |
+| Evidence collection & finding logs | Mattermost channel notifications & MR link delivery |

package/adapters/dot/coreview.md

@@ -0,0 +1,88 @@
+# DOT Adapter: Coreview Review Triage (`@coreview-bot`)
+
+## 1. Overview & Role of Coreview
+
+In the DOT ecosystem, `@coreview-bot` operates as an external, company-level automated code reviewer attached to GitLab Merge Requests (specifically MRs targeting `develop`).
+
+> [!IMPORTANT]
+> **We do not have access to `@coreview-bot`'s internal rules or heuristics.**
+> - Do not attempt to reverse-engineer or invent Coreview behavior.
+> - Treat Coreview strictly as an external reviewer providing asynchronous critique on GitLab MRs.
+> - Evaluate its comments objectively through the lens of the repository's ground truth.
+
+---
+
+## 2. Coreview Triage Workflow
+
+```mermaid
+flowchart TD
+    MRDev[MR Targeting develop Created] --> FetchBot[Fetch Comments via glab mr view --comments]
+    FetchBot --> CheckComments{Bot Comments Found?}
+    
+    CheckComments -->|No| Done([Complete Triage])
+    CheckComments -->|Yes| Evaluate{Evaluate Each Comment}
+    
+    Evaluate -->|VALID: Real Defect| Fix[1. Surgical Code Fix<br>2. Run Tests & Linter<br>3. Commit & Cherry-pick to all branches<br>4. Reply with commit hash]
+    Evaluate -->|HALU: False Positive| Halu[1. Do NOT modify code<br>2. Reply on GitLab Note with technical explanation]
+    
+    Fix --> Done
+    Halu --> Done
+```
+
+---
+
+## 3. Step 1: Fetching Bot Comments
+
+After pushing the MR targeting `develop` (`[MR DEV]`), inspect the review comments posted by the bot:
+
+```bash
+glab mr view <mr-id> --comments --repo <repo>
+```
+
+---
+
+## 4. Step 2: Rigorous Evaluation Protocol
+
+Every Coreview comment must be categorized into one of two paths:
+
+### Case A: Feedback is VALID (Real Issue)
+- **Criteria**:
+  - Uncovered a real type mismatch or potential runtime `undefined` / `null` exception.
+  - Identified an unhandled timezone conversion or unused import/variable.
+  - Highlighted a genuine performance or concurrency risk.
+- **Action Plan**:
+  1. Apply the fix surgically to the local working branch.
+  2. Re-run all unit tests and static analysis:
+     ```bash
+     npx jest --testPathIgnorePatterns="dotify-api"
+     npx tsc --noEmit
+     ```
+  3. Commit and push the fix to the branch:
+     ```bash
+     git commit -m "fix(coreview): resolve <issue summary>"
+     git push origin <branch-name>
+     ```
+  4. Cherry-pick the new fix commit to all other active environment branches (`main`, `staging`).
+  5. Post a resolution note on GitLab citing the commit hash:
+     ```bash
+     glab mr note <mr-id> --repo <repo> -m "Fixed in commit <commit-hash>: <technical explanation of the resolution>"
+     ```
+
+### Case B: Feedback is HALU (False Positive / Hallucinated)
+- **Criteria**:
+  - The bot suggests calling an API, library method, or hook that does not exist in the codebase or standard library.
+  - The bot flags intentional architecture or established framework patterns as "errors".
+  - The bot proposes invalid TypeScript syntax or breaks existing type contracts.
+  - The bot misinterprets domain-specific business logic already agreed in the Goal Contract.
+- **Action Plan**:
+  1. **DO NOT modify any code.**
+  2. Post a polite, evidence-backed technical rebuttal on the GitLab note explaining why the suggestion is invalid:
+     ```bash
+     glab mr note <mr-id> --repo <repo> -m "Feedback is invalid / false positive: <detailed technical explanation with file citations>."
+     ```
+
+---
+
+## 5. Anti-Pattern: Blind Compliance
+
+Agents must **never** rewrite working, verified code solely because an automated review bot posted a comment. If the bot's suggestion violates the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md) or introduces broken dependencies, it MUST be triaged as `HALU` with evidence.

package/adapters/dot/gitlab.md

@@ -0,0 +1,128 @@
+# DOT Adapter: GitLab Integration (`glab`)
+
+## 1. Purpose & Scope
+
+This module encapsulates all GitLab operations within the DOT ecosystem. Once a code change has successfully passed the [Generic AI Engineering Loop](file:///Users/egagofur/Development/work/ai-engineering-loop/README.md), this adapter automates issue tracking and Merge Request (MR) generation via the `glab` CLI.
+
+---
+
+## 2. Step-by-Step GitLab Workflow
+
+```mermaid
+flowchart TD
+    Pass([Core Loop PASS]) --> CheckIssue{Issue Exists?}
+    
+    CheckIssue -->|No| CreateIssue[Create GitLab Issue Card via glab]
+    CheckIssue -->|Yes| UseIssue[Capture Existing Issue URL]
+    
+    CreateIssue --> PushBranch[Push Working Branch to Remote]
+    UseIssue --> PushBranch
+    
+    PushBranch --> CreateMR[Create Merge Request via glab]
+    CreateMR --> CaptureMR[Capture MR URL & ID for Multi-Branch / Bot Triage]
+```
+
+---
+
+## 3. Step 1: Git Context & Remote Repository Inspection
+
+1. Check current branch and git status:
+   ```bash
+   git status
+   git log -n 5 --stat
+   ```
+2. Determine repository path and remote URLs:
+   ```bash
+   git remote -v
+   ```
+3. Push working branch to remote:
+   ```bash
+   git push -u origin <branch-name>
+   ```
+
+---
+
+## 4. Step 2: GitLab Issue Card Generation
+
+### A. Check for Existing Issue
+- Look for an existing issue number in:
+  - Branch name (e.g. `issue-235-...`, `fix/300-...`).
+  - Commit message (e.g. `fix(#300): ...`, `Refs #300`).
+  - Search open issues:
+    ```bash
+    glab issue list --repo <repo> --search "<keywords>"
+    ```
+
+### B. Create Standardized Issue Card
+If no issue exists, create one in the designated tracker (e.g. `dot-system/dotify-new` for central Dotify tracker, or the target repository):
+
+```bash
+glab issue create \
+  --repo <target-issue-repo> \
+  --title "[<Module>] <Summary>" \
+  --description "<Issue Description Markdown>" \
+  --assignee <username> \
+  --label "Ready to Test" \
+  --yes
+```
+
+#### Standardized Issue Description Template:
+```markdown
+## Issue Description
+[Detailed description of the bug or feature, explaining root cause and business impact.]
+
+## Scope
+- [x] [Component 1 modified]
+- [x] [Component 2 modified]
+- [x] [Unit tests added in path/to/test.ts]
+
+## Testing Steps
+1. Login as [User Role / Email].
+2. Navigate to [Target Menu / URL].
+3. Perform [Action e.g. submit attendance, clock-in, approve overtime].
+4. Verify [Expected Result].
+
+## Expectation
+| Kondisi / Skenario | Logika Lama (Sebelum) | Logika Baru (Sesudah) |
+|---|---|---|
+| [Scenario 1] | [Incorrect status/error] | [Correct expected status] |
+| [Scenario 2] | [Unhandled edge case] | [Properly handled] |
+
+## Notes
+- Base branch: `<target-base>`
+- Verified with automated test suites.
+```
+
+---
+
+## 5. Step 3: Base Merge Request Creation
+
+Create the primary Merge Request targeting the base branch (`main`, `staging`, or `develop`):
+
+```bash
+glab mr create \
+  --repo <current-repo> \
+  --source-branch <branch-name> \
+  --target-branch <target-branch> \
+  --title "<type>(<scope>): <short description>" \
+  --description "<MR Description Markdown>" \
+  --assignee <username> \
+  --yes
+```
+
+#### Standardized MR Description Template:
+```markdown
+## Issue
+<GitLab Issue URL>
+
+## What did you do?
+- <Concise point 1 explaining root cause fix>
+- <Concise point 2 explaining edge cases handled>
+- <Concise point 3 mentioning unit test coverage>
+
+## Screenshot / Video
+<!-- Attach screenshots, terminal test logs, or UI captures if available -->
+
+## Note for Deployment
+- No manual database migrations required. (or specify migration command if applicable)
+```

package/adapters/dot/mattermost.md

@@ -0,0 +1,102 @@
+# DOT Adapter: Mattermost Notifications
+
+## 1. Overview & Objectives
+
+The **Mattermost Notification Module** formats final release notes and automatically delivers them to designated team channels via the Mattermost MCP server or CLI.
+
+This provides seamless visibility to QA engineers, product managers, and reviewers upon successful completion of the delivery pipeline.
+
+---
+
+## 2. Channel Resolution & Dispatch Flow
+
+```mermaid
+flowchart TD
+    Complete[MRs Created Across Environments] --> CheckMap[Check /Users/egagofur/.gemini/config/mattermost-channel-mapping.json]
+    
+    CheckMap --> Found{Channel Found for Repo?}
+    
+    Found -->|Yes| Dispatch[Dispatch via MCP mattermost_send_message]
+    Found -->|No| PromptUser[Ask User for Target Channel]
+    
+    PromptUser --> SaveMap[Save New Channel to mattermost-channel-mapping.json]
+    SaveMap --> Dispatch
+    
+    Dispatch --> CheckMCP{MCP Success?}
+    CheckMCP -->|Yes| Done([Notification Complete])
+    CheckMCP -->|No / Failed| FallbackCLI[Fallback to Mattermost Agent CLI]
+    FallbackCLI --> Done
+```
+
+---
+
+## 3. Mandatory Attribution Rule
+
+> [!IMPORTANT]
+> When sending messages or replying to threads on Mattermost (via MCP tools or CLI):
+> - **Always** include the sender attribution parameter (`from: "AI Agent"`) in MCP calls:
+>   ```json
+>   {
+>     "channel": "internal-dotify",
+>     "message": "...",
+>     "from": "AI Agent"
+>   }
+>   ```
+> - **Always** include the CLI flag (`--from "AI Agent"`) in CLI calls:
+>   ```bash
+>   node /Users/egagofur/Development/work/kontribusi/mattermost-agent/dist/cli/index.js send <channel> "<message>" --from "AI Agent"
+>   ```
+> - Do not omit or suppress sender attribution.
+
+---
+
+## 4. Channel Resolution Logic
+
+1. **Inspect Mapping File**:
+   Read `/Users/egagofur/.gemini/config/mattermost-channel-mapping.json` using the current repository name or project slug (e.g. `dotify-new`, `dotify-api`, `dot-system/dotify-new`).
+2. **Channel Found**:
+   Dispatch message to the mapped channel name (e.g. `"internal-dotify"`).
+3. **Channel Unknown**:
+   - **DO NOT GUESS** or broadcast to arbitrary channels.
+   - Ask the user to specify the target channel for this repository.
+   - Immediately persist the user's answer into `/Users/egagofur/.gemini/config/mattermost-channel-mapping.json` for future automated runs.
+
+---
+
+## 5. Standardized Mattermost Markdown Report Format
+
+Render separate, ready-to-copy Markdown blocks for every generated Merge Request:
+
+```text
+[MR <ENV_TAG>] <MR_URL>
+Changes log 
+- <Concise change point 1>
+- <Concise change point 2>
+- <Concise change point 3>
+```
+
+### Environment Tags:
+- `[MR DEV]`: Merge Request targeting `develop`.
+- `[MR STAGING]`: Merge Request targeting `staging`.
+- `[MR MAIN]` (or `[MR PROD]`): Merge Request targeting `main` / `master`.
+
+### Example Report:
+```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.
+```