jamminrebel/pom-omp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initialize POM 2 repo (docs guards green; release gates recorded NOT RUN pending install)

Browse Source
This commit is contained in:
Antigravity
2026-08-19 10:31:00 +02:00
commit 7ffd00b5c5
111 changed files with 12522 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
README.md Normal file
View File

@@ -0,0 +1,222 @@
# 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.