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.

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.

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

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