diff --git a/docs/pnpm/PNPM_MIGRATION.md b/docs/pnpm/PNPM_MIGRATION.md index fa0f7dd7..c2e3afb2 100644 --- a/docs/pnpm/PNPM_MIGRATION.md +++ b/docs/pnpm/PNPM_MIGRATION.md @@ -1,6 +1,6 @@ -# PNPM Migration Roadmap +# PNPM Migration Tracker -This document is the canonical cross-repo plan for migrating the ByteLyst ecosystem's Node.js/TypeScript repositories from `npm` to `pnpm`. +This document is the canonical ecosystem tracker for migrating ByteLyst Node.js and TypeScript repositories from `npm` to `pnpm`. ## Objective @@ -11,183 +11,245 @@ Standardize on `pnpm` for: - 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 -### Completed Pilot +- **Ready for sequential rollout:** yes +- **Ready for parallel or one-shot migration:** no +- **Current next repo:** `learning_ai_notes` +- **Completed pilot:** `learning_ai_flowmonk` -- **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` +## Pilot Evidence -### What the pilot proved +### `learning_ai_flowmonk` -- 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 +- [x] migrated +- [x] audited +- [x] verified +- [x] pushed +- migration commit: [`32160af`](https://github.com/saravanakumardb1/learning_ai_flowmonk/commit/32160af) — `feat(build): migrate flowmonk to pnpm workspace` +- docs checkpoint: [`2a293c1`](https://github.com/saravanakumardb1/learning_ai_flowmonk/commit/2a293c1) — `docs(roadmap): record pnpm migration checkpoint` +- audit fix commit: [`c4cb9b3`](https://github.com/saravanakumardb1/learning_ai_flowmonk/commit/c4cb9b3) — `fix(audit): harden push triggers and offline replay` +- docs alignment commit: [`8894285`](https://github.com/saravanakumardb1/learning_ai_flowmonk/commit/8894285) — `docs(audit): align flowmonk completion status` -## Readiness Decision +## Sequential Rollout Order -- **Ready for phased ecosystem rollout:** yes -- **Ready for one-shot all-at-once migration:** no +Do not change the order below unless a later repo becomes a hard dependency blocker for an earlier repo. -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. +### Wave 0 — Completed Pilot -## 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 +- [x] `learning_ai_flowmonk` ### 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` +- [ ] `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` +- [ ] `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` +- [ ] `learning_voice_ai_agent` +- [ ] `learning_ai_common_plat` -## Why this order +## Repo Tracker -- 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 +Update each repo section immediately after work lands. -## Special Notes +### 1. `learning_ai_notes` -### `learning_ai_common_plat` +- [ ] 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 -This repo is already the ecosystem's `pnpm` center of gravity. The work here is less about “switching package manager” and more about: +### 2. `learning_ai_local_memory_gpt` -- standardizing docs/scripts/CI expectations -- ensuring downstream repos consume shared packages cleanly -- avoiding regressions in shared package behavior +- [ ] 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` -### `learning_voice_ai_agent` +### 3. `learning_ai_trails` -This repo should keep only a pointer or local wrapper doc once the shared canonical roadmap lives in `learning_ai_common_plat/docs/pnpm/`. +- [ ] 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` -## Minimal Checklist Per Repo +### 4. `learning_ai_fastgap` -Use this checklist for each migration: +- [ ] 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` -- [ ] 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 +### 5. `learning_ai_clock` -## Operator Guidance +- [ ] 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` -### Do +### 6. `learning_ai_jarvis_jr` -- 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 +- [ ] 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` -### Do not +### 7. `learning_ai_peakpulse` -- 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 +- [ ] 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` -## Current Recommendation +### 8. `learning_voice_ai_agent` -The next repo to migrate should be: +- [ ] 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 -- **`learning_ai_notes`** +### 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 roadmap: `learning_ai_common_plat/docs/pnpm/PNPM_MIGRATION.md` +- canonical tracker: this file - completed pilot: `learning_ai_flowmonk` -- proven approach: fast sequential waves with mandatory audit -- next recommended repo: `learning_ai_notes` +- 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