bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(pnpm): strengthen migration tracker gates

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-22 14:15:48 -07:00
parent 828d31b63d
commit afcbf852b2
1 changed files with 203 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

344
docs/pnpm/PNPM_MIGRATION.md
View File

@ -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