docs: the line is the push (improvise-79h5)

The user settled the second half of improvise-79h5: "I don't mind
amending on a branch that hasn't been pushed, but don't do anything that
requires a force push". Rule 8, AGENTS.md's top line, "Commit early",
cloud-agents and the code-review summary now say so. Unpushed commits may
be tidied but never moved onto another base; nothing pushed is rewritten.

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:07:34 -07:00
parent 46e8792aca
commit 1fb1bd00c4
4 changed files with 25 additions and 14 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 (no rebase, squash or force-push) |
| `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/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
+16 -8
View File
@@ -44,12 +44,19 @@ not in a second copy.
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. What it forbids is rewriting history:
- never `git rebase`;
- never squash, in any form: `git reset --soft`, `git merge --squash`, a
`rebase -i` fixup;
- never `git reset` to drop commits;
- never amend a commit you have pushed, and never force-push.
WIP 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.
- **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.
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
@@ -83,8 +90,9 @@ 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. Do not tidy the WIPs into one before the PR: squashing is
forbidden (rule 8), and the WIPs are the history.
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).
## Gates
+5 -3
View File
@@ -6,9 +6,11 @@
from logic
- @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. Never rebase or squash, never `reset` away commits, and never
amend or force-push a pushed commit: the merge structure of git history is a causal record (the user,
2026-09-25). The rule and its incidents are `.agents/skills/wave/agent-rules.md`, rule 8.
- 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
`.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
every session, and query it as you work. **Reading only** — the MCP must never write `kb.pl`.
+3 -2
View File
@@ -137,7 +137,8 @@ environment, where egress leaves through your own network boundary.
- A merged PR cannot carry follow-up work: restart from the latest default
branch and open a new PR.
- Reconcile diverging history only by merge, including when bringing the
default branch into a working branch. Never rebase, squash, amend a
pushed commit or force-push (`.agents/skills/wave/agent-rules.md`, rule 8).
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).
- Keep `context/repo-map.md` and `context/design-principles.md` current —
they are the two docs agents are expected to maintain by hand.