adlee-was-taken 7f73a00c78 feat(scripts): preflight gate, plus the git rules that would have caught it ...

A run on 2026-09-10 burned most of a session on three failures, all
mechanical and all preventable by one check at the start.

The expensive one was not the wrong branch. An executor stashed its own
partial work with a descriptive message, came back to a clean tree,
concluded "subagent edits are not persisting", and re-fired subagents
twice against that theory. The work was in stash@{0} the whole time.

So preflight.sh prints the stash stack UNCONDITIONALLY and first, pass or
fail. An agent that sees the stack cannot invent the tooling theory. The
checks are ordered by how much time each failure actually cost, not by
severity:

  0. stash stack, always printed
  1. not the shared primary checkout (git-dir vs git-common-dir)
  2. on a branch that contains origin/<base>
  3. clean working tree
  4. not behind origin/<base>

Check 2 is deliberately not "must equal main". A feature branch cut from
an up-to-date base is fine; what caused the incident was a LEFTOVER
branch from a merged PR (docs/admin-screenshots), which fails the
ancestor test while a fresh feature branch passes. Verified against the
real commit: `git merge-base --is-ancestor origin/main 5b7ae6d` fails.

AGENTS.md gains the rules the incident earned, the first of which is the
one that matters:

  - If the tree looks unexpectedly clean, run `git stash list` BEFORE
    concluding anything about your tooling.
  - Never bare `git stash` / `pop`. ~20 worktrees on this machine share
    ONE stack; another session pushing an entry shifts every index, and
    pop deletes on success, so a wrong index is unrecoverable.
  - Work in a worktree, not the shared checkout the operator is using.
  - The plan is the contract. If an approved item looks wrong, STOP and
    say so rather than implementing the alternative -- the same run
    re-derived a design that had been explicitly reviewed and rejected,
    because the rejected version sounded more reasonable in isolation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VRQXz5SYZYVWscxS1QqF6U

2026-09-09 22:34:05 -04:00

4.2 KiB

Executable File

Raw Permalink Blame History

View Raw