pom-omp/TASKLIST.md

# 🪴 POM 2 Wiki Recovery Backlog

## 1. 🚨 Release-truth emergency
Purpose: stop shipping claims that outrun the current package, dependency state, and verification evidence.

- [x] 1.1 Repair packaged runtime contents before any wiki/publication claim.
  - [x] 1.1.1 Add `prompts/` to `package.json:21-35` `files` because `src/prompts.ts:23,43-49` loads bundled prompt fragments at runtime and `README.md:9-13` advertises 13 prompt fragments; completion: `npm pack --dry-run` lists all 13 `prompts/*.md` and a tarball install can resolve `../prompts`.
  - [x] 1.1.2 Regenerate `RELEASE.json` only after the package file allowlist is corrected; completion: `npm run release:manifest` includes prompt files in `sourceInventory` and `npm run release:check` passes against the generated bytes.
- [ ] 1.2 Replace hard-coded release PASS mythology with evidence-backed release status.
  - [x] 1.2.1 Rewrite `scripts/release-manifest.mjs:31-67` so `verification` and audit strings are generated from recorded current gate outputs or marked `NOT RUN`/`BLOCKED`, not literal PASS values; completion: changing gate evidence changes rendered `RELEASE.json` without hand edits.
  - [x] 1.2.2 Remove or update stale 2026-07-12 audit language in `scripts/release-manifest.mjs:63-64` and `RELEASE.json:33-34`; completion: release manifest states the exact audit command/date/result actually rerun, or explicitly says audit is not current.
  - [ ] 1.2.3 Add a release-evidence note to the future wiki explaining that `AGENTS.md` was rehashed in `RELEASE.json:45-49` but green gates were not rerun afterward; completion: wiki release page distinguishes manifest freshness from full verification truth.
- [x] 1.3 Make the dependency-install blocker first-class instead of hiding it behind failed full verify.
  - [ ] 1.3.1 Document the current blocker: internal npm Artifactory timed out twice, leaving full verify blocked by missing `@oh-my-pi/*` SDK packages, Node types, `yauzl` types/deps, and theme schema expected by `scripts/verify.mjs:66`; completion: release/readiness page lists the exact missing dependency families and retries attempted.
  - [x] 1.3.2 Keep the partial green evidence scoped precisely: `npm run smoke`, `npm run release:check`, and the state test pass, while full gate is not green; completion: no page or manifest says `npm run verify` passed until `npm install` succeeds and the full command is rerun.
  - [x] 1.3.3 Add a recovery task for maintainers with a working registry: rerun `npm install`, then `npm run verify`, then regenerate/recheck release evidence; completion: captured command outputs are linked from the wiki readiness page.

## 2. 📜 Canonical SSOT contracts
Purpose: align all docs and wiki pages to source-owned contracts, with source/runtime outranking older docs.

- [x] 2.1 Declare source ownership for generated project layout.
  - [x] 2.1.1 Treat `src/persistence.ts:226-239` as canonical for generated directories: `06_ledgers` and `07_exports`; completion: wiki SSOT page cites this range as owner and no page presents `06_exports` as the active exports directory.
  - [x] 2.1.2 Fix `docs/INVENTORY.md:34-43`, which currently lists stale `06_exports`; completion: inventory has `06_ledgers` for decisions/validation ledgers and `07_exports` for checkpoint/final archives.
  - [x] 2.1.3 Fix `skills/pom/references/artifacts.md:3-11`, which currently lists stale `06_logs`; completion: skills reference matches `06_ledgers`/`07_exports` and defers to `src/persistence.ts` for future layout truth.
- [ ] 2.2 Correct prompt precedence and override wording everywhere.
  - [x] 2.2.1 Rewrite `POM.yml:87-97` prompt precedence to match `src/prompts.ts:83-117`: immutable law is prepended first, `personality-${state.mode}` follows, requested bundled/project fragments are composed with project fragments replacing bundled by id, and executable stage contract is appended last by `renderStagePrompt`; completion: wording no longer implies arbitrary project-local override order after the contract.
  - [ ] 2.2.2 Add a wiki prompt-contract page that cites `src/prompts.ts:23,43-49,83-117` and defines replacement-by-id; completion: agents can answer “which prompt wins?” without reading README/POM.yml.
