690529:1702 ADR-030-230 context aware #09

2026-05-29 17:02:12 +07:00
parent 8367ced926
commit f33487f511
9 changed files with 1774 additions and 12 deletions
@@ -1,29 +1,47 @@
-# ADR-031: NAP-DMS Integration Strategy (Hermes Agent & Telegram Bridge)
+# ADR-031: Hermes Agent — Autonomous Dev Orchestrator & Telegram DevOps Bridge (v2.0)

 ## Status

 - **Status:** Draft
 - **Date:** 2026-05-28
+- **Version:** 2.0 (2026-05-29 — grill-with-docs: Orchestration as primary concern)
 - **Deciders:** NAP-DMS Architecture Team
+- **Supersedes:** ADR-031 v1.1 (DevOps Bridge only)

-### Locked Decisions During Grill
+### Locked Decisions (v1.x — DevOps Bridge Foundation)

-ข้อตกลงด้านล่างถูกล็อคระหว่าง grill session แล้ว แต่ ADR-031 ยังอยู่ในสถานะ Draft จนกว่า scope และ rollout plan จะ stable:
+ข้อตกลงด้านล่างถูกล็อคตั้งแต่ v1.x และยังคงบังคับใช้ใน v2.0:

-* **Hermes role:** Hermes เป็น Developer Operations Agent / Integration Assistant เท่านั้น ไม่ใช่ production DMS service และไม่ใช่ AI inference boundary ของ DMS
-* **Database access:** Hermes เชื่อม MariaDB ได้เฉพาะ read-only account หรือ read-only replica สำหรับ schema inspection, metadata diagnostics, และ query verification เท่านั้น
-* **Document storage:** Hermes ห้าม mount, browse, หรืออ่าน permanent document storage ของ production โดยตรง หากต้องตรวจเอกสารจริงต้องผ่าน DMS Backend API
+* **Hermes role:** Hermes เป็น Developer Operations Agent / Autonomous Dev Orchestrator ไม่ใช่ production DMS service และไม่ใช่ AI inference boundary ของ DMS
+* **Database access:** Hermes เชื่อม MariaDB ได้เฉพาะ read-only account สำหรับ schema inspection, metadata diagnostics เท่านั้น
+* **Document storage:** Hermes ห้าม mount, browse, หรืออ่าน permanent document storage ของ production โดยตรง
 * **Telegram scope:** Hermes Telegram ใช้สำหรับ DevOps commands เท่านั้น ไม่ใช่ production DMS command channel
-* **DMS Telegram:** Telegram command สำหรับ query/mutate เอกสารจริงเป็น future separate ADR/spec และต้อง enforce ADR-009/016/019/023A
-* **Hermes proxy:** `hermes proxy` เป็น Developer AI Proxy only สำหรับ coding/devops assistance ไม่ใช่ DMS AI runtime หรือ document intelligence path
-* **Telegram writes:** Telegram write actions ต้องมี explicit confirmation; forbidden actions เช่น push ไป `main`/`master`, production deploy, schema migration execution, direct DB writes, และ storage delete ห้ามทำผ่าน Telegram
-* **Schema rollout:** ADR-031 rollout ไม่เพิ่มหรือแก้ production DMS schema รวมถึงไม่สร้าง `user_telegram_mapping`
+* **DMS Telegram:** Telegram command สำหรับ query/mutate เอกสารจริงเป็น future separate ADR/spec
+* **Hermes proxy:** `hermes proxy` เป็น Developer AI Proxy only ไม่ใช่ DMS AI runtime
+* **Telegram writes:** ต้องมี explicit confirmation; push `main`/`master`, production deploy, schema migration, direct DB writes, storage delete ห้ามทุกกรณี
+* **Schema rollout:** ADR-031 ไม่เพิ่มหรือแก้ production DMS schema
+
+### Locked Decisions (v2.0 — Orchestration Layer)
+
+ข้อตกลงใหม่จาก grill session 2026-05-29:
+
+* **Cloud AI Exception:** Hermes Orchestrator layer อนุญาต Cloud AI API (Claude/GPT-4o) ได้ — เป็น exception จาก ADR-023A ที่ใช้เฉพาะ DevOps/Dev Orchestration layer เท่านั้น ไม่ใช่ DMS document processing
+* **Data Classification (Dev-Out Policy):** Code, Config, ADR, Stack trace ส่ง Cloud AI ได้ — Production runtime data จาก DB query (document content, user info, project business data) ห้ามส่งออกทุกกรณี
+* **Dev Qdrant:** Separate Qdrant instance บน ASUSTOR สำหรับ codebase embedding โดยเฉพาะ — ห้ามใช้ Qdrant instance เดียวกับ DMS document RAG (ADR-023A)
+* **SOUL.md:** Hermes working journal อยู่ใน container เท่านั้น (`/volume1/docker/hermes/SOUL.md`) ไม่ sync กลับ repo
+* **Context Source:** Hermes ดึง project context จาก `specs/06-Decision-Records/CONTEXT-ADR-031.md` + `AGENTS.md` โดยตรง ไม่ใช้ Obsidian หรือ external knowledge base
+* **Sub-agent Delegation:** Hermes orchestrate โดย (1) Cloud sub-agents ใช้ model เล็กกว่า (Claude Haiku/GPT-4o-mini) สำหรับ code generation tasks และ (2) MCP invocations ไปยัง Windsurf/agy ที่มีอยู่แล้ว
+* **Git Identity:** Hermes ใช้ Gitea service account (`hermes-bot`) push เฉพาะ `hermes/*` branches — ห้าม push ตรง `main`/`develop` ทุกกรณี — ทุก change ต้องผ่าน PR ที่ human approve

 ## Context

