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.omp.loca.zone/` | Live |
| `bugs.url` | `https://wiki.omp.loca.zone/` | Live |
| `bugs.email` | `antigravity@loca.zone` | Live |
| `repository.url` | `git+https://omp.loca.zone/pom-omp.git` | Reserved — not yet serving Git |

There is deliberately no public forge mirror: this package has never been published to npm, and no GitHub or self-hosted Git endpoint exists for it today. Until `repository.url` is actually served, obtain the checkout out of band from the maintainer. 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` does not currently complete in this environment. See [Verification status](#verification-status) before treating a failure as a code defect.

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: PARTIAL.

Currently passing:

| Check | Command |
|---|---|
| Extension smoke test | `npm run smoke` |
| Release manifest parity | `npm run release:check` |
| State unit tests | `node --import tsx --test tests/state.test.ts` |

The full gate is BLOCKED, not passing. `npm run verify` cannot complete because an npm registry outage (repeated `ETIMEDOUT` on install) left `node_modules` incomplete. Missing at minimum:

| Missing | Blocks |
|---|---|
| `@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-tui`, `@oh-my-pi/pi-utils` | `npm run check`, every test importing `src/` modules that reference the OMP SDK |
| `@types/node` | `npm run check` (`tsc --noEmit`) |
| `yauzl` | `tests/zip.test.ts` and the archive verification path in `src/zip.ts` |
| `node_modules/@oh-my-pi/pi-coding-agent/src/modes/theme/theme-schema.json` | `node scripts/verify.mjs` theme validation |

No claim is made that `npm run verify` has passed in this environment.

### Registry outage and offline guidance

Rules while the registry is unreachable:

- Do not vendor dependencies into the repository.
- Do not stub, hand-write, or copy the OMP SDK packages or the OMP theme schema to turn a gate green. A gate satisfied by a stub proves nothing about the shipped extension.
- Repair or retry registry access, rerun `npm install`, then rerun the full `npm run verify` gate and record its real result.

What each check needs:

| Check | Offline without installed dependencies |
|---|---|
| `npm run smoke` | Meaningful — runs through `tsx` against `src/` without resolving the OMP SDK at runtime |
| `npm run release:check` | Meaningful — `scripts/release-manifest.mjs` uses Node builtins only |
| `node --import tsx --test tests/state.test.ts` | Meaningful — exercises state logic only |
| `npm run check` | Requires installed dependencies (OMP SDK type declarations plus `@types/node`) |
| `npm test` (full suite) | Requires installed dependencies (`yauzl`, `yazl`, OMP SDK) |
| `node scripts/verify.mjs` | Requires installed dependencies (reads the OMP theme schema from `node_modules`) |
| `npm run pack:dry` | Requires a resolvable npm environment |
| `npm run doctor` | Requires Bun plus 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 what currently passes and what is blocked.

## Governing law

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