# HestAI-MCP

**Governance and session management layer of the HestAI ecosystem — pre-release, B1 Foundation phase**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

## Overview

HestAI-MCP is the governance and session management layer of the HestAI ecosystem — a five-system stack for AI-assisted software development. It is currently **pre-release at B1 (Foundation phase)**: functional and in daily use, but still discovering its full scope.

Its role in the ecosystem: **knows WHO agents are and HOW they should behave** — provider-agnostic. It does not spawn CLIs or know which model runs underneath; that is the workbench's job.

**What it does today:**
- Injects system governance (`.hestai-sys/`) into projects at runtime — agent constitutions, skills, rules — without copy-pasting between projects
- Tracks sessions (`clock_in`/`clock_out`) and archives transcripts in OCTAVE format
- Bootstraps agent binding (`bind`)
- Posts structured review comments to GitHub PRs (`submit_review`)

**What it's building toward:** persistent memory across sessions (the context feedback loop requires `context_update`, planned Phase 4), Orchestra Map dependency tracking (ADR-0034 MVP validated, automation not yet built), and document routing (`document_submit`, Phase 4).

**Where it fits:** built on `octave-mcp` (document format foundation), works alongside `odyssean-anchor-mcp` (identity binding ceremony, merger planned), `debate-hall-mcp` (structured deliberation), and `hestai-workbench` (execution/UI layer).

## Architecture

```
YOUR PROJECT (using HestAI)
├── .hestai-sys/              # TIER 1: SYSTEM (read-only, injected by MCP at runtime, gitignored)
│   ├── CONSTITUTION.md       # Immutable laws
│   ├── governance/           # Rules, North Stars
│   ├── library/
│   │   ├── agents/           # Agent definitions
│   │   ├── skills/           # Capability definitions
│   │   └── patterns/         # Reusable solution patterns
│   └── templates/            # Document templates
│
├── .hestai/                  # TIER 2: PROJECT GOVERNANCE (committed, PR-controlled)
│   ├── north-star/           # Project North Star
│   ├── decisions/            # Architectural Decision Records
│   ├── rules/                # Project-wide standards
│   └── state/ → .hestai-state/  # TIER 3: WORKING STATE (symlink, gitignored)
│       ├── context/          # Living context files (generated by clock_in)
│       ├── sessions/
│       │   ├── active/       # Current sessions
│       │   └── archive/      # Completed sessions (OCTAVE compressed)
│       └── reports/          # Generated reports
│
├── docs/                     # Developer documentation (ADRs, guides)
└── src/                      # Your code
```

**Note for AI Agents:** Even though `.hestai-sys/` is gitignored, you can still read it! Use:
- `Read .hestai-sys/README.md` - Start here for governance overview
- `Glob .hestai-sys/**/*.md` - Discover all governance files

### Key Principle: Single Writer

**All `.hestai/state/` writes go through MCP tools.** No direct file creation.

```
Agent → MCP Tool (clock_in/clock_out/bind) → System Steward → Files
```

This prevents:
- Multi-agent conflicts
- Governance drift
- Inconsistent documentation

### The Three Tiers

| Tier | Location | Git | Mutability |
|------|----------|-----|------------|
| **1: System Governance** | `.hestai-sys/` | Gitignored | Read-only (MCP-injected at runtime) |
| **2: Project Governance** | `.hestai/north-star/`, `.hestai/decisions/` | Committed | Human via PR |
| **3: Working State** | `.hestai/state/` (symlinked) | Gitignored | Via MCP tools (clock_in/clock_out) |

For detailed architecture, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## MCP Tools

| Tool | Purpose | Status |
|------|---------|--------|
| `clock_in` | Start session, create session dir, return context paths | Implemented |
| `clock_out` | End session, compress transcript to OCTAVE, archive | Implemented |
| `bind` | Lightweight agent binding bootstrap | Implemented |
| `submit_review` | Post structured review comments to GitHub PRs | Implemented |
| `document_submit` | Route docs to correct location | Planned (Phase 4) |
| `context_update` | Update context with conflict resolution | Planned (Phase 4) |

## Documentation Format

### When to use OCTAVE (`.oct.md`)
- Agent constitutions
- Governance rules
- North Stars
- Context files (PROJECT-CONTEXT, etc)
- Session archives

### When to use Markdown (`.md`)
- Developer guides
- ADRs
- READMEs
- Setup instructions

**Decision:** Primary audience AI agents? → `.oct.md`. Human developers? → `.md`

## Quick Start

```bash
# Clone and install (uv recommended)
git clone https://github.com/elevanaltd/HestAI-MCP.git
cd hestai-mcp
uv sync --all-extras

# Run tests
.venv/bin/python -m pytest

# Check quality
.venv/bin/python -m ruff check src tests scripts && .venv/bin/python -m mypy src && .venv/bin/python -m black --check src tests scripts
```

### MCP Configuration

**Default behavior (simplest):** `.hestai-sys` is created in the current working directory where the server runs:

```json
{
  "mcpServers": {
    "hestai": {
      "command": "python",
      "args": ["-m", "hestai_mcp.mcp.server"]
    }
  }
}
```

**Optional override:** Control location via `HESTAI_PROJECT_ROOT` env var:

```bash
# .env file (optional - only if you want a custom location)
HESTAI_PROJECT_ROOT=/path/to/shared/location
```

> **Opt-in:** Governance injection only runs if the project has a `.hestai/` directory or `HESTAI_GOVERNANCE_ENABLED=true` in `.env`. New projects must opt in explicitly.

> **Design:** Follows the debate-hall pattern - creates governance in CWD by default, just like `./debates/`. Each project/worktree gets its own `.hestai-sys` unless explicitly configured otherwise.

## Governance Rules

Documentation placement is governed by rules injected to `.hestai-sys/governance/rules/` (source: `src/hestai_mcp/_bundled_hub/governance/rules/`):

| Rule | Document | Purpose |
|------|----------|---------|
| **Visibility** | `visibility-rules.oct.md` | Where docs belong (product placement) |
| **Hub Authoring** | `hub-authoring-rules.oct.md` | What goes in system governance (`.hestai-sys/`) |
| **Naming** | `naming-standard.oct.md` | How to name files |
| **Format** | In visibility-rules | When to use OCTAVE vs Markdown |

## Development Status

- ✅ Phase 0-2: Foundation, porting, MCP server
- ✅ Phase 2.5: Hub architecture, bundled governance
- ✅ Odyssean Anchor: Agent identity binding (ADR-0036)
- ✅ Clock tools: Session lifecycle with AI synthesis
- ✅ Submit review: GitHub PR review comment tool
- 🚧 Phase 3: Single writer tools (document_submit, context_update)
- 🚧 Phase 5: Fractal refactor and modularization (ADR-0184)

## Related

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Detailed architecture

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

"Odyssean Anchor" is a registered trademark of Shaun Buswell - see [docs/trademarks.md](docs/trademarks.md) for usage guidelines.