diff --git a/docs/COMPLETION_CHECKLIST.md b/docs/COMPLETION_CHECKLIST.md index 40d9f78..89c20f7 100644 --- a/docs/COMPLETION_CHECKLIST.md +++ b/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`. -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 +4. Run `source ~/.zshrc && export GITEA_NPM_TOKEN`. +5. Run `git status --short`; stop if there are unexpected local edits in files + you need to touch. +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. -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 +10. Implement only the assigned item or bucket. +11. Run the full relevant gates again. +12. Commit the implementation first. +13. Run `git pull --rebase --autostash` again before editing audit docs. If it + conflicts, resolve only if the conflict is simple and in docs; otherwise + stop. If a rebase applies remote code changes, rerun gates before the doc + 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 + pushed: implementation , docs . +Gates: ; ; ; . +Next: . +``` + +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 " +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 ```