hivemind-context-governance 1.3.0 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,164 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] - 2026-02-12
+
+### Added
+- **Evidence Gate System** — Escalating prompt pressure with 4 tiers (INFO → WARN → CRITICAL → DEGRADED) that intensify over unresolved turns
+- **Evidence-based argument-back** — Every detection signal now includes data-backed evidence strings and counter-arguments against common agent excuses
+- **"I am retard" mode** — New `automationLevel` CLI option with 5 levels (manual/guided/assisted/full/retard); retard mode forces strict governance, skeptical output, code review, max handholding
+- **Write-without-read tracking (FileGuard)** — `soft-governance.ts` tracks blind file writes; detection engine generates `write_without_read` signal with evidence
+- **`AutomationLevel` config type** — Persisted in `config.json`, read by hooks every turn (Rule 6)
+- **`compileEscalatedSignals()`** — New entry point for evidence-based prompt injection, wraps `compileSignals()` with tiers + evidence + counter-excuses
+- **`computeEscalationTier()`** — Pure function: turns × threshold → tier classification
+- **44 new test assertions** — Evidence gate system tests: escalation, evidence quality, retard mode init, format compatibility (688 total)
+
+### Changed
+- **Session lifecycle hook** — Now uses `compileEscalatedSignals()` instead of `compileSignals()` for richer prompt injection
+- **Prompt format** — Escalated signals show `[TIER] message`, `EVIDENCE: data`, `↳ counter-argument` (backward compatible with non-escalated signals)
+- **Retard mode auto-config** — Forces strict governance, beginner expert level, skeptical output, code review required, be_skeptical=true
+- **Archived 9 historical plan documents** to `docs/archive/`
+
+## [2.3.0] - 2026-02-12
+
+### Added
+- **Entry chain edge case tests** — JSONC config handling, re-init guard, config persistence verification (14 new assertions)
+- **Config persistence verification** — `loadConfig` deep-merges constraints with defaults, partial updates preserve existing values
+- **Re-init guard** — `hivemind init` no longer overwrites existing config (preserves governance_mode, language)
+
+### Fixed
+- **JSONC config handling** — `opencode.jsonc` files now parsed correctly (was crashing on trailing commas/comments)
+- **Master plan file tree accuracy** — docs now match actual output of `hivemind init`
+- **Frozen config (L8)** — All 3 hooks now re-read config from disk each invocation via `loadConfig(directory)` instead of using stale closure values
+- **Tool gate duplication (L9)** — Removed 130-line duplicated `createToolGateHookInternal` body; now delegates to `createToolGateHook().internal`
+- **Dead sentiment_signals field (L10)** — Removed deprecated `SentimentSignal` type and `sentiment_signals: []` from BrainState schema
+- **README accuracy (L1)** — Updated from "11 tools, 386 assertions" to "14 tools, 621 assertions"
+- **CLI --help (L5)** — `--help` and `-h` flags now show help instead of running init
+
+### Changed
+- Hook factories accept `_initConfig` parameter (unused — config read from disk per Rule 6)
+- `bin/hivemind-tools.cjs` and `skills/` added to package.json `files` array for npm shipping
+- Removed stale `tasks/prd-production-ready.md` and orphan `session-ses_3b3a.md`
+
+### Removed
+- `SentimentSignal` interface and `sentiment_signals` field from BrainState
+- Duplicated `createToolGateHookInternal` function body (kept as thin wrapper for backward compat)
+- `src/lib/sentiment.ts` export from barrel (file retained for git history)
+
+## [2.2.0] - 2026-02-12
+
+### Added
+- **export_cycle tool** (14th tool) — Captures subagent results into hierarchy tree + mems brain
+- **Auto-capture hook** — `tool.execute.after` auto-captures all Task tool returns into `brain.cycle_log[]`
+- **Pending failure acknowledgment** — `pending_failure_ack` flag set when subagent reports failure; system prompt warns until agent acknowledges
+- **Skill system** (5 skills) — Behavioral governance through skills: `hivemind-governance` (bootstrap), `session-lifecycle`, `evidence-discipline`, `context-integrity`, `delegation-intelligence`
+- **Tool activation engine** (7 priorities) — Suggests next tool based on session state (LOCKED → declare_intent, high drift → map_context, etc.)
+- **Enhanced CLI** — `bin/hivemind-tools.cjs` expanded to 23 commands (source-audit, list-tools, list-hooks, verify-package, etc.)
+- 36 new test assertions for cycle intelligence
+- Entry chain E2E tests (56 assertions)
+
+## [2.1.0] - 2026-02-11
+
+### Added
+- **Hierarchy tree engine** — Navigable tree with timestamp-based stamps, DFS traversal, cursor tracking
+- **Detection engine** — Tool classification (read/write/query/governance), counter logic, keyword scanning, signal compilation
+- **Per-session files** — Each session archived with `.json` export + `.md` export
+- **Session manifest** — `manifest.json` registry of all sessions
+- **Configurable thresholds** — `detection_thresholds` in config for turn count, failures, section repetition
+- **Migration path** — `hierarchy_migrate` tool converts flat hierarchy to tree format
+- **hierarchy_prune tool** — Removes completed branches, moves cursor to root
+- **Compact purification** — `compact_session` generates next-compaction report for context preservation
+- 2 new tools: `hierarchy_prune`, `hierarchy_migrate` (13 total)
+- 158 new test assertions (hierarchy tree 55, detection 45, compact purification 34, entry chain 24)
+
+### Changed
+- Session lifecycle hook now compiles detection signals into `<hivemind>` prompt injection
+- Soft governance hook now runs full detection engine (tool classification, keyword scanning, failure tracking)
+- Tree-aware chain analysis — detects timestamp gaps between nodes
+- `max_active_md_lines` wired into detection thresholds
+
+## [2.0.0] - 2026-02-11
+
+### Breaking Changes
+- System prompt injection restructured — uses `<hivemind>` tag instead of `<hivemind-governance>` and `<agent-configuration>`
+- Commit suggestion removed from system prompt (was user concern, not agent concern)
+- Mems count removed from system prompt (not actionable)
+
+### Added
+- **Priority-sectioned system prompt** — drops lowest priority sections when budget exceeded instead of malformed truncation
+- **Anchor age indicators** — anchors in system prompt show `(Xh ago)` / `(Xd ago)`
+- **Input validation** — all string args validated for non-empty content
+- **Helper footers** — every tool output suggests the logical next action
+- **Upsert for anchors** — updating an existing key shows the delta (was/now)
+- **Memory deduplication** — save_mem rejects duplicate content on same shelf
+- **Session awareness** — save_anchor/save_mem warn when no active session
+- **Overwrite warning** — declare_intent warns when replacing an existing trajectory
+- **Output budget** — think_back capped at 2000 chars, anchors at 5, plan at 10 lines
+
+### Fixed
+- **System prompt malformed XML** — truncation was closing `</agent-configuration>` inside `<hivemind-governance>` producing invalid XML
+- **Hook inconsistency** — write tool lists now identical between before/after hooks (exact Set.has matching)
+- **Fuzzy tool matching** — replaced dangerous `startsWith`/`includes` with exact `Set.has()`
+- **Double save** — soft-governance hook consolidated to single disk write
+- **Array mutation** — list-shelves sort no longer mutates shared state
+- **scan_hierarchy JSON** — now returns structured text like all other tools
+- **self_rate threshold** — score 6-7 now shows positive feedback instead of drift warning
+
+### Changed
+- System prompt budget increased from 1000 to 2500 chars
+- Package.json: removed src/ from files, added exports field, tightened peerDependencies
+- Error messages standardized with `ERROR:` prefix and guidance
+- scan_hierarchy description differentiated from think_back
+- save_anchor description removes "API keys" (security risk)
+- README rewritten to document all 11 tools and 4 hooks
+
+## [1.6.0] - 2026-02-11
+
+### Fixed
+- **SHOWSTOPPER**: Tool registration changed from array to named Record — tools were being registered as "0", "1", "2" instead of "declare_intent", "map_context", etc. Agents could not call any tool by name.
+- **CRITICAL**: `hivemind init` crash on npm install — `docs/` directory now included in `package.json#files`
+- **CRITICAL**: System transform hook now accepts `model` parameter matching SDK contract
+- **CRITICAL**: Legacy `.opencode` path in self-rate tool changed to `.hivemind/logs`
+- **HIGH**: Double-counting turn increments — `incrementTurnCount` removed from `tool.execute.before` hook (kept only in `tool.execute.after`)
+- **MEDIUM**: All 11 tools now accept `ToolContext` parameter matching SDK `execute(args, context)` signature
+
+### Changed
+- Removed unused `zod` dependency from `package.json#dependencies` (SDK re-exports via `tool.schema.*`)
+- Stale `.opencode/planning/` doc comment in `src/cli/init.ts` updated to `.hivemind/`
+
+## [1.5.0] - 2026-02-11
+
+### Added
+- **Mems Brain** — Persistent, shelf-organized memory system for cross-session knowledge
+- 3 new tools: `save_mem`, `list_shelves`, `recall_mems`
+- Auto-mem on compaction: saves session summary to "sessions" shelf
+- System prompt injection: mem count indicator
+- Compaction context: injects recent mems for context preservation
+- 40 new test assertions (Round 4)
+
+## [1.4.0] - 2026-02-11
+
+### Changed
+- **BREAKING**: Migrated from `.opencode/planning/` to `.hivemind/` directory structure
+- Plugin now creates `.hivemind/sessions/` for session state
+- Added `.hivemind/10-commandments.md` (tool design reference)
+- `.hivemind/plans/` for plan storage (not `.plan/plans/`)
+
+### Added
+- 10 Commandments document for tool design principles
+- `.hivemind/` directory structure with sessions, brain, plans, logs subdirectories
+- Git hooks setup script (scripts/setup-git-hooks.sh)
+- Pre-commit hook for enforcing atomic commits and session awareness
+
+### Fixed
+- Path references throughout codebase, tests, documentation
+
+### Migration Guide
+Existing projects using `.opencode/planning/` can manually move files:
+1. Create `.hivemind/` directory structure
+2. Move `.opencode/planning/` contents to `.hivemind/`
+3. Update `opencode.json` plugin registration if needed
+
 ## [1.3.0] - 2026-02-11
 
 ### Added
