From 1f5dc1a812924aeffe0e181acd938e8a3dbc928e Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Mon, 4 May 2026 14:50:07 -0700 Subject: [PATCH] docs: add CODEX_RESUME_PROMPT.md for platform-side agent hand-off MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of the trading repo's resume prompt but anchored on the platform-side audit work. Any agent (Codex, Claude, Gemini, etc.) running on this machine can paste in the short prompt at the bottom of this file and self-bootstrap from the full brief above. Brief covers: - Required reads (HANDOVER.md + AUDIT_PLATFORM.md, optionally the trading repo's HANDOVER for cross-repo context) - Environment (source ~/.zshrc for GITEA_NPM_TOKEN — without it pnpm install -r fails on the private @bytelyst/* mobile dep) - Verification gates with explicit "error count must go down, never up" rule - Working-tree state: 3 nomgap WIP files + 1 regenerated lockfile that the agent must NOT touch - The P-sweep: 85 pre-existing lint errors, broken down by rule, with a per-package workflow (one package = one commit) and a suggested walking order - Commit conventions matching the prior session (chore(P-sweep): pnpm --filter lint:fix) - Seven explicit "do not" rules — the most important being do-not- modify the audit's load-bearing eslint config block (`**/*.cjs` + `**/scripts/**`) which prevents 45 errors from regressing - When-to-stop-and-ask criteria so the agent doesn't blindly delete "unused" exports that downstream repos (trading vendor) consume Refs: docs/HANDOVER.md, docs/AUDIT_PLATFORM.md. Co-Authored-By: Claude Sonnet 4.6 --- docs/CODEX_RESUME_PROMPT.md | 254 ++++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 docs/CODEX_RESUME_PROMPT.md diff --git a/docs/CODEX_RESUME_PROMPT.md b/docs/CODEX_RESUME_PROMPT.md new file mode 100644 index 00000000..443977f0 --- /dev/null +++ b/docs/CODEX_RESUME_PROMPT.md @@ -0,0 +1,254 @@ +# 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/ 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: 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/ 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 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 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. +```