- [ ] 2.3 Correct command-surface truth.
  - [x] 2.3.1 Update `README.md:58-77` and `POM.yml:38-54` to include implemented `/pom status [--json]` and `/pom help`, matching `src/command.ts:23-40,132-145,224-225`; completion: command map contains every verb registered in `src/command.ts` and no unimplemented verb is advertised.
  - [ ] 2.3.2 Add wiki command page ownership: command implementation lives in `src/command.ts`, parser behavior in `src/parser.ts`, human manifest in `POM.yml`; completion: docs duplicate command summaries only by linking to this owner page.
- [ ] 2.4 Correct validation ownership.
  - [x] 2.4.1 Rewrite `docs/TOOL_MATRIX.md:5-13` so standalone validation belongs to `pom_validate` and `pom_stage action=pass` is validation-gated, not a generic validation tool; completion: matrix matches `src/tools.ts:93-164,203-221`.
  - [ ] 2.4.2 Add wiki gate page: `pom_validate` emits scoped reports, `pom_stage pass` runs the stage/delivery scope and calls `passStage` only after a passing report; completion: page cites `src/tools.ts:138-148` and `src/state.ts` pass invariants.
- [x] 2.5 Fix stale contributor-guide discrepancy claims before copying them into the wiki.
  - [x] 2.5.1 Correct `AGENTS.md:158-162`: `stopGuard` and `destructiveProjectCommands` do have consumers in `src/events.ts:87-93,186-203`, so do not preserve the old “no runtime consumer exists” claim; completion: known-discrepancies page says these settings are wired and cites both `src/config.ts:45-53` and `src/events.ts` consumers.
  - [x] 2.5.2 Correct the test-count wording: there are 8 test files in `tests/*.test.ts` but nine test declarations/behavioral tests are asserted by `scripts/verify.mjs:29-31`; completion: docs distinguish file count from test declaration/manifest count without calling it inconsistent.

## 3. 🗺️ Wiki information architecture and content ownership
Purpose: create a navigable wiki/SSOT instead of scattered README/docs/skills fragments with no publication skeleton.

- [ ] 3.1 Create the repository wiki entrypoints and navigation scaffold.
  - [x] 3.1.1 Add `docs/index.md` as the human landing page that links the existing docs: `ARCHITECTURE.md`, `SETTINGS.md`, `TOOL_MATRIX.md`, `INVENTORY.md`, `AUDIT.md`, `DESIGN_REVIEW.md`, `OFFICIAL_SOURCES.md`, and `POM_ARCHITECTURE.mmd`; completion: README can link one docs index instead of leaving only three docs discoverable at `README.md:115-119`.
  - [x] 3.1.2 Add a sidebar/navigation file appropriate for the chosen wiki generator and list source-truth pages before narrative/audit pages; completion: every existing doc is reachable from the sidebar in one click.
  - [x] 3.1.3 Add minimal Quartz 5 configuration/content-vault structure only after deciding whether the repo wiki lives in `docs/` or a separate content vault; completion: local preview can render the docs index and all internal links without pretending a live wiki exists.
- [ ] 3.2 Assign ownership so duplicate facts stop drifting.
  - [x] 3.2.1 Create a wiki ownership table: runtime contracts owned by `src/*`, package/release truth by `package.json` + `scripts/release-manifest.mjs` + command evidence, operator flows by README, deep reference by docs, agent-facing quick refs by `skills/pom/references/*`; completion: each duplicated fact has a named owner and “mirrors must cite owner” rule.
  - [ ] 3.2.2 Consolidate docs/skills duplication for layout, command map, validation scopes, resource counts, and prompt order; completion: each mirror page cites its source owner and contains no independent stale variants.
  - [x] 3.2.3 Add a “source beats docs” note to wiki landing/readiness pages; completion: future agents know to verify against code before editing narrative docs.
- [x] 3.3 Define repository-wiki versus generated-project-vault boundaries.
  - [x] 3.3.1 Document that repo docs describe the extension, while generated project vault files are created by `src/persistence.ts` under project `content/`; completion: README’s `content/` tree cannot be mistaken for this repository’s missing live wiki.
  - [x] 3.3.2 Add a wiki page for generated vault shape based on `README.md:80-98` and `src/persistence.ts`; completion: generated-project docs and repository wiki scaffolding are separate navigation branches.

## 4. 🧭 Operator onboarding and package metadata
Purpose: make a new maintainer/operator able to acquire, install, verify, and report on POM without hidden assumptions.

