learning_ai_common_plat/docs/CODEX_RESUME_PROMPT.md

# Codex Resume Prompt — Common Platform Audit

Paste the contents of this file into a fresh Codex / Claude / Gemini agent
session running on the **same machine** that did the original work
(`Sar-M2-bl`, user `saravana`). The agent will pick up the platform-side
audit work and drive the open lint debt to zero.

The short "copy-paste" version of this prompt lives at the bottom of this
file.

---

## ── BEGIN AGENT BRIEF ──

You are resuming a tooling-backed audit of a 69-package pnpm workspace.
A prior session already unblocked the lint pipeline, ran every gate, and
catalogued what was left. A fresh rerun on 2026-05-04 shows the old
**85 pre-existing lint errors** are now stale: current workspace lint exits
0 with 0 errors. Do not start a P-sweep unless a fresh lint log shows new
errors.

### Step 0 — Required reads (do this BEFORE writing any code)

Read these two files in order. They are the source of truth — anything
contradicting them is wrong:

1. `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/HANDOVER.md`
2. `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`

If you also plan to work cross-repo (the platform's vendored packages get
re-shipped to the trading repo), also skim:

3. `/Users/saravana/BytelystAI/trading/learning_ai_invt_trdg/docs/HANDOVER.md`

After reading, summarise in your own words: which audit items are done
(section A — 13 items), that section P is currently clear, and what optional
follow-up you are about to attempt. If your summary disagrees with the audit
doc tables, re-read.

### Step 1 — Environment

This machine has the private-registry token in `~/.zshrc`. **Every shell
you spawn** must source it before running `pnpm`. Without it `pnpm`
prints `WARN: Failed to replace env in config: ${GITEA_NPM_TOKEN}` and
the install will fail on the private `@bytelyst/*` packages used by the
mobile workspace and by transitive deps.

```bash
source ~/.zshrc
export GITEA_NPM_TOKEN    # ~/.zshrc defines it on this machine but does not export it
echo "$GITEA_NPM_TOKEN" | wc -c     # must print 41 (40 chars + newline)
```

### Step 2 — Verification gates (run BEFORE and AFTER every change)

You MUST run these before claiming any item ✅ done. If a gate fails
after your change, you broke something — fix it before committing. Do
NOT --no-verify. Do NOT skip hooks.

```bash
cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat
source ~/.zshrc
export GITEA_NPM_TOKEN

pnpm install -r --prefer-offline    # → cache hit, finishes in seconds
pnpm typecheck                       # → exit 0 (all 69 packages compile)
pnpm test                            # → ~2,200 tests pass; rerun focused package if a known flake appears
pnpm lint > /tmp/lint.log 2>&1       # current baseline: exit 0, 0 errors / 0 warnings
```

The warning sweep is complete as of `663dcde`; keep future changes on the
0-error / 0-warning baseline.
`@bytelyst/auth` has a package-local Vitest timeout in `d3fbeba` because
production 12-round `bcryptjs` hashes can exceed Vitest's default 5s timeout on
this machine.

### Step 3 — Working tree state at handover

The prior nomgap-on-Vercel WIP files were finalized in `b440330` and are no
longer expected to be dirty:

- `docker-compose.ecosystem.yml`
- `products/nomgap/product.json`
- `services/platform-service/src/modules/flags/seed.ts`

`pnpm-lock.yaml` is clean and was not committed during the warning sweep. Do
not commit it as a side effect; if your work needs dependency changes, make
that decision deliberately in a dedicated dependency commit.

### Step 4 — Priority queue: the P-sweep

The P-sweep is currently complete. The stale 85-error handoff broke down by
rule as:

| Rule                                | Count | Notes                                              |
| ----------------------------------- | ----: | -------------------------------------------------- |
| `@typescript-eslint/no-unused-vars` |    67 | Mostly unused imports / unused destructured params |
| `prefer-const`                      |     7 | `let` declarations never reassigned                |
| `no-redeclare`                      |     7 | Identifiers shadowing globals or duplicate imports |
| `no-useless-escape`                 |     4 | Regex / string escapes that are no-ops             |

Recent upstream work made `^_`-prefix vars an official escape hatch
(`varsIgnorePattern`, `caughtErrorsIgnorePattern`,
`destructuredArrayIgnorePattern`). Use that — don't delete identifiers
that might be public API.

If a fresh lint log shows new errors, use this workflow per package (one commit
per package, no exceptions):

```bash
# 1. Identify package owners by looking at the lint log
grep -B 6 "[1-9][0-9]* problems" /tmp/lint.log | grep "/(packages|services|dashboards)/" | sort -u

# 2. Pick one. Run lint:fix scoped to it.
pnpm --filter @bytelyst/<pkg> exec eslint . --ext .ts,.tsx --fix

# 3. Inspect the diff. The autofixer can:
#    - delete unused imports (usually safe)
#    - delete unused exports (BREAKING — public API)
#    - rename `let` to `const` (always safe)
#    - remove regex escapes (almost always safe; verify regex behaviour)
git diff --stat
git diff   # eyeball every hunk

# 4. For unused vars the autofixer can't safely remove (function params
#    that satisfy an interface, destructured shape that documents the
#    contract), prefix with `_`:
#    function foo(req, _res, next) { ... }

# 5. Re-run gates for the package only:
pnpm --filter @bytelyst/<pkg> typecheck
pnpm --filter @bytelyst/<pkg> test
pnpm --filter @bytelyst/<pkg> exec eslint . --ext .ts,.tsx

# 6. Commit:
#    chore(P-sweep): pnpm --filter @bytelyst/<pkg> lint:fix
#    Refs: docs/AUDIT_PLATFORM.md item P.

# 7. Push, then update docs/AUDIT_PLATFORM.md to add the package to a
#    new "P. Cleared packages" sub-table with the commit hash.
```

Suggested order (estimated highest error count first — confirm by
inspection):

1. `services/platform-service` — biggest service, likely biggest chunk
2. `services/extraction-service`, `services/cowork-service`, `services/billing-service`, `services/growth-service`, `services/tracker-service`
3. `packages/auth`, `packages/llm`, `packages/cosmos`
4. `packages/datastore`, `packages/events`, `packages/event-store`
5. `dashboards/admin-web`, `dashboards/tracker-web`, `dashboards/ux-lab`
6. Everything remaining (one pass)

Target for any future sweep: reduce the fresh lint error count to 0.

### Step 5 — Secondary work (after P-sweep is done)

| #   | Item  | What                                                                                                    | Effort |
| --- | ----- | ------------------------------------------------------------------------------------------------------- | ------ |
| 1   | W     | Preserve the completed 0-warning lint baseline during future feature work                               | varies |
| 2   | TODO  | Make `services/platform-service/scripts/migrate-referrals.ts --help` independent of service env loading | 30 min |
| 3   | (new) | Audit any package whose tests skip > 5% (look at `feedback-client`, `cowork-service`) — investigate why | 1-2 hr |

### Step 6 — Commit conventions

Match the prior session's conventions exactly so audit history stays grep-able:

- **One package per commit** for the P-sweep. Combining packages destroys
  blameability.
- Subject: `chore(P-sweep): pnpm --filter @bytelyst/<pkg> lint:fix` —
  if the fix needed manual edits beyond `--fix`, use
  `chore(P-sweep): clear lint debt in @bytelyst/<pkg>`.
- Body explains anything non-obvious: "renamed `_options` to satisfy
  interface; removed unused export X after confirming no consumers in
  workspace."
- Reference: `Refs: docs/AUDIT_PLATFORM.md item P.`
- End with `Co-Authored-By: <model> <noreply@anthropic.com>`.
- After committing, **edit `docs/AUDIT_PLATFORM.md`** — add the package
  to a "P. Cleared packages" sub-table with the commit hash. Update the
  "remaining errors" count in section P intro.

### Step 7 — Things to NEVER do

1. **Do not reintroduce nomgap or lockfile side effects** (see step 3).
2. **Do not commit `pnpm-lock.yaml` as a side effect.** If your work
   actually needs new deps, mention it explicitly in the commit body.
3. **Do not bulk-fix multiple packages in one commit.** Each package
   needs eyeball review of the autofixer's diff. Combining them hides
   regressions.
4. **Do not blindly accept `eslint --fix` for unused exports.** An
   "unused" export at the workspace level might be re-exported from an
   index file or consumed by a downstream repo (e.g. the trading repo
   vendors several `@bytelyst/*` packages and consumes them through
   barrel imports). When in doubt: prefix with `_` rather than delete.
5. **Do not skip verification gates.** "It looks fine" is not
   verification. Run the commands and see exit 0.
6. **Do not push --force to main.** Backup branch
   `backup/main-20260504-062733` exists for emergency rollback;
   rewriting public history is still wrong.
7. **Do not modify the audit-fix eslint config block** (the `**/*.cjs`
   and `**/scripts/**` block in `eslint.config.js`) without
   understanding why it was added. It's load-bearing — removing it
   re-breaks 45 errors in design-tokens.

### Step 8 — When you finish a chunk

After each commit + push:

1. Run the verification gates **again** (push hooks may have reformatted
   files via `lint-staged`).
2. Update `docs/AUDIT_PLATFORM.md` with the cleared package + hash.
3. Tell the human: package name, commit hash, error-count delta. Three
   sentences max. Example:
   > Cleared `services/platform-service`: 23 → 0 errors via mostly-`--fix`
   > with two manual `_`-prefix renames in `modules/referrals`. Commit
   > `abc1234`. Workspace error count now 62.

### Step 9 — When to stop and ask

Stop and ask the human, do not guess, when:

- A fresh lint log shows an "unused" export consumed by code outside this repo (trading repo
  vendors several packages — check there before deleting).
- A `lint:fix` autofix changes runtime behaviour (rare for the rules in
  scope, but possible with `no-useless-escape` if a regex is doing
  something subtle).
- Tests start failing in a package whose code you didn't directly touch
  (transitive type breakage).
- You have cleared any fresh lint errors and want direction on Section W.

Otherwise: keep going. The point of this brief is so you don't have to
ping the human every package.

## ── END AGENT BRIEF ──

---

## Short copy-paste prompt for Codex

Paste this single block into Codex / Claude / Gemini:

```
Resume the platform audit on this machine. Read
/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/CODEX_RESUME_PROMPT.md
in full first. Source ~/.zshrc and export GITEA_NPM_TOKEN in every shell.
Run the verification gates, confirm lint still exits 0 with 0 errors / 0
warnings, and do not start a P-sweep unless a fresh lint log shows new errors.
Do not reintroduce nomgap WIP or commit pnpm-lock.yaml as a side effect.
```