# Intent Petri

A Pi coding-agent extension that maintains a human-oriented intent and action map as a dynamically detailed Petri corridor.

Intent Petri is not a tool-call dashboard. It helps a person recover orientation during a long-running coding-agent session:

- **STACK** — the certain refinement chain from North Star to the current leaf;
- **NOW** — which committed leaf intent is active;
- **WHY** — why this action is active now;
- **NEXT** — committed successors and explicitly provisional future paths;
- **WATCH** — gates, plan-adjustment triggers, failures, or path tensions needing attention.

## Current scope · V2.3 web hub

- one Pi main Agent and one Execution Token per session;
- schema-2, revisioned, atomic GraphPatch updates;
- arbitrarily nested hierarchical refinement with one executable active leaf;
- `committed / provisional / directional` planning semantics;
- branch-aware state and history reconstruction from verified Pi checkpoints;
- Mermaid TD projections plus atomic `current.json` / `activity.json` session exports;
- **local multi-session web hub** (`intent-petri-hub`) as the primary visualization;
- no Intent Petri status line, widget, modal, float pane, or Herdr terminal graph plugin inside Pi;
- extension version/source diagnostics and user-npm preference over duplicate project-local instances;
- a private append-only SQLite audit cache that is never branch authority.

Observed execution reconciliation, automatic Observer proposals, multi-Agent split/join, macOS Pet, and a native model Path Head remain out of scope.

## Visualization · multi-session web hub

Frontend stack: **Vite + React** (`hub-ui/`), built to static assets and served by the local hub. Chosen for clear component boundaries and low ceremony while iterating on graph/list UX. Not TanStack Start / SvelteKit — this is a localhost single-page app, not a full-stack product.

Each Pi window writes its own projection under:

```text
$XDG_STATE_HOME/intent-petri/sessions/<session-id>/active/
```

A **singleton** local hub process serves every session at once:

```bash
# from this repo (builds UI then ensures hub):
nub run hub

# or after UI is built:
nubx intent-petri-hub ensure --open
```

UI development (hot reload, proxies `/api` → hub):

```bash
nub run hub:ui:dev
# separate terminal: node bin/intent-petri-hub.mjs ensure
```

- List: `http://127.0.0.1:7731/`
- One session: `http://127.0.0.1:7731/s/<session-id>`
- Bind: `127.0.0.1` only
- Port: `INTENT_PETRI_HUB_PORT` (default `7731`)
- Auto-open browser on session start: set `INTENT_PETRI_HUB_OPEN=1`

Inside Pi:

```text
/intent-petri status
/intent-petri doctor
/intent-petri viewer   # ensures hub and opens the session URL
```

The extension starts the hub in the background on `session_start` (no browser focus steal by default). Terminal `intent-petri-viewer` remains available for offline ASCII dumps; it is no longer the primary UI. The Herdr graph plugin has been removed.

## Development

This project uses [nub](https://nubjs.com/docs):

```bash
nub install
nub run typecheck
nub run test
nub run package:check
nub run smoke:extension
```

Try the extension without installing it globally:

```bash
INTENT_PETRI_PREFER_LOCAL=1 pi --no-extensions -e .
```

`/intent-petri doctor` reports the exact loaded version, source path, and hub status. A repository copy loaded with `-e .` is suppressed when the user npm package is installed; set `INTENT_PETRI_PREFER_LOCAL=1` only for intentional development smoke tests.

The Agent receives the schema-2 `update_action_path` tool. Current leaves and ancestor shells must be committed; future nodes may remain provisional or directional until evidence selects them.

## Documentation

- [Intent Petri V2: certain current stack, provisional future](VERSION2.md)
- [Why this project exists](docs/kickoff/START.md)
- [Conversation that started it](docs/kickoff/CHAT.md)
- [Intent Petri design](docs/design/INTENT_PETRI_NET.md)
- [Archived telemetry-first design](docs/design/TRACE_PI_ARCHIVE.md)
- [Pi extension API notes](docs/references/PI_EXTENSION_API.md)
- [V2 implementation report](docs/implementation/V2.md)
- [V2 acceptance record](docs/implementation/V2_ACCEPTANCE.md)
- [Shipping Slice 1 implementation report](docs/implementation/SLICE_1.md)