learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md

PNPM Migration Roadmap

This document is the canonical cross-repo plan for migrating the ByteLyst ecosystem's Node.js/TypeScript repositories from npm to pnpm.

Objective

Standardize on pnpm for:

• faster installs
• stricter dependency resolution
• cleaner workspace behavior with shared @bytelyst/* packages
• consistent CI, Docker, and local development workflows

Current Status

Completed Pilot

• FlowMonk — completed, audited, verified, and pushed
  • migration commit: 32160af — feat(build): migrate flowmonk to pnpm workspace
  • audit fix commit: c4cb9b3 — fix(audit): harden push triggers and offline replay
  • docs alignment commit: 8894285 — docs(audit): align flowmonk completion status

What the pilot proved

• root workspace migration is workable for multi-surface repos
• CI must install from the workspace root when shared packages are involved
• Dockerfiles and helper scripts need explicit pnpm handling
• docs can overstate completion unless a post-migration audit is mandatory
• post-completion audit must be part of the migration, not an optional cleanup

Readiness Decision

• Ready for phased ecosystem rollout: yes
• Ready for one-shot all-at-once migration: no

Even though none of the repos are actively deployed, the safest quality path is a fast sequential rollout in the right order, not a big-bang cutover.

Canonical Migration Version

• target package manager metadata: pnpm@10.6.5

Required Quality Gates for Every Repo

Every repo migration must complete all of the following before it is marked complete:

Gate 1 — Manifest and workspace alignment

• add packageManager: "pnpm@10.6.5"
• decide whether the repo needs a root workspace
• add pnpm-workspace.yaml when shared local packages or multi-surface installs require it
• generate and commit pnpm-lock.yaml
• remove obsolete package-lock.json files

Gate 2 — CI and Docker alignment

• update CI to use pnpm
• update cache configuration to use the right lockfile path(s)
• update Dockerfiles and helper scripts to install with pnpm
• verify shared package resolution in both local and CI layouts

Gate 3 — Docs and developer workflow alignment

• update README / AGENTS / CLAUDE / copilot / helper docs
• update canonical build, test, typecheck, and dev commands
• update any migration tracker / roadmap docs for the repo

Gate 4 — Verification

• install succeeds under pnpm
• typecheck passes
• tests pass
• build passes
• any repo-specific required verification is run truthfully

Gate 5 — Post-completion audit

Required after the migration appears complete:

• review completed claims against actual code and tests
• identify recently marked-complete features lacking real coverage
• fix any runtime, ownership, replay, or CI/Docker regressions found
• rerun verification after the fixes
• update docs to the audited truth state

Migration Pattern Proven by FlowMonk

For repos similar to FlowMonk, the proven migration sequence is:

1. add root package.json if a workspace root is needed
2. add pnpm-workspace.yaml
3. generate pnpm-lock.yaml
4. remove old package-lock.json
5. update package-level packageManager
6. update CI
7. update Dockerfiles and helper scripts
8. update docs
9. run full verification
10. run post-completion audit
11. commit and push incrementally

Ecosystem Rollout Order

Wave 0 — Pilot

• learning_ai_flowmonk — complete

Wave 1 — Best next repos

These are the best next candidates for a high-signal, lower-risk continuation:

• learning_ai_notes
• learning_ai_local_memory_gpt
• learning_ai_trails

Wave 2 — Medium complexity product repos

• learning_ai_fastgap
• learning_ai_clock
• learning_ai_jarvis_jr
• learning_ai_peakpulse

Wave 3 — Higher blast-radius repos

• learning_voice_ai_agent
• learning_ai_common_plat

Why this order

• Wave 1 validates the process across more product repos without immediately touching the largest shared-platform blast radius
• Wave 2 expands the pattern to broader product surfaces
• Wave 3 is delayed until the process is stable enough for the biggest dependency and workflow impacts

Special Notes

learning_ai_common_plat

This repo is already the ecosystem's pnpm center of gravity. The work here is less about “switching package manager” and more about:

• standardizing docs/scripts/CI expectations
• ensuring downstream repos consume shared packages cleanly
• avoiding regressions in shared package behavior

learning_voice_ai_agent

This repo should keep only a pointer or local wrapper doc once the shared canonical roadmap lives in learning_ai_common_plat/docs/pnpm/.

Minimal Checklist Per Repo

Use this checklist for each migration:

• package metadata updated
• lockfile generated and committed
• old npm lockfiles removed
• CI updated
• Docker/scripts updated
• docs updated
• install verified
• typecheck verified
• tests verified
• build verified
• post-completion audit performed
• docs updated to audited truth state
• incremental commits pushed

Operator Guidance

Do

• migrate repos sequentially in the defined order
• commit in logical batches
• push after each verified batch
• treat the audit as mandatory
• prefer truthful status over optimistic status

Do not

• migrate the entire ecosystem in one cutover
• mark repos complete before the audit pass
• leave mixed npm/pnpm docs in a migrated repo
• assume CI/Docker correctness from local success alone

Current Recommendation

The next repo to migrate should be:

• learning_ai_notes

Summary

• canonical roadmap: learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md
• completed pilot: learning_ai_flowmonk
• proven approach: fast sequential waves with mandatory audit
• next recommended repo: learning_ai_notes