Project State

Project State — Full Reference

Tier 2: detection algorithm, fallback chain, SQLite schema, MCP protocol, CLI toolkit, STATE.md/TASKS.md templates.

1. Mode Configuration

Set once during hseos install. Stored in hseos.config.yaml:

state_management:
  mode: hybrid          # mcp-sqlite | cli-sqlite | skill-only | hybrid
  db_path: .hseos/state/project.db   # used by mcp-sqlite and cli-sqlite
  mcp_port: 3100        # used by mcp-sqlite
  fallback_chain:       # only used when mode = hybrid
    - mcp-sqlite
    - cli-sqlite
    - skill-only

2. Mode Descriptions

2.1 mcp-sqlite — Structured + Atomic

• MCP server at localhost:3100 exposes tools: state_read, state_write, tasks_list, tasks_update
• SQLite backend: structured queries, transactions, history
• Best for: teams, multi-agent workflows, long-running epics
• Requires: tools/mcp-project-state/ running (started via hseos state start)

2.2 cli-sqlite — Shell Toolkit

• Shell scripts (tools/cli-project-state/project-state.sh) and PowerShell (project-state.ps1)
• Same SQLite file, no server process required
• Best for: solo developers, CI pipelines, offline use
• Requires: sqlite3 on PATH (bash) or PSSQLite module (PowerShell)

2.3 skill-only — Zero Infrastructure

• Direct markdown writes to STATE.md and TASKS.md
• No dependencies, no install, works everywhere
• Best for: minimal setup, quick projects, environments without tooling
• Limitations: no atomicity, no query capability, no history

2.4 hybrid — Auto-detect with Fallback

• Runtime detection at session start
• Falls back gracefully when a higher-tier backend is unavailable
• Fallback order: mcp-sqlite → cli-sqlite → skill-only

3. Hybrid Detection Algorithm

function detect_mode():
  config = load hseos.config.yaml → state_management
  if config.mode != hybrid:
    return config.mode

  // Try MCP
  probe = curl -s -o /dev/null -w "%{http_code}" http://localhost:{mcp_port}/health
  if probe == "200":
    return mcp-sqlite

  // Try CLI
  if which sqlite3 || which pwsh:
    if file_exists(config.db_path):
      return cli-sqlite
    if can_create(config.db_path):
      return cli-sqlite

  // Fallback
  return skill-only

Agents MUST run detection once per session and cache the result in working memory.

4. MCP Server Protocol

Server: tools/mcp-project-state/index.js (Node.js + better-sqlite3)

4.1 Tools exposed

4.2 Start / stop

hseos state start    # starts MCP server in background (port 3100)
hseos state stop     # stops MCP server
hseos state status   # shows mode, backend, db path, server status

4.3 SQLite schema

CREATE TABLE state (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL,
  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE tasks (
  id TEXT PRIMARY KEY,
  owner TEXT NOT NULL,
  description TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',  -- pending | done | blocked
  depends_on TEXT,  -- JSON array of task IDs
  note TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE state_history (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  key TEXT NOT NULL,
  old_value TEXT,
  new_value TEXT NOT NULL,
  changed_by TEXT NOT NULL,  -- agent code
  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
);

5. CLI Toolkit

5.1 Bash — tools/cli-project-state/project-state.sh

./project-state.sh state read
./project-state.sh state write branch feature/my-feature
./project-state.sh state write phase execution
./project-state.sh tasks list
./project-state.sh tasks list --status pending
./project-state.sh tasks add T5 GHOST "Implement auth endpoint"
./project-state.sh tasks done T5
./project-state.sh tasks block T6 "waiting on T5"

5.2 PowerShell — tools/cli-project-state/project-state.ps1

./project-state.ps1 state read
./project-state.ps1 state write -key branch -value feature/my-feature
./project-state.ps1 tasks list
./project-state.ps1 tasks add -id T5 -owner GHOST -desc "Implement auth endpoint"
./project-state.ps1 tasks done -id T5

6. STATE.md Template

Location: STATE.md (project root)

# Project State

> Managed by HSEOS. Do not edit manually — use `hseos state write` or let agents update this.
> Last updated: {{updated_at}}

## Current State

- **branch:** {{branch}}
- **epic_id:** {{epic_id}}
- **phase:** {{phase}}
- **active_agent:** {{active_agent}}
- **status:** {{status}}
- **last_updated:** {{last_updated}}

## Features

| ID | Feature | Status | Branch |
|---|---|---|---|
| F1 | {{name}} | {{status}} | {{branch}} |

## Deployment

| Environment | Version | Status | Last Deploy |
|---|---|---|---|
| dev | {{version}} | {{status}} | {{timestamp}} |
| staging | — | — | — |
| prod | — | — | — |

## Notes

{{freeform notes — cleared on each phase transition}}

7. TASKS.md Template

Location: TASKS.md (project root)

# Task Backlog

> Managed by HSEOS. Agents update this file on every task transition.
> Prune completed tasks when > 5 done and no open task depends on them.

## In Progress

- [~] T{{id}} — [{{owner}}] {{description}} *(depends: {{deps}})*

## Pending

- [ ] T{{id}} — [{{owner}}] {{description}} *(depends: {{deps}})*

## Blocked

- [~] T{{id}} — [{{owner}}] {{description}} — **Blocked:** {{reason}}

## Completed (last sprint)

- [x] T{{id}} — [{{owner}}] {{description}}

8. Agent Responsibilities

9. Escalation

Escalate (inform user) when:

• Hybrid detection falls back from MCP to CLI (log warning: "MCP unavailable, using CLI")
• Hybrid detection falls back from CLI to skill-only (log warning: "CLI unavailable, using markdown")
• STATE.md or TASKS.md is absent and the project config expects them
• Concurrent write conflict detected (two agents wrote in the same minute — check timestamps)

Quick Mode

For low-context activation, load .enterprise/governance/agent-skills/project-state/SKILL-QUICK.md or QUICK.md first. Load this full skill for deep analysis, violation fixing, or formal review gates.