# 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`