pom-omp/AGENTS.md

# Repository Guidelines

## Project Overview

- identity: `@jamminrebel/pom-omp` 2.0.0, MIT, ESM — POM 2 "Produce Magnum Opus", an Oh My Pi (OMP) extension.
- purpose: turn OMP's native models, tools, task agents, IRC, todo, sessions, approvals, compaction and TUI into an evidence-gated production operating system for long-form creative work (README.md:3).
- governs, never replaces: OMP performs execution; POM adds stage contracts, canonical artifacts, prompt provenance, deterministic validation, Git checkpoints, and an Obsidian/Quartz-compatible vault (README.md:5, POM.yml:6-9, docs/ARCHITECTURE.md:3-27).
- ships: 9 stages (0..8), 7 `pom_*` tools, 14 task agents, 13 prompt fragments, 3 rules, 2 themes, native task+IRC Hive planning, optional Swarm DAGs, verified ZIP delivery (README.md:9-20).
- operator loop: `/pom new "Title"` -> `/pom run next` -> `/pom hive stage` -> `/pom evidence` -> `/pom check stage` -> model calls `pom_stage action=pass` only after a PASS report -> `/pom export final` (README.md:44-56). `/pom` opens the command center; `Alt+P` is the shortcut.
- this file is the repository contributor guide. Generated POM projects get their own `AGENTS.md` written by `bootstrapProject` (src/persistence.ts:241-307) — different file, different audience.

## Architecture & Data Flow

- flow: `/pom` command -> parser -> stage machine -> persistence + git + router -> prompt-stack injection -> OMP model turn -> `pom_*` tools -> validators -> exporter.
- entry point: default export `pomExtension(pi: ExtensionAPI)` in `src/index.ts`; sets label `POM · Produce Magnum Opus`, builds the runtime, then registers in this order: `registerPomTools`, `registerPomRenderers`, `registerPomEvents`, `registerPomCommand` (src/index.ts:13-49). Keep registration centralized there.
- runtime boundary: `src/runtime.ts` `PomRuntime` = `get`, `set`, `restore`, `getConfig`, `refreshConfig`, `telemetry`.
  - `set` clones state, stamps `updatedAt`, appends a session branch entry of type `pom-state`, writes `00_admin/project_state.json`, and syncs generated knowledge files when `state.initialized` (src/index.ts:25-31). Never persist state around it.
  - `restore` precedence: session branch via `restoreLatest` -> `<cwd>/00_admin/project_state.json` -> fresh uninitialized state (src/index.ts:33-42).
- command layer: `src/command.ts` registers `pom` plus shortcut `alt+p` and owns all verbs (`new`, `run`, `hive`, `swarm`, `evidence`, `check`, `vault`, `export`, `status`, `prompt`, `tools`, `theme`, `settings`, `doctor`, `help`). `src/parser.ts` tokenizes quotes/escapes, defaults the verb to `dashboard`, and parses `--flag[=value]` into a Map.
- stage run: `runStage` = `startStage(gotoStage(...))` -> `runtime.set` -> `enterStageBranch` -> `routeStage` -> `updateChrome` -> `pi.sendUserMessage(await renderStagePrompt(...), { deliverAs: "followUp" })` (src/command.ts:94-105).
- routing: `src/router.ts` applies the stage tool profile when `autoToolProfiles`, resolves `spec.modelRole` via `ctx.models.resolve`, calls `pi.setModel`, and sets thinking `xhigh` for every stage except stage 7 (`high`).
- domain: `src/domain.ts` holds `POM_VERSION` / `POM_SCHEMA_VERSION` (both "2.0.0"), `STAGES: readonly StageSpec[]`, `ArtifactRecord`, `EvidenceRecord`, `StageBlocker`, `StageRunState`, `HiveTask`, `HiveMission`, `PomState`, `PomConfig`, `DEFAULT_CONFIG`.
  - stages: 0 init, 1 genre, 2 voice, 3 store, 4 bible, 5 outline, 6 chapters, 7 draft, 8 delivery. Each `StageSpec` owns `id`, `slug`, `name`, `icon`, `toolProfile`, `modelRole`, `agents`, `artifacts`, `acceptance`, `todos`.