-การตั้งค่าระบบ **Hermes Agent** ในโปรเจกต์ **NAP-DMS (LCBP3)** เวอร์ชัน 1.9.0 เพื่อเชื่อมต่อกับโครงสร้างพื้นฐานเดิมและขยายขีดความสามารถผ่าน Telegram Bridge สำหรับการแจ้งเตือนและการสั่งงานผ่านระบบ Command
+การตั้งค่าระบบ **Hermes Agent** ในโปรเจกต์ **NAP-DMS (LCBP3)** เพื่อทำหน้าที่เป็น **Autonomous Development Loop Orchestrator** — ควบคุมงาน AI Coding ทั้งหมด วาง Roadmap จ่ายงานให้ sub-agents ตรวจสอบผลลัพธ์ และสร้าง PR สำหรับ human review

-Hermes Agent ถูกนิยามเป็น **Developer Operations Agent / Integration Assistant** สำหรับงานพัฒนา, ตรวจสอบ, ประสานเครื่องมือ, และช่วยสั่งงาน DevOps เท่านั้น ไม่ใช่ production DMS service และไม่ใช่ AI inference boundary ของ DMS ตาม ADR-023/ADR-023A
+ใน v2.0 Hermes มี 2 primary roles:
+1. **Autonomous Dev Orchestrator** (primary) — คุม development loop ตั้งแต่ requirement จนถึง PR
+2. **Telegram DevOps Bridge** (subsystem) — DevOps commands, CI status, Gitea notifications
+
+Hermes ไม่ใช่ production DMS service และไม่ใช่ DMS AI inference boundary (ADR-023/ADR-023A) แต่ได้รับ **Cloud AI exception** สำหรับ dev orchestration layer โดยเฉพาะ พร้อม Data Classification Policy ที่ชัดเจน

 ## Decision

@@ -58,6 +76,166 @@ Hermes Agent ถูกนิยามเป็น **Developer Operations Agent /

 ---