@@ -90,6 +248,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Session lifecycle management
 - Planning directory structure (.opencode/planning/)
 
+[2.3.0]: https://github.com/shynlee04/hivemind-plugin/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/shynlee04/hivemind-plugin/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/shynlee04/hivemind-plugin/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.6.0...v2.0.0
+[1.6.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.2.1...v1.3.0
+[1.2.1]: https://github.com/shynlee04/hivemind-plugin/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/shynlee04/hivemind-plugin/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/shynlee04/hivemind-plugin/releases/tag/v1.0.0

package/README.md

@@ -1,218 +1,259 @@
 # HiveMind Context Governance
 
-A lightweight context-aware governance layer for OpenCode that prevents drift and manages session state across lifecycles.
+A lightweight context governance layer for [OpenCode](https://opencode.ai) that prevents drift, manages session state, and preserves memory across agent lifecycles.
 
-## What is HiveMind?
+**14 tools** | **4 hooks** | **5 automation levels** | **688 test assertions**
 
-HiveMind provides **soft governance** for AI-assisted development — it tracks context, warns about drift, and maintains session state without hard-blocking your workflow.
+## Quick Start
 
-### Key Features
-
-- **3-Level Hierarchy**: Trajectory → Tactic → Action
-- **3 Governance Modes**: Strict, Assisted, Permissive
-- **4 Lifecycle Tools**: declare_intent, map_context, compact_session, self_rate
-- **Session Archiving**: Automatic compaction and history tracking
-- **Drift Detection**: Warnings when context goes stale
-- **Sentiment Detection**: Automatic detection of negative signals and confusion
-- **Complexity Nudges**: Gentle warnings when sessions get complex (3+ files or 5+ turns)
-- **Self-Rating**: Agent self-assessment for drift tracking (1-10 scale)
-
-## Installation
+```bash
+# Install
+npm install hivemind-context-governance
 
-One command. That's it.
+# Initialize in your project
+npx hivemind init
 
-```bash
-npx hivemind-context-governance
+# Check status
+npx hivemind status
 ```
 
-This does everything:
-1. Creates `.opencode/planning/` with session state files
-2. Registers HiveMind in your `opencode.json` automatically
-3. Next time you open OpenCode, HiveMind is active
+This creates a `.hivemind/` directory and registers the plugin in `opencode.json`.
 
-> **No cloning. No manual JSON editing. No `npm install`.** OpenCode auto-installs npm plugins at runtime.
+## How It Works
 
-### Options
+HiveMind uses a 3-level hierarchy to track what you're working on:
 
-```bash
-npx hivemind-context-governance --mode strict --lang en
+```
+Trajectory (Level 1) → Tactic (Level 2) → Action (Level 3)
 ```
 
-| Option | Values | Default |
-|--------|--------|---------|
-| `--mode` | `strict`, `assisted`, `permissive` | `assisted` |
-| `--lang` | `en`, `vi` | `en` |
+Every session starts with `declare_intent`, which sets the trajectory and unlocks the session. As you work, `map_context` updates your current focus. When done, `compact_session` archives everything and resets.
 
-### Other CLI Commands
+The plugin fires 4 hooks automatically — injecting context into every LLM turn, tracking metrics after every tool call, enforcing governance before writes, and preserving hierarchy across context compaction.
+
+## Governance Modes
+
+| Mode | Behavior | Best For |
+|------|----------|----------|
+| **strict** | Session starts LOCKED. Warns on writes without intent. | High-compliance projects |
+| **assisted** | Session starts OPEN. Guidance without blocking. | Most projects (default) |
+| **permissive** | Always OPEN. Silent tracking only. | Maximum autonomy |
 
 ```bash
-npx hivemind-context-governance status     # Show current state
-npx hivemind-context-governance compact    # Manual compaction info
-npx hivemind-context-governance help       # Show help
+# Initialize with a specific mode
+npx hivemind init --mode strict
+npx hivemind init --mode assisted --lang vi
 ```
 
-## Using the Tools
+## Tools (14)
+
+### Core (3 tools)
 
-Within OpenCode, use the 4 lifecycle tools:
+| Tool | When | What It Does |
+|------|------|--------------|
+| `declare_intent` | Starting work | Set your focus and mode. Unlocks the session. |
+| `map_context` | Changing focus | Update trajectory/tactic/action hierarchy. |
+| `compact_session` | Finishing work | Archive session and reset for next work. |
 
 ```typescript
-// Start a session
-declare_intent({
-  mode: "plan_driven",
-  focus: "Implement user authentication"
-})
-
-// Update context
-map_context({
-  level: "tactic",
-  content: "Set up JWT middleware",
-  status: "active"
-})
-
-// Rate your performance (self-assessment)
-self_rate({
-  score: 8,
-  reason: "Making good progress on auth flow",
-  turn_context: "Currently testing JWT validation"
-})
-
-// Archive and reset
-compact_session({
-  summary: "Auth system foundation complete"
-})
+declare_intent({ mode: "plan_driven", focus: "Build auth system" })
+// → Session: "Build auth system". Mode: plan_driven. Status: OPEN.
+
+map_context({ level: "tactic", content: "Implement JWT validation" })
+// → [tactic] "Implement JWT validation" → active
+
+compact_session({ summary: "Auth middleware complete" })
+// → Archived. 15 turns, 4 files. 3 total archives.
 ```
 
-## Governance Modes
+### Self-Awareness (1 tool)
 
-| Mode | Behavior | Use Case |
-|------|----------|----------|
-| **strict** | Session starts LOCKED. Must call `declare_intent` before writes. | High-compliance projects |
-| **assisted** | Session starts OPEN. Warnings logged but not blocking. | Balanced guidance |
-| **permissive** | Session always OPEN. Silent tracking only. | Maximum autonomy |
+| Tool | When | What It Does |
+|------|------|--------------|
+| `self_rate` | Self-reflection | Rate your own performance (1-10) for drift detection. |
 
-## Project Structure
+### Cognitive Mesh (4 tools)
 
-After initialization:
+| Tool | When | What It Does |
+|------|------|--------------|
+| `scan_hierarchy` | Quick status check | Snapshot of session state, metrics, anchors. |
+| `save_anchor` | Saving immutable facts | Persist constraints that survive compaction. |
+| `think_back` | Feeling lost | Deep refocus with plan review and chain analysis. |
+| `check_drift` | Before completing | Verify alignment with declared trajectory. |
 
-```
-.opencode/planning/
-├── index.md          # Project trajectory
-├── active.md         # Current session
-├── brain.json        # Machine state
-├── config.json       # Settings
-└── archive/          # Session history
-    └── session_2026-02-10_xxx.md
-```
+### Mems Brain (3 tools)
 
-## Sentiment Detection
+| Tool | When | What It Does |
+|------|------|--------------|
+| `save_mem` | Saving a lesson | Store decisions, patterns, errors to persistent memory. |
+| `list_shelves` | Browsing memories | See what's in the Mems Brain by shelf. |
+| `recall_mems` | Searching memories | Search past decisions and patterns by keyword. |
 
-HiveMind automatically detects negative signals in user messages and agent responses:
+### Hierarchy Ops (2 tools)
 
-**Detected Patterns:**
-- **Negative keywords**: stop, wrong, no, bad, incorrect, confused, mistake, error
-- **Agent failure phrases**: "I apologize", "you are right", "I was wrong", "my mistake"
-- **Cancellation patterns**: cancel, abort, start over, scratch that, never mind
-- **Confusion indicators**: "I'm confused", "doesn't make sense", "unclear"
+| Tool | When | What It Does |
+|------|------|--------------|
+| `hierarchy_prune` | Cleaning up | Remove completed branches from the tree. |
+| `hierarchy_migrate` | Upgrading | Migrate flat hierarchy to navigable tree format. |
 
-**Trigger Threshold:**
-- 2 negative signals within 5 turns triggers a drift warning
-- Warning logged to TUI: `[ContextRefresh] Drift detected. Consider compact_session.`
-- Warning added to `active.md` for visibility
+### Cycle Intelligence (1 tool)
 
-## Complexity Nudges
+| Tool | When | What It Does |
+|------|------|--------------|
+| `export_cycle` | After subagent returns | Capture subagent results into hierarchy + mems. |
 
-When sessions get complex, HiveMind provides gentle nudges:
+## Hooks (4)
 
-**Thresholds (configurable):**
-- 3+ unique files touched, OR
-- 5+ turns since last `declare_intent`
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `experimental.chat.system.transform` | Every LLM turn | Injects `<hivemind>` context into system prompt |
+| `tool.execute.before` | Before tool calls | Governance enforcement (warns on writes without intent) |
+| `tool.execute.after` | After tool calls | Tracks metrics, violations, drift detection |
+| `experimental.session.compacting` | Context compaction | Preserves hierarchy across LLM context boundaries |
 
-**Behavior:**
-- One nudge per session (deduplicated)
-- Resets when new intent is declared
-- Logs: `[Nudge] Complexity rising (X files, Y turns). Consider declare_intent.`
+> **Note:** In OpenCode v1.1+, `tool.execute.before` cannot block execution. HiveMind provides governance through warnings and tracking only.
 
-## Architecture
+## Configuration
 
-```
-┌─────────────────────────────────────────┐
-│           OpenCode Agent                │
-└─────────────┬───────────────────────────┘
-              │
-┌─────────────▼───────────────────────────┐
-│      HiveMind Plugin (3 hooks)          │
-│  ├─ tool.execute.before (governance)    │
-│  ├─ chat.message (sentiment detection)  │
-│  └─ experimental.session.compacting     │
-└─────────────┬───────────────────────────┘
-              │
-┌─────────────▼───────────────────────────┐
-│      4 Lifecycle Tools                  │
-│  ├─ declare_intent                      │
-│  ├─ map_context                         │
-│  ├─ compact_session                     │
-│  └─ self_rate                           │
-└─────────────┬───────────────────────────┘
-              │
-┌─────────────▼───────────────────────────┐
-│      State Management                   │
-│  ├─ brain.json (runtime state)          │
-│  ├─ active.md (session focus)           │
-│  └─ index.md (project trajectory)       │
-└─────────────────────────────────────────┘
+Configuration is stored in `.hivemind/config.json` and re-read from disk on every hook invocation (Rule 6: config persistence).
+
+```json
+{
+  "governance_mode": "assisted",
+  "max_turns_before_warning": 5,
+  "auto_compact_on_turns": 15,
+  "stale_session_days": 3,
+  "commit_suggestion_threshold": 3,
+  "max_active_md_lines": 50,
+  "language": "en"
+}
 ```
 
-## Development
+## CLI
 
 ```bash
-# Install dependencies
-npm install
+npx hivemind init              # Initialize HiveMind in a project
+npx hivemind init --mode strict # Initialize with strict governance
+npx hivemind status            # Check current state
+npx hivemind help              # Show help
+npx hivemind --help            # Show help
+```
 
-# Run tests
-npm test
+### Ecosystem Verification (`bin/hivemind-tools.cjs`)
 
-# Type check
-npm run typecheck
+```bash
+node bin/hivemind-tools.cjs source-audit    # Verify all source files
+node bin/hivemind-tools.cjs list-tools      # List all 14 tools
+node bin/hivemind-tools.cjs list-hooks      # List all 4 hooks
+node bin/hivemind-tools.cjs verify-package  # Check npm package completeness
+```
 
-# Build
-npm run build
+## Project Structure
 
-# Watch mode
-npm run dev
+```
+.hivemind/
+├── 10-commandments.md   # Tool design reference
+├── sessions/
+│   ├── index.md         # Project trajectory (goals, constraints, history)
+│   ├── active.md        # Current session
+│   ├── manifest.json    # Session registry
+│   └── archive/         # Completed sessions
+├── templates/
+│   └── session.md       # Session template
+├── hierarchy.json       # Navigable tree hierarchy
+├── brain.json           # Machine state (session, metrics, hierarchy)
+├── config.json          # Governance settings
+├── anchors.json         # Immutable facts
+└── mems.json            # Persistent memory brain
 ```
 
-## Test Coverage
+## Typical Workflow
 
-| Component | Assertions | Status |
-|-----------|-----------|--------|
-| Schema (BrainState, Hierarchy) | 35 | ✅ Pass |
-| Init + Planning FS | 29 | ✅ Pass |
-| Tool Gate (governance) | 12 | ✅ Pass |
-| Self-Rate Tool | 28 | ✅ Pass |
-| Integration Tests | 27 | ✅ Pass |
-| **Total** | **131** | ✅ **All Pass** |
+```
+1. Start session
+   declare_intent({ mode: "plan_driven", focus: "Build auth system" })
 
-## Requirements
+2. Work on high-level planning
+   map_context({ level: "trajectory", content: "OAuth2 + JWT architecture" })
 
-- Node.js 18+
-- OpenCode with plugin support
+3. Switch to implementation
+   map_context({ level: "tactic", content: "Set up Passport.js" })
 
-## Design Philosophy
+4. Specific action
+   map_context({ level: "action", content: "Install passport-jwt package" })
+   [do the work...]
 
-| Principle | Description |
-|-----------|-------------|
-| **Lightweight** | 4 tools, 3 hooks — minimal surface area |
-| **User-driven** | No agent hierarchy — you control the workflow |
-| **Soft enforcement** | Warns and logs, never hard-blocks |
-| **Session brain** | Every session is archived and traceable |
-| **Drift-aware** | Automatic detection via sentiment + complexity |
-| **Self-assessment** | Built-in 1-10 scale rating for agent self-awareness |
+5. Mark complete, next action
+   map_context({ level: "action", content: "Install passport-jwt", status: "complete" })
+   map_context({ level: "action", content: "Configure JWT strategy" })
 
-## Documentation
+6. Finish session
+   compact_session({ summary: "Auth system foundation complete" })
+```
 
-- [AGENTS.md](./AGENTS.md) — Complete guide for agents using the tools
-- [CHANGELOG.md](./CHANGELOG.md) — Release history
+## Test Coverage
+
+| Component | Assertions |
+|-----------|-----------|
+| Schema (BrainState, Hierarchy) | 35 |
+| Init + Planning FS | 30 |
+| Tool Gate (governance) | 12 |
+| Soft Governance (tracking) | 27 |
+| Self-Rate Tool | 28 |
+| Complexity Detection | 28 |
+| Integration (E2E workflow) | 74 |
+| Auto-Hooks Pure Functions | 39 |
+| Session Export | 32 |
+| Session Structure | 18 |
+| Round 3 Tools (Cognitive Mesh) | 32 |
+| Round 4 Mems Brain | 40 |
+| Hierarchy Tree Engine | 55 |
+| Detection Engine | 45 |
+| Compact Purification | 34 |
+| Entry Chain (E2E lifecycle) | 56 |
+| Cycle Intelligence | 36 |
+| **Total** | **621** |
 
 ## License
 
 MIT
+
+---
+
+## Tiếng Việt
+
+### HiveMind là gì?
+
+HiveMind là một lớp quản lý ngữ cảnh nhẹ cho OpenCode, giúp ngăn chặn sai lệch (drift) và quản lý trạng thái phiên làm việc xuyên suốt vòng đời của agent AI.
+
+### Bắt đầu nhanh
+
+```bash
+npm install hivemind-context-governance
+npx hivemind init --lang vi
+```
+
+### Các chế độ quản lý
+
+| Chế độ | Hành vi |
+|--------|---------|
+| **strict** | Phiên bắt đầu ở trạng thái KHÓA. Cảnh báo khi ghi mà chưa khai báo ý định. |
+| **assisted** | Phiên bắt đầu ở trạng thái MỞ. Hướng dẫn nhưng không chặn. |
+| **permissive** | Luôn MỞ. Chỉ theo dõi im lặng. |
+
+### 14 Công cụ
+
+- **Cốt lõi:** `declare_intent`, `map_context`, `compact_session`
+- **Tự đánh giá:** `self_rate`
+- **Lưới nhận thức:** `scan_hierarchy`, `save_anchor`, `think_back`, `check_drift`
+- **Bộ nhớ:** `save_mem`, `list_shelves`, `recall_mems`
+- **Phân cấp:** `hierarchy_prune`, `hierarchy_migrate`
+- **Chu trình:** `export_cycle`
+
+### Quy trình làm việc
+
+1. Khai báo ý định → `declare_intent`
+2. Cập nhật ngữ cảnh → `map_context`
+3. Làm việc → sử dụng các công cụ nhận thức khi cần
+4. Lưu bài học → `save_mem`, `save_anchor`
+5. Kết thúc → `compact_session`