hivemind-context-governance 2.6.0 → 2.6.1

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `experimental.chat.messages.transform` hook with stop-checklist injection and continuity context enrichment (`<anchor-context>`, `<focus>`)
+- Session boundary manager (`src/lib/session-boundary.ts`) with lifecycle warning integration and checklist-boundary recommendation
+- Non-disruptive SDK session rollover after compaction (`client.session.create`) with non-fatal fallback behavior
+- Task manifest persistence for `todo.updated` events into `.hivemind/state/tasks.json`
+- Optional `auto_commit` governance flow for file-changing tools (`write`, `edit`, `bash`) with new auto-commit helpers
+
 ### Fixed
 - `export_cycle` now synchronizes flat `brain.hierarchy` projection after tree mutations, eliminating hierarchy/tree desync after subagent exports
 - `declare_intent` no longer overwrites per-session files with legacy active template content; legacy `active.md` is updated separately for backward compatibility
@@ -24,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 - `README.md` fully rewritten: coherent install-to-runtime flow, upgrade guidance, troubleshooting, and expanded Vietnamese section focused on practical onboarding
+- `README.md` refreshed for Phase B: hook count/tool catalog accuracy, merged tool names, and new governance capabilities
 
 ## [2.6.0] - 2026-02-12
 

package/README.md

