docs(audit): add agent checklist workflow
Extend the warning completion checklist with a repeatable agent protocol, claim table, commit/update format, stop conditions, and up to three safe parallel workstream prompts.
This commit is contained in:
parent
af893c23be
commit
437a0fed5a
@ -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(<area>): <small warning cleanup>
|
||||
docs(audit): mark <area> warning cleanup
|
||||
```
|
||||
|
||||
Recommended commit body:
|
||||
|
||||
```text
|
||||
What changed:
|
||||
- ...
|
||||
|
||||
Warning impact:
|
||||
- <rule/file>: <before> -> <after>
|
||||
|
||||
Verification:
|
||||
- pnpm --filter <workspace> build
|
||||
- pnpm --filter <workspace> test
|
||||
- pnpm --filter <workspace> 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 `<commands>`.
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user