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.

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.

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

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