@@ -5,11 +5,13 @@
 HiveMind is an [OpenCode](https://opencode.ai) plugin that prevents AI agents from drifting, forgetting, and losing coherence during long coding sessions. It enforces a simple backbone — *declare what you're doing, track as you go, archive when done* — and connects every piece into one unified system.
 
 ```
-14 tools · 5 hooks · 5 skills · 3 slash commands · interactive CLI · Ink TUI dashboard · EN/VI
+10 tools · 6 hooks · 5 skills · 3 slash commands · interactive CLI · Ink TUI dashboard · EN/VI
 ```
 
 [![npm version](https://img.shields.io/npm/v/hivemind-context-governance)](https://www.npmjs.com/package/hivemind-context-governance)
 
+**Found this useful?** [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-orange?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/shynlee04l)
+
 ---
 
 ## The Problem
@@ -27,19 +29,25 @@ Without governance, long AI sessions decay:
 
 ---
 
-## Quick Start
+ ## Quick Start
 
-### 1. Install
+### One Command - That's It
 
 ```bash
-npm install hivemind-context-governance
+npx hivemind-context-governance init --mode assisted
 ```
 
-### 2. Initialize (Interactive Wizard)
+**What happens (guaranteed):**
+1. Downloads from npm automatically (no manual install needed)
+2. Creates `.hivemind/` directory with brain.json, config.json
+3. Registers plugin in `opencode.json` (so OpenCode auto-loads it)
+4. Syncs commands/skills into `.opencode/`
+5. Creates session template files
+6. Opens a session in `OPEN` mode (assisted) or `LOCKED` mode (strict)
 
-```bash
-npx hivemind-context-governance
-```
+**Works on any machine, any project. No exceptions.**
+
+### Verify Installation (Optional)
 
 The wizard walks you through step by step:
 
@@ -60,21 +68,52 @@ The wizard walks you through step by step:
 │  ○ guided   — Suggestions only
 │  ● assisted — Balanced automation (recommended)
 │  ○ full     — Maximum automation
-│  ○ retard   — Maximum handholding, skeptical of everything
+│  ○ coach    — Maximum handholding, skeptical of everything
 
 ◆  Configuration saved! .hivemind/ created.
 ```
 
-### 3. Non-Interactive Alternative
+### Non-Interactive Alternative
 
 ```bash
 npx hivemind-context-governance init --mode strict --lang vi --automation full
 ```
 
-### 4. Open OpenCode
+This does **exactly the same** as the interactive wizard:
+- Creates `.hivemind/` structure
+- Registers plugin in `opencode.json` 
+- Syncs OpenCode assets
+- Initializes brain state with your chosen settings
+
+### Verify Installation
+
+After running `init`, verify everything is set up:
+
+```bash
+npx hivemind-context-governance status
+```
+
+Or manually check `opencode.json` contains:
+```json
+{
+  "plugin": ["hivemind-context-governance"]
+}
+```
+
+### Open OpenCode
 
 That's it. The plugin auto-activates. The AI agent gets governance context injected into every turn.
 
+**Important:** If you run `init` again on an existing project, it will:
+- Keep your existing `.hivemind/` state
+- Refresh OpenCode assets
+- Ensure plugin is still registered in `opencode.json`
+
+**How it works:**
+- `init` automatically registers `hivemind-context-governance` in `opencode.json`'s `plugin` array
+- OpenCode reads this on startup and auto-loads the plugin
+- If you manually edit `opencode.json`, make sure `plugin` is an array containing `"hivemind-context-governance"`
+
 ---
 
 ## How It Works
@@ -97,15 +136,16 @@ Trajectory (Level 1) — "Build authentication system"
 
 ### Under the Hood
 
-HiveMind fires **5 hooks automatically** on every turn:
+HiveMind fires **6 hooks automatically** on every turn:
 
 | Hook | When | What It Does |
 |------|------|-------------|
-| `system.transform` | Every LLM turn | Injects `<hivemind>` block with hierarchy, drift, warnings |
+| `experimental.chat.system.transform` | Every LLM turn | Injects `<hivemind>` block with hierarchy, drift, warnings |
+| `experimental.chat.messages.transform` | Before LLM response | Injects stop-checklist and continuity context (`<anchor-context>`, `<focus>`) |
 | `tool.execute.before` | Before any tool | Governance gate — warns on writes without intent |
 | `tool.execute.after` | After any tool | Tracks metrics, detects violations, captures cycles |
 | `session.compacting` | On context compaction | Preserves hierarchy + metrics across compaction |
-| `event` | On session events | Reacts to idle, file edits, compaction events |
+| `event` | On session events | Reacts to idle/file edits/compaction and persists `todo.updated` into task manifest |
 
 ### Data Flow
 
@@ -142,11 +182,11 @@ HiveMind fires **5 hooks automatically** on every turn:
 | `guided` | Suggestions only, never auto-acts |
 | `assisted` | Balanced automation *(default)* |
 | `full` | Maximum automation, minimal prompting |
-| `retard` | Maximum handholding — strict governance, skeptical output, strongest discipline |
+| `coach` | Maximum handholding — strict governance, skeptical output, strongest discipline |
 
 ---
 
-## Tools Reference (14)
+## Tools Reference (10)
 
 ### Core Lifecycle (3 tools)
 
@@ -170,22 +210,19 @@ compact_session({ summary: "Auth middleware complete" })
 // → Archived. 15 turns, 4 files. Session reset.
 ```
 
-### Awareness & Correction (4 tools)
+### Awareness & Correction (2 tools)
 
 | Tool | Agent Thought | What It Does |
 |------|--------------|-------------|
 | `scan_hierarchy` | *"Quick status check"* | Shows session state, metrics, anchors |
 | `think_back` | *"I feel lost"* | Deep refocus with plan review + chain analysis |
-| `check_drift` | *"Am I still on track?"* | Verifies alignment with trajectory |
-| `self_rate` | *"How am I doing?"* | Rate performance 1-10 for drift detection |
 
-### Persistent Memory (3 tools)
+### Persistent Memory (2 tools)
 
 | Tool | Agent Thought | What It Does |
 |------|--------------|-------------|
 | `save_mem` | *"This is worth remembering"* | Store decisions/patterns to persistent memory |
-| `list_shelves` | *"What do I know?"* | Browse Mems Brain by shelf |
-| `recall_mems` | *"I've seen this before"* | Search past decisions by keyword |
+| `recall_mems` | *"I've seen this before"* | Search or list Mems Brain by keyword/shelf |
 
 ### Immutable Facts (1 tool)
 
@@ -193,12 +230,11 @@ compact_session({ summary: "Auth middleware complete" })
 |------|--------------|-------------|
 | `save_anchor` | *"This must not be forgotten"* | Persist constraints that survive compaction + chaos |
 
-### Hierarchy Tree (2 tools)
+### Hierarchy Tree (1 tool)
 
 | Tool | Agent Thought | What It Does |
 |------|--------------|-------------|
-| `hierarchy_prune` | *"Clean up finished work"* | Remove completed branches from tree |
-| `hierarchy_migrate` | *"Upgrade the tree"* | Migrate flat hierarchy → navigable tree |
+| `hierarchy_manage` | *"Clean up or migrate the tree"* | Unified `prune` and `migrate` operations |
 
 ### Delegation Intelligence (1 tool)
 
@@ -214,10 +250,15 @@ HiveMind ships 3 OpenCode slash commands that work immediately after install:
 
 | Command | Purpose |
 |---------|---------|
-| `/hivemind-scan` | Project reconnaissance — scans structure, detects stack, identifies stale artifacts |
+| `/hivemind-scan` | Brownfield reconnaissance — analyze, recommend, orchestrate baseline context |
 | `/hivemind-status` | Full governance status — session, hierarchy, metrics, mems, config |
 | `/hivemind-compact` | Guided session archival with pre-compact checklist |
 
+`/hivemind-scan` runs a practical sequence with `scan_hierarchy` actions:
+1. `action: "analyze"` — detect framework mode (`gsd/spec-kit/both/none`) + BMAD signals
+2. `action: "recommend"` — generate remediation runbook
+3. `action: "orchestrate"` — persist non-destructive baseline anchors + memory
+
 ---
 
 ## Skills (5 Behavioral Governance Skills)
@@ -239,6 +280,8 @@ Skills teach the agent *how* to use governance effectively:
 ```bash
 npx hivemind-context-governance             # Interactive setup wizard
 npx hivemind-context-governance init        # Same (or use flags)
+npx hivemind-context-governance scan        # Brownfield scan wrapper
+npx hivemind-context-governance sync-assets # Sync packaged OpenCode assets to .opencode
 npx hivemind-context-governance status      # Show session state
 npx hivemind-context-governance settings    # Show configuration
 npx hivemind-context-governance dashboard   # Launch live TUI dashboard
@@ -252,12 +295,68 @@ npx hivemind-context-governance help        # Show help
 |------|--------|---------|
 | `--mode` | `permissive` · `assisted` · `strict` | `assisted` |
 | `--lang` | `en` · `vi` | `en` |
-| `--automation` | `manual` · `guided` · `assisted` · `full` · `retard` | `assisted` |
+| `--automation` | `manual` · `guided` · `assisted` · `full` · `coach` | `assisted` |
 | `--expert` | `beginner` · `intermediate` · `advanced` · `expert` | `intermediate` |
 | `--style` | `explanatory` · `outline` · `skeptical` · `architecture` · `minimal` | `explanatory` |
 | `--code-review` | *(flag)* | off |
 | `--tdd` | *(flag)* | off |
+| `--target` | `project` · `global` · `both` *(for init/sync-assets)* | `project` |
+| `--overwrite` | *(flag, for sync-assets)* | off |
 | `--force` | *(flag)* — removes existing .hivemind/ before re-init | off |
+| `--action` | `status` · `analyze` · `recommend` · `orchestrate` *(for scan)* | `analyze` |
+| `--json` | *(flag, for scan)* | off |
+| `--include-drift` | *(flag, for scan status)* | off |
+
+### OpenCode Asset Sync
+
+HiveMind can sync packaged OpenCode assets (`commands`, `skills`, and optional ecosystem groups) into OpenCode paths.
+
+```bash
+# Default: project-local .opencode/
+npx hivemind-context-governance sync-assets
+
+# Global OpenCode config path (~/.config/opencode or platform equivalent)
+npx hivemind-context-governance sync-assets --target global
+
+# Sync both project and global targets
+npx hivemind-context-governance sync-assets --target both
+
+# Replace existing files (default behavior is no-clobber)
+npx hivemind-context-governance sync-assets --overwrite
+```
+
+`init` also performs asset sync automatically. Re-running `init` on an existing project refreshes missing assets without resetting `.hivemind` state.
+
+Packaged optional ecosystem assets now include starter files for:
+- `agents`
+- `workflows`
+- `templates`
+- `prompts`
+- `references`
+
+These are synced into `.opencode/` (or global OpenCode config path) alongside commands and skills.
+
+### Existing User Upgrade (No Re-init Required)
+
+```bash
+npm install hivemind-context-governance@latest
+npx hivemind-context-governance sync-assets --target project
+```
+
+Use `--target both` if you want project-local and global OpenCode paths updated together.
+
+### Brownfield Scan via CLI
+
+```bash
+# Analyze framework + stack + artifact risks
+npx hivemind-context-governance scan --action analyze --json
+
+# Generate remediation sequence
+npx hivemind-context-governance scan --action recommend
+
+# Persist safe baseline anchors + memory
+npx hivemind-context-governance scan --action orchestrate --json
+```
 
 ### Dashboard (Optional TUI)
 
@@ -282,6 +381,31 @@ When OpenCode loads HiveMind **before** `hivemind init` was run:
 
 This prevents the "agent starts coding immediately without understanding the project" failure mode.
 
+## Brownfield Runbook (\"Please scan my project and refactor it\")
+
+Recommended execution order:
+
+1. Analyze:
+```ts
+scan_hierarchy({ action: "analyze", json: true })
+```
+2. Recommend:
+```ts
+scan_hierarchy({ action: "recommend" })
+```
+3. Orchestrate baseline:
+```ts
+scan_hierarchy({ action: "orchestrate", json: true })
+```
+4. Lock execution focus:
+```ts
+declare_intent({ mode: "exploration", focus: "Brownfield stabilization" })
+map_context({ level: "tactic", content: "Context purification and framework resolution" })
+map_context({ level: "action", content: "Execute safe cleanup checkpoints" })
+```
+
+This sequence ensures framework detection, context purification, baseline persistence, and drift-safe execution before large refactors.
+
 ---
 
 ## `.hivemind/` Directory Structure
@@ -335,13 +459,36 @@ npx hivemind-context-governance init --force
 
 ## Troubleshooting
 
+### "Plugin not loading" or "Setup guidance keeps appearing"
+
+**Cause:** The plugin was never registered in `opencode.json`.
+
+**Fix:** Run the init command **once**:
+```bash
+npx hivemind-context-governance init --mode assisted
+```
+
+This does **all** of the following:
+- Creates `.hivemind/` directory structure
+- Registers plugin in `opencode.json` (so OpenCode auto-loads it)
+- Syncs commands/skills into `.opencode/`
+- Initializes brain state
+
+**Important:** If you run `init` again on an existing project:
+- It keeps your existing `.hivemind/` state ✅
+- It refreshes OpenCode assets ✅
+- It ensures plugin is still registered ✅
+
+### Other Issues
+
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| Setup guidance keeps appearing | `.hivemind/config.json` missing | Run `npx hivemind-context-governance` |
+| Setup guidance keeps appearing | `.hivemind/config.json` missing | Run `npx hivemind-context-governance init --mode assisted` |
 | Framework conflict warning | Both `.planning/` and `.spec-kit/` exist | Select one framework via locked menu |
 | Dashboard won't start | Optional deps not installed | `npm install ink react` |
 | Session feels stale after idle | Auto-archive rotated state | Use `scan_hierarchy` + `think_back` |
 | Want fresh start | Old config causing issues | `npx hivemind-context-governance purge` then re-init |
+| "Plugin already registered" message | Normal behavior on upgrade | No action needed |
 
 ---
 
@@ -350,7 +497,7 @@ npx hivemind-context-governance init --force
 ```bash
 npm run build      # Full build (clean + compile + chmod)
 npm run typecheck   # TypeScript type checking
-npm test           # Run all 41 test files (705+ assertions)
+npm test           # Run all test files (700+ assertions)
 npm run dev        # Watch mode
 ```
 
@@ -368,6 +515,8 @@ MIT
 
 > *Phần này không phải bản dịch — mà được viết riêng cho người dùng Việt Nam, với giải thích kỹ hơn về cách hoạt động và lý do tại sao.*
 
+**Cảm thấy hữu ích?** [![Mời cà phê](https://img.shields.io/badge/Mời%20cà%20phê-ủng%20hộ-orange?logo=buy-me-a-coffee&logoColor=white)](https://buymeacoffee.com/shynlee04l)
+
 ## HiveMind Là Gì?
 
 Hãy tưởng tượng bạn thuê một lập trình viên AI rất giỏi, nhưng anh ta có một vấn đề: **mỗi 30 phút anh ta quên hết mọi thứ đang làm**.
@@ -420,40 +569,104 @@ Khi xong việc, `compact_session` sẽ:
 
 ## Cài Đặt Từ Đầu Đến Cuối
 
-### Bước 1: Cài Package
+### Một Lệnh - Xong Ngay
 
 ```bash
-npm install hivemind-context-governance
+npx hivemind-context-governance init --mode assisted
 ```
 
-### Bước 2: Chạy Wizard Cấu Hình
+**Điều gì sẽ xảy ra (đảm bảo):**
+1. Tự động tải từ npm (không cần cài thủ công)
+2. Tạo thư mục `.hivemind/` với brain.json, config.json
+3. Đăng ký plugin trong `opencode.json` (để OpenCode tự động load)
+4. Đồng bộ commands/skills vào `.opencode/`
+5. Tạo các file session template
+6. Mở session ở chế độ `OPEN` (assisted) hoặc `LOCKED` (strict)
 
-```bash
-npx hivemind-context-governance
+**Hoạt động trên mọi máy, mọi project. Không ngoại lệ.**
+
+### Xác Nhận Cài Đặt (Tùy Chọn)
+
+Wizard sẽ hướng dẫn bạn từng bước:
+
+```
+◆  Welcome to HiveMind Context Governance!
+
+◆  Select governance mode:
+│  ○ strict    — Session starts LOCKED. Must declare intent before writes.
+│  ● assisted  — Session starts OPEN. Guidance without blocking. (recommended)
+│  ○ permissive — Always OPEN. Silent tracking only.
+
+◆  Select language:
+│  ○ English
+│  ● Tiếng Việt
+
+◆  Select automation level:
+│  ○ manual   — No automation, you control everything
+│  ○ guided   — Suggestions only
+│  ● assisted — Balanced automation (recommended)
+│  ○ full     — Maximum automation
+│  ○ coach    — Maximum handholding, skeptical of everything
+
+◆  Configuration saved! .hivemind/ created.
 ```
 
-Wizard sẽ hỏi bạn từng bước:
+### Cài Đặt Không Tương Tác
+
+```bash
+npx hivemind-context-governance init --mode strict --lang vi --automation full
+```
 
-1. **Chế độ quản trị**: 
-   - `strict` = Nghiêm ngặt (agent phải khai báo trước khi làm bất cứ gì)
-   - `assisted` = Hỗ trợ (khuyên nhủ nhưng không chặn) ← **khuyến nghị cho người mới**
-   - `permissive` = Tự do (chỉ theo dõi, không can thiệp)
+Lệnh này làm **đúng như** wizard tương tác:
+- Tạo cấu trúc `.hivemind/`
+- Đăng ký plugin trong `opencode.json`
+- Đồng bộ OpenCode assets
+- Khởi tạo brain state với cài đặt đã chọn
 
-2. **Ngôn ngữ**: Chọn `vi` để nhận cảnh báo bằng tiếng Việt
+### Mở OpenCode
 
-3. **Mức tự động hóa**: Từ `manual` (tự tay) đến `retard` (giám sát tối đa)
+Xong. Plugin tự động hoạt động. AI agent sẽ nhận governance context được inject vào mỗi turn.
 
-4. **Hành vi agent**: Mức chuyên gia, phong cách output, ràng buộc
+### Xác Nhận Cài Đặt (Tùy Chọn)
 
-### Bước 3: Mở OpenCode
+```bash
+npx hivemind-context-governance status
+```
 
-Plugin tự động hoạt động. Không cần thêm bước nào.
+Hoặc kiểm tra thủ công `opencode.json` có chứa:
+```json
+{
+  "plugin": ["hivemind-context-governance"]
+}
+```
 
-### Bước 4: Sử Dụng Slash Command
+### Sử Dụng Slash Command
 
 Gõ `/hivemind-scan` trong OpenCode để quét dự án và tạo bản đồ cơ sở trước khi bắt đầu code.
 
-## 14 Công Cụ — Giải Thích Chi Tiết
+Hoặc dùng CLI trực tiếp:
+
+```bash
+npx hivemind-context-governance scan --action analyze --json
+npx hivemind-context-governance scan --action recommend
+npx hivemind-context-governance scan --action orchestrate --json
+```
+
+## Runbook Brownfield (Tiếng Việt)
+
+Khi người dùng nói: *\"Hãy quét dự án và refactor\"*, chạy theo thứ tự:
+
+1. `scan_hierarchy({ action: "analyze", json: true })`
+2. `scan_hierarchy({ action: "recommend" })`
+3. `scan_hierarchy({ action: "orchestrate", json: true })`
+4. `declare_intent(...)` + `map_context(...)` để khóa focus trước khi sửa code
+
+Mục tiêu:
+- Phát hiện framework (`gsd/spec-kit/both/none`) và tín hiệu BMAD
+- Cô lập artifact cũ/stale có nguy cơ nhiễm context
+- Lưu baseline anchors + memory trước khi refactor diện rộng
+
+## 10 Công Cụ — Giải Thích Chi Tiết
 
 ### Nhóm 1: Vòng Đời Session
 
@@ -469,15 +682,13 @@ Gõ `/hivemind-scan` trong OpenCode để quét dự án và tạo bản đồ c
 |---------|-------------|---------------------|
 | `scan_hierarchy` | Muốn xem nhanh trạng thái | Nắm bắt tình hình trong 1 giây |
 | `think_back` | Cảm thấy lạc | Hồi phục context sâu sau compaction |
-| `check_drift` | Trước khi kết luận xong | Kiểm tra có đúng hướng với mục tiêu ban đầu không |
-| `self_rate` | Tự đánh giá | Chấm điểm 1-10 để phát hiện vấn đề sớm |
+| `scan_hierarchy` (`include_drift`) | Trước khi kết luận xong | Kiểm tra độ lệch hướng theo trajectory/tactic/action |
 
 ### Nhóm 3: Bộ Nhớ Dài Hạn
 
 | Công Cụ | Khi Nào Dùng | Tại Sao Quan Trọng |
 |---------|-------------|---------------------|
 | `save_mem` | Học được bài học quan trọng | Quyết định, pattern, lỗi — tồn tại vĩnh viễn |
-| `list_shelves` | Muốn xem có gì trong bộ nhớ | Tổng quan kho tri thức |
 | `recall_mems` | Gặp vấn đề quen thuộc | Tìm giải pháp từ quá khứ |
 | `save_anchor` | Sự thật bất biến | Port number, schema, API endpoint — không bao giờ quên |
 
@@ -485,8 +696,7 @@ Gõ `/hivemind-scan` trong OpenCode để quét dự án và tạo bản đồ c
 
 | Công Cụ | Khi Nào Dùng | Tại Sao Quan Trọng |
 |---------|-------------|---------------------|
-| `hierarchy_prune` | Cây quá nhiều nhánh đã xong | Giữ cây gọn gàng |
-| `hierarchy_migrate` | Nâng cấp từ bản cũ | Chuyển đổi hierarchy phẳng → cây |
+| `hierarchy_manage` | Cây nhiều nhánh hoặc cần nâng cấp | Gộp cả prune và migrate trong một công cụ |
 | `export_cycle` | Subagent vừa trả kết quả | Không export = mất intelligence từ subagent |
 
 ## Lần Đầu Mở OpenCode (Quan Trọng!)
@@ -547,6 +757,16 @@ npx hivemind-context-governance init --force
 5. **Kết thúc bằng `compact_session`** — Lưu trữ có cấu trúc, session sau vào lại không bị "reset trí nhớ"
 6. **Dùng `/hivemind-scan` khi mới vào project** — Hiểu project trước khi code
 
+## Về Tác Giả
+
+HiveMind được xây dựng bởi [shynlee04](https://github.com/shynlee04) — một lập trình viên đã quá mệt mỏi với việc AI agent quên mất đang làm gì giữa chừng phiên code. Sau quá nhiều lần tự hỏi "khoan đã, tại sao mình lại quyết định kiến trúc này nhỉ?", ý tưởng về một hệ thống quản trị context đã ra đời.
+
+Khi không bận xây dựng công cụ để AI "trung thực" hơn, mình thường làm việc với full-stack applications, mày mò developer tooling, và ủng hộ phong cách phát triển có sự hỗ trợ của AI mà thực sự hiệu quả.
+
+**Cảm thấy hữu ích?** [Mời mình ly cà phê ☕](https://buymeacoffee.com/shynlee04l) — nó tiếp thêm năng lượng cho những đêm code muộn để tạo ra những công cụ như thế này.
+
+---
+
 > *Nếu bạn coi HiveMind như "bộ điều phối context" thay vì "một bộ tool phụ", chất lượng session sẽ khác biệt rõ rệt.*
 
 ---
@@ -561,7 +781,7 @@ npx hivemind-context-governance init --force
 │  │                                          │   │
 │  │  ┌─────────┐ ┌──────────┐ ┌──────────┐ │   │
 │  │  │  Hooks  │ │  Tools   │ │  Events  │ │   │
-│  │  │  (5)    │ │  (14)    │ │  handler │ │   │
+│  │  │  (6)    │ │  (10)    │ │  handler │ │   │
 │  │  └────┬────┘ └────┬─────┘ └────┬─────┘ │   │
 │  │       │           │            │        │   │
 │  │       ▼           ▼            ▼        │   │
@@ -586,4 +806,14 @@ npx hivemind-context-governance init --force
 
 ---
 
+## About
+
+HiveMind is built by [shynlee04](https://github.com/shynlee04), a developer who got tired of AI agents forgetting what they were doing halfway through coding sessions. After one too many "wait, why did we decide this architecture again?" moments, the idea for a context governance system was born.
+
+When not building tools to keep AI honest, you'll find me working on full-stack applications, tinkering with developer tooling, and advocating for AI-assisted development that actually works.
+
+**Found this useful?** [Buy me a coffee ☕](https://buymeacoffee.com/shynlee04l) — it fuels the late-night coding sessions that make tools like this possible.
+
+---
+
 *Built for developers who believe AI agents should be accountable, not just capable.*

package/agents/hivemind-brownfield-orchestrator.md

@@ -0,0 +1,18 @@
+---
+name: hivemind-brownfield-orchestrator
+description: Run a safe brownfield stabilization sequence before broad refactors.
+model: default
+---
+
+You are a hidden orchestration agent for brownfield projects.
+
+Workflow:
+1. Run `scan_hierarchy` with `{ action: "analyze", json: true }`.
+2. If framework conflict is detected, return recommendations first and stop destructive changes.
+3. Run `scan_hierarchy` with `{ action: "orchestrate", json: true }` to persist baseline anchors and memory.
+4. Return a concise execution order using `declare_intent` and `map_context`.
+
+Rules:
+- Never edit code in this phase.
+- Prioritize artifact purification and framework conflict resolution.
+- Require evidence outputs before claiming readiness.

package/bin/hivemind-tools.cjs

@@ -158,8 +158,21 @@ function validateHierarchyChain(tree) {
 function getHiveMindPaths(dir) {
   const hivemindDir = path.join(dir, '.hivemind');
   const sessionsDir = path.join(hivemindDir, 'sessions');
+  const activeDir = path.join(sessionsDir, 'active');
   const archiveDir = path.join(sessionsDir, 'archive');
   const templatesDir = path.join(hivemindDir, 'templates');
+  const docsDir = path.join(hivemindDir, 'docs');
+
+  // Bridge: detect v2.0.0 structure (state/) vs legacy flat
+  const stateDir = path.join(hivemindDir, 'state');
+  const memoryDir = path.join(hivemindDir, 'memory');
+  const isNew = exists(stateDir) && exists(path.join(hivemindDir, 'manifest.json'));
+  const isLegacy = exists(path.join(hivemindDir, 'brain.json')) && !exists(stateDir);
+  // Fresh install or new structure → use state/ paths; legacy → flat paths
+  const brainPath = (isNew || !isLegacy) ? path.join(stateDir, 'brain.json') : path.join(hivemindDir, 'brain.json');
+  const hierarchyPath = (isNew || !isLegacy) ? path.join(stateDir, 'hierarchy.json') : path.join(hivemindDir, 'hierarchy.json');
+  const anchorsPath = (isNew || !isLegacy) ? path.join(stateDir, 'anchors.json') : path.join(hivemindDir, 'anchors.json');
+  const memsPath = (isNew || !isLegacy) ? path.join(memoryDir, 'mems.json') : path.join(hivemindDir, 'mems.json');
 
   // OpenCode config — check both .json and .jsonc
   let opencodeConfigPath = path.join(dir, 'opencode.json');
@@ -187,18 +200,19 @@ function getHiveMindPaths(dir) {
   return {
     project: dir,
     hivemind: hivemindDir,
-    brain: path.join(hivemindDir, 'brain.json'),
+    brain: brainPath,
     config: path.join(hivemindDir, 'config.json'),
-    hierarchy: path.join(hivemindDir, 'hierarchy.json'),
+    hierarchy: hierarchyPath,
+    anchors: anchorsPath,
+    mems: memsPath,
     manifest: path.join(sessionsDir, 'manifest.json'),
-    indexMd: path.join(sessionsDir, 'index.md'),
+    indexMd: path.join(hivemindDir, 'INDEX.md'),
     activeMd: path.join(sessionsDir, 'active.md'),
+    activeDir,
     archive: archiveDir,
     templates: templatesDir,
     sessionTemplate: path.join(templatesDir, 'session.md'),
-    commandments: path.join(hivemindDir, '10-commandments.md'),
-    anchors: path.join(hivemindDir, 'anchors.json'),
-    mems: path.join(hivemindDir, 'mems.json'),
+    commandments: path.join(docsDir, '10-commandments.md'),
     sessions: sessionsDir,
     opencode: { path: opencodeConfigPath, type: opencodeConfigType },
     globalOpencode: { path: globalOpencodeConfig, type: globalConfigType },
@@ -260,8 +274,8 @@ function cmdVerifyInstall(args) {
   const coreFiles = [
     ['brain.json', paths.brain],
     ['config.json', paths.config],
-    ['index.md', paths.indexMd],
-    ['active.md', paths.activeMd],
+    ['INDEX.md', paths.indexMd],
+    ['active-session', exists(paths.activeDir) ? paths.activeDir : paths.activeMd],
     ['10-commandments.md', paths.commandments],
   ];
 
@@ -656,7 +670,13 @@ function cmdEcosystemCheck(args) {
   }
 
   // 2. INIT: .hivemind/ exists with core files
-  const coreFiles = [paths.brain, paths.config, paths.indexMd, paths.activeMd, paths.commandments];
+  const coreFiles = [
+    paths.brain,
+    paths.config,
+    paths.indexMd,
+    exists(paths.activeDir) ? paths.activeDir : paths.activeMd,
+    paths.commandments,
+  ];
   const existingCore = coreFiles.filter(f => exists(f));
   if (existingCore.length === coreFiles.length) {
     chain.push({ step: 'init', status: 'pass', detail: `${existingCore.length}/${coreFiles.length} files` });