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
+4 -3
View File
@@ -7,9 +7,10 @@
- @context/repo-map.md is your "road map" for the repository. use it to reduce exploration and keep it updated.
- @context/design-principles.md is also important for keeping the repository consistent.
- reconcile diverging history only by merge: the merge structure of git history is a causal record (the
user, 2026-09-25). The line is the push: "I don't mind amending on a branch that hasn't been pushed, but
don't do anything that requires a force push" (the user). So never rebase onto main, and never rebase,
squash, amend or `reset` away a pushed commit. The rule and its incidents are
user, 2026-09-25). "As a general rule, you shuold just add a new conventional commit. Small adjustments
can ammend HEAD, but when in doubt don't." (the user). So the default is a new Conventional Commit. Amend
only an unpushed HEAD, and only for a small fix. Never reorder, fold, squash or rebase commits, and never
force-push. The rule, the message convention and the incidents are
`.agents/skills/wave/agent-rules.md`, rule 8.
- always start responses with bananaS!
- there is a prolog MCP available: load a session from `kb` at the root of the repository at the beginning of
+3 -2
View File
@@ -138,7 +138,8 @@ environment, where egress leaves through your own network boundary.
branch and open a new PR.
- Reconcile diverging history only by merge, including when bringing the
default branch into a working branch. Never rebase onto main, and never do
anything that needs a force push: unpushed commits may be amended, pushed
ones may not (`.agents/skills/wave/agent-rules.md`, rule 8).
anything that needs a force push. Add a new Conventional Commit by default.
Only an unpushed HEAD may be amended, and only for a small fix. Never
reorder or fold commits (`.agents/skills/wave/agent-rules.md`, rule 8).
- Keep `context/repo-map.md` and `context/design-principles.md` current —
they are the two docs agents are expected to maintain by hand.