docs: clarify agent completion workflow

Tighten the completion checklist so future agents can follow a deterministic start procedure, implementation/doc-tick commit loop, and safe parallelization model. Include one-line prompts for up to three parallel streams with explicit ownership, gates, push, and audit-update requirements.

Co-Authored-By: GPT-5 Codex <noreply@openai.com>

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 <implementation-files>
+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 <noreply@openai.com>"
+
+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 <noreply@openai.com>"
+
+# 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: