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:

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:

npm install
npm run verify
npm run link

npm run verify completes green from a clean npm install on this host. See Verification status for the recorded gate evidence.

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

/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:

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. Seven evidence-backed gates PASS, one FAILS on dev-only transitive advisories, and two 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`	PASS — 0 vulnerabilities
Full development tree audit	`npm audit`	FAIL — 16 advisories (9 moderate, 7 high)
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

The development-tree FAIL is disclosed, not waived. Every advisory (adm-zip, fast-xml-parser, sharp/libvips, @opentelemetry/core, tar) is transitive under the @oh-my-pi/* peer SDK and dev-only: npm audit --omit=dev reports 0, and POM’s three runtime dependencies are crc-32, yauzl, and yazl, so nothing reaches the published tarball. No in-window remediation exists — npm audit fix --dry-run changes 0 packages and still reports 16, because the vulnerable versions are pinned by the SDK’s own ranges. Clearing it requires an upstream @oh-my-pi release; forcing it would leave the >=16.4.6 <17 peer window.

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

/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:

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; every POM document is reachable from there.

Direct links: Settings, Architecture, Tool Matrix, Ownership, Boundary, and Vault.

Development

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

POM 2 Documentation

Explorer

README