diff --git a/docs/COMPLETION_CHECKLIST.md b/docs/COMPLETION_CHECKLIST.md index 97d3128..40d9f78 100644 --- a/docs/COMPLETION_CHECKLIST.md +++ b/docs/COMPLETION_CHECKLIST.md @@ -28,6 +28,133 @@ means, and which gates must pass before pushing. or auth behavior, pause and confirm unless the audit item explicitly requires that contract change. +## Fresh-Agent Start Procedure + +Every agent should do this before writing code: + +1. Read `docs/CODEX_RESUME_PROMPT.md` in full. +2. Read `docs/AUDIT_REDESIGN.md` and this checklist. +3. If touching platform, also read + `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/HANDOVER.md` + and + `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`. +4. Run `source ~/.zshrc && export GITEA_NPM_TOKEN && git status --short`. +5. Confirm the target audit row is still open and no other agent has claimed or + pushed it. +6. Run the relevant baseline gates before making code changes when the work is + not docs-only. +7. Implement only the assigned item or bucket. +8. Run the full relevant gates again. +9. Commit the implementation first. +10. Update the audit row status and fix commit with the short implementation + hash, then commit the doc tick separately. +11. Push both commits. +12. Report the item id, implementation commit hash, doc tick commit hash, and + gate output in three sentences or fewer. + +## Exact Commit and Audit Update Loop + +Use this loop for every trading audit item: + +```bash +source ~/.zshrc +export GITEA_NPM_TOKEN +git status --short + +# Baseline gates before substantial code changes +npm --prefix web run typecheck +npm --prefix web run build +npm --prefix web test +npx tsc --noEmit -p backend/tsconfig.json + +# Edit files, then repeat gates +npm --prefix web run typecheck +npm --prefix web run build +npm --prefix web test +npx tsc --noEmit -p backend/tsconfig.json + +git add +git commit -m "fix(B2,B3): short description" \ + -m "Present-tense why paragraph." \ + -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \ + -m "Co-Authored-By: GPT-5 Codex " + +IMPLEMENTATION_HASH="$(git rev-parse --short HEAD)" +# Edit docs/AUDIT_REDESIGN.md: ⬜ -> ✅ and Fix commit -> $IMPLEMENTATION_HASH +git add docs/AUDIT_REDESIGN.md +git commit -m "docs(B2,B3): tick ticker header audit rows" \ + -m "Record the implementation commit in the redesign audit table." \ + -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \ + -m "Co-Authored-By: GPT-5 Codex " + +# Final gates after both commits +npm --prefix web run typecheck +npm --prefix web run build +npm --prefix web test +npx tsc --noEmit -p backend/tsconfig.json + +git push +``` + +Do not amend the implementation commit to include the audit-row hash after the +hash is written into the table. That creates a self-referential hash loop. The +preferred pattern is one implementation commit plus one small docs tick commit. + +For docs-only work, use the same commit style but run at least +`git diff --check` and the trading gates unless the human explicitly waives +them. + +## Parallelization Rules + +Maximum parallel streams: 3 agents. + +- Parallel streams must own disjoint files or clearly disjoint repos. +- Only one agent may edit `docs/AUDIT_REDESIGN.md` at a time. If multiple + agents finish together, each should pull/rebase first, then update only its + own rows. +- Do not parallelize two items that both touch `web/src/views/HomeView.tsx`, + shared strategy-builder files, or backend route helpers unless one agent is + explicitly acting as integrator. +- Prefer one frontend feature stream, one backend/security/test stream, and one + platform-lint stream. +- Each agent must push incremental commits for its owned item before taking the + next item. +- If a gate fails in code outside the agent's touched files, stop and report + instead of masking the failure. +- If merge conflicts appear in audit docs only, resolve by preserving all + completed rows and commit hashes. + +Recommended three-way split for the current backlog: + +| Stream | Owns | Avoids | +| --- | --- | --- | +| Agent 1 - Web feature | `B2+B3`, then `B4+B5`, then `B6-B10` | Backend route/cache files and platform repo | +| Agent 2 - Backend/security/tests | `C2`, `F6`, `C1`, then `C3-C7` | `TickerHeader`, layout polish, platform repo | +| Agent 3 - Platform/infra/docs | Platform `P-sweep`, then `E1/E3/E4` if platform is blocked | nomgap WIP files and active trading feature files | + +If only two agents are available, run Agent 1 and Agent 2. If only one agent is +available, follow the recommended next commits top-down. + +## One-Line Parallel Agent Prompts + +Agent 1: + +```text +In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement B2+B3 only: wire TickerHeader Watchlist/alert actions and company name from fetchResearchProfile; run all trading gates, commit implementation, tick only B2/B3 rows with the implementation hash in a docs commit, push, and report hashes plus gate output. +``` + +Agent 2: + +```text +In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement C2 only: add a 30-minute in-memory FMP cache keyed by full upstream URL with tests where practical; run all trading gates, commit implementation, tick only C2 with the implementation hash in a docs commit, push, and report hashes plus gate output. +``` + +Agent 3: + +```text +In /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat, read docs/HANDOVER.md and docs/AUDIT_PLATFORM.md plus the trading docs/COMPLETION_CHECKLIST.md, then do one package-scoped P-sweep lint fix only without touching nomgap WIP or platform pnpm-lock.yaml; run platform typecheck/test/lint, commit that package only, update AUDIT_PLATFORM.md if applicable, push, and report hashes plus before/after lint error count. +``` + ## Current Snapshot Completed in trading: