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:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user