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.

• 1.1 Repair packaged runtime contents before any wiki/publication claim.
  • 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.
  • 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.
  • 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.
  • 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.
• 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.
  • 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.
  • 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.

• 2.1 Declare source ownership for generated project layout.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
• 2.5 Fix stale contributor-guide discrepancy claims before copying them into the wiki.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
• 3.3 Define repository-wiki versus generated-project-vault boundaries.
  • 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.
  • 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.

• 4.1 Add repository acquisition and install-path clarity to README/wiki.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
• 4.3 Write a blocked-prerequisites lane for maintainers when external services fail.
  • 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.
  • 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.

• 5.1 Add narrow documentation contract checks.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
• 5.3 Keep automation scoped and source-grounded.
  • 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.
  • 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.
  • 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.

• 7.1 Resolve unresolved runtime/doc-contract tasks before final docs claim completeness.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.