- state machine: `src/state.ts`, clone-then-mutate.
  - `gotoStage` rejects incomplete prerequisites; `startStage` rejects complete stages and unresolved blockers; `passStage` requires an active run, a validation report path, zero unresolved blockers, and evidence for every acceptance criterion (src/state.ts:97-188).
  - `recordEvidence` checks the criterion belongs to the active stage, demands a non-empty summary plus >=1 path, de-duplicates normalized paths, replaces prior evidence for that criterion (src/state.ts:144-168).
  - canonical state path: `<projectRoot>/00_admin/project_state.json` via `statePath`.
- persistence: `src/persistence.ts` serializes writes per absolute path (`writeQueues`), writes a temp file then `rename`, and appends a trailing newline to JSON.
  - manifest `00_admin/artifact_manifest.json`: entries need safe unique relative paths, stage 0..8, semver version, valid status, SHA-256, positive bytes, parseable `updatedAt`, valid rights status.
  - `registerArtifact`: `secureExistingPath` -> reject empty file -> `relativeProjectPath` -> SHA-256 -> manifest save -> `artifact.registered` in `00_admin/artifact_events.jsonl` -> knowledge sync (src/persistence.ts:123-163).
  - `bootstrapProject` creates `00_admin`, `01_planning`, `02_story_bible`, `03_manuscript/chapters`, `04_images/{references,generated}`, `05_research`, `06_ledgers`, `07_exports`, `.omp/prompts`, `content`, and refuses a non-empty unrecognized directory that has no `00_admin/project_state.json` (src/persistence.ts:216-239).
- events: `src/events.ts`.
  - `resources_discover` advertises bundled `../skills`, `../prompts`, `../themes` via `fileURLToPath(new URL(...))`; it does not advertise `agents/` or `rules/`.
  - `before_agent_start` injects the composed prompt stack into `event.systemPrompt` and returns a hidden `pom:event` message.
  - native `task` / `irc` are observed only: `tool_call` / `tool_result` update Hive mission status plus telemetry and append durable `native.task.started`, `native.task.finished`, `native.irc.send`, `native.irc.result` ledger events.
- prompts: `src/prompts.ts` loads bundled `../prompts` plus project `.omp/prompts`; id = markdown basename; project fragments override bundled by id; every fragment is SHA-256 stamped in an HTML comment (id/source/hash); a stack is immutable law -> `personality-${state.mode}` -> requested ids, and each use is logged to the prompt ledger.
- delegation: `src/studio.ts` builds `HiveMission` ids `s${spec.id}-${randomUUID().slice(0,8)}`, caps agents at `maxStudioAgents`, and converts a mission into one native task batch whose shared context tells agents to coordinate over native IRC and never pass the stage. `src/swarm.ts` optionally writes `00_admin/swarms/<missionId>.yaml` (specialists plus an `integrator`) through `secureFuturePath`.
- validation: `src/validators.ts` `validatePom(state, scope, opts)`; scopes `quick`, `stage`, `canon`, `continuity`, `knowledge`, `files`, `delivery`, `all`; report schema "1.0.0"; `passed` is true only when no check has status `fail`; reports land in `00_admin/validation/stage-<n>-<scope>-<stamp>.json` when initialized.
- delivery: `src/exporter.ts` writes `00_admin/SHA256SUMS.txt`, a delivery report under `07_exports`, then `07_exports/<projectSlug>-<kind>.zip`, verifies it and writes `<base>.verification.json`. `src/zip.ts` (yazl create, yauzl read, `crc-32`) rejects encryption, compression methods other than 0/8, duplicate members, unsafe names, empty archives, size drift and CRC mismatch, and returns the archive SHA-256.
- terminal: `src/ui.ts` writes statuses `pom-stage`, `pom-progress`, `pom-gate`, `pom-hive` and widget `pom-hud`; `src/visual.ts` renders the HUD with width-safe truncation and caches unchanged frames; `src/renderers.ts` renders custom message types `pom:event`, `pom:validation`, `pom:hive`, `pom:milestone` and adds a thinking lane when enabled and view is not minimal/compact.
- git: `src/git.ts` shells `execFile("git", ["-C", root, ...])`, initializes when needed, uses branches `pom/stage-<id>-<slug>`, and checkpoints with `git add -A` + `git commit` unless `gitMode` disables it.

