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 / test` all pass cleanly. `pnpm lint` was failing
fast at one package (hiding everything downstream); a structural eslint
config fix + 13 mechanical lint fixes have made the lint pipeline run
end-to-end. **85 pre-existing lint errors are now visible** that nobody
had seen before — they belong to package owners to clear with
`pnpm --filter <pkg> lint:fix` followed by an eyeball review.

---

## What's working right now

| Check                  | Result             | Notes                                                                              |
| ---------------------- | ------------------ | ---------------------------------------------------------------------------------- |
| `pnpm install -r`      | ✅ pass            | 4 cosmetic peer warnings (`@azure/core-client`)                                    |
| `pnpm typecheck`       | ✅ pass            | All 69 packages compile                                                            |
| `pnpm test`            | ✅ pass            | ~2,200 tests across 18+ suites                                                     |
| `pnpm lint` (pipeline) | ✅ runs end-to-end | Was bailing fast; this audit unblocked it                                          |
| `pnpm lint` (errors)   | 🟡 85              | All pre-existing, surfaced by the unblock — see `docs/AUDIT_PLATFORM.md` section P |

---

## Critical context for the next dev

### 1. The `.npmrc` token requirement

`.npmrc` references `${GITEA_NPM_TOKEN}`. **Without it exported**, `pnpm`
emits noisy WARNs and `pnpm install -r` fails on the mobile / vendored
`@bytelyst/*` private packages. Every developer needs to:

```bash
# Add to ~/.zshrc (or ~/.bashrc)
export GITEA_NPM_TOKEN=<token-from-1Password>
```

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

### 2. Working tree state at handover

Three files are uncommitted and **were intentionally left alone** by the
audit — they're an in-progress nomgap-on-Vercel migration by another
contributor:

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

Plus `pnpm-lock.yaml` regenerated by the audit's `pnpm install -r` run
(+2,938/-8,520 lines — large but expected). **Don't commit the lockfile
without inspecting it** — it likely upgraded transitive versions.

### 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** (open): 85 pre-existing lint errors surfaced. Top rules:
  - 67 × `@typescript-eslint/no-unused-vars`
  - 7 × `prefer-const`
  - 7 × `no-redeclare`
  - 4 × `no-useless-escape`
- **Section W** (low priority): 96 `no-console` warnings in CLI tools etc.
- **Section R** (housekeeping): 4 misc observations.

**Note**: a recent upstream commit (in the rebased main since this audit
started) tightened the unused-vars rule with `varsIgnorePattern: '^_'`,
`caughtErrorsIgnorePattern: '^_'`, etc. — meaning `_`-prefix is now an
official escape hatch for intentionally-unused names. This makes the
85-error sweep easier (just rename, don't delete).

---

## Suggested next steps

1. **P sweep** — package owners run `pnpm --filter <pkg> lint:fix` per
   package, eyeball the diff (the autofixer can technically remove unused
   exports, which is breaking), commit. Target 6–10 small commits.
   Likely owners by error count:
   - `services/platform-service` (probably the biggest chunk)
   - `services/extraction-service`, `services/cowork-service`
   - `packages/auth`, `packages/llm`, `packages/cosmos`
   - `dashboards/admin-web`, `dashboards/tracker-web`
2. **R3** — silence the `.npmrc` WARN with a graceful fallback (not
   blocking; just noisy).
3. **R4** — add explicit `@azure/core-client@^1.10.0` to the two services
   that pull `@azure/cosmos` to silence peer warnings.
4. _(optional)_ commit the regenerated `pnpm-lock.yaml` once someone with
   context can verify the upgrades it introduced.

---

## Repo state checklist

```bash
# Verify clean state before starting
cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat
source ~/.zshrc                  # ensure GITEA_NPM_TOKEN is loaded
git status                       # 4 unrelated WIP files expected (see §2 above)
git log --oneline -3             # top: 8f541c9 chore(audit): unblock workspace lint pipeline...

# Run the gates
pnpm install -r --prefer-offline # → done in seconds (cache hit)
pnpm typecheck                   # → exit 0
pnpm test                        # → ~2,200 pass
pnpm lint > /tmp/lint.log 2>&1   # → exit 1 with 85 errors (see AUDIT_PLATFORM.md §P)
```

---

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