# 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 / 157 warnings**; the old
85-error P-sweep handoff is stale.

---

## 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; cowork-service `EPIPE` flake cleared on focused rerun |
| `pnpm lint` (pipeline) | ✅ runs end-to-end | Was bailing fast; this audit unblocked it                           |
| `pnpm lint` (errors)   | ✅ 0               | 157 warnings remain — see `docs/AUDIT_PLATFORM.md` section W        |

---

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

```bash
source ~/.zshrc
export GITEA_NPM_TOKEN
```

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** (✅ 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`.
- **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. **Section W** — optionally review warnings case-by-case.
2. _(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
export GITEA_NPM_TOKEN           # ensure pnpm can read the token
git status                       # 4 unrelated WIP files expected (see §2 above)
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
```

---

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