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's left. Your job is to clear the **85 pre-existing lint
errors** that are now visible — one package at a time, with eyeball
review, no shortcuts.

### 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), which are ⬜ open (section P — the 85 errors),
and which package you are about to attempt first. 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           # gets GITEA_NPM_TOKEN onto your shell
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

pnpm install -r --prefer-offline    # → cache hit, finishes in seconds
pnpm typecheck                       # → exit 0 (all 69 packages compile)
pnpm test                            # → ~2,200 tests pass
pnpm lint > /tmp/lint.log 2>&1       # baseline: exit 1, 85 errors

# After your change:
pnpm lint > /tmp/lint-after.log 2>&1
diff <(grep -c "errors" /tmp/lint.log) <(grep -c "errors" /tmp/lint-after.log)
# Error count MUST go DOWN, never up.
```

The 96 `no-console` warnings are intentional in CLI scripts and are NOT
your problem. Focus on errors.

### Step 3 — Working tree state at handover

Three files are uncommitted in the working tree and were intentionally
left alone by the prior audit. **Do not touch them.** They belong to an
in-progress nomgap-on-Vercel migration owned by another contributor:

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

A fourth file — `pnpm-lock.yaml`, +2,938/-8,520 lines — is from the prior
session's `pnpm install -r` regeneration. Don't commit it. If your work
needs a clean lockfile, run install yourself and decide deliberately.

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

The 85 errors break down by rule:

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

**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: 6–10 small commits, lint error count 85 → 0.

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

| #   | Item  | What                                                                                                         | Effort |
| --- | ----- | ------------------------------------------------------------------------------------------------------------ | ------ |
| 1   | R3    | Silence the `.npmrc` `${GITEA_NPM_TOKEN}` WARN with a graceful fallback                                      | 30 min |
| 2   | R4    | Add explicit `@azure/core-client@^1.10.0` to the two services using `@azure/cosmos` to silence peer warnings | 15 min |
| 3   | (new) | Decide whether to commit the regenerated `pnpm-lock.yaml` (review the diff)                                  | 1 hr   |
| 4   | (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 touch the nomgap WIP files** (see step 3). Different
   contributor's in-flight work.
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:

- An "unused" export is 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 all 85 errors and want direction on Section R or
  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 — it contains your full brief, the P-sweep workflow, the
verification gates, and the commit conventions. Then walk the 85 lint
errors package-by-package: pick one, run `pnpm --filter <pkg> exec
eslint . --ext .ts,.tsx --fix`, eyeball the diff, run gates, commit
(one package = one commit, subject `chore(P-sweep): ...`), push, tick
the audit doc, repeat. Source ~/.zshrc in every shell so
GITEA_NPM_TOKEN is available. Do not touch the nomgap WIP files. Do
not bulk-fix. After each push, tell me the package, commit hash, and
error-count delta in three sentences.
```