learning_ai_common_plat/docs/HANDOVER.md

Handover — Common Platform Audit

Last updated: 2026-05-04 Last commit (audit): 8f541c9 — chore(audit): unblock workspace lint pipeline + 13 mechanical fixes Backup branch: backup/main-20260504-062733 (taken from origin/main HEAD 46a16f0)

---

TL;DR

A tooling-backed audit was performed across all 69 workspace packages. pnpm install / typecheck / lint pass cleanly on the current workspace. pnpm lint was previously failing fast at one package, but a structural eslint config fix + 13 mechanical lint fixes made the lint pipeline run end-to-end. A fresh rerun on 2026-05-04 shows 0 lint errors / 0 warnings; the old 85-error P-sweep handoff is stale and the warning sweep is complete.

---

What's working right now

Check	Result	Notes
pnpm install -r	✅ pass	No warnings when GITEA_NPM_TOKEN is exported
pnpm typecheck	✅ pass	All 69 packages compile
pnpm test	✅ pass	~2,200 tests; prior transient platform/cowork flakes cleared on rerun, auth bcrypt timeout fixed in d3fbeba
pnpm lint (pipeline)	✅ runs end-to-end	Was bailing fast; this audit unblocked it
pnpm lint	✅ 0/0	0 errors / 0 warnings after 663dcde

---

Critical context for the next dev

1. The .npmrc token requirement

.npmrc references ${GITEA_NPM_TOKEN}. On this machine, ~/.zshrc defines the variable but does not export it. Without export, pnpm emits noisy WARNs. Every developer shell should run:

source ~/.zshrc
export GITEA_NPM_TOKEN

The audit session's tooling runs all relied on this being sourced.

2. Working tree state at handover

The nomgap deployment edits that were previously uncommitted were finalized in b440330 (chore(nomgap): finalize product deployment config):

• docker-compose.ecosystem.yml — removes nomgap-web from the Docker stack
• products/nomgap/product.json — replaces flag set, restructures containers
• services/platform-service/src/modules/flags/seed.ts — adds 14 lines of seed flags

The current working tree is clean after 663dcde; pnpm-lock.yaml is clean and was not committed as part of the warning sweep.

3. The audit doc is the source of truth

docs/AUDIT_PLATFORM.md has the full breakdown:

• Section A (✅ done): 13 lint pipeline blockers fixed in 8f541c9.
• Section P (✅ clear): current workspace lint has 0 errors.
• Section W (active): warnings only. Recent follow-ups cleared admin feedback warnings (db4257f), predictive campaign event typing (021f053), tracker roadmap/config warnings (04d2398), and broadcast-client deep-link diagnostics (5fb4921). The remaining admin-web W2 warnings were cleared in 1089597, config Key Vault diagnostics were documented in 5b0fbc2, monitoring health-check output was documented in e9a70ed, and create-app / design-token generator CLI output was documented in 433c3a5. Diagnostics client console capture was documented in 91e08bf, extraction sidecar development alerts were documented in 9cd7089, platform-service scripts were documented/typed in 2c9dc18, and platform-service runtime console diagnostics were replaced in 663dcde. Workspace lint is now 0 errors / 0 warnings.
• Section R (housekeeping): token export and peer-warning observations are documented/verified.

For the live warning checklist and parallel-agent workflow, use docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md.

Note: a recent upstream commit tightened the unused-vars rule with varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_', etc. — meaning _-prefix is now an official escape hatch for intentionally-unused names.

---

Suggested next steps

1. Keep future feature work on the 0-warning lint baseline.
2. Before changing migration scripts, address the TODO in services/platform-service/scripts/migrate-referrals.ts so --help can run without platform service env vars.
3. Keep packages/auth/vitest.config.ts package-local; it reflects the production bcrypt cost without weakening auth assertions.

---

Repo state checklist

# Verify clean state before starting
cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat
source ~/.zshrc
export GITEA_NPM_TOKEN           # ensure pnpm can read the token
git status                       # clean expected
git log --oneline -3

# Run the gates
pnpm install -r --prefer-offline # → done in seconds (cache hit)
pnpm typecheck                   # → exit 0
pnpm test                        # → ~2,200 pass; rerun focused package if a known flake appears
pnpm lint > /tmp/lint.log 2>&1   # → exit 0, 0 errors / 0 warnings

---

Branches & backups

• main — current
• backup/main-20260504-062733 — snapshot of origin/main HEAD 46a16f0 taken before the audit-fix commit. Roll back with git reset --hard backup/main-20260504-062733 if anything goes wrong.

---

Companion: trading repo

The audit work that prompted this platform pass is documented in the sibling repo learning_ai_invt_trdg (specifically docs/HANDOVER.md and docs/AUDIT_REDESIGN.md there). That repo consumes 9 vendored @bytelyst/* packages from this platform — fix upstream here, re-vendor there. Backup branch in that repo: backup/main-20260504-061739.