From e9ae8cc45994fcbd181ab71abf033cf04fa504d4 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 5 Jul 2026 15:16:06 -0400 Subject: [PATCH] =?UTF-8?q?refactor(conductor/workflow.md):=20thin-pointer?= =?UTF-8?q?=20=C2=A7Known=20Pitfalls=20to=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per agent_directives_consolidation_20260705 §3.2. The 25-line §Known Pitfalls section (the git restore/git checkout/git reset hard ban with full rationale + correct non-destructive inspection pattern) is replaced with a thin pointer to AGENTS.md §Critical Anti-Patterns, the canonical project-wide home for HARD BANs. Net: 25 lines reduced to 7 lines (72% reduction). The full content remains in AGENTS.md where the 4 canonical HARD BANs are documented. --- conductor/workflow.md | 23 ++--------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/conductor/workflow.md b/conductor/workflow.md index b937c8e3..a9ed703b 100644 --- a/conductor/workflow.md +++ b/conductor/workflow.md @@ -432,28 +432,9 @@ After Tier 2 finishes a track (success or give-up): ## Known Pitfalls (2026-06-05) -### HARD BAN: `git checkout -- `, `git restore`, `git reset` (Added 2026-06-10) +For the canonical project-wide HARD BANs (`git restore`, `git stash*`, day estimates, opaque types), see `AGENTS.md` §"Critical Anti-Patterns" (the 4 canonical HARD BANs with full rationale). This section is a thin pointer to that canonical home. -**Per AGENTS.md (Critical Anti-Patterns):** These three commands are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress `src/*` edits twice in one session (2026-06-07). If you think you need one, ASK FIRST. - -The intent of "look at what the file looked like at commit X" is non-destructive inspection. The CORRECT way: - -```bash -# WRONG: overwrites the working tree -git checkout HEAD~1 -- src/foo.py - -# RIGHT: prints to stdout, leaves working tree alone -git show HEAD~1:src/foo.py -``` - -`git checkout -- ` and `git restore` are particularly dangerous because: -- They overwrite uncommitted changes silently -- They overwrite previously-committed state in the working tree if the user has already committed and then re-edited -- The user doesn't see the loss until they notice missing changes - -If you genuinely need to revert (e.g., the working tree is broken from a previous agent), use `git stash` first to capture the in-progress state, ASK THE USER, then proceed. - -This was the actual cause of the 2026-06-10 `mma_tier_usage_reset_fix` regression: an agent used `git checkout --` to "peek at baseline", which overwrote the just-committed FR1+FR2 fixes. Recovery was via re-applying the fixes with `edit_file` (option B chosen by the user). Don't repeat this. +For the 4 hard-ban examples and the correct non-destructive inspection pattern (`git show :` for reading old content; `git stash` to capture in-progress state before asking the user), see `AGENTS.md` §"Critical Anti-Patterns" (the project-wide canonical). ### Defer-Not-Catch Pattern for Native Crashes