diff --git a/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md b/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md index 6b95c1ad..4d9a95c1 100644 --- a/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md +++ b/docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md @@ -32,6 +32,130 @@ Recent warning-cleanup commits: | `9625999` | `@lysnrai/platform-service` | Removed stale eslint-disable comments. | | `6978ddb` | `@lysnrai/cowork-service` | Typed test doubles for IPC/Fastify mocks. | +## Agent Execution Protocol + +Any agent should be able to continue this work by following this protocol. +When in doubt, optimize for small commits, clean verification, and an updated +checklist. + +### 1. Start-of-Run Checklist + +- [ ] Read this file in full. +- [ ] Read `docs/AUDIT_PLATFORM.md`. +- [ ] Run: + + ```bash + cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat + source ~/.zshrc + export GITEA_NPM_TOKEN + git status --short + pnpm lint > /tmp/lint-before.log 2>&1 + ``` + +- [ ] Confirm `pnpm lint` exits `0`. +- [ ] Confirm the only pre-existing uncommitted files are still: + - `docker-compose.ecosystem.yml` + - `products/nomgap/product.json` + - `services/platform-service/src/modules/flags/seed.ts` + - `pnpm-lock.yaml` +- [ ] Pick one unchecked workstream item or one coherent group of adjacent + items. +- [ ] Add your in-progress marker in the table below before editing, using + your agent name/session if available. + +### 2. Per-Commit Workflow + +For each incremental commit: + +1. Change only the files owned by the selected checklist item. +2. Run scoped gates first. +3. Run workspace lint. +4. Commit only the files you touched. +5. Push. +6. Re-run the scoped gates after push. +7. Update this checklist with: + - checkbox status, + - commit hash, + - warning-count delta, + - verification commands. +8. Commit and push the checklist update separately unless it is a tiny checkbox + update tied to the same change and hooks already ran. + +Recommended commit subject format: + +```text +chore(): +docs(audit): mark warning cleanup +``` + +Recommended commit body: + +```text +What changed: +- ... + +Warning impact: +- : -> + +Verification: +- pnpm --filter build +- pnpm --filter test +- pnpm --filter exec eslint . --ext .ts,.tsx +- pnpm lint +``` + +### 3. Checklist Update Format + +When completing an item, update the checkbox line like this: + +```markdown +- [x] `path/to/file.ts`: short task description. Done in `abc1234`; warning + delta `-2`; verified with ``. +``` + +For workstream-level completions, add a row to the progress log: + +```markdown +| 2026-05-04 | `abc1234` | Short completed change. | Removed N warnings; lint remains 0 errors. | +``` + +### 4. Stop Conditions + +Stop and ask for guidance when: + +- A fix changes user-visible product behavior. +- A React hook warning appears to require data-flow redesign. +- A `console.*` call is part of intentional user-facing CLI output and no policy + exists yet. +- A test failure appears in a package you did not touch and does not clear on + one focused rerun. +- You need to touch the nomgap WIP files or `pnpm-lock.yaml`. +- More than one workstream wants the same files. + +## Parallelization Plan + +Maximum parallel streams: 3. + +Parallel work is safe only when each agent owns a disjoint file set. All agents +must start from the same pushed `main`, claim their stream in this document, +and push small commits quickly. If two agents need the same files, serialize. + +### Active / Claim Table + +| Stream | Status | Owner | File ownership | Current target | Last commit | +| ------ | ------ | ----- | ---------------------------------------------------------- | ------------------------------------------------- | ----------- | +| A | Open | — | `dashboards/admin-web/**` | W2 admin web React warnings | — | +| B | Open | — | `services/platform-service/src/**` only | W3/W4 service runtime console + predictive typing | — | +| C | Open | — | lint policy, CLI/script files, tracker module config, docs | W1/W5/W6/W7/W8/W9/W10 | — | + +### One-Line Prompts For Parallel Agents + +Use at most three of these at once: + +- **Agent A:** "Work only in `dashboards/admin-web/**`; clear one small group of W2 React warnings, run admin-web typecheck/test/lint plus workspace lint, commit/push, then update `docs/AUDIT_WARNING_COMPLETION_CHECKLIST.md` with commit hash and warning delta." +- **Agent B:** "Work only in `services/platform-service/src/**`; tackle either W3 runtime console logging or W4 predictive analytics typing, run platform-service build/targeted tests/lint plus workspace lint, commit/push, then update the checklist with commit hash and warning delta." +- **Agent C:** "Work only on lint policy/CLI docs/config or tracker-web module warning files; do not touch admin-web or platform-service runtime files, run scoped gates plus workspace lint, commit/push, then update the checklist with commit hash and warning delta." + ## Operating Rules - Keep `pnpm lint` at `0` errors at all times. @@ -105,8 +229,9 @@ This workstream is complete when: Goal: distinguish intentional warning classes from real quality issues. -- [ ] Capture a fresh warning inventory: - `pnpm lint > /tmp/lint-warning-inventory.log 2>&1`. +- [x] Capture a fresh warning inventory: + `pnpm lint > /tmp/lint-final-pass.log 2>&1`. Done before `af893c2`; + latest summarized baseline is `0` errors / `189` warnings. - [ ] Split warnings into buckets: `console`, `no-explicit-any`, `no-unused-vars`, `react-hooks/exhaustive-deps`, `@next/next/no-img-element`, Node module warnings, stale disables. @@ -124,7 +249,7 @@ Goal: distinguish intentional warning classes from real quality issues. Goal: remove obvious dashboard warnings and review hook warnings safely. - [ ] `dashboards/admin-web/src/app/(dashboard)/experiments/[id]/page.tsx`: - remove or use unused `Download`. + remove or use unused `Download`. Owner: Stream A. - [ ] Same file: review `fetchExperimentData` dependency warning. - [ ] Same file: remove, rename, or use unused `experiment` argument. - [ ] `dashboards/admin-web/src/app/(dashboard)/experiments/page.tsx`: @@ -190,6 +315,9 @@ Goal: remove production `any`s from - [ ] Run predictive analytics tests. - [ ] Run platform-service build/test/lint gates. +Suggested split: do this as one commit if all 5 `any`s share one domain shape; +otherwise split by function/section and update this checklist after each commit. + ### W5. Platform Scripts + Codegen Goal: make script warnings intentional and policy-backed. @@ -251,6 +379,9 @@ quality commits. - [ ] Do not include nomgap WIP files in the lockfile decision. - [ ] Re-run install/typecheck/test/lint after lockfile action. +Do not start W8 in parallel with package changes that might run install or alter +dependency metadata. + ### W9. Known Test Flakes + Load Sensitivity Goal: make the suite reliable enough for repeated audit gates. @@ -270,11 +401,13 @@ Goal: make the suite reliable enough for repeated audit gates. Goal: keep future agents aligned with the true baseline. - [ ] Update `docs/AUDIT_PLATFORM.md` after each meaningful warning-policy - milestone. -- [ ] Update `docs/HANDOVER.md` when the current gate story changes. + milestone. Include commit hash and current lint baseline. +- [ ] Update `docs/HANDOVER.md` when the current gate story changes. Include + known flakes/load sensitivity if still relevant. - [ ] Keep `docs/CODEX_RESUME_PROMPT.md` aligned with the latest workflow. -- [ ] Record warning counts after each batch in this checklist. -- [ ] Include commit hashes in this checklist for major completed batches. +- [ ] Record warning counts after each batch in this checklist. Use the latest + `/tmp/lint-*.log` path and warning count. +- [ ] Include commit hashes in this checklist for every completed batch. - [ ] Keep "do not touch nomgap WIP" instructions visible until those files are resolved by their owner.