## Key Directories

- src/: extension source, 25 modules, no build step (OMP loads TypeScript directly).
- tests/: 8 `*.test.ts` files on `node:test`, importing production code.
- scripts/: `verify.mjs` (structural gates), `release-manifest.mjs` (RELEASE.json generate/check), `smoke.ts` (runtime smoke), `install.sh` / `install.ps1`.
- agents/: 14 `pom-*.md` specialist task-agent definitions.
- prompts/: 13 prompt fragments; ids are basenames; `personality-*.md` map to `PomMode`.
- rules/: 3 scoped production rules (`pom-artifact-integrity`, `pom-continuity`, `pom-rights`).
- skills/pom/: `SKILL.md` plus `references/` (`core-law.jml`, `workflow.md`, `tool-routing.md`, `todo-blueprints.md`, `artifacts.md`, `agent-studios.md`, `commands.md`, `qa.md`, `ui.md`).
- themes/: `pom-nocturne.json` (dark), `pom-parchment.json` (light).
- config/: shipped templates — `config.yml` (OMP host settings), `pom.json` (POM defaults), `APPEND_SYSTEM.md`, `mcp.json.example`.
- docs/: `ARCHITECTURE.md`, `SETTINGS.md`, `TOOL_MATRIX.md`, `INVENTORY.md`, `AUDIT.md`, `DESIGN_REVIEW.md`, `OFFICIAL_SOURCES.md`, `POM_ARCHITECTURE.mmd`.

## Development Commands

- setup: `npm install`
- typecheck: `npm run check` -> `tsc --noEmit` (tsconfig includes `src/**/*.ts` only; tests are not typechecked)
- tests: `npm test` -> `node --import tsx --test tests/*.test.ts`
  - one file: `node --import tsx --test tests/state.test.ts`
  - one case: `node --import tsx --test --test-name-pattern="<regex>" tests/state.test.ts`
- runtime smoke: `npm run smoke` -> `node --import tsx scripts/smoke.ts`
- structural gates: `node scripts/verify.mjs`
- release manifest: `npm run release:manifest` (write), `npm run release:check` (fail if stale)
- full gate: `npm run verify` = check -> test -> smoke -> scripts/verify.mjs -> release:check -> `npm pack --dry-run`
- host install: `npm run link` (`omp plugin link .`), then restart OMP or `/reload-plugins`, then `/pom theme install`
- host check: `npm run doctor` (`omp plugin doctor`; needs Bun + OMP installed)

## Code Conventions & Common Patterns

- imports:
  - relative source imports are extensionless: `./state`, `./domain`, `./tool-profiles` — never `.ts` / `.js`, despite `allowImportingTsExtensions: true`.
  - Node builtins use the `node:` prefix; OMP SDK types come in as `import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent"`.
