bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(audit): refresh platform handoff state

Browse Source 
Update the platform audit handoff and resume prompt to match the live gates: install, typecheck, test, and lint now pass with 0 lint errors when GITEA_NPM_TOKEN is exported after sourcing ~/.zshrc.

Refs: docs/AUDIT_PLATFORM.md section P.
This commit is contained in:
Saravana Achu Mac 2026-05-04 15:09:42 -07:00
parent 1f5dc1a812
commit 41af641c54
3 changed files with 84 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/AUDIT_PLATFORM.md
View File

@ -12,12 +12,12 @@ Legend: 🔴 critical · 🟠 high · 🟡 medium · 🟢 low ·
## 0. Health snapshot
| Check | Result | Notes |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `pnpm install -r` | ✅ pass | 4 peer warnings — `@azure/cosmos` wants `@azure/core-client@^1.10.0`. Cosmetic. |
| `pnpm typecheck` | ✅ pass | All TS sources compile (`tsc --noEmit`). |
| `pnpm test` | ✅ pass | ~2,200 tests across 18+ test suites, all green. |
| `pnpm lint` | 🟡 partial | After this audit's structural fixes: still 85 pre-existing errors in code, 96 warnings. See section P. |
| Check | Result | Notes |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `pnpm install -r` | ✅ pass | No warnings when `GITEA_NPM_TOKEN` is exported after sourcing `~/.zshrc`. |
| `pnpm typecheck` | ✅ pass | All TS sources compile (`tsc --noEmit`). |
| `pnpm test` | ✅ pass | ~2,200 tests across 18+ test suites; one cowork-service `EPIPE` flake cleared on focused rerun. |
| `pnpm lint` | ✅ pass | Workspace lint exits 0 with 0 errors. Remaining output is warnings only. See section W. |
## A. Lint pipeline blockers (fixed by this audit)
@ -39,43 +39,26 @@ Legend: 🔴 critical · 🟠 high · 🟡 medium · 🟢 low ·
These all matter because `pnpm -r exec eslint` bails on the first package
failure, so the 45-error design-tokens issue was hiding everything below it.
Now the pipeline runs to completion and **surfaces the real lint debt** (next
section).
Now the pipeline runs to completion and the current workspace has **0 lint
errors**.
## P. Pre-existing lint debt now visible
## P. Pre-existing lint debt cleared
After section A's structural unblocks the workspace-wide lint reports:
Current workspace-wide lint reports no errors:
```
✖ 181 problems (85 errors, 96 warnings)
0 errors
```
Errors break down by rule (top 4):
The stale handoff note expected 85 pre-existing errors, but a live rerun on
2026-05-04 found none. No P-sweep package commits were needed in this session.
| Rule | Count | Notes |
| ----------------------------------- | ----: | ------------------------------------------------------------------ |
| `@typescript-eslint/no-unused-vars` | 67 | Mostly unused imports / unused destructured params in tests + code |
| `prefer-const` | 7 | `let` declarations never reassigned |
| `no-redeclare` | 7 | Likely identifiers shadowing globals / re-imports |
| `no-useless-escape` | 4 | Regex / string escapes that are no-ops |
## W. Pre-existing lint warnings
All of these are autofixable for the most part (`pnpm lint:fix`) **except**
where renaming an unused var changes a public API surface. They span multiple
packages I don't have working knowledge of (auth, llm, cosmos, billing-service,
tracker-service, growth-service, etc.). I'm not fixing them blind in this pass
— each one is a one-liner but a wrong rename can break a downstream consumer.
**Recommendation**: a follow-up sweep where the package owner runs
`pnpm --filter <pkg> lint:fix`, eyeballs the diff, and commits per package.
Should be 6–10 small commits.
## W. Pre-existing lint warnings (96)
Mostly `no-console` in CLI tools (`create-app`, `keyvault`, `sidecar-monitor`,
`generate.ts`, `roadmap/page.tsx`) and one `no-explicit-any` in `api-client`.
These are intentional in CLI scripts (we already disabled `no-console` for
`**/scripts/**` in this audit's eslint config change), and the rest are case-by-
case judgment calls. Not blocking.
Remaining lint output is warnings only, mostly `no-console` in CLI tools and
diagnostic scripts (`create-app`, `keyvault`, `sidecar-monitor`, `gen-module`,
`migrate-referrals`, `roadmap/page.tsx`) plus a few `no-explicit-any` warnings.
These are case-by-case judgment calls and not blocking.
## R. Repo-state observations (not fixed)
@ -83,15 +66,14 @@ case judgment calls. Not blocking.
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | :----------------: |
| R1 | Working tree had 3 uncommitted edits when the audit started: `docker-compose.ecosystem.yml` (removes `nomgap-web` from Docker), `products/nomgap/product.json` (replaces flag set + adds containers), `services/platform-service/src/modules/flags/seed.ts` (+14 lines of flags). These look like an in-progress nomgap-on-Vercel migration. **Not touched** — out of audit scope and missing context. | — | ⬜ |
| R2 | Local `main` was 17 commits behind `origin/main` at the start of the session. Backup branch `backup/main-20260504-062733` was taken from `origin/main` (the source of truth) — local stale main was _not_ backed up. | 🟢 | ✅ (backup exists) |
| R3 | `.npmrc` references `${GITEA_NPM_TOKEN}` — pnpm prints a noisy WARN if the env var is unset. Cosmetic; the install still resolves the public packages it can. | 🟢 | ⬜ |
| R4 | `pnpm install -r` reports 4 missing peer warnings for `@azure/core-client@^1.10.0`. Adding it as an explicit dep on the two services that use `@azure/cosmos` would silence the warning. | 🟢 | ⬜ |
| R3 | `.npmrc` references `${GITEA_NPM_TOKEN}`. On this machine `~/.zshrc` defines the token but does not export it, so use `source ~/.zshrc && export GITEA_NPM_TOKEN` before `pnpm`; this silences the WARN. | 🟢 | ✅ documented |
| R4 | Earlier `pnpm install -r` reported peer warnings for `@azure/core-client@^1.10.0`. A live rerun with the token exported reported no peer warnings. | 🟢 | ✅ verified |
---
## Ordering of fixes
1. **Section A** (this commit) — structural unblocks so `pnpm lint` runs end-to-end again.
2. **Section P** — per-package `lint:fix` sweeps owned by each package's
maintainer. Each package = one commit. ~6–10 commits.
3. **Section W** — case-by-case `no-console` review (defer; warnings only).
4. **Section R** — chore-level housekeeping (peer deps, .npmrc).
2. **Section P** — no current lint errors; no package sweeps needed.
3. **Section W** — case-by-case warning review (defer; warnings only).
4. **Section R** — housekeeping verified/documented.

69
docs/CODEX_RESUME_PROMPT.md
View File

@ -14,9 +14,10 @@ file.
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.
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)
@ -31,10 +32,10 @@ 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.
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
@ -45,7 +46,8 @@ 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
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)
```
@ -58,20 +60,16 @@ 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
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.
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
```
The 96 `no-console` warnings are intentional in CLI scripts and are NOT
your problem. Focus on 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
@ -89,7 +87,8 @@ needs a clean lockfile, run install yourself and decide deliberately.
### Step 4 — Priority queue: the P-sweep
The 85 errors break down by rule:
The P-sweep is currently complete. The stale 85-error handoff broke down by
rule as:
| Rule | Count | Notes |
| ----------------------------------- | ----: | -------------------------------------------------- |
@ -103,7 +102,8 @@ Recent upstream work made `^_`-prefix vars an official escape hatch
`destructuredArrayIgnorePattern`). Use that — don't delete identifiers
that might be public API.
**Workflow per package** (one commit per package, no exceptions):
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
@ -148,16 +148,15 @@ inspection):
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.
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 | 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 |
| # | 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
@ -218,15 +217,14 @@ After each commit + push:
Stop and ask the human, do not guess, when:
- An "unused" export is consumed by code outside this repo (trading repo
- 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 all 85 errors and want direction on Section R or
Section W.
- 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.
@ -242,13 +240,8 @@ 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.
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.
```

77
docs/HANDOVER.md
View File

@ -9,24 +9,23 @@
## TL;DR
A tooling-backed audit was performed across all 69 workspace packages.
`pnpm install / typecheck / test` all pass cleanly. `pnpm lint` was failing
fast at one package (hiding everything downstream); a structural eslint
config fix + 13 mechanical lint fixes have made the lint pipeline run
end-to-end. **85 pre-existing lint errors are now visible** that nobody
had seen before — they belong to package owners to clear with
`pnpm --filter <pkg> lint:fix` followed by an eyeball review.
`pnpm install / typecheck / lint` pass cleanly on the current workspace.
`pnpm lint` was previously failing fast at one package, but a structural eslint
config fix + 13 mechanical lint fixes made the lint pipeline run end-to-end.
A fresh rerun on 2026-05-04 shows **0 lint errors**; the old 85-error P-sweep
handoff is stale.
---
## What's working right now
| Check | Result | Notes |
| ---------------------- | ------------------ | ---------------------------------------------------------------------------------- |
| `pnpm install -r` | ✅ pass | 4 cosmetic peer warnings (`@azure/core-client`) |
| `pnpm typecheck` | ✅ pass | All 69 packages compile |
| `pnpm test` | ✅ pass | ~2,200 tests across 18+ suites |
| `pnpm lint` (pipeline) | ✅ runs end-to-end | Was bailing fast; this audit unblocked it |
| `pnpm lint` (errors) | 🟡 85 | All pre-existing, surfaced by the unblock — see `docs/AUDIT_PLATFORM.md` section P |
| Check | Result | Notes |
| ---------------------- | ------------------ | ------------------------------------------------------------------- |
| `pnpm install -r` | ✅ pass | No warnings when `GITEA_NPM_TOKEN` is exported |
| `pnpm typecheck` | ✅ pass | All 69 packages compile |
| `pnpm test` | ✅ pass | ~2,200 tests; cowork-service `EPIPE` flake cleared on focused rerun |
| `pnpm lint` (pipeline) | ✅ runs end-to-end | Was bailing fast; this audit unblocked it |
| `pnpm lint` (errors) | ✅ 0 | Warnings only — see `docs/AUDIT_PLATFORM.md` section W |
---
@ -34,13 +33,13 @@ had seen before — they belong to package owners to clear with
### 1. The `.npmrc` token requirement
`.npmrc` references `${GITEA_NPM_TOKEN}`. **Without it exported**, `pnpm`
emits noisy WARNs and `pnpm install -r` fails on the mobile / vendored
`@bytelyst/*` private packages. Every developer needs to:
`.npmrc` references `${GITEA_NPM_TOKEN}`. On this machine, `~/.zshrc` defines
the variable but does not export it. Without export, `pnpm` emits noisy WARNs.
Every developer shell should run:
```bash
# Add to ~/.zshrc (or ~/.bashrc)
export GITEA_NPM_TOKEN=<token-from-1Password>
source ~/.zshrc
export GITEA_NPM_TOKEN
```
The audit session's tooling runs all relied on this being sourced.
@ -64,37 +63,20 @@ without inspecting it** — it likely upgraded transitive versions.
`docs/AUDIT_PLATFORM.md` has the full breakdown:
- **Section A** (✅ done): 13 lint pipeline blockers fixed in `8f541c9`.
- **Section P** (open): 85 pre-existing lint errors surfaced. Top rules:
- 67 × `@typescript-eslint/no-unused-vars`
- 7 × `prefer-const`
- 7 × `no-redeclare`
- 4 × `no-useless-escape`
- **Section W** (low priority): 96 `no-console` warnings in CLI tools etc.
- **Section R** (housekeeping): 4 misc observations.
- **Section P** (✅ clear): current workspace lint has 0 errors.
- **Section W** (low priority): warnings only, mostly `no-console` in CLI tools.
- **Section R** (housekeeping): token export and peer-warning observations are documented/verified.
**Note**: a recent upstream commit (in the rebased main since this audit
started) tightened the unused-vars rule with `varsIgnorePattern: '^_'`,
`caughtErrorsIgnorePattern: '^_'`, etc. — meaning `_`-prefix is now an
official escape hatch for intentionally-unused names. This makes the
85-error sweep easier (just rename, don't delete).
**Note**: a recent upstream commit tightened the unused-vars rule with
`varsIgnorePattern: '^_'`, `caughtErrorsIgnorePattern: '^_'`, etc. — meaning
`_`-prefix is now an official escape hatch for intentionally-unused names.
---
## Suggested next steps
1. **P sweep** — package owners run `pnpm --filter <pkg> lint:fix` per
package, eyeball the diff (the autofixer can technically remove unused
exports, which is breaking), commit. Target 6–10 small commits.
Likely owners by error count:
- `services/platform-service` (probably the biggest chunk)
- `services/extraction-service`, `services/cowork-service`
- `packages/auth`, `packages/llm`, `packages/cosmos`
- `dashboards/admin-web`, `dashboards/tracker-web`
2. **R3** — silence the `.npmrc` WARN with a graceful fallback (not
blocking; just noisy).
3. **R4** — add explicit `@azure/core-client@^1.10.0` to the two services
that pull `@azure/cosmos` to silence peer warnings.
4. _(optional)_ commit the regenerated `pnpm-lock.yaml` once someone with
1. **Section W** — optionally review warnings case-by-case.
2. _(optional)_ commit the regenerated `pnpm-lock.yaml` once someone with
context can verify the upgrades it introduced.
---
@ -104,15 +86,16 @@ official escape hatch for intentionally-unused names. This makes the
```bash
# Verify clean state before starting
cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat
source ~/.zshrc # ensure GITEA_NPM_TOKEN is loaded
source ~/.zshrc
export GITEA_NPM_TOKEN # ensure pnpm can read the token
git status # 4 unrelated WIP files expected (see §2 above)
git log --oneline -3 # top: 8f541c9 chore(audit): unblock workspace lint pipeline...
git log --oneline -3
# Run the gates
pnpm install -r --prefer-offline # → done in seconds (cache hit)
pnpm typecheck # → exit 0
pnpm test # → ~2,200 pass
pnpm lint > /tmp/lint.log 2>&1 # → exit 1 with 85 errors (see AUDIT_PLATFORM.md §P)
pnpm test # → ~2,200 pass; rerun focused package if a known flake appears
pnpm lint > /tmp/lint.log 2>&1 # → exit 0, 0 errors
```
---