learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md

PNPM Migration Tracker

This document is the canonical ecosystem tracker for migrating ByteLyst Node.js and 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

Tracker Rules

• Sequential only — migrate one repo at a time in the order below.
• No overlapping repo migrations — do not start the next repo until the current repo is fully verified, audited, committed, pushed, and tracked here.
• Fix issues immediately — if tests, builds, CI assumptions, Docker assumptions, or docs fail, fix them in the same repo before moving on.
• Incremental commits required — commit migration work, fix work, and docs/tracker updates in logical batches.
• Tracker updates are mandatory — every completed repo must have its checkbox updated and commit links recorded here.

Definition of Done For Each Repo

A repo is only complete when all of the following are true:

• packageManager metadata updated to pnpm@10.6.5
• pnpm-lock.yaml generated and committed
• obsolete package-lock.json files removed
• workspace/root package layout updated if needed
• CI updated to use pnpm
• Dockerfiles and helper scripts updated to use pnpm
• repo docs updated to pnpm
• install/typecheck/test/build verification passed
• post-completion audit performed and any issues fixed
• /production-readiness executed where applicable, or equivalent repo-local readiness checks executed if the workflow does not directly cover that repo
• migration commit links added here
• fix/audit commit links added here
• docs/tracker commit links added here
• commits pushed

Mandatory Verification Before Moving To The Next Repo

For every repo migration:

1. run the repo's own install, typecheck, test, and build commands
2. run the post-completion audit against recently completed claims
3. fix issues immediately in that repo
4. rerun verification after fixes
5. run /production-readiness when the repo is directly covered by that workflow
6. when the repo is not directly covered by /production-readiness, run equivalent repo-local readiness checks and rerun any impacted downstream verification before advancing
7. update this tracker with real commit links
8. push the commits before starting the next repo

/production-readiness Workflow Policy

The /production-readiness workflow is mandatory quality enforcement for covered repos and must be used as part of the migration sign-off process.

Repos directly covered today

• learning_ai_common_plat
• learning_voice_ai_agent
• learning_multimodal_memory_agents

Repos not directly covered today

For the other product repos, run their repo-native verification plus the equivalent readiness checks expected by this tracker. If a migration affects shared dependencies, CI assumptions, shared Docker behavior, or downstream integrations, rerun any impacted /production-readiness phases before moving on.

Current Status

• Ready for sequential rollout: yes
• Ready for parallel or one-shot migration: no
• Current next repo: learning_ai_notes
• Completed pilot: learning_ai_flowmonk

Pilot Evidence

learning_ai_flowmonk

• migrated
• audited
• verified
• pushed
• migration commit: 32160af — feat(build): migrate flowmonk to pnpm workspace
• docs checkpoint: 2a293c1 — docs(roadmap): record pnpm migration checkpoint
• audit fix commit: c4cb9b3 — fix(audit): harden push triggers and offline replay
• docs alignment commit: 8894285 — docs(audit): align flowmonk completion status

Sequential Rollout Order

Do not change the order below unless a later repo becomes a hard dependency blocker for an earlier repo.

Wave 0 — Completed Pilot

• learning_ai_flowmonk

Wave 1 — Best next repos

• 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

Repo Tracker

Update each repo section immediately after work lands.

1. learning_ai_notes

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD
• notes: next recommended repo after the FlowMonk pilot

2. learning_ai_local_memory_gpt

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD

3. learning_ai_trails

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD

4. learning_ai_fastgap

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD

5. learning_ai_clock

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD

6. learning_ai_jarvis_jr

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD

7. learning_ai_peakpulse

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness or equivalent readiness checks passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD

8. learning_voice_ai_agent

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD
• notes: use the local pointer doc learning_voice_ai_agent/PNPM_MIGRATION.md to reference this tracker

9. learning_ai_common_plat

• migration started
• migration completed
• repo verification passed
• post-completion audit passed
• /production-readiness passed
• docs/tracker updated
• commits pushed
• migration commit: TBD
• fix/audit commit: TBD
• docs/tracker commit: TBD
• notes: highest blast-radius repo; keep last in sequence unless it becomes a hard blocker

Why The Sequence Matters

• the pilot already proved that “migration complete” is not enough without audit-backed verification
• CI, Docker, and sibling-repo dependency assumptions can fail in ways that local installs alone do not expose
• later high-blast-radius repos should benefit from everything learned in the earlier waves

Legacy Pointer

The old product-level roadmap location now exists only as a pointer:

• learning_voice_ai_agent/PNPM_MIGRATION.md

Summary

• canonical tracker: this file
• completed pilot: learning_ai_flowmonk
• next repo in sequence: learning_ai_notes
• rule: do not move to the next repo until the current repo passes verification, audit, readiness, commit, push, and tracker update