= STATE
image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]

:toc: left
:toclevels: 3
:source-highlighter: highlight.js

*Stateful Context Tracking Engine for AI Conversation Continuity*

== Overview

STATE is a checkpoint/restore system for AI conversations that persists project
context, decisions, and next actions across multiple Claude conversations.

=== Problem

* Each new Claude conversation starts with zero context about ongoing projects
* Complex project interdependencies get lost between sessions
* Progress gets reset; decisions already made must be repeated
* Token limits force mid-project context loss

=== Solution

* Single declarative file (`STATE.a2ml`) in A2ML (Annotated Markup Language)
* Human-readable TOML-like key-value format (not JSON/binary)
* Download at end of session -> Upload at start of next
* Claude reads it and resumes exactly where you left off
* Includes: current project focus, blockers, next actions, completion percentages

== Quick Start

=== Development Environment

*Primary (Guix):*

[source,bash]
----
guix shell -m manifest.scm
just test
----

*Fallback (Nix):*

[source,bash]
----
nix develop
just test
----

*Container (Wolfi + Guix):*

[source,bash]
----
nerdctl build -t state:latest .
nerdctl run -it --rm state:latest
----

=== End of Conversation

----
User: "Create STATE handover and prepare for next session"
Claude:
  1. Updates all project completion percentages
  2. Lists critical blockers
  3. Exports STATE.a2ml
  4. Says: "Download STATE.a2ml now - you'll upload it next session"
----

=== Start of Next Conversation

----
User: [Uploads STATE.a2ml] "Continue from this state"
Claude:
  1. Reads and parses STATE.a2ml
  2. Reconstructs project context
  3. Identifies current focus
  4. Picks up exactly where last conversation left off
----

== Technology Stack

*Language:* A2ML (Annotated Markup Language)

* TOML-like key-value format, human-readable
* Machine-parseable with standard TOML tooling
* Typed and verified document format

*Package Management:* Guix (primary), Nix (fallback)

*Containers:* Wolfi base image with Guix

== File Structure

The STATE.a2ml file contains these major sections:

[[metadata]]
=== Metadata
Format version and timestamps for tracking state evolution.

[[user]]
=== User Context
Name, roles, language preferences, tool preferences, and values.

[[session]]
=== Session Context
Conversation ID, message counts, and token limit status.

[[focus]]
=== Focus
Current project, phase, deadlines, and blocking dependencies.

[[projects]]
=== Project Catalog
Complete list of all projects with:

* Status (in-progress, blocked, paused, complete, abandoned)
* Completion percentage
* Category and phase
* Dependencies and blockers
* Next actions

[[history]]
=== History
Completion snapshots over time for velocity tracking and estimation.

[[critical-next]]
=== Critical Next Actions
Prioritized list of immediate actions with optional deadlines.

[[questions-for-maintainer]]
=== Questions for Maintainer (Advanced)
Categorized questions requiring human input. Prevents AI from making assumptions.

Categories: `architecture`, `priorities`, `integration`, `deployment`, `testing`, `community`

[[long-term-roadmap]]
=== Long-Term Roadmap (Advanced)
Extended roadmap with:

* `post-v1` - Planned releases after initial major version
* `vision-items` - Aspirational features without timeline
* `research-tracks` - Exploratory work with goals and status

[[state-summary]]
=== State Summary (Advanced)
Quick-reference snapshot for AI to assess project health at a glance.

[source,toml]
----
[state-summary]
project = "My Project"
version = "0.2.0"
overall-completion = 55
next-milestone = "v0.3"
critical-blockers = 0
high-priority-issues = 3
updated = "2025-12-08"
----

== Files in This Repository

=== Core

* `STATE.a2ml` - Template state file
* `lib/` - Modular library
* `examples/` - Example state files

=== Documentation

* `README.adoc` - This documentation
* `USAGE.adoc` - Comprehensive usage guide
* `CHANGELOG.adoc` - Version history
* `CONTRIBUTING.adoc` - Contribution guidelines
* `GOVERNANCE.adoc` - Project governance
* `CODE_OF_CONDUCT.adoc` - Community standards

=== Infrastructure

* `channels.scm` - Guix channel definition
* `manifest.scm` - Guix package manifest
* `guix.scm` - Guix package definition
* `flake.nix` - Nix flake (fallback)
* `Containerfile` - Wolfi + Guix container
* `justfile` - Task automation
* `.gitlab-ci.yml` - CI/CD pipeline

== Roadmap

=== Phase 1: Foundation

* [x] Basic STATE.a2ml structure
* [x] Project metadata encoding
* [x] Session checkpoint
* [x] Manual download/upload cycle

=== Phase 2: Smart Queries

* [x] Modular architecture
* [x] GraphViz DOT visualization
* [x] Mermaid diagram generation
* [x] History tracking
* [x] Velocity calculation
* [x] Time estimation

=== Phase 3: Automation

* [ ] Elixir service for STATE.a2ml read/write
* [ ] Integration with Echomesh for automatic state capture
* [ ] Periodic exports
* [ ] Diff tracking

=== Phase 4: Full Integration

* [ ] UPM (Universal Project Manager) integration
* [ ] Git hooks for auto-update on commits
* [ ] Team collaboration features

== License

PMPL-1.0-or-later. See LICENSE.txt for details.

== Author

Designed by Jonathan D.A. Jewell +
Implemented with Claude assistance +
December 2025
