# 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/ 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/ typecheck pnpm --filter @bytelyst/ test pnpm --filter @bytelyst/ exec eslint . --ext .ts,.tsx # 6. Commit: # chore(P-sweep): pnpm --filter @bytelyst/ 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/ lint:fix` — if the fix needed manual edits beyond `--fix`, use `chore(P-sweep): clear lint debt in @bytelyst/`. - 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: `. - 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. ```