- [x] 4.1 Add repository acquisition and install-path clarity to README/wiki.
  - [x] 4.1.1 Expand `README.md:22-42` with repository acquisition flow: clone/download source, `npm install`, source-tree verification, `npm run link`, restart OMP or `/reload-plugins`, `/pom theme install`, and `npm run doctor`; completion: an operator starting from no checkout can reach a linked plugin.
  - [x] 4.1.2 Distinguish source checkout install from published package install, including the current package defect where published installs would miss `prompts/` until `package.json:21-35` is repaired; completion: no instructions imply npm-published install is safe before package allowlist verification.
  - [x] 4.1.3 Add SDK/engine compatibility to README/wiki: peer packages `@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-tui`, `@oh-my-pi/pi-utils` are `>=16.4.6 <17` (`package.json:42-45`), Bun host is `>=1.3.14` (`package.json:57-58`), Node/npm are needed for local scripts; completion: compatibility is visible before install commands.
- [ ] 4.2 Add package metadata required for trustworthy distribution.
  - [x] 4.2.1 Add `repository`, `homepage`, and `bugs` fields to `package.json`, or explicitly block on the authoritative public URLs if unknown; completion: npm package metadata points operators to source, docs/wiki, and issue reporting without guesswork.
  - [x] 4.2.2 After metadata changes, regenerate `RELEASE.json` via `npm run release:manifest`; completion: metadata changes are included in `sourceInventory` and `npm run release:check` passes.
- [x] 4.3 Write a blocked-prerequisites lane for maintainers when external services fail.
  - [x] 4.3.1 Add docs guidance for registry outages: do not vendor/stub OMP SDK or theme schema; retry/repair registry, then run full gate; completion: dependency failure is recorded as external blocker, not hidden by partial tests.
  - [x] 4.3.2 Add a short “what can be verified offline” section: source reads, release manifest check, state test, and smoke may pass, but `scripts/verify.mjs` theme schema and full `npm run verify` require installed deps; completion: partial verification labels are exact.

## 5. 🧪 Verification automation and mutation checks
Purpose: make the wiki cleanup self-defending so stale docs and fake release claims fail visibly.

Note: check-docs.mjs now runs 7 checks — package-metadata (canonical loca.zone URLs) was added as check 7.

- [x] 5.1 Add narrow documentation contract checks.
  - [x] 5.1.1 Add a script or targeted test that compares README/POM.yml command maps to `src/command.ts` completions and HELP text; completion: omission of `/pom status [--json]` or `/pom help` fails the check.
  - [x] 5.1.2 Add a layout-doc check that fails if docs/skills mention `06_exports` or `06_logs` as canonical generated directories; completion: stale path names cannot re-enter `docs/INVENTORY.md` or `skills/pom/references/artifacts.md`.
  - [x] 5.1.3 Add a prompt-order doc check or snapshot tied to `composePromptStack`/`renderStagePrompt`; completion: docs cannot claim contract-before-law or non-ID override semantics.
- [ ] 5.2 Add package/release mutation checks.
  - [x] 5.2.1 Add a packaging assertion that every runtime-loaded bundled resource root in source (`../prompts`, `../skills`, `../themes`, plus any future agents/rules discovery roots) is represented in `package.json.files`; completion: deleting `prompts/` from `files` fails before pack.
  - [x] 5.2.2 Add a release-truth check that prevents `scripts/release-manifest.mjs` from rendering PASS claims when the corresponding gate evidence file/command result is missing or stale; completion: old hard-coded PASS strings cannot survive without evidence.
  - [ ] 5.2.3 Add a mutation proof for the release check: temporarily remove `prompts/` from package files or alter one command-map doc entry and confirm the new check fails, then revert; completion: failure output is captured in wiki verification notes.
- [x] 5.3 Keep automation scoped and source-grounded.
  - [x] 5.3.1 Do not add broad linters or formatters as a substitute for contract checks; completion: each new check defends one listed defect with a precise failure message.
  - [x] 5.3.2 Update `scripts/verify.mjs` only if dependency availability is restored; completion: new checks run under the existing `npm run verify` sequence without masking the current install blocker.

## 6. 🍎 Ego browser handoff and live roast
Purpose: acknowledge that official ego lite is macOS-only today while still enabling Linux-safe preview work and a later real ego audit.

- [ ] 6.1 Record the ego platform boundary as a blocker, not a workaround.
  - [ ] 6.1.1 Add wiki/readiness task noting official ego lite is macOS-only, Linux support is roadmap-only, the Darwin installer cannot run on this Linux host, and `ego-browser` is absent; completion: no Linux verification step claims to satisfy an ego requirement.
  - [ ] 6.1.2 Prepare a macOS handoff checklist: checkout source, install dependencies, run local wiki preview, install/run official ego lite, open the wiki, capture link/navigation/rendering findings; completion: a macOS operator can execute without needing this Linux session.
