pom-omp/README.md

# POM 2 — Produce Magnum Opus

POM is an Oh My Pi extension that turns OMP's native models, tools, task agents, IRC, todo system, sessions, approvals, compaction, and TUI into an evidence-gated production operating system.

POM does **not** replace OMP's execution primitives. It governs them with stage contracts, canonical artifacts, prompt provenance, deterministic validation, Git checkpoints, and an Obsidian/Quartz-compatible knowledge base.

## What ships

- 9 authoritative production stages (`0` through `8`)
- 7 typed `pom_*` tools
- 14 specialist task agents
- 13 prepared prompt fragments
- 3 scoped production rules
- 2 installable OMP themes
- Native task + IRC Hive planning
- Optional OMP Swarm DAG generation
- Evidence-backed gates and blocker lifecycle
- Symlink-safe artifact registration with SHA-256 and semantic versions
- Streaming ZIP creation plus central-directory, decompression, size, and CRC-32 verification
- Obsidian-flavoured Markdown vault ready for Quartz 5

## Install and verify

### Prerequisites

| Requirement | Version | Why |
|---|---|---|
| Node.js | 22 or newer | Runs the local scripts (`verify`, `smoke`, `release:check`) and the `node:test` suite |
| npm | bundled with Node 22 | Installs dependencies and links the plugin into the OMP host |
| Bun | `>=1.3.14` (`engines.bun`) | Runs the OMP host that loads this extension |
| OMP | installed and on `PATH` | Provides `omp plugin link` and `omp plugin doctor` |
| `@oh-my-pi/pi-coding-agent` | `>=16.4.6 <17` | Peer dependency: extension host API |
| `@oh-my-pi/pi-tui` | `>=16.4.6 <17` | Peer dependency: TUI components |
| `@oh-my-pi/pi-utils` | `>=16.4.6 <17` | Peer dependency: host paths and shared utilities |

POM has no build step. OMP loads the TypeScript under `src/` directly, so the installed tree is the shipped tree.

### Source checkout install

Step 1 — obtain the repository source. Canonical project coordinates are recorded in `package.json` and point at the maintainer's own infrastructure rather than a third-party forge:

| Field | Value | State |
|---|---|---|
| `homepage` | `https://wiki.pom.loca.zone/` | Live |
| `bugs.url` | `https://wiki.pom.loca.zone/` | Live |
| `bugs.email` | `antigravity@loca.zone` | Live |
| `repository.url` | `git+https://git.omp.loca.zone/jamminrebel/pom-omp.git` | Live — self-hosted Gitea, anonymous clone |

There is deliberately no public forge mirror and this package has never been published to npm. Clone from the owned endpoint:

```bash
git clone https://git.omp.loca.zone/jamminrebel/pom-omp.git
```

Do not substitute a third-party URL that has not been confirmed.

Step 2 — install, verify, and link from the checkout root:

```bash
npm install
npm run verify
npm run link
```