+## Orchestration Architecture (v2.0 — Primary Concern)
+
+### Overview: Autonomous Development Loop
+
+Hermes ทำหน้าที่เป็น "Lead Developer" / "Conductor" ที่คุม development loop ทั้งหมด โดยไม่ลงไปเขียนโค้ดทุกบรรทัดเอง แต่วางแผน จ่ายงาน ตรวจสอบผลลัพธ์ และสร้าง PR:
+
+```
+[Developer / Telegram Command]
+        │
+        ▼
+┌─────────────────────────────────────────┐
+│  Hermes Orchestrator (Flagship Cloud AI) │
+│  Claude / GPT-4o                         │
+│  Context: CONTEXT-ADR-031.md + AGENTS.md │
+│  Memory:  SOUL.md (container-local)      │
+│  Search:  Dev Qdrant (ASUSTOR)           │
+└──────────┬──────────────────────────────┘
+           │
+   ┌───────┴────────┐
+   ▼                ▼
+[Cloud Sub-agents]  [MCP Tool Invocations]
+Claude Haiku /      Windsurf / agy / Codex
+GPT-4o-mini         (existing tools, no new models)
+   │                ▼
+   └────────┬───────
+            ▼
+   [Self-Correction Loop]
+   npm run lint / jest / tsc
+   → Error? Re-delegate to sub-agent
+   → Pass? Continue
+            │
+            ▼
+   [Git: hermes/* branch]
+   hermes-bot commits
+   Creates PR → Human Review & Approve
+```
+
+### Step 1: Requirement & Context Assembly
+
+Hermes โหลด context แบบ **selective** ตาม task type เพื่อลด token ที่ส่งไป Cloud AI:
+
+| Task Type | Context ที่โหลด |
+|-----------|----------------|
+| DevOps / CI / Git | `CONTEXT-ADR-031.md` + `AGENTS.md` |
+| DMS feature coding | `CONTEXT-ADR-031.md` + `AGENTS.md` + `CONTEXT.md` |
+| Schema / DB work | `CONTEXT-ADR-031.md` + `AGENTS.md` + `CONTEXT.md` + schema SQL (read-only) |
+| Bug fix / refactor | `CONTEXT-ADR-031.md` + `AGENTS.md` + Dev Qdrant (code patterns) |
+
+**Sources:**
+- `specs/06-Decision-Records/CONTEXT-ADR-031.md` — agent rules, project identity, tooling, infra paths
+- `CONTEXT.md` (root) — domain terminology (Correspondence, RFA, Workflow Engine, AI concepts) — โหลดเฉพาะ DMS feature tasks
+- `AGENTS.md` — TypeScript rules, forbidden patterns (no `any`, no `parseInt` on UUID), ADR references
+- Dev Qdrant (ASUSTOR) — semantic code search หา reference patterns จาก codebase embeddings
+
+**ห้ามดึง** production runtime data (DB query results, document content, user data) เข้า cloud AI context
+
+### Step 2: Semantic Code Search (Dev Qdrant)
+
+Hermes ใช้ Qdrant instance แยก (บน ASUSTOR, ไม่ใช่ DMS Qdrant) ทำ semantic search หา reference patterns ใน codebase:
+
+```yaml
+# docker-compose.hermes-qdrant.yml (ASUSTOR — แยกจาก DMS)
+services:
+  hermes-qdrant:
+    image: qdrant/qdrant:latest
+    container_name: hermes-qdrant
+    volumes:
+      - hermes_qdrant_data:/qdrant/storage
+    ports:
+      - "6334:6333"   # port แยกจาก DMS Qdrant (:6333)
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+```
+
+Collection: `lcbp3_code_chunks` — indexed by `repoName` + `moduleName` (ไม่ใช่ `projectPublicId` ซึ่งเป็น DMS document isolation)
+
+### Step 3: Sub-agent Delegation
+
+Hermes แตกงานเป็น tasks แล้ว delegate ผ่าน 2 channels:
+
+**Channel A — Cloud Sub-agents (Code Generation):**
+```
+Orchestrator (Claude/GPT-4o)
+  → "เขียน NestJS service สำหรับ X"
+  → Sub-agent (Claude Haiku / GPT-4o-mini)
+  → Returns code diff
+  → Orchestrator validates against AGENTS.md rules
+```
+
+**Channel B — MCP Tool Invocations (File Execution):**
+```
+Orchestrator
+  → MCP hermes-tools: bash/git operations บน ASUSTOR
+  → MCP mariadb: schema lookup (read-only)
+  → MCP gitea: PR/issue management
+  → Triggers Windsurf/agy ถ้า complex scaffolding needed
+```
+
+**Data Classification Enforcement:**
+| ส่งได้ | ห้ามส่ง |
+|--------|---------|
+| Code snippets, patterns | Production DB query results |
+| ADR/spec content | Document content (title, body) |
+| Stack traces, error output | User data, project names from DB |
+| Config files, tsconfig | API keys, tokens, passwords |
+| Schema structure (column names) | Storage paths ที่มี PII |
+
+### Step 4: Self-Correction Loop
+
+โค้ดที่ sub-agent ส่งกลับมาต้องผ่าน validation ก่อนใช้:
+
+```bash
+# Hermes runs via MCP hermes-tools
+npm run lint          # ESLint — ต้องผ่านทุก rule
+npx tsc --noEmit      # TypeScript strict mode
+npm test -- --passWithNoTests  # Jest tests ที่เกี่ยวข้อง
+```
+
+ถ้าพบ error → Hermes วิเคราะห์ output → ส่งกลับให้ sub-agent แก้ไข (max 3 iterations)
+ถ้า iteration > 3 → หยุดและแจ้ง developer ผ่าน Telegram
+
+### Step 5: Git Identity & PR Flow
+
+```
+hermes-bot commits → hermes/feat-{task-id} branch
+  ├─ git config user.name "Hermes Bot"
+  ├─ git config user.email "hermes-bot@np-dms.work"
+  ├─ commit message: "feat(hermes): {task description}\n\nOrchestrated by Hermes ADR-031 v2.0"
+  └─ push → Gitea → Create PR → assign to developer
+```
+
+**Git Identity Rules:**
+- Service account: `hermes-bot` (Gitea, least privilege, write token เฉพาะ feature branches)
+- Branch pattern: `hermes/feat-*`, `hermes/fix-*`, `hermes/refactor-*`
+- ห้าม push ตรง `main`, `develop`, `release/*` ทุกกรณี
+- PR ต้องผ่าน CI (lint + test) ก่อน merge
+- Human ต้อง review และ approve ก่อน merge เสมอ — ห้าม auto-merge
+
+### SOUL.md — Hermes Working Journal
+
+`/volume1/docker/hermes/SOUL.md` เก็บ per-session working memory ของ Hermes:
+
+```markdown
+## Session 2026-05-29T10:30
+Task: scaffold correspondence search feature
+Context loaded: CONTEXT-ADR-031.md, backend/src/modules/correspondence/
+Sub-agents delegated: 2 code generation calls
+Iterations: 1 (lint pass first try)
+PR created: hermes/feat-correspondence-search → #142
+Status: DONE
+```
+
+- ไม่ commit ลง repo — อยู่ใน container volume เท่านั้น
+- Hermes อ่าน SOUL.md ต้น session เพื่อ resume context
+- Rotate ทุก 30 วัน หรือ manual clear
+
+---
+
 ## Implementation Details

 ### 1. Infrastructure Configuration