- [ ] 6.2 Provide Linux-safe pre-ego preview and link verification.
  - [x] 6.2.1 Add a non-ego local preview path using the chosen Quartz/static renderer or markdown link checker; completion: docs index/sidebar/internal links render locally on Linux and failures are recorded as pre-ego findings.
  - [ ] 6.2.2 Label Linux preview evidence as “pre-ego” only; completion: readiness gate still requires macOS ego review or an explicit future Linux ego release.
- [ ] 6.3 Run the later ego-browser live wiki roast when available.
  - [ ] 6.3.1 On macOS ego or future Linux ego, drive the live wiki with ego-browser: homepage, sidebar, docs index, command page, release truth page, generated-vault page, and readiness page; completion: screenshots/DOM notes prove navigation and content match source contracts.
  - [ ] 6.3.2 File roast findings back into the wiki backlog/remediation list with source references; completion: every ego finding has a linked page/selector and a source-owner decision.

## 7. ✅ Final publication/readiness gate
Purpose: publish only after package truth, docs truth, automation, and live verification agree.

- [x] 7.1 Resolve unresolved runtime/doc-contract tasks before final docs claim completeness.
  - [x] 7.1.1 Decide and implement whether `resources_discover` should advertise shipped `agents/` and `rules/` in addition to `skills/`, `prompts/`, and `themes` (`src/events.ts:19-24`); completion: source behavior and docs agree, or docs explicitly say agents/rules are packaged but not resource-discovered.
  - [x] 7.1.2 Give `pom_stage action=inspect` a dedicated branch or document its current summary fallthrough (`src/tools.ts:93-164`); completion: tool docs and behavior agree, and inspect has an objective test if behavior changes.
- [ ] 7.2 Run dependency-ordered final gates.
  - [x] 7.2.1 After registry/dependencies are restored, run `npm install`, `npm run release:manifest`, `npm run release:check`, and `npm run verify`; completion: outputs are captured and release/readiness pages cite exact current results.
  - [x] 7.2.2 Run package dry-run and inspect the file list for `prompts/`, `agents/`, `rules/`, `skills/`, `themes`, docs, scripts, README, POM.yml, AGENTS.md, LICENSE, and RELEASE.json; completion: packaged content matches runtime resource needs.
  - [ ] 7.2.3 Run wiki preview/link verification on Linux and ego live roast on macOS/future ego; completion: both evidence classes are stored with labels and no broken internal links remain.
- [ ] 7.3 Publish only with exact status labels.
  - [x] 7.3.1 Update README/wiki readiness summary to one of: `BLOCKED` with external prerequisite, `PARTIAL` with exact passing checks, or `READY` with all gates and ego audit complete; completion: no PASS/READY claim lacks linked evidence.
  - [ ] 7.3.2 Final definition of done: package includes runtime prompts; release manifest is evidence-backed; docs/index/sidebar/wiki exist; stale layout/command/prompt/validation/test/settings claims are corrected; package metadata is present or explicitly URL-blocked; runtime/doc-contract decisions for resources and inspect are resolved; full verify is green after dependency install; Linux preview passes; macOS/future ego audit is complete or publication remains blocked.

## 8. 🚀 Post-publication reconciliation (Phase E, 2026-08-19)

Publication changed the facts behind several items above. Status recorded, not silently ticked:

- 1.2.3 and 1.3.1 are OBSOLETE, not open: the internal-Artifactory blocker is gone. The lockfile's `resolved` URLs were repointed from the dead mirror to `registry.npmjs.org` (integrity hashes and version pins untouched), `npm install` succeeded, and all six repository-local gates were rerun green afterwards. Manifest freshness and verification truth now agree.
- 7.2.3 stays PARTIAL: the Linux half is done — `check-docs` check 5 link-and-orphan PASS, wiki builds via `dev/wikis/build.sh pom`, and `https://wiki.pom.loca.zone/` plus deep pages return 200. The macOS/ego live roast remains platform-blocked (section 6).
- 7.3.2 stays OPEN for the ego-audit clause only. Every other clause is satisfied: `prompts/` ships, `RELEASE.json` is evidence-backed from `00_admin/validation/`, docs index and wiki exist and are served, stale claims are corrected, and package metadata is live rather than reserved.
- Publication facts: self-hosted Gitea (loopback 51400) serves `https://git.omp.loca.zone/jamminrebel/pom-omp.git` with anonymous HTTPS clone; `main` and `v2.0.0` are pushed; the docs wiki is served from `dev/wikis/pom/current`; `wiki.omp.loca.zone` was left untouched.