Skip to content

docs(agents): mandatory pre-flight + forbidden-commands warnings for dirty trees#582

Merged
fglock merged 1 commit intomasterfrom
docs/agents-md-dirty-tree-rules
Apr 28, 2026
Merged

docs(agents): mandatory pre-flight + forbidden-commands warnings for dirty trees#582
fglock merged 1 commit intomasterfrom
docs/agents-md-dirty-tree-rules

Conversation

@fglock
Copy link
Copy Markdown
Owner

@fglock fglock commented Apr 28, 2026

Summary

AGENTS.md already warned about git stash, but said nothing about
git checkout <path>, git restore, git reset --hard, or
git clean — which are equally destructive when run on a dirty
working tree. This gap caused a real data-loss incident on
2026-04-28, where ~600 module results from cpan_random_tester.pl
were silently destroyed by an agent running
git checkout dev/cpan-reports/.

This PR makes the rules harder to ignore:

  1. MANDATORY PRE-FLIGHT block at the very top: the exact `git diff

    /tmp/wip-*.patch+ WIP-branch commit commands an agent must run the momentgit status` shows unstaged work it didn't create.

  2. FORBIDDEN COMMANDS ON A DIRTY TREE block enumerating each
    destructive verb (checkout <path>, restore, reset --hard,
    clean -fd, stash) with the safe alternative (mv aside, then
    git show HEAD:path).
  3. Incident Log table: each new incident appends a row in the same
    commit that fixes it, so future agents can see the warnings are
    tied to real failures rather than abstract caution.
  4. Top-of-file note telling readers the warning blocks document real
    losses.

The two existing rules already in AGENTS.md (the git stash warning
block and the "save with git diff > backup.patch" guidance under
"How to Check Regressions") are preserved verbatim.

Test plan

  • make passes locally (BUILD SUCCESSFUL, parallel unit tests green)
  • Documentation-only change; no runtime impact

Generated with Devin

…dirty trees

Adds two big warning blocks (peer to the existing `git stash` one) and a
short Incident Log so the rules are tied to a real, recent failure.

Motivated by a 2026-04-28 incident: an agent ran
`git checkout dev/cpan-reports/` on an unstaged cpan-tester refresh and
silently destroyed ~600 module results. AGENTS.md already warned about
`git stash` but said nothing about `checkout <path>` / `restore` /
`reset --hard` / `clean`, which are equally destructive on a dirty tree.

Changes:
- New "MANDATORY PRE-FLIGHT FOR ANY DIRTY TREE" block with the exact
  snapshot + WIP-branch commands to run first.
- New "FORBIDDEN COMMANDS ON A DIRTY TREE" block enumerating the
  destructive verbs and the safe alternative.
- New "Incident Log" table; future incidents append here.
- Top-of-file note telling readers the warnings document real losses,
  not hypothetical ones.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@fglock fglock merged commit e3750ee into master Apr 28, 2026
2 checks passed
@fglock fglock deleted the docs/agents-md-dirty-tree-rules branch April 28, 2026 10:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant