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

Remaining lint output is warnings only. Treat warning cleanup as case-by-case Section W work, not part of the completed P-sweep.

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 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	Review remaining lint warnings case-by-case	varies
2	(new)	Decide whether to commit the regenerated pnpm-lock.yaml (review the diff)	1 hr
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 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:

• 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, and do
not start a P-sweep unless a fresh lint log shows new errors. Do not touch the
nomgap WIP files or commit pnpm-lock.yaml as a side effect.