docs: harden parallel agent checklist

Add explicit sync, collision, reporting, multi-row, and newly-discovered-work rules so independent agents can safely make incremental commits, update audit rows with implementation hashes, and push without trampling parallel streams.

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

docs/COMPLETION_CHECKLIST.md

@@ -38,20 +38,82 @@ Every agent should do this before writing code:
    `/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`.
+4. Run `source ~/.zshrc && export GITEA_NPM_TOKEN`.
-5. Confirm the target audit row is still open and no other agent has claimed or
+5. Run `git status --short`; stop if there are unexpected local edits in files
-   pushed it.
+   you need to touch.
-6. Run the relevant baseline gates before making code changes when the work is
+6. Run `git pull --ff-only` so the local branch includes any other agent's
+   completed rows and commits.
+7. Confirm the target audit row is still open and no other agent has pushed it.
+   If the row is already `✅`, skip it and take the next assigned row.
+8. Inspect the files you expect to edit and confirm they do not overlap with an
+   active parallel stream.
+9. Run the relevant baseline gates before making code changes when the work is
    not docs-only.
-7. Implement only the assigned item or bucket.
+10. Implement only the assigned item or bucket.
-8. Run the full relevant gates again.
+11. Run the full relevant gates again.
-9. Commit the implementation first.
+12. Commit the implementation first.
-10. Update the audit row status and fix commit with the short implementation
+13. Run `git pull --rebase --autostash` again before editing audit docs. If it
-    hash, then commit the doc tick separately.
+    conflicts, resolve only if the conflict is simple and in docs; otherwise
-11. Push both commits.
+    stop. If a rebase applies remote code changes, rerun gates before the doc
-12. Report the item id, implementation commit hash, doc tick commit hash, and
+    tick. Recompute the implementation hash after any rebase.
+14. Update the audit row status and fix commit with the final short
+    implementation hash, then commit the doc tick separately.
+15. Run final gates after both commits.
+16. Run `git pull --rebase --autostash` one last time before `git push`. If it
+    applies remote commits, rerun the final gates before pushing.
+17. Push both commits.
+18. Report the item id, implementation commit hash, doc tick commit hash, and
     gate output in three sentences or fewer.
 
+## Work Claiming and Collision Handling
+
+- The assignment prompt is the claim. Do not create a claim-only commit unless
+  the human explicitly asks for one.
+- Before starting, check `git log --oneline -10` and the audit table. Another
+  agent may have finished the item while your session was idle.
+- If another agent lands the same item first, do not duplicate it. Pull, verify
+  the row is `✅`, and move to the next assigned item only if the prompt allows
+  continuing.
+- If your implementation files overlap with another active stream, pause and
+  ask for an integrator decision. The most common overlap files are
+  `web/src/views/HomeView.tsx`, strategy-builder components, backend API route
+  helpers, and audit docs.
+- If only the audit doc conflicts, preserve all completed rows and all commit
+  hashes. Never erase another agent's row update.
+- If a package manager changes a lockfile you do not own, revert only that
+  incidental lockfile hunk before committing. Do not revert unrelated human or
+  agent edits.
+
+## Report Format After Each Push
+
+Use this exact shape:
+
+```text
+<ITEM> pushed: implementation <hash>, docs <hash-or-none>.
+Gates: <gate 1 result>; <gate 2 result>; <gate 3 result>; <gate 4 result>.
+Next: <next queue item or blocker>.
+```
+
+Example:
+
+```text
+B2+B3 pushed: implementation abc1234, docs def5678.
+Gates: web typecheck exit 0; web build ✓ built; web test 155/155; backend tsc exit 0.
+Next: C2 FMP cache.
+```
+
+## Multi-Row and Newly Discovered Work
+
+- If one cohesive fix closes multiple audit rows, commit it once with all IDs in
+  the subject, for example `fix(B2,B3): wire ticker header actions`.
+- In the audit table, put the same implementation hash in each closed row.
+- If you discover a real issue that is not in the audit, do not quietly broaden
+  scope. Add a new audit row or a checklist note in a docs commit, then ask the
+  human to prioritize it unless it blocks the current item.
+- If an item's acceptance criteria are ambiguous, inspect existing code and docs
+  first. If still ambiguous and the fix changes user-visible behavior or public
+  contracts, pause and ask.
+
 ## Exact Commit and Audit Update Loop
 
 Use this loop for every trading audit item:
@@ -60,6 +122,7 @@ Use this loop for every trading audit item:
 source ~/.zshrc
 export GITEA_NPM_TOKEN
 git status --short
+git pull --ff-only
 
 # Baseline gates before substantial code changes
 npm --prefix web run typecheck
@@ -79,6 +142,8 @@ git commit -m "fix(B2,B3): short description" \
   -m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \
   -m "Co-Authored-By: GPT-5 Codex <noreply@openai.com>"
 
+git pull --rebase --autostash
+# If the rebase applies remote code changes, rerun the relevant gates before editing docs.
 IMPLEMENTATION_HASH="$(git rev-parse --short HEAD)"
 # Edit docs/AUDIT_REDESIGN.md: ⬜ -> ✅ and Fix commit -> $IMPLEMENTATION_HASH
 git add docs/AUDIT_REDESIGN.md
@@ -93,6 +158,8 @@ npm --prefix web run build
 npm --prefix web test
 npx tsc --noEmit -p backend/tsconfig.json
 
+git pull --rebase --autostash
+# If the rebase applies remote commits, rerun the final gates before pushing.
 git push
 ```