- errors: throw `Error` for precondition, schema, config, manifest and path violations (`assertState`, `loadPomConfig`, `secureExistingPath`); represent observable tool failures as `isError: true` results, not throws.
- tools: defined in `src/tools.ts`; ids are exactly `pom_state`, `pom_stage`, `pom_artifact`, `pom_validate`, `pom_prompt`, `pom_hive`, `pom_export`.
  - schemas use `const { z } = pi.zod` with inline `z.object` / `z.enum`; one targeted `@ts-expect-error` covers OMP 16.4.x + Zod v4 instantiation depth (src/tools.ts:58-61) — keep it narrow.
  - every result goes through `textResult(text, details?, isError = false)` -> `{ content: [{ type: "text", text }], details, isError }`.
  - mutators declare `approval: "write"`; `pom_validate` and `pom_prompt` declare `approval: "read"`.
  - every execute handler returns `textResult("Cancelled", undefined, true)` when `signal?.aborted`.
- state: clone with `structuredClone` before nested mutation, then persist through `runtime.set`.
- async: `async`/`await` everywhere for FS, OMP hooks, tools, config and validation; no callback style.
- naming: kebab-case multiword filenames (`tool-profiles.ts`); camelCase functions, PascalCase types; POM-owned identifiers keep the `pom` / `pom_` / `pom-` prefix per surface (tool ids `pom_*`, statuses `pom-*`, message types `pom:*`, agents `pom-*`).
- tool profiles: `src/tool-profiles.ts` appends POM tools to host tools for non-`auto` profiles, always keeps `read`, and stores the baseline in a `WeakMap` keyed by `pi` — use `resetToolBaselineForTests()` rather than assuming a fresh baseline.
- config: `src/config.ts` merges built-in `DEFAULT_CONFIG` -> `~/.omp/agent/pom.json` -> `<project>/.omp/pom.json`, validates booleans/enums/bounded integers and throws `Invalid POM setting ...`; writes go temp-file-then-rename.
  - keys and defaults: `autoToolProfiles` true, `autoModelRouting` true, `dashboardWidget` true, `stopGuard` true, `defaultMode` "autopilot", `defaultView` "cinematic", `defaultMotion` "subtle", `defaultToolProfile` "auto", `maxStudioAgents` 6, `projectRootMode` "child", `destructiveProjectCommands` "block", `gitMode` "branch-per-stage", `hudPlacement` "aboveEditor", `showThinkingLane` true (src/domain.ts:471-486, docs/SETTINGS.md:31-46).
  - OMP host settings belong in `<project>/.omp/config.yml`; the shipped template is `config/config.yml` and `bootstrapProject` writes the same values (theme `pom-nocturne`/`pom-parchment`, `task.maxConcurrency: 8`, `compaction.strategy: snapcompact`, `defaultThinkingLevel: high`).
- asset shapes:
  - agents: frontmatter `name: pom-<kebab>`, non-empty `description`, `tools:` list that includes `yield`, plus `model`, `thinkingLevel`, `read-summarize`; enforced by `scripts/verify.mjs:58-64`.
  - rules: frontmatter `description` plus `globs` array.
  - skill: `skills/pom/SKILL.md` frontmatter `name: pom`, `description`, `alwaysApply: false`.
  - prompts: frontmatter optional — personality fragments carry `description`, operational fragments start with prose; the loader accepts any `.md`.
  - themes: keep `$schema`, `name` (must equal filename stem), `vars`, `colors`, `export`; `/pom theme install` copies `themes/*.json` into `getCustomThemesDir()` from `@oh-my-pi/pi-utils`.
- POM.yml is the human-facing project/release manifest (boundaries, stages, gate, commands, tools, delegation, terminal, knowledge, integrity, resources, release) — not a runtime schema; nothing loads it at runtime.

## Important Files

- src/index.ts: extension entry, runtime construction, registration order.
- src/domain.ts: schema versions, `STAGES`, artifact/evidence/blocker/hive/state/config types, `DEFAULT_CONFIG`.
- src/state.ts: stage lifecycle invariants, evidence rules, canonical state path.
- src/persistence.ts: workspace layout, atomic writes, manifest/ledger/knowledge persistence, bootstrap.
- src/tools.ts: the 7 `pom_*` tool contracts, approvals, result shape.
- src/events.ts: OMP event surface, resource discovery, prompt injection, native task/IRC observation.
- src/validators.ts: deterministic checks and report contract.
- src/paths.ts: `canonicalRoot`, `secureExistingPath`, `secureFuturePath`, `relativeProjectPath`, `assertSafeArchivePath`.
- scripts/verify.mjs: structural release gates (see Testing & QA).
- scripts/release-manifest.mjs: RELEASE.json generation and `--check` staleness semantics.
- package.json: OMP entry `omp.extensions: ["./src/index.ts"]`, scripts, peer window, ship list.
- tsconfig.json: `target ES2022`, `module ESNext`, `moduleResolution Bundler`, `strict`, `noEmit`, `skipLibCheck`, `allowImportingTsExtensions`.

## Runtime/Tooling Preferences

- package manager: npm, authoritative `package-lock.json` (lockfileVersion 3). Do not introduce bun/pnpm/yarn lockfiles.
- local scripts run on Node + `tsx` + `tsc`; `engines.bun >= 1.3.14` describes the OMP host, and `npm run doctor` is the only Bun+OMP gate.
- no build step and no `dist/`: OMP loads `src/index.ts` directly.
- SDK window: `@oh-my-pi/pi-coding-agent`, `pi-tui`, `pi-utils` are peers at `>=16.4.6 <17`. Do not use APIs that require OMP 17.x.
- runtime dependencies are deliberately three: `crc-32`, `yauzl`, `yazl` (ZIP integrity). Add a dependency only when the host SDK and Node builtins genuinely cannot do the job.
- `.gitignore` covers `node_modules/`, `*.tgz`, `*.zip`, `coverage/`, `dist/`, `.DS_Store`, `*.log`.

## Testing & QA

- framework: Node's built-in runner, `import test from "node:test"` + `import assert from "node:assert/strict"`, flat `test("...")` calls, no `describe`.
- tests import production code directly with extensionless specifiers (`../src/state`); never copy implementation into a test.
- filesystem tests isolate with `mkdtemp(join(tmpdir(), ...))` and clean up in `finally` via `rm({ recursive: true, force: true })`.
- test-file names do not map 1:1 to modules: `tests/command.test.ts` exercises `src/parser.ts`, `tests/events.test.ts` exercises `src/policy.ts`.
- covered by unit tests: parser, policy, paths, state, domain, persistence, studio, swarm, validators, zip. Not directly covered: `src/tools.ts`, `src/visual.ts` — add tests there when changing behavior.
- `scripts/smoke.ts` is the end-to-end guard: bootstrap a temp project with `projectRootMode: "cwd"`, assert generated `.omp/config.yml` and `content/production-board.md` content, then assert `validatePom(state, "quick", { writeReport: false }).passed === true`.
- `scripts/verify.mjs` enforces, and will fail a change that breaks any of these:
  - required files exist, including `src/index.ts`, `src/events.ts`, `src/tools.ts`, `src/visual.ts`, `skills/pom/SKILL.md`, `config/APPEND_SYSTEM.md`, `prompts/stage-run.md`, both themes, `scripts/smoke.ts`.
  - `RELEASE.json.version === package.json.version`; release inventory stages/customTools/behavioralTests = 9/7/9; `pkg.omp.extensions` deep-equals `["./src/index.ts"]`; `pkg.version === "2.0.0"`; every `package.json.files` entry exists.
  - exactly one `registerCommand("pom"` and one `registerShortcut("alt+p"` in `src/command.ts`; exactly nine `id: 0..8` stage ids in `src/domain.ts`; exactly seven `name: "pom_*"` tools in `src/tools.ts`.
  - `src/tools.ts` contains none of `allowArgs`, `formatApprovalDetails`, `concurrency: "exclusive"`, `ExtensionAPI = any`; `src/omp-shim.d.ts` and `src/node-shim.d.ts` must not exist.
  - asset counts 14 agents / 13 prompts / 3 rules / 2 themes, agent frontmatter shape, theme names and required color keys (read from the installed `@oh-my-pi/pi-coding-agent` theme schema, so `npm install` is a prerequisite), and the nine required directories.
- after changing any shipped file (anything in `package.json.files` plus `package.json`), run `npm run release:manifest`; `npm run release:check` compares rendered bytes and fails with "RELEASE.json is stale".
- run `npm run verify` before packaging or linking. Host-level acceptance stays `npm run doctor` plus an interactive OMP session: `/pom` overlay, HUD, statuses, cards, `/pom theme install`, and a smoke project taken through stage 0 validation plus a checkpoint archive.

## Governance Invariants

Preserve these when changing runtime behavior (source: the shipped contributor guide, `rules/*.md`, `skills/pom/references/core-law.jml`).

- do not duplicate host primitives: task, IRC, todo, sessions, approvals, compaction, memory, model execution, TUI. Observe and route them; never build a parallel system.
- stage completion requires active execution, complete evidence, zero open blockers, and a passing validation report. Never mark a stage complete by direct state mutation.
- truth hierarchy: system + explicit user requirements > canonical project files and `00_admin/project_state.json` > manifest / evidence / ledgers > live OMP execution > vault projection > memory. The vault is a navigable projection, not a source of truth.
- keep canonical state and artifacts under the project root; reject traversal and symlink escape through `src/paths.ts` helpers (lexical plus realpath containment) — do not substitute plain `join`/`resolve` checks.
- never fake tool use, files, citations, images, counts, hashes, checks, ZIP tests, or completion. Partial, missing and blocked states stay disclosed as `PARTIAL` / `BLOCKED`.
- artifact claims need real non-empty regular files with measured bytes, SHA-256, category, stage, semver version, status, rights, source and notes recorded in the manifest.
- delivery claims need a fresh archive with safe member names, no duplicates/encryption/unsupported methods, central-directory parsing, decompression, size and CRC-32 checks, an archive hash, and an external verification report.
- continuity: story changes must preserve or explicitly revise canon, timeline, knowledge, relationships, props, injuries, rules, mysteries, setups and payoffs; contradictions require explicit canon selection, dependency mapping, revision logging and revalidation.
- rights: no living-author imitation, fabricated quotations, unauthorized asset redistribution, invented private-identity facts, or unsupported rights claims.
- use OMP renderers and UI hooks (`setWidget`, `setStatus`, `setWorkingMessage`, message cards) instead of printing raw terminal control sequences.
- delegation: one widest safe native task batch per independent wave, each task carrying objective, owned files and acceptance conditions; keep IRC terse with the `CLAIM / QUERY / ANSWER / ALERT / HANDOFF / DONE` vocabulary; durable findings go into project files or ledgers, not chat.
- tool routing: native tool first — `read` for files/directories/archives/static URLs, `glob` for bounded discovery, `grep` for bounded regex, AST/LSP for symbol work, browser only for authenticated/interactive/JS-only pages, `ask` only after exhausting sources.

## Known Discrepancies

Verified inconsistencies in the current tree — do not "fix" them silently as part of unrelated work, and do not describe them as working.

- `pom_stage` accepts an `inspect` action in its schema with no dedicated branch; it falls through to the sync/refresh path and returns summary state. **Decision**: keep as summary fallback; if dedicated inspect behavior is needed, add a branch and update schema/tests.
- `resources_discover` advertises only skills, prompts and themes; `agents/` and `rules/` are shipped but not advertised through that event. **Decision**: agents and rules are packaging-only resources; add them to resources_discover if/when agent-facing discovery is required.
- `docs/INVENTORY.md` claims "9 behavioral tests across 8 test files"; the tree contains 8 test files with 9 test declarations. `scripts/verify.mjs` asserts the manifest number (9) without distinguishing file count from declaration count.