docs: default to a new conventional commit; amend only an unpushed HEAD (improvise-1xfb.2)

Narrows what #305 allowed to the user's ruling: reordering, folding and
tidying WIPs are out, and commit messages follow Conventional Commits with
the ticket id at the end of the subject.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
This commit is contained in:
Edward Langley
2026-09-24 19:21:15 -07:00
parent 6427312da2
commit d1b3258aeb
4 changed files with 36 additions and 18 deletions
+1 -1
View File
@@ -27,7 +27,7 @@ them here would let the copy drift:
| `context/design-principles.md` | The "why" — functional-first, polymorphism over conditionals, correctness by construction, layering, §7 testing doctrine |
| `context/repo-map.md` | The "where", plus **numbered gotchas** — read the ones your diff touches |
| `prolog-sessions/kb.pl` | Executable knowledge: `invariant/2`, `doctrine/2`, `forbidden/2`, `decision/3`, and prior `work_done/3` |
| `AGENTS.md` | Working rules: bug-first tests, `Option`/`Result`/`Box` at the edges, history reconciled only by merge, and nothing that needs a force push |
| `AGENTS.md` | Working rules: bug-first tests, `Option`/`Result`/`Box` at the edges, history reconciled only by merge, a new conventional commit by default (amend only an unpushed HEAD, for a small fix), and nothing that needs a force push |
| `.agents/skills/wave/agent-rules.md`, "GitHub" | The reviewer's rule: what to read before your first comment, how to answer each existing review, and what every review you post must state. Read it before reviewing a PR |
`kb.pl` is the highest-value and least-obvious of these. Grep it before
+28 -12
View File
@@ -43,21 +43,36 @@ not in a second copy.
check before a PR is such a time.
8. **Reconcile diverging history only by merge.** To take a newer main,
re-pin on purpose first (rule 7): `git fetch gh`, then `git rev-parse
gh/main`. Then run `git merge <new SHA>`. Merge commits and plain
WIP commits are what the rule wants.
gh/main`. Then run `git merge <new SHA>`. Merge commits and new
commits are what the rule wants.
**The line is the push.** The user: "I don't mind amending on a branch
that hasn't been pushed, but don't do anything that requires a force push"
(2026-09-25; improvise-79h5).
- **Before your first push**, you may amend, reorder or fold your own
commits. You may never move them onto another base: no `git rebase` onto
main and no `git reset --soft gh/main`. Both incidents below were exactly
that, on commits that had not been pushed.
**The default is a new commit.** The user: "As a general rule, you shuold
just add a new conventional commit. Small adjustments can ammend HEAD, but
when in doubt don't." (2026-09-25; improvise-1xfb.2). That narrows an
earlier ruling: "I don't mind amending on a branch that hasn't been pushed,
but don't do anything that requires a force push" (2026-09-25;
improvise-79h5).
- **Amend only HEAD, only for a small adjustment, and only while HEAD is
unpushed.** A typo, a file left out of the commit you just made, a
formatter's fix to it. When in doubt, add a new commit.
- **Never reorder, fold or squash commits, pushed or not**, and never move
them onto another base: no `git rebase` onto main and no `git reset
--soft gh/main`. Both incidents below were exactly that, on commits that
had not been pushed.
- **Once a commit is pushed**, nothing may rewrite it: no rebase, squash
(`git reset --soft`, `git merge --squash`, a `rebase -i` fixup), amend or
`git reset` that drops it. Anything that would need a force push is
forbidden, and so is the force push itself.
**Messages are Conventional Commits**: `type(scope): subject`, with the
scope optional. The types in use are `feat`, `fix`, `test`, `docs`, `ci`
and `chore`. A ticket id goes at the end of the subject in parentheses, as
the history already carries it: `fix(tui): the grid and the tile bar scroll
by the width they are drawn in (improvise-gtn7.1)`. A merge commit keeps
the message git writes for it. The message says what changed. The argument
for the change lives in `context/`, never only in the message
(`context/design-principles.md` §6).
The user's reason: "the merge structure of git history is a causal record"
(2026-09-25; improvise-1xfb.1). A merge keeps that record, and a rewrite
replaces it with a story. The rewrite is also where the damage comes from.
@@ -90,9 +105,10 @@ Commit a WIP as soon as your first test run is green, and again after every
meaningful step. Push your branch (rule 4) once it is worth keeping. An agent
finished a whole ticket with every gate green and lost all of it, uncommitted,
when its worktree was deleted in a disk cleanup. A local commit survives a
deleted worktree. You may tidy your WIPs before your first push. After it,
they are history and stay as they are, because rewriting a pushed commit would
need a force push (rule 8).
deleted worktree. Make each step its own conventional commit, and leave it
that way: steps are not reordered or folded together afterwards. A small fix
to the step you just committed may amend it while it is unpushed. Anything
more, or any doubt, is a new commit (rule 8).
## Gates