@leejungkiin/awkit 1.7.1 → 1.7.5

package/docs/brainstorm_smart_setup.md

@@ -0,0 +1,113 @@
+# Brainstorming: AWKit Smart Setup & Ecosystem Engine (SAEE)
+
+> **Revision History**
+> | Version | Date | Author | Description |
+> |---|---|---|---|
+> | v1.0.0 | 2026-05-28 | Antigravity Orchestrator | Initial concept proposal for Smart Setup inspired by `claude-code-setup` |
+
+---
+
+## 💡 Bối Cảnh & Cơ Hội
+
+Anthropic vừa ra mắt `claude-code-setup` nhằm tối ưu hóa môi trường lập trình của Claude Code dựa trên phân tích cấu trúc dự án. Đối với **AWKit**, đây là cơ hội tuyệt vời để nâng cấp lệnh `/init` (và lệnh CLI `awkit init/setup`) từ một bộ khung tĩnh thành một **Hệ điều hành thích ứng thông minh (Adaptive Development OS)**.
+
+Thay vì chỉ copy-paste các template tĩnh, AWKit có thể chủ động quét, phân tích và cấu hình toàn bộ hệ sinh thái phù hợp nhất cho dự án của người dùng.
+
+---
+
+## 🎯 5 Trụ Cột Của AWKit Smart Setup (SAEE)
+
+Chúng ta có thể xây dựng tính năng này xoay quanh 5 trục chính:
+
+```mermaid
+graph TD
+    A[Codebase Quét & Phân Tích] --> B(1. Smart Stack Analyzer)
+    B --> C(2. MCP Auto-Recommender)
+    B --> D(3. Adaptive Skill Activation)
+    B --> E(4. Automated Hook System)
+    B --> F(5. Tailored Workflows)
+    C & D & E & F --> G[Cập nhật .project-identity & specs/]
+```
+
+### 1. Smart Stack Analyzer (SSA)
+Bộ quét thông minh phân tích sâu codebase để phát hiện:
+- **Ngôn ngữ & Runtime**: Node.js, Python, Swift, Kotlin, Go, v.v.
+- **Framework & Libraries**: React, Next.js, Expo, UIKit, Jetpack Compose, FastAPI, Express.
+- **Database & Cloud**: Firebase, SQLite, PostgreSQL, Appwrite.
+- **Package Manager**: npm, pnpm, yarn, bun, poetry, swift package manager.
+
+### 2. MCP Auto-Recommender (MCP-AR)
+Đề xuất và tự động thiết lập các kết nối MCP phù hợp với dự án:
+*   *Web/Frontend Apps*: Đề xuất `playwright` cho việc test UI và debug giao diện trực quan.
+*   *Mobile Apps*: Đề xuất `maestro` cho end-to-end testing, `ios-simulator` và `android-cli-plugin`.
+*   *Database & Backend*: Đề xuất `sqlite-mcp-server` hoặc `firebase-mcp-server` khi phát hiện các gói firebase trong dependency.
+
+### 3. Adaptive Skill Activation (ASA)
+AWKit sở hữu hơn 90+ skills chuyên sâu (ví dụ: `expo-build-optimizer`, `swiftui-pro`, `android-aso`, `firebase-firestore`). SAEE sẽ:
+- Nhận diện những skills có ích nhất cho stack hiện tại.
+- Tự động điền các skill này vào mục tiêu của agent để kích hoạt chúng một cách tối ưu, giảm thiểu noise context từ các skill không liên quan.
+
+### 4. Automated Hook System (AHS)
+Thiết lập các quy tắc tự động hóa trong phiên làm việc:
+- **Preflight build hooks**: Tự động chạy `awkit build` trước khi cho phép auto-commit.
+- **Git Hook Automation**: Liên kết với quy tắc *Auto-Commit After Build* (qua `awkit gate git auto`).
+- **Security Check Hook**: Cảnh báo hoặc chặn chỉnh sửa các file nhạy cảm (`.env`, private keys) được định nghĩa sẵn.
+
+### 5. Tailored Workflows & Roles (TWR)
+Tự động tinh chỉnh và nạp các workflows thích ứng:
+- Nếu phát hiện dự án mobile: Tự động nạp `/aso-audit`, `/ios-build`, `/app-store-screenshots`.
+- Nếu phát hiện dự án backend/API: Nạp `/api-test`, `/deploy-app-hosting`.
+- Đề xuất các **Subagents / Roles chuyên dụng** trong `AGENTS.md` (như Security Auditor, UX Reviewer).
+
+---
+
+## 🛠️ Luồng Thực Thi Đề Xuất (Interactive /init Workflow)
+
+Khi người dùng chạy `/init` hoặc CLI `awkit setup`, quy trình sẽ diễn ra như sau:
+
+> [!IMPORTANT]
+> Triết lý thiết kế: **Smart Recommendations, Explicit Approvals**. AI phân tích và đưa ra đề xuất tối ưu, nhưng người dùng luôn giữ quyền quyết định cuối cùng qua UI trực quan.
+
+### 🔄 Chi Tiết Quy Trình 3 Bước
+
+```
+┌────────────────────────────────────────────────────────┐
+│  Bước 1: Quét Codebase & Nhận Diện                     │
+├────────────────────────────────────────────────────────┤
+│  Analyzing package.json, Xcode project, App.tsx...     │
+│  🔍 Tech stack phát hiện: React Native, Expo, Firebase  │
+└──────────────────────────┬─────────────────────────────┘
+                           ▼
+┌────────────────────────────────────────────────────────┐
+│  Bước 2: Brainstorm Đề Xuất Hệ Sinh thái                │
+├────────────────────────────────────────────────────────┤
+│  💡 MCP: Đề xuất kích hoạt maestro, firebase-mcp       │
+│  🎯 Skills: Tự động bật expo-build-optimizer, firestore│
+│  ⚡ Hooks: Bật auto-lint, auto-commit sau build        │
+└──────────────────────────┬─────────────────────────────┘
+                           ▼
+┌────────────────────────────────────────────────────────┐
+│  Bước 3: Ghi nhận & Cấu hình                           │
+├────────────────────────────────────────────────────────┤
+│  ✓ Cập nhật .project-identity                          │
+│  ✓ Khởi tạo specs/PROJECT.md & REQUIREMENTS.md         │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Kế Hoạch Triển Khai (Roadmap)
+
+Chúng ta có thể thực hiện theo mô hình **7-Gate System** của AWKit:
+
+### Phase 1: Infrastructure & Analyzer (🏗️ Gate 4 - Phase A)
+- Phát triển module `scripts/smart-analyzer.js` sử dụng Node.js để phân tích nhanh các file cấu hình dự án (`package.json`, `Gemfile`, `build.gradle`, `Package.swift`).
+- Định nghĩa schema map cho các gợi ý (Stack -> MCPs, Skills, Workflows).
+
+### Phase 2: CLI Integration (🎨 Gate 4 - Phase B)
+- Mở rộng lệnh CLI `awkit setup` và `/init` workflow trong `workflows/lifecycle/init.md`.
+- Xây dựng giao diện CLI interactive đẹp mắt sử dụng `inquirer` hoặc các form UI tương tác của AWKit.
+
+### Phase 3: Actionable Execution (⚡ Gate 4 - Phase C)
+- Hiện thực hóa việc tự động cập nhật `.project-identity` và auto-scaffolding cấu trúc thư mục tối ưu dựa trên phân tích.
+- Tích hợp chặt chẽ với Symphony để tạo bộ task mẫu cho từng stack (ví dụ: Task bootstrap cho Expo).

package/docs/deep-research-report (1).md

@@ -0,0 +1,293 @@
+# Báo cáo phân tích về Fable 5 và thiết kế hệ đa tác tử tương thích Opus 4.8, GPT-5.5 và Gemini
+
+## Tóm tắt điều hành
+
+Bằng chứng mạnh nhất hiện có không cho thấy Fable 5 là một “bầy agent bí mật” thuần túy, mà là một hệ nhiều lớp gồm: mô hình nền rất mạnh, bộ phân loại an toàn đứng ngoài mô hình, cơ chế định tuyến rủi ro sang Claude Opus 4.8, bộ nhớ/sổ ghi chú dài hạn cho tác vụ nhiều bước, và một chương trình trusted access tách biệt cho biến thể ít guardrail hơn là Mythos 5. Anthropic công khai xác nhận Fable 5 và Mythos 5 là “cùng model nền”, rằng các truy vấn thuộc cyber/bio/chem/distillation có thể bị chuyển sang Opus 4.8, và rằng mô hình có thể duy trì hiệu năng trên các tác vụ dài, dùng “own notes”, và làm việc tự trị lâu hơn các Claude trước đó. Project Glasswing cũng cho thấy mô hình có khả năng phân tích, thử nghiệm và tìm lỗi phần mềm theo hướng agentic, nhiều trường hợp “gần như hoàn toàn tự động”. citeturn8view0turn9view0
+
+Tệp người dùng cung cấp trông giống một prompt hệ thống rò rỉ hoặc tổng hợp cho “Claude Fable 5”, với cấu trúc module rất lớn: product info, refusal handling, legal/financial, wellbeing, evenhandedness, knowledge cutoff, memory system, và các chỉ dẫn web-search/product behavior. Nó gợi ý rằng lớp orchestration thực tế không chỉ nằm trong weights của model, mà còn nằm trong prompt stack, policy routing, memory application, và công cụ xung quanh model. Tuy vậy, đây là một artefact chưa được Anthropic xác thực; nên dùng nó như nguồn gợi ý kiến trúc, không phải bằng chứng kết luận. fileciteturn0file0
+
+Nếu mục tiêu là thiết kế một hệ tương đương chạy được trên Claude Opus 4.8, GPT-5.5 và Gemini, giải pháp tốt nhất không phải sao chép prompt rò rỉ, mà là xây một control plane chung theo mô hình **manager–workers–critic–safety router**. Manager nhận yêu cầu, chia việc thành worker đọc/tìm kiếm/kiểm chứng, worker chỉ trả về tóm tắt có cấu trúc thay vì đổ toàn bộ log vào luồng chính, critic so chéo nguồn và phát hiện mâu thuẫn, còn safety router quyết định khi nào phải chặn, hạ cấp, hoặc xin duyệt người vận hành. Mẫu này phù hợp với tài liệu chính thức của cả Anthropic, OpenAI và Google: Anthropic nhấn mạnh explicit tool use, parallel tool calls và kiểm soát subagent; OpenAI công khai hai pattern “handoffs” và “agents-as-tools” cùng cơ chế approvals/state; Google công khai managed agents, collaborative planning, sandbox, MCP, function calling modes và network allowlists. citeturn26view0turn27view1turn27view0turn29view1turn29view2turn29view4turn22view0turn23view0turn20view3turn23view3
+
+Về tương thích nền tảng, Anthropic Opus 4.8 phù hợp làm “deep specialist” cho coding, research và delegated work nếu được hướng dẫn rõ khi nào spawn subagent, khi nào dùng tool, và nếu được cấp budget output đủ lớn ở effort cao. GPT-5.5 phù hợp làm manager hoặc synthesizer nhờ context 1M, max output 128K, tool surface rộng, Agents SDK có handoff/asTool/approval/state khá rõ ràng. Gemini phù hợp cho tác vụ nghiên cứu dài, async và môi trường có tool/mạng cần quản lý chặt, đặc biệt nếu dùng Deep Research Agent hoặc managed Antigravity agent với collaborative planning, MCP và network allowlist. citeturn27view3turn27view1turn17view1turn17view4turn29view1turn29view2turn22view0turn23view0turn23view3
+
+Điểm quan trọng nhất về an toàn là: không dựa vào “một system prompt lớn” để kiểm soát toàn hệ. Các nguồn chính thức và học thuật đều chỉ ra rủi ro ở ba tầng khác nhau: prompt leak, context pollution/context rot, và hạ tầng sandbox/tooling. Vì vậy hệ tương đương phải có guardrail ở **tool boundary**, **approval boundary**, **context boundary**, và **output boundary**; nếu không, càng nhiều subagent càng tăng xác suất rò prompt, lạm dụng tool, viết song song xung đột, hoặc tự tin sai theo kiểu “early commitment” vào giả thuyết sai. citeturn28view0turn30view4turn29view2turn5academia14turn5academia16turn5academia20turn5academia23
+
+## Bằng chứng rò rỉ và các tuyên bố có thể kiểm chứng
+
+Mermaid dưới đây tách các mốc “rò rỉ”, “công bố chính thức” và “tranh cãi công khai” đã xác minh được trong tập nguồn hiện có.
+
+```mermaid
+timeline
+    title Dòng thời gian rò rỉ và công khai liên quan đến Mythos và Fable
+    2026-03-26 : Sự tồn tại của Claude Mythos trở nên công khai do draft blog bị rò rỉ (nguồn thứ cấp)
+    2026-04-07 : Anthropic công bố Project Glasswing và Claude Mythos Preview
+    2026-06-09 : Anthropic công bố Claude Fable 5 và Claude Mythos 5
+    2026-06-10 : Tranh luận công khai về data retention và false positives quanh Fable 5
+    2026-06-12 : Anthropic cập nhật rằng Fable 5 và Mythos 5 bị tạm ngừng truy cập
+    Không rõ ngày : Tệp prompt “Claude Fable 5” do người dùng cung cấp như một artefact rò rỉ
+```
+
+Việc phân loại mức độ tin cậy là rất quan trọng ở chủ đề này. Nguồn **xác minh mạnh** là bài công bố chính thức của Anthropic về Fable 5, Project Glasswing, tài liệu prompt engineering/guardrails chính thức của Anthropic, cùng tài liệu chính thức của OpenAI và Google về orchestration/agents. Nguồn **mạnh vừa** là Reuters, Axios, The Verge, OpenAI/Google docs phụ trợ và vài bài báo học thuật. Nguồn **yếu hơn hoặc chỉ mang tính gợi ý** gồm Wikipedia/các bản mirror thứ cấp về thời điểm lộ Mythos, và tệp prompt rò rỉ do người dùng cung cấp. citeturn8view0turn9view0turn28view0turn16view0turn22view0turn5news3turn2news6turn13news2turn7search17
+
+Bảng dưới đây đối chiếu các tuyên bố “rò rỉ hoặc suy đoán” với phần nào đã được Anthropic hoặc nguồn mạnh xác nhận.
+
+| Tuyên bố | Nguồn rò rỉ / suy đoán | Nguồn xác minh hoặc bác bỏ | Đánh giá |
+|---|---|---|---|
+| Fable 5 và Mythos 5 dùng cùng model nền | Tệp prompt rò rỉ và các thảo luận cộng đồng | Anthropic xác nhận Mythos 5 là “the same underlying model as Fable 5”. citeturn8view0 | **Đã xác minh** |
+| Fable 5 có cơ chế fallback sang Opus 4.8 cho chủ đề rủi ro | Leak và báo chí | Anthropic xác nhận cyber/bio/chem/distillation bị route sang Opus 4.8; Reuters cũng nêu fallback này. citeturn8view0turn5news3 | **Đã xác minh** |
+| Kiến trúc dựa trên nhiều lớp prompt/policy/memory thay vì chỉ model weights | Tệp prompt rò rỉ | Tệp rò rỉ cho thấy prompt stack module hóa; Anthropic docs chính thức cũng có guidance tách prompt engineering, guardrails và memory-style behavior ra khỏi core model. fileciteturn0file0 citeturn26view0turn28view0 | **Hợp lý nhưng chưa xác nhận nội bộ** |
+| Fable 5 vận hành tốt hơn trong công việc dài nhiều bước, dùng ghi chú nội bộ/file memory | Leak và lời đồn “agentic” | Anthropic nói Fable 5 “stays focused across millions of tokens” và cải thiện đầu ra bằng “its own notes”; file-based memory giúp mạnh lên rõ rệt trong Slay the Spire. citeturn8view0 | **Đã xác minh ở mức hành vi** |
+| Claude Code/Fable vận hành các workflow đa agent trong thực tế | Thảo luận cộng đồng | Anthropic trích dẫn phản hồi khách hàng rằng Fable 5 xử lý “complex multi-agent workflows our employees run daily” trong Claude Code. citeturn8view0 | **Đã xác minh gián tiếp** |
+| Fable 5/M Mythos có khả năng cyber agentic rất mạnh, có thể tìm-zero day tự động | Cộng đồng gọi là “too powerful”, “agentic hacker” | Anthropic/Glasswing mô tả Mythos Preview đã tìm hàng nghìn lỗ hổng nghiêm trọng và gần như tự động tìm/khai thác một số lỗi; Reuters và Axios phản ánh tranh cãi công khai quanh khả năng này. citeturn9view0turn5news3turn7news1 | **Đã xác minh ở mức public claims** |
+| Full system prompt trong tệp người dùng là prompt thật cuối cùng của Anthropic | Artefact do người dùng cung cấp | Không có xác thực công khai từ Anthropic; nội dung nên xem như **purported leak / composite artifact**. fileciteturn0file0 | **Chưa xác minh** |
+
+Về “community traces”, trong bộ nguồn đã truy xuất, dấu vết công khai có thể xác minh rõ nhất là: sự tồn tại của Mythos bị lộ do draft/blog leak theo các nguồn thứ cấp; phản ứng công khai sau lệnh đình chỉ Fable/Mythos ngày 13 tháng 6 năm 2026; và một ví dụ X được báo chí ghi lại là Sridhar Vembu bình luận về AI sovereignty sau khi Mỹ hạn chế truy cập Fable 5. Tuy nhiên, tôi **không truy xuất được một cách đáng tin cậy** các thread Reddit/Hacker News/X nguyên bản, giàu chi tiết về kiến trúc sub-agent của Fable 5, trong tập nguồn hiện tại. Điều đó tự nó là một tín hiệu: phần lớn chi tiết kỹ thuật khả tín đang nằm trong bài công bố chính thức và artefact prompt rò rỉ hơn là trong các thread cộng đồng dễ xác minh. citeturn7search17turn7news2turn2news6
+
+## Kiến trúc Fable 5 suy ra từ nguồn chính thức và artefact rò rỉ
+
+Ở mức công khai, Fable 5 có thể được hiểu như một hệ hai lớp rõ ràng. Lớp thứ nhất là model nền rất mạnh, dùng chung với Mythos 5. Lớp thứ hai là “safety router” gồm classifier và chính sách định tuyến: nếu classifier phát hiện truy vấn liên quan tới misuse hoặc jailbreak, đặc biệt ở cyber, biology, chemistry và distillation, truy vấn sẽ không cho main model trả lời trực tiếp mà chuyển sang Claude Opus 4.8. Anthropic còn nói hơn 95% session không bị fallback, cho thấy fallback là guardrail chọn lọc chứ không phải mode mặc định. Họ cũng thừa nhận false positives tồn tại, bug bounty hơn 1.000 giờ vẫn chưa tìm thấy “universal jailbreak”, nhưng không coi việc ngăn universal jailbreak là tuyệt đối khả thi. Đây là kiến trúc “gate + degrade + trusted-access exception”, không phải một prompt đơn lẻ sẽ giải quyết mọi thứ. citeturn8view0
+
+Project Glasswing cho biết Mythos Preview được dùng để tìm và nối các lỗ hổng phần mềm trong những codebase cực lớn và nhạy cảm. Anthropic viết rằng model đã tìm “thousands of high-severity vulnerabilities”, trong một số trường hợp “nearly all” được model phát hiện và phát triển exploit “entirely autonomously”. Đồng thời, Anthropic nói sức mạnh cyber này là hệ quả của “strong agentic coding and reasoning skills”. Nói cách khác, năng lực agentic không phải là lớp ngoài trang trí, mà là phần lõi của sản phẩm. citeturn9view0
+
+Ở tầng prompt/orchestration, artefact rò rỉ cho thấy một bố cục kiểu “modular constitution” với nhiều khối chỉ dẫn: product info, refusal handling, child safety, legal/financial, user wellbeing, political evenhandedness, memory, knowledge cutoff, web-search defaults, v.v. Tệp này còn thể hiện một budget token rất lớn và một phong cách chỉ đạo công cụ có tính vận hành, không chỉ mang tính “chat persona”. Dù chưa thể coi đó là prompt chính thức cuối cùng, nó rất phù hợp với cách các model frontier hiện nay thường được ghép bởi nhiều lớp: **model nền + system stack + policy stack + tool router + memory adapter**. fileciteturn0file0
+
+Anthropic còn xác nhận Fable 5 có bộ nhớ và long-context mạnh hơn đáng kể, có thể “stays focused across millions of tokens” và cải thiện đầu ra bằng “its own notes”. Điều này đặc biệt quan trọng cho thiết kế hệ đa tác tử: nếu manager cố nhồi mọi log và mọi intermediate output vào một luồng duy nhất, hiệu năng sẽ suy giảm. OpenAI mô tả chính hiện tượng này là “context pollution” và “context rot”, và khuyến nghị subagent chỉ đưa trả **summary đã chưng cất** thay vì đổ log thô vào thread chính. Tôi cho rằng đây là manh mối rất mạnh cho cách một hệ kiểu Fable 5 nên được tổ chức: manager giữ context điều hành; worker thực hiện phần “ồn”; chỉ các kết luận đã cấu trúc mới quay lại main thread. citeturn8view0turn30view4
+
+Từ các nguồn chính thức của OpenAI và Google, ta còn thấy một mẫu hội tụ của kiến trúc agent hiện đại. OpenAI phân biệt rất rõ giữa **handoffs** và **agents-as-tools**: nếu specialist nên nắm luôn nhánh hội thoại, dùng handoff; nếu manager vẫn phải chịu trách nhiệm câu trả lời cuối, gọi specialist như tool. Google thì đóng gói managed agent trong một Linux sandbox, cho phép code execution, web browse, file handling, MCP, collaborative planning và background execution. Hai nhà cung cấp khác nhau nhưng cùng hội tụ vào một ý: orchestration hiệu quả là **phân quyền có ranh giới**, không phải thả tự do nhiều agent tranh nhau làm việc. citeturn29view1turn22view0turn23view0
+
+Bảng sau tóm tắt các pattern điều phối có thể suy ra và lý do chúng quan trọng.
+
+| Pattern điều phối | Dấu hiệu từ nguồn | Ý nghĩa kỹ thuật | Failure mode nếu thiếu |
+|---|---|---|---|
+| Safety router ngoài model | Fable classifier + fallback sang Opus 4.8. citeturn8view0 | Giảm rủi ro bằng degrade path thay vì chỉ từ chối | False positive, route nhầm, hoặc bypass classifier |
+| Manager giữ thread chính; worker trả summary | OpenAI mô tả context pollution/context rot; subagent trả distilled takeaways. citeturn30view4 | Bảo vệ context quyết định khỏi log ồn | Context window bị “thối”, chất lượng synth giảm |
+| Parallel read-only workers | Claude docs khuyến nghị parallel tool calls; Codex dùng parallel agents cho exploration/tests/triage; Gemini hỗ trợ parallel function calling. citeturn26view0turn30view4turn20view2 | Tăng tốc mà ít xung đột | Race condition, duplicate work, token burn |
+| Explicit subagent policy | Opus 4.8 spawn ít subagent hơn mặc định; Codex không spawn tự động nếu không yêu cầu. citeturn27view0turn30view4 | Tránh delegation mơ hồ và khó debug | Under-delegation hoặc over-delegation |
+| Resumable state + approvals | OpenAI approvals dùng interruptions + state; Gemini research dài phải background/poll. citeturn29view2turn29view4turn23view0 | Cho workflow dài và side-effect an toàn | Mất trạng thái, chạy lại sai, side-effect không duyệt |
+| Memory qua notes/files, không dựa vào hidden thoughts | Fable dùng own notes; Gemini có thought summaries; OpenAI reasoning tokens không được giữ như transcript hữu ích. citeturn8view0turn21view4turn17view2 | Dùng summary hữu hình làm state chuẩn | Phụ thuộc mù vào hidden reasoning, khó audit |
+
+Hai bài phân tích học thuật gần hơn với phần “giải phẫu rủi ro” cũng đáng chú ý. “Benchmarking Mythos-Linked Bug Rediscovery” cho thấy failure mode phổ biến của model khi làm cyber analysis là **chốt quá sớm vào một ứng viên có vẻ hợp lý nhưng sai**; điều này ủng hộ mạnh cho việc phải có critic/verifier độc lập trong hệ đa agent. “Mythos and the Unverified Cage” thì lập luận rằng ngay cả khi behavior guardrails tốt, hạ tầng sandbox và tool boundary vẫn có thể là điểm vỡ, nên containment phải được xem như một lớp kỹ thuật độc lập cần kiểm chứng. citeturn5academia14turn5academia20
+
+## Hàm ý thiết kế cho hệ tương thích Opus 4.8, GPT-5.5 và Gemini
+
+Tôi hiểu “ChatGPT 5.5” ở đây theo nghĩa model GPT-5.5 trong tài liệu chính thức của OpenAI, vì docs hiện dùng tên model ID là `gpt-5.5` và không nêu một model ID riêng gọi là “chatgpt-5.5”. Với mục tiêu xây một orchestration layer chung, đó là cách hiểu thực dụng nhất. citeturn17view1
+
+Bảng dưới đây là các ràng buộc và đặc điểm thực dụng nhất khi triển khai cùng một workflow trên ba họ model.
+
+| Nền tảng | Ràng buộc và strengths chính | Hệ quả cho workflow |
+|---|---|---|
+| **Claude Opus 4.8** | Anthropic ghi rõ Opus 4.8 có context 1M mặc định, nhưng trên Microsoft Foundry mặc định chỉ 200k; adaptive thinking **không bật mặc định**; với use case coding/agentic nên bắt đầu từ `xhigh` và tối thiểu `high`; nếu chạy `max` hoặc `xhigh` thì nên cấp max output lớn, bắt đầu từ 64k; model thiên về reasoning hơn tool calls, và spawn ít subagent hơn mặc định. citeturn27view3turn27view1turn27view0 | Cần **nói thẳng** khi nào dùng tool, khi nào spawn subagent, khi nào song song, và khi nào không. Opus 4.8 là specialist mạnh, nhưng orchestration tốt phải rất explicit. |
+| **GPT-5.5** | OpenAI docs nêu GPT-5.5 có context 1M, max output 128K, reasoning levels từ `none` tới `xhigh`, tools gồm functions, web search, file search, computer use; reasoning tokens không hiển thị nhưng vẫn tiêu tốn token/context trong lúc chạy; OpenAI khuyến nghị để dành khoảng 25k tokens cho reasoning + outputs khi bắt đầu thử nghiệm. citeturn17view1turn17view2turn17view4 | Rất hợp làm **manager/synthesizer** hoặc orchestrator chính. Cần budgeting token thật chặt, và nên dùng Agents SDK pattern “handoff vs asTool” thay vì prompt mơ hồ. |
+| **Gemini** | Google docs nêu nhiều model Gemini có context 1M+; thinking là dynamic mặc định, có `thinkingLevel`; function calling có các mode `VALIDATED`, `AUTO`, `ANY`, `NONE`; hỗ trợ parallel function calling; managed agents chạy trong Linux sandbox; outbound network mặc định mở, có thể allowlist hoặc disable; Deep Research Agent cần `background=true`, hỗ trợ collaborative planning, MCP và file search. citeturn20view5turn21view4turn20view3turn20view2turn22view0turn23view3turn23view0turn23view1 | Tốt cho **research async**, sandboxed execution và tích hợp tool bên ngoài. Nhưng phải khóa network/tooling chủ động; nếu không, phạm vi hành động mặc định quá rộng cho nhiều use case doanh nghiệp. |
+
+Ba nhà cung cấp cũng cho ba “ngôn ngữ prompt” hơi khác nhau. Anthropic ưu tiên rõ ràng, role setting, XML tags, explicit tool guidance và model-specific tuning; OpenAI nghiêng về kết hợp prompt với orchestration primitives trong SDK; Google cho phép system_instruction, AGENTS.md, SKILL.md, tool modes và collaborative planning. Vì vậy, một base prompt đủ tốt phải ở mức trừu tượng vừa phải, còn các “delta prompt” hoặc runtime adapter mới là nơi tối ưu hành vi đặc thù của từng model. citeturn26view0turn29view1turn23view5turn23view6
+
+Về memory/state, không nên coi hidden reasoning như bộ nhớ có thể tin cậy. OpenAI nói reasoning tokens không được giữ như history hữu ích cho bước sau; Google chỉ cho thought summaries/thought signatures với mục đích hỗ trợ; Anthropic lại nhấn vào “notes” và file-based memory. Vì vậy, mọi workflow nghiêm túc nên chuẩn hóa state ngoài model bằng một **work ledger** hữu hình: plan hiện tại, danh sách worker, kết quả đã xác minh, unresolved questions, citations, và danh sách side-effect pending approval. Đây là điểm quan trọng nhất để hệ chạy qua nhiều turn và nhiều model mà không lệ thuộc vào đặc thù hidden state của từng hãng. citeturn17view2turn21view4turn8view0turn29view4
+
+## System prompt và workflow đề xuất
+
+### Prompt nền tảng đề xuất
+
+Đây là một **prompt gốc mới**, lấy cảm hứng từ các pattern đã xác minh, nhưng không sao chép prompt rò rỉ.
+
+```xml
+<system>
+  <identity>
+    You are an orchestrating research-and-execution agent.
+    Your job is to produce high-quality, verifiable results by coordinating bounded specialist workers.
+  </identity>
+
+  <core_principles>
+    Prefer accuracy over speed when they conflict.
+    Keep the main thread clean: do not dump raw logs, raw tool output, or long exploratory notes into the main conversation.
+    Never rely on hidden chain-of-thought as shared memory. Use explicit summaries, plans, and state objects.
+    Use tools when they materially improve correctness, freshness, or grounding.
+    If the task may cause external side effects or touches high-risk domains, stop and require approval or switch to safe mode.
+  </core_principles>
+
+  <orchestration_policy>
+    First classify the task into one of:
+    research | coding | analysis | retrieval | synthesis | high-risk | mixed.
+    If mixed, decompose into bounded subproblems.
+
+    Create a work plan with:
+    - objective
+    - deliverable format
+    - required evidence
+    - tool budget
+    - approval requirements
+    - context budget
+    - stop conditions
+
+    Spawn specialist workers only when delegation creates clear value:
+    - parallel reading or retrieval
+    - independent comparisons
+    - verification or criticism
+    - large-context partitioning
+    - specialized tooling
+
+    Do not spawn workers for trivial work that can be done directly.
+    Prefer parallel workers for read-heavy tasks.
+    Prefer sequential execution for write-heavy or state-mutating tasks.
+  </orchestration_policy>
+
+  <worker_contract>
+    Every worker receives:
+    - task_id
+    - role
+    - objective
+    - allowed_tools
+    - constraints
+    - dependencies
+    - output_schema
+
+    Every worker must return a structured result:
+    {
+      "task_id": "...",
+      "status": "done|blocked|needs_clarification|unsafe",
+      "summary": "...",
+      "key_facts": [],
+      "evidence": [{"source": "...", "claim": "..."}],
+      "uncertainties": [],
+      "risk_flags": [],
+      "recommended_next_actions": []
+    }
+
+    Workers must return distilled findings, not raw internal reasoning.
+  </worker_contract>
+
+  <verification_policy>
+    For consequential claims, route at least one verifier/critic pass.
+    If sources conflict, surface the disagreement instead of averaging them away.
+    If evidence is weak, say so explicitly.
+  </verification_policy>
+
+  <context_policy>
+    Maintain a visible work ledger:
+    - current_plan
+    - completed_tasks
+    - pending_tasks
+    - verified_facts
+    - open_questions
+    - pending_approvals
+
+    Compact aggressively:
+    - keep requirements, decisions, verified facts, and citations
+    - discard noisy logs after summarizing them
+    - when context is large, summarize each branch before synthesis
+  </context_policy>
+
+  <safety_policy>
+    Never provide disallowed harmful instructions.
+    Place validation at the tool boundary.
+    Require approval before:
+    - file mutation
+    - network actions outside allowlist
+    - transactions
+    - sending messages
+    - executing dangerous code
+    - operating on sensitive data
+    If a request is dual-use or policy-sensitive, respond safely, narrow scope, or route to a safer fallback model.
+  </safety_policy>
+
+  <final_answer_policy>
+    Final answers should contain:
+    - concise executive summary
+    - main findings
+    - uncertainty notes
+    - citations or evidence references
+    - recommended next actions, if useful
+    Provide brief progress updates during long runs, but do not narrate every micro-step.
+  </final_answer_policy>
+</system>
+```
+
+Prompt này bám rất sát những gì cả ba ecosystem đều hỗ trợ tốt: Anthropic thích XML, explicit delegation và tool guidance; OpenAI hỗ trợ manager–specialist boundary rõ ràng; Google hỗ trợ system_instruction + file/skill mounting + collaborative planning. citeturn26view0turn27view1turn27view0turn29view1turn23view5turn23view6
+
+### Workflow điều phối đề xuất
+
+Quy trình thực thi nên đi theo các bước dưới đây.
+
+1. **Intake và phân loại rủi ro.** Manager xác định nhiệm vụ là research, coding, synthesis, mixed hay high-risk; đồng thời đặt deliverable contract và lựa chọn adapter theo model. Với yêu cầu có khả năng mới/động, manager ưu tiên web/retrieval thay vì trả lời từ memory. Điều này phù hợp với rulebooks chính thức của Anthropic, OpenAI và Google về current/fresh information, tools và agent planning. citeturn8view2turn16view0turn22view0
+
+2. **Lập kế hoạch có cấu trúc.** Đối với bài toán lớn, manager tạo plan trước khi chạy. Nếu dùng Gemini Deep Research, có thể bật collaborative_planning để người dùng duyệt plan trước khi execution; với GPT-5.5 hoặc Opus 4.8 không có primitive y hệt, plan này nên được dựng ở application layer bằng một “planning pass” đầu tiên. citeturn23view0turn29view1
+
+3. **Fan-out sang worker read-only hoặc bounded specialists.** Các công việc như đọc nhiều tài liệu, tra cứu nhiều nguồn, tách một corpus dài, hay so sánh nhiều phương án nên được song song hóa; việc sửa file, ghi DB, gửi email hay side-effect khác phải đi tuần tự. Cả Anthropic và OpenAI đều nhấn mạnh giá trị của parallel tool/agent calls cho read-heavy work, còn OpenAI cảnh báo ghi song song dễ tạo xung đột. citeturn26view0turn30view4
+
+4. **Chuẩn hóa kết quả worker.** Mỗi worker chỉ được trả về summary + evidence + uncertainty + risk flags theo schema chuẩn. Không đưa raw chain-of-thought, không đưa toàn bộ command logs lên main thread. Đây là cơ chế giảm context rot mạnh nhất và là điểm then chốt để chạy cùng lúc trên nhiều provider. citeturn30view4turn17view2turn21view4
+
+5. **Critic/verifier pass.** Một worker độc lập hoặc chính manager ở chế độ verifier so chéo các results, tìm mâu thuẫn, phát hiện “early commitment” hay nguồn yếu. Đây là lớp nên có đối với mọi tác vụ mà sai số không chấp nhận được. citeturn5academia14turn29view1
+
+6. **Safety gate và approval gate.** Trước mỗi side effect hoặc khi rơi vào vùng dual-use, workflow dừng ở approval boundary. OpenAI có primitives chính thức cho approvals và resumable state; Gemini có background state trong Interactions/managed agents; với Anthropic cần tự cài ở app/tool layer. citeturn29view2turn29view4turn23view0turn22view0
+
+7. **Synthesis cuối.** Manager tạo câu trả lời cuối từ verified facts và citations, đồng thời lưu work ledger đã compacted cho turn sau. Người dùng chỉ thấy plan đã duyệt, tiến độ ở mức hợp lý, kết quả, uncertainty và references; họ không cần thấy toàn bộ nội bộ reasoning. citeturn29view4turn26view0
+
+```mermaid
+flowchart TD
+    A[Yêu cầu người dùng] --> B[Intake + phân loại rủi ro]
+    B --> C[Lập kế hoạch và budget]
+    C --> D{Cần chia việc?}
+    D -- Không --> E[Manager xử lý trực tiếp]
+    D -- Có --> F[Spawn worker read-only hoặc bounded specialists]
+    F --> G[Worker trả summary có cấu trúc]
+    G --> H[Critic hoặc verifier so chéo]
+    E --> H
+    H --> I{Có side effect hoặc rủi ro cao?}
+    I -- Có --> J[Approval hoặc fallback safe mode]
+    I -- Không --> K[Synthesis cuối]
+    J --> K
+    K --> L[Lưu work ledger đã compact]
+    L --> M[Trả kết quả có chứng cứ]
+```
+
+### Cơ chế fallback và an toàn
+
+Hệ tối thiểu nên có bốn fallback.
+
+Thứ nhất là **capability fallback**: nếu model chính không nên trả lời vì guardrail classifier, do policy, hoặc vì tool surface không phù hợp, route sang model ít quyền hơn nhưng an toàn hơn, đúng tinh thần Fable 5 → Opus 4.8. citeturn8view0
+
+Thứ hai là **context fallback**: khi tiến gần ngưỡng context, thay vì tiếp tục append transcript, hệ buộc compact thành ledger summaries. Điều này đặc biệt quan trọng với GPT-5.5 vì reasoning tokens vẫn ăn budget, và với mọi workflow multi-agent vì context rot. citeturn17view2turn30view4
+
+Thứ ba là **tool fallback**: nếu network không cần thiết, disable mạng; nếu cần, allowlist domain; nếu tool external quá rộng, giới hạn allowed tools hoặc dùng function mode chặt hơn như `VALIDATED` hoặc `ANY` tuỳ mục đích trên Gemini, hay `needsApproval` trên OpenAI. citeturn23view3turn20view3turn29view2
+
+Thứ tư là **leak fallback**: đừng cố giấu mọi thứ bằng một prompt khổng lồ. Thay vào đó, đưa thông tin theo nguyên tắc need-to-know, lọc output sau sinh, và thường xuyên audit prompt/output. Cả Anthropic docs lẫn các paper về PLeak/SysVec đều ủng hộ hướng giảm nội dung nhạy cảm trong prompt và thêm lớp defensive post-processing. citeturn28view0turn5academia16turn5academia23
+
+## Biến thể theo model, ca kiểm thử và kiểm soát rủi ro
+
+### Biến thể prompt theo từng model
+
+| Model | Delta prompt nên thêm | Vì sao |
+|---|---|---|
+| **Claude Opus 4.8** | “Use tools when they materially improve correctness. Spawn subagents only for parallel read-heavy work. At high-complexity tasks, prefer `xhigh` effort. If using adaptive thinking, only trigger it for multi-step reasoning. Provide concise progress updates.” citeturn27view3turn27view1turn27view0 | Opus 4.8 literal hơn, ưu tiên reasoning hơn tool calls, và spawn ít subagent mặc định. |
+| **GPT-5.5** | “The manager stays responsible for the final answer unless a handoff is explicitly required. Prefer specialists as tools for bounded tasks. Keep state resumable. Reserve context headroom for reasoning.” citeturn29view1turn29view4turn17view2 | GPT-5.5 có primitives orchestration tốt nhất ở SDK/runtime; prompt nên bám kiến trúc đó. |
+| **Gemini** | “If the task is large or research-heavy, produce a plan first. Use background execution for long runs. Keep network disabled unless allowlisted. Use collaborative planning when scope is uncertain. Use AGENTS.md/SKILL.md for reusable behavior and tools.” citeturn23view0turn23view3turn23view5turn23view6turn22view0 | Gemini mạnh về async research và managed agent sandbox, nhưng cần kiểm soát network/tooling chặt hơn. |
+
+### Ca kiểm thử khuyến nghị
+
+| Test case | Hành vi mong đợi | Tiêu chí pass |
+|---|---|---|
+| **Deep research có web + tài liệu nội bộ** | Manager lập plan, spawn 2–4 worker: web researcher, document extractor, verifier, synthesizer. Nếu dùng Gemini có thể dùng collaborative planning trước khi chạy. citeturn23view0turn29view1 | Báo cáo có cấu trúc, có citations, nêu rõ uncertainties, không tràn log vào câu trả lời cuối. |
+| **Codebase review read-only** | Worker song song cho security, test gaps, maintainability; không ghi file; critic hợp nhất. Pattern này gần ví dụ chính thức của Codex. citeturn30view4 | Tạo findings theo category, file references rõ, không conflict write. |
+| **Tác vụ có side effect** | Model đề xuất action nhưng dừng ở approval gate; resume từ state sau khi duyệt. citeturn29view2turn29view4 | Không có side effect nào chạy trước approval. |
+| **Truy vấn dual-use hoặc policy-sensitive** | Safety router route sang safe mode hoặc fallback model; không trả hướng dẫn gây hại. Fable 5 dùng chính pattern này với Opus 4.8. citeturn8view0 | Câu trả lời an toàn, có ích ở mức được phép, nêu giới hạn rõ ràng. |
+| **Corpus rất dài** | Chia tài liệu theo shard, mỗi worker trả takeaway + citations, manager chỉ giữ ledger ngắn gọn. citeturn30view4turn20view5 | Không có context collapse, chất lượng synthesis ổn định. |
+
+### Rủi ro, misuse và giảm thiểu
+
+| Rủi ro | Mô tả | Giảm thiểu |
+|---|---|---|
+| **Prompt leak / policy exfiltration** | Worker hoặc user cố kéo lộ system prompt, policy, credentials, hidden instructions. PLeak cho thấy đây là class attack thực. citeturn5academia16turn28view0 | Need-to-know prompts, output screening, prompt audits, không nhét bí mật không cần thiết vào prompt, tách credentials ra khỏi model context. |
+| **Tool abuse / credential overreach** | Managed agent có mạng hoặc tool quá rộng, lạm dụng token/quyền. Gemini mặc định mở outbound network; tool có thể dùng bất kỳ credential được cấp. citeturn22view0turn23view3 | Network allowlist hoặc disable, least-privilege, short-lived tokens, approval on side effects. |
+| **Context pollution / context rot** | Main thread ngập log, stack trace, command output; chất lượng quyết định giảm dần. OpenAI nêu hiện tượng này rất rõ. citeturn30view4 | Worker chỉ trả summary có cấu trúc; context compaction định kỳ; work ledger ngoài model. |
+| **Parallel write conflicts** | Nhiều agent sửa cùng vùng state hoặc codebase. OpenAI khuyên cẩn trọng với write-heavy workflows song song. citeturn30view4 | Chỉ song song cho read-heavy; write theo lock hoặc serialized step. |
+| **Sai tự tin do chốt sớm vào giả thuyết thuận mắt** | Paper bug-rediscovery cho thấy model dễ “early commitment”. citeturn5academia14 | Bắt buộc verifier/critic pass, yêu cầu nêu alternative hypotheses, stress-test nguồn. |
+| **Tin tưởng quá mức vào behavioral safeguards** | Paper về “Unverified Cage” lập luận containment hạ tầng cũng có thể vỡ. citeturn5academia20 | Guardrail ở tool boundary, sandbox boundary, audit logs, formal verification cho infra quan trọng. |
+| **False positives / degraded UX** | Fable guardrails rất chặt, có thể chặn cả yêu cầu lành tính. Anthropic thừa nhận điều này. citeturn8view0turn13news2 | Dùng degrade path thay vì refusal cứng; hiển thị lý do ở mức khái quát; có escalation path cho trusted users. |
+
+## Kết luận và giới hạn còn mở
+
+Kết luận mạnh nhất của nghiên cứu này là: **điểm đáng học từ Fable 5 không phải một “prompt ma thuật”, mà là kiến trúc điều phối nhiều lớp**. Phần cốt lõi có vẻ là frontier model rất mạnh; phần tạo nên sản phẩm vận hành được là safety router, memory discipline, bounded subagenting, structured summaries, resumable state, approvals và tool/network governance. Điều này khớp cùng lúc với Anthropic public materials, với docs mới của OpenAI về handoffs/asTool/state/approvals, và với Google managed agents/Deep Research/collaborative planning. citeturn8view0turn9view0turn29view1turn29view2turn29view4turn22view0turn23view0
+
+Nếu phải triển khai ngay một hệ tương đương đa nền tảng, tôi sẽ chọn **GPT-5.5 làm manager/synthesizer**, **Claude Opus 4.8 làm deep specialist cho coding/analysis**, và **Gemini làm async research runner hoặc sandboxed execution surface**. Nhưng cùng một design vẫn có thể chạy đơn nền tảng nếu giữ được năm bất biến: plan-first, bounded workers, structured worker schema, explicit safety/approval boundaries, và work ledger ngoài model. Đây là phần “portable architecture” thực sự. citeturn17view1turn29view1turn27view3turn23view0turn22view0
+
+Giới hạn chính của báo cáo là hai điểm. Thứ nhất, tôi không xác minh được một bộ thread Reddit/Hacker News/X nguyên bản, giàu chi tiết kỹ thuật về sub-agent coordination của Fable 5, trong tập nguồn đã truy xuất; phần “community trace” vì vậy kém đầy đủ hơn mong muốn. Thứ hai, tệp prompt do người dùng cung cấp rất hữu ích như một artefact, nhưng vẫn là nguồn chưa được xác thực công khai; tôi đã dùng nó như tín hiệu thiết kế, không như chứng cứ kết luận. Dù vậy, ngay cả khi bỏ hẳn artefact này ra, các nguồn chính thức vẫn đủ để suy ra một workflow hệ đa tác tử tương đương, an toàn hơn và portable hơn nhiều so với việc cố tái hiện noe exact leaked prompt. fileciteturn0file0 citeturn8view0turn9view0turn26view0turn29view1turn22view0

package/docs/history/GEMINI.v1.md

@@ -0,0 +1,135 @@
+# GEMINI.md — Antigravity v12.5
+
+> Rules only. Updated: 2026-05-22
+
+---
+
+## Identity
+
+- Bạn là **Antigravity Orchestrator**.
+- Pragmatic. Regression-averse. Symphony-first. Multi-project.
+
+---
+
+## Session Protocol
+
+> [!CAUTION]
+> MỌI session code/debug/plan PHẢI chạy init chain TRƯỚC action. Bỏ qua = vi phạm.
+
+### Init Chain (BẮT BUỘC)
+```
+symphony-orchestrator → awf-session-restore (gitnexus state) → nm-memory-sync → orchestrator → action
+```
+
+- **Ngoại lệ:** Câu hỏi đơn giản hoặc user yêu cầu bỏ qua.
+- **Exit Protocol:** Task done → `symphony next` + present "Next steps" (gồm `🧘 Dừng phiên` nếu ≥3 tasks done hoặc xong Gate lớn). nm-memory-sync auto-save. Deploy/push → check in-progress tasks trước.
+- **Context Recovery:** Re-read `.project-identity`, GEMINI.md, chạy `nmem_recall`, thông báo user.
+- **File-Level Guards:** Khi sửa `symphony/**/*.json`, `.project-identity`, hoặc `**/SKILL.md` → Đọc lại SKILL.md tương ứng.
+
+---
+
+## Rules
+
+### Code
+- Production quality. File < 500 lines.
+- Không sửa code ngoài scope. Không hardcode secrets → `.env`. Không `git reset --hard`.
+- AI models: Gemini 2.5+ hoặc mới hơn. Firebase: Firebase AI Logic SDK.
+
+### Auto-Commit After Build (BẮT BUỘC)
+- Build OK → TỰ ĐỘNG `git add` → `git commit` → `git push`. KHÔNG hỏi user.
+- Commit: conventional format. Push (non-force) SafeToAutoRun=true.
+- Push fail → retry `git pull --rebase && git push` 1 lần. Vẫn fail → báo user, KHÔNG force push.
+
+### Command Wrapper & Build Automation
+- Build: CHỈ dùng `awkit build`. CẤM gọi native (`xcodebuild`, `./gradlew`, `npm run build`).
+- `automation.build.enabled: false` → DỪNG, báo user. KHÔNG fallback native.
+- Thêm params qua `--`: `awkit build -- -destination '...'`. Bypass wrapper = VI PHẠM.
+
+### 7-Gate System
+- Triage: TRIVIAL (→ Gate 4 thẳng) | MODERATE (→ G3+4+5) | COMPLEX (→ all gates).
+- Gates: G1 brainstorm → G1.5 module-spec (COMPLEX+>3mod) → G2 spec-gate → G2.5 visual (skip nếu backend) → G3 symphony-enforcer → G4 execution → G5 verification.
+- **Gate 4 Three-Phase:**
+  - Phase A 🏗️ Infrastructure → B 🎨 UI Shell (mock) → C ⚡ Logic (real data).
+  - COMPLEX+UI: 3 phases bắt buộc. MODERATE+UI: A+C gộp, B optional. TRIVIAL: bypass.
+  - Phase B xong → **DỪNG, chờ "APPROVE UI"**. Gộp B+C = vi phạm.
+  - Mỗi feature Phase C xong → checkpoint user test.
+- Kiro: `.kiro/specs/` → auto-accelerate G1,1.5,2,3.
+- **Gate 2 Claude Planner (New):** Khi Gate 2 (Spec/Architecture Planning) kích hoạt cho MODERATE hoặc COMPLEX tasks, AI tự động chạy `claude-planner` bằng cách gọi `scripts/claude-plan.js`. Nếu Claude CLI chưa cài hoặc hết hạn (lệnh lỗi), AI tự động bỏ qua và sử dụng mô hình hiện tại để lập kế hoạch một cách bình thường.
+- Sửa schema/UI ngoài approved design → ⛔ DỪNG quay G2/2.5.
+- Chi tiết: `orchestrator/SKILL.md` + `symphony-enforcer/SKILL.md`.
+
+### Mindful Stop
+- Iterate ≥3 lần trên 1 feature → DỪNG: "⏸️ Đề xuất commit và trải nghiệm thực tế."
+- Keywords [polish, optimize, refine, tối ưu, tweak] → hỏi "Vấn đề cụ thể? Hay phòng ngừa?" → không rõ → backlog P2.
+- ≥3 tasks done hoặc xong Gate lớn → suggest "🧘 Dừng phiên".
+- KHÔNG tự đề xuất tối ưu trừ security/crash bug.
+
+### NeuralMemory
+- Brain = projectId. PHẢI switch brain TRƯỚC mọi nmem call.
+- `nmem_remember()` tag projectId. Cross-brain: `nmem_recall(query, brains=["default", projectId])`.
+
+### Anti-Yapping & Token Optimization
+- Sau khi dùng tool sửa code → KHÔNG in lại code trong chat. Tóm tắt bằng bullets.
+- Code block trong chat: tối đa 10 dòng. Show diff → dùng `render_diffs()`.
+
+### Image Generation Efficiency
+- Image gen: grid/spritesheet cho batch variants, không gen từng ảnh rời.
+
+### Communication (CAVEMAN ULTRA)
+- Chat: Tiếng Việt, tối đa 1-2 câu ngắn. Code/Docs: Tiếng Anh.
+- CẤM giải thích dài, chào hỏi. Chỉ xuất KẾT QUẢ.
+- Planning artifacts (implementation_plan.md, walkthrough.md) VẪN chi tiết theo format chuẩn.
+- Tài liệu thảo luận & brainstorm (Brief, Requirements, Brainstorm) PHẢI dùng tiếng Việt (hoặc ngôn ngữ giao tiếp của User), chỉ Code/Architecture mới bắt buộc dùng tiếng Anh.
+
+### Brainstorm & Plan Integrity (BPIP)
+- CẤM ghi đè (overwrite) toàn bộ BRIEF.md hoặc plan.md khi tinh chỉnh ý tưởng.
+- PHẢI sử dụng công cụ sửa code (replace_file_content) để cập nhật từng phần.
+- PHẢI duy trì bảng Revision History ở đầu mỗi file design/planning.
+- PHẢI lưu bản sao dự phòng vào `docs/history/` trước khi sửa đổi lớn (định dạng `[filename].v[N].md`, ví dụ: `implementation_plan.v1.md`).
+
+
+### Anti-sycophancy
+- Push back khi approach có vấn đề. Nêu ưu+nhược, không chỉ list ưu điểm.
+- Cảnh báo TRƯỚC khi implement nếu vi phạm best practices. Nói "Tôi không chắc" khi không chắc.
+
+### Safety Guardrails
+- CẤM SafeToAutoRun cho: recursive delete (`rm -rf`), force push, `DROP/DELETE` (no WHERE), docker prune, publish, deploy production.
+- Commit: CHỈ qua `awkit gate git auto`. CẤM `git commit` trực tiếp qua bash.
+- Destructive command → double-confirm user. Không chắc → hỏi trước.
+
+### Mandatory Check-Then-Act Protocol (🔥 BẮT BUỘC)
+- TRƯỚC khi dùng công cụ sửa code/run command lần đầu mỗi task, PHẢI tự trả lời trong `<thought>` (KHÔNG in ra chat):
+  1. Init Chain đã chạy?
+  2. KIẾN TRÚC: Đã xem CODEBASE.md? Đang sửa Definition (gốc) hay Usage (ngọn)? (Cấm grep bừa bãi).
+  3. Sửa symbol lớn? → `gitnexus_impact` trước.
+  4. Commit → `awkit gate git auto` only.
+
+### Decision Principles
+Complete>Shortcuts, Evidence>Assumptions, Standard>Custom, Explicit>Implicit, Test>Trust, Small>Big, Root>Leaves.
+
+### Project Context
+- CODEBASE.md tồn tại → KHÔNG scan raw directory.
+- KHÔNG hỏi user về project structure.
+- CODEBASE.md outdated → ghi chú "⚠️ dùng /codebase-sync".
+
+### Tư Duy Kiến Trúc & GitNexus (Anti-Grep-First)
+- **Top-Down:** LUÔN đọc `CODEBASE.md` trước để map requirement vào đúng Layer kiến trúc.
+- **Root > Leaves:** Đổi GIÁ TRỊ → Tìm Definition (gốc: theme, config, entity). CẤM grep blind value ở Usage (ngọn).
+- **GitNexus Graph:** Có Anchor Class → `gitnexus_context` để hiểu luồng, `gitnexus_impact` TRƯỚC KHI sửa.
+- `.gitnexus/` tồn tại → BẮT BUỘC dùng GitNexus. `gitnexus_detect_changes()` trước commit.
+- Chi tiết: `gitnexus-intelligence/SKILL.md`.
+
+### Kiro Specs
+- `.kiro/specs/` tồn tại → source of truth: requirements.md (G1+1.5 AUTO-PASS), design.md (G2 AUTO-APPROVE), tasks.md (G3 AUTO-IMPORT).
+- Gate 4 code PHẢI đối chiếu `.kiro/specs/<module>/`. Chi tiết: `orchestrator/SKILL.md`.
+
+---
+
+## Routing
+
+- **Execution order:** `symphony-orchestrator` → `awf-session-restore` (gitnexus state) → `nm-memory-sync` → `symphony-enforcer` → `orchestrator` (triage + gate-check) → action
+- **Gate skills:** `orchestrator` (triage) → `brainstorm-agent` (G1) → `module-spec-writer` (G1.5) → `spec-gate` (G2) → `visual-design-gate` (G2.5) → `symphony-enforcer` (G3) → `verification-gate` (G5)
+- **Code intelligence:** `gitnexus-intelligence` (impact analysis, blast radius, safe refactoring)
+- **Skill catalog:** xem `orchestrator/SKILL.md`
+- **Workflows:** 75+ (`/xxx`). Core: `/init` `/code` `/debug` `/recap` `/next` `/todo` `/gitnexus`
+- **Shortcuts:** `/todo` `/done` `/next`

package/docs/history/PRD.v1.md

@@ -0,0 +1,55 @@
+# Product Requirements Document (PRD) — MemoizedFibonacci
+
+## Revision History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0 | 2026-06-22 | Antigravity Orchestrator | Initial draft for MemoizedFibonacci feature. |
+
+---
+
+## 1. Vision & Objectives
+
+* **Project Summary:** The `MemoizedFibonacci` feature provides a highly optimized, high-performance utility class/module for calculating Fibonacci sequences. It leverages an advanced caching (memoization) mechanism to avoid the exponential time complexity $O(2^n)$ associated with naive recursive methods, turning sequence generation into a linear time $O(n)$ or constant-time $O(1)$ operation for subsequent lookups.
+* **Problem Statement:** Standard recursive calculations of Fibonacci numbers quickly exhaust CPU resources and crash due to call stack size limits or integer overflows when $n \ge 79$ in standard floating-point representation. Naive memory caches can also grow indefinitely, leading to memory leaks in server environments.
+* **Target Audience:** Core application developers, backend engineers running mathematical modeling services, and background agents requiring sequence calculations.
+
+---
+
+## 2. Core Principles & Philosophy
+
+* **Performance & Scalability:** Constant lookups $O(1)$ for cached values, linear complexity $O(n)$ for first-time calculations.
+* **Robustness & Accuracy:** Complete support for `BigInt` calculations to prevent integer overflow beyond JS safe limit ($n > 78$).
+* **Memory Safety & Self-Regulation:** Integrated Least Recently Used (LRU) cache eviction strategy to guarantee a fixed maximum memory footprint.
+* **Non-Blocking Operation:** Heavy calculations ($n \ge 100,000$) must run asynchronously (chunked loops or offloaded execution) to prevent thread/event-loop blockage.
+
+---
+
+## 3. Scope & Feature List
+
+### In Scope
+* **Multiple Calculation Modes:** Synchronous calculations for small inputs; asynchronous (non-blocking) computation for larger values.
+* **Flexible Precision:** Standard JS numbers for fast calculations ($n \le 78$) and `BigInt` for arbitrarily large numbers.
+* **LRU Caching Strategy:** A bounded in-memory cache that automatically evicts least recently accessed Fibonacci numbers when the maximum cache capacity is reached.
+* **Cache Metrics:** Reporting of cache metrics such as hit rate, miss rate, current size, and eviction count.
+* **Resource Guardrails:** Hard limits on inputs to prevent CPU exhaustion.
+
+### Out of Scope
+* **Negative/Fractional Fibonacci:** No support for negative numbers or fractional inputs (standard integer sequence only).
+* **Distributed Cache integration:** No built-in Redis/Memcached integration (limited to localized, bounded memory cache with extensible hooks).
+
+---
+
+## 4. Key Performance Indicators (KPIs)
+
+* **Execution Time (Cached):** Sub-microsecond response time for any cached value.
+* **Execution Time (Uncached):** Linear scaling $O(n)$. Computing $F(10000)$ uncached must complete in under 5 milliseconds.
+* **Call Stack Safety:** Zero recursion-based Call Stack Size Exceeded errors.
+* **Memory Limit:** Strict enforcement of maximum cache entries (e.g. defaults to 1,000 values), keeping peak memory consumption under 25MB even for large BigInts.
+
+---
+
+## 5. Anti-Patterns (What NOT to do)
+* Do not use recursive calls without tail call optimization or loop conversion. Recursion is forbidden for calculations.
+* Do not store calculated BigInt values as standard floats since precision is lost.
+* Do not allow the cache size to grow indefinitely (bounded cache is mandatory).