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

## Scope

This tracker is for repos that still require an `npm` to `pnpm` migration, plus the shared tracker-hosting and downstream validation work needed to safely roll those migrations through the ecosystem.

This tracker is **not** a claim that every listed repo is still on `npm` today. Some repos may already use `pnpm` in part or in full; those repos should be handled here only if they still require migration cleanup, downstream validation, or tracker-hosting updates.

This migration is a **repo-by-repo standardization effort across independent repositories**. It is **not** a plan to merge product repos into a single mega-monorepo. `learning_ai_common_plat` remains the canonical `pnpm` workspace for shared packages/services, while product repos stay independently versioned and independently deployable.

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

## Tracker State Semantics

- A wave checkbox means the repo has fully cleared the migration sequence and can be considered done for this tracker.
- A repo-section checkbox is only updated when there is evidence in code, verification output, and pushed commits.
- `TBD` commit fields mean the repo has not yet cleared that stage.
- If a repo is blocked, document the blocker in that repo's `notes:` line before moving away from it.

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

If any item above is false, the repo remains in-progress for this tracker.

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

Equivalent readiness checks should include, at minimum, the repo's canonical install, typecheck, test, build, and any documented quality gates required by its own AGENTS/README/workflows.

## Current Status

- **Ready for sequential rollout:** complete
- **Ready for parallel or one-shot migration:** N/A — tracker is in post-migration maintenance state
- **Current next repo:** none — tracker complete unless a follow-up cleanup or newly discovered regression reopens a repo
- **Completed pilot:** `learning_ai_flowmonk`

## Follow-up Validation: Local Gitea npm Registry

The Gitea npm registry migration is **complete**. All 10 product repos consume `@bytelyst/*` from the local Gitea registry (49 packages published). Docker builds use pnpm + BuildKit secret mount.

See [`docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md`](../devops/GITEA_NPM_REGISTRY_MIGRATION.md) for full details.

## Pilot Evidence

### `learning_ai_flowmonk`

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

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

- [x] `learning_ai_flowmonk`

### Wave 1 — Best next repos

- [x] `learning_ai_notes`
- [x] `learning_ai_local_memory_gpt`
- [x] `learning_ai_trails`

### Wave 2 — Medium complexity product repos

- [x] `learning_ai_fastgap`
- [x] `learning_ai_clock`
- [x] `learning_ai_jarvis_jr`
- [x] `learning_ai_peakpulse`

### Wave 3 — Higher blast-radius repos

- [x] `learning_voice_ai_agent`
- [x] `learning_multimodal_memory_agents`

### Wave 4 — Shared-platform validation and tracker-hosting cleanup

- [x] `learning_ai_common_plat`

## Repo Tracker

Update each repo section immediately after work lands.

### 1. `learning_ai_notes`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `90dd2d3`
- fix/audit commit: `17a117f`
- docs/tracker commit: `14e7e49`
- notes: `pnpm run verify` passed in `learning_ai_notes`; backend and web Docker builds passed after aligning NoteLett to the shared `.docker-deps` consumer flow and fixing `prep-consumer.sh` to pack the transitive `@bytelyst/*` closure

### 2. `learning_ai_local_memory_gpt`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `f7d47b1`
- notes: `pnpm run verify` passed (141 tests); backend Docker build required node:22-slim + native build tools for better-sqlite3; web Docker build required selective COPY to avoid node_modules symlink conflict; Next.js 16 needed --webpack flag + transpilePackages + webpack symlinks config for pnpm @bytelyst/\* resolution

### 3. `learning_ai_trails`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `d8d0fbb`
- notes: `pnpm run verify` passed (222 tests); includes SDK package; backend + web Docker builds passed on first try with .docker-deps consumer pattern

### 4. `learning_ai_fastgap`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `8826f8a`
- notes: `844 tests passed (505 mobile + 209 backend + 130 web); 3-package workspace (mobile root + backend + web); backend + web Docker builds passed with .docker-deps consumer pattern`

### 5. `learning_ai_clock`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `582936a`
- notes: `576 tests passed (182 backend + 394 web); web Docker needed NODE_TLS_REJECT_UNAUTHORIZED=0 for Google Fonts through corporate proxy; added missing root .gitignore`

### 6. `learning_ai_jarvis_jr`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `732c153`
- notes: `260 tests passed (209 backend + 51 web); backend + web Docker builds passed; iOS job unchanged`

### 7. `learning_ai_peakpulse`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `ab7d702`
- notes: `65 tests passed (backend only, no web); backend Docker build passed; iOS job unchanged; added node_modules to root .gitignore`

### 8. `learning_voice_ai_agent`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `c3a88af`
- notes: `115 backend tests passed; replaced manual webpack aliases with transpilePackages; fixed Stripe API version; backend + web Docker builds passed; iltorb native dep needed --ignore-scripts in Docker`

### 8b. `learning_multimodal_memory_agents`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` or equivalent readiness checks passed
- [x] docs/tracker updated
- [x] commits pushed
- migration commit: `e0461c7`
- notes: `103 backend tests passed; pnpm-workspace.yaml added (backend + mindlyst-native/web); fixed tsconfig.build.json .next/ exclusion; lint-staged updated to pnpm; @bytelyst/* already on Gitea registry ^0.1.0; Dockerfiles already pnpm + BuildKit`

### 9. `learning_ai_common_plat`

- [x] migration started
- [x] migration completed
- [x] repo verification passed
- [x] post-completion audit passed
- [x] `/production-readiness` passed
- [x] docs/tracker updated
- [x] commits pushed
- notes: `Already pnpm-native; added packageManager: pnpm@10.6.5 to root package.json; all packages build clean`

## Blocker Logging Rule

If a repo cannot be completed in sequence:

- do not silently skip it
- record the blocker in that repo's `notes:` line
- record any partial commit links already created
- explain why it is safe to proceed to a later repo, if an exception is required

## 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: none — all repos migrated
- current mode: complete — all 10 product repos + common-plat on pnpm with Gitea npm registry
- rule: if any repo is reopened, do not move to the next repo until the current repo passes verification, audit, readiness, commit, push, and tracker update