`npm run verify` completes green from a clean `npm install` on this host. See [Verification status](#verification-status) for the recorded gate evidence.

Step 3 — restart OMP or run `/reload-plugins`, then install the bundled themes:

```text
/pom theme install
```

POM inserts `/theme pom-nocturne` into the editor. Press Enter to activate it. `pom-parchment` is the matching light theme.

Step 4 — run the host-level check in an environment with Bun and OMP installed:

```bash
npm run doctor
```

### Published package install

The published-package flow installs `@jamminrebel/pom-omp` into the OMP host, which then discovers the extension through the `omp.extensions` entry (`./src/index.ts`). No `npm install` line is printed here because no published tarball from this repository has been produced or verified against the precondition below.

Precondition: the tarball must contain `prompts/`. `src/prompts.ts` resolves bundled prompt fragments from `../prompts` at runtime, and `prompts` was only added to the `files` array in `package.json` as of this change. Any published tarball predating this change ships without `prompts/`, so prompt composition fails at runtime; such a tarball must not be relied on.

### Verification status

Overall readiness: GREEN for the six repository-local gates; four host-dependent gates remain NOT RUN.

`npm run verify` exits 0 from a clean `npm install` on this host. Each gate below is recorded as evidence under `00_admin/validation/` and rendered into `RELEASE.json` by `scripts/release-manifest.mjs`; a missing evidence file renders NOT RUN, and `passed !== true` renders FAIL.

| Gate | Command | State |
|---|---|---|
| TypeScript | `npm run check` | PASS |
| Behavioral tests | `npm test` | PASS |
| Runtime smoke | `npm run smoke` | PASS |
| Structural verification | `node scripts/verify.mjs` | PASS |
| Theme schema | asserted inside `scripts/verify.mjs` | PASS |
| Pack dry run | `npm run pack:dry` | PASS |
| Production dependency audit | `npm audit --omit=dev` | NOT RUN |
| Full development tree audit | `npm audit` | NOT RUN |
| OMP plugin doctor | `npm run doctor` | NOT RUN — requires Bun plus an installed OMP host |
| Interactive TUI smoke | manual OMP session | NOT RUN — requires an interactive terminal |

Never satisfy a gate with a stub: do not vendor dependencies into the repository, and do not hand-write or copy the OMP SDK packages or the OMP theme schema. A gate satisfied by a stub proves nothing about the shipped extension.

Dependency requirements per check:

| Check | Needs installed dependencies |
|---|---|
| `npm run smoke` | No — runs through `tsx` against `src/` without resolving the OMP SDK at runtime |
| `npm run release:check` | No — `scripts/release-manifest.mjs` uses Node builtins only |
| `node --import tsx --test tests/state.test.ts` | No — exercises state logic only |
| `npm run check` | Yes — OMP SDK type declarations plus `@types/node` |
| `npm test` (full suite) | Yes — `yauzl`, `yazl`, OMP SDK |
| `node scripts/verify.mjs` | Yes — reads the OMP theme schema from `node_modules` |
| `npm run pack:dry` | Yes — resolvable npm environment |
| `npm run doctor` | Yes — plus Bun and an installed OMP host |

## Production loop

```text
/pom new "My Project"
/pom run next
/pom hive stage
/pom evidence
/pom check stage
# The model calls pom_stage action=pass only after the report passes.
/pom export final
```

`/pom` opens the terminal command center. `Alt+P` is the keyboard shortcut.

## Command map

| Command | Purpose |
|---|---|
| `/pom` | Open the command-center overlay |
| `/pom new <title>` | Create project, vault, ledgers, state, and Git root |
| `/pom resume [state-path]` | Restore a canonical project state |
| `/pom run [next\|all\|0..8]` | Start authoritative production |
| `/pom hive [lean\|stage\|audit]` | Queue a native task + IRC specialist wave |
| `/pom swarm [parallel\|sequential\|pipeline] [count]` | Generate an optional OMP Swarm DAG |
| `/pom evidence` | Record acceptance evidence interactively |
| `/pom check [scope]` | Run deterministic validation |
| `/pom vault` | Insert the production-board mention |
| `/pom export [checkpoint\|final]` | Build and verify an archive |
| `/pom prompt [list\|show\|run] [id]` | Inspect or run prompt fragments |
| `/pom tools [show\|reset\|profile <name>]` | Inspect or change active-tool routing |
| `/pom theme install` | Install POM Nocturne and Parchment |
| `/pom status [--json]` | Inspect canonical project state |
| `/pom settings` | Configure density, motion, thinking lane, and HUD placement |
| `/pom doctor` | Run POM's project diagnostics |
| `/pom help` | Show built-in command reference |

Validation scopes: `quick`, `stage`, `canon`, `continuity`, `knowledge`, `files`, `delivery`, and `all`.

## Project knowledge base

Every project contains a publishable knowledge layer:

```text
content/
├── index.md
├── production-board.md
├── artifact-index.md
├── 01-planning.md
├── 02-story-bible.md
├── 03-manuscript.md
├── 04-visuals.md
├── 05-research.md
├── 06-ledgers.md
└── 07-delivery.md
```

The generated notes use YAML frontmatter, wikilinks, callouts, maps of content, and canonical file links. Project truth remains in the project tree; the vault is its navigable knowledge projection.

## Visual experience

POM uses OMP hooks rather than raw ANSI logging:

- Persistent production HUD via `setWidget()`
- Compact stage/gate/Hive segments via `setStatus()`
- Semantic active-phase text via `setWorkingMessage()`
- Expandable validation, Hive, and milestone message cards
- Tool call/result renderers with partial-state feedback
- Keyboard-controlled custom overlay
- Optional visible-thinking lane annotation
- Width-safe rendering and cached unchanged HUD frames

The interface rewards verified evidence, resolved blockers, clean handoffs, stage completion, and archive verification—not meaningless activity.

## Configuration

OMP host settings belong in `<project>/.omp/config.yml`. POM-specific settings belong in `<project>/.omp/pom.json`; global POM defaults may live at `~/.omp/agent/pom.json`.

Start at the [documentation index](docs/index.md); every POM document is reachable from there.

Direct links: [Settings](docs/SETTINGS.md), [Architecture](docs/ARCHITECTURE.md), [Tool Matrix](docs/TOOL_MATRIX.md), [Ownership](docs/OWNERSHIP.md), [Boundary](docs/BOUNDARY.md), and [Vault](docs/VAULT.md).

## Development

```bash
npm run check
npm test
npm run smoke
npm run verify
npm pack
```

The local test suite imports production code. The final host smoke test remains `omp plugin doctor` plus an interactive OMP session.

`npm run check`, `npm test`, and `npm run verify` require a complete `node_modules`; see [Verification status](#verification-status) for the recorded gate evidence.

## Governing law

> OMP performs the work. POM governs the production. The vault preserves the truth. Git preserves its history. Validation earns every completion claim.