@@ -801,6 +979,7 @@ ADR-031 ต้อง rollout แบบเป็น stage เพื่อลด
 - ADR-016: Security & Authentication
 - ADR-019: Hybrid Identifier Strategy (UUIDv7)
 - ADR-023/ADR-023A: Unified AI Architecture และ AI isolation boundary
+- ADR-031 v2.0: Cloud AI exception สำหรับ Hermes dev orchestration layer (ดู Locked Decisions v2.0)

 ---

@@ -812,3 +991,5 @@ ADR-031 ต้อง rollout แบบเป็น stage เพื่อลด
 | 2026-05-28 | 1.1.0 | Added sections 4–6 from CONTEXT-ADR-031-Added-2: Hermes Interface Modes, agy+Hermes MCP Integration, Deploy Prerequisites; fixed port conflict (hermes proxy :8766, not :8765) |
 | 2026-05-29 | 1.1.1 | Aligned with CONTEXT-ADR-031.md grill-with-docs: fixed monorepo structure (flat layout), corrected file paths, updated repo URL to git.np-dms.work, added AGENTS.md v1.9.7 reference |
 | 2026-05-29 | 1.1.2 | Linked root CONTEXT.md with specs/CONTEXT-ADR-031.md; fixed setup-context.sh paths; updated Windsurf/agy/Hermes symlink targets |
+| 2026-05-29 | 2.0.0 | **v2.0 Rewrite** — grill-with-docs: Orchestration as primary concern; Added Autonomous Dev Loop architecture; Cloud AI exception (Data Classification Policy C); Separate Dev Qdrant on ASUSTOR; SOUL.md container-local journal; Sub-agent delegation (Cloud+MCP); Git identity hermes-bot + hermes/* branches + PR-only flow |
+| 2026-05-29 | 2.0.1 | Step 1 context assembly: เพิ่ม `CONTEXT.md` (root domain terminology) เป็น selective context source สำหรับ DMS feature coding และ Schema/DB work tasks |