From 1fb1bd00c4ce37b8c7eec614317707d57d1f8cd9 Mon Sep 17 00:00:00 2001 From: Edward Langley Date: Thu, 24 Sep 2026 19:07:34 -0700 Subject: [PATCH] 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) Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze --- .agents/skills/code-review/SKILL.md | 2 +- .agents/skills/wave/agent-rules.md | 24 ++++++++++++++++-------- AGENTS.md | 8 +++++--- context/cloud-agents.md | 5 +++-- 4 files changed, 25 insertions(+), 14 deletions(-) diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 7f626cc0..6def7a5d 100644 --- a/.agents/skills/code-review/SKILL.md +++ b/.agents/skills/code-review/SKILL.md @@ -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 diff --git a/.agents/skills/wave/agent-rules.md b/.agents/skills/wave/agent-rules.md index f223e38e..3e42463f 100644 --- a/.agents/skills/wave/agent-rules.md +++ b/.agents/skills/wave/agent-rules.md @@ -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 `. 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 diff --git a/AGENTS.md b/AGENTS.md index 6e6a83c1..f27c2cde 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`. diff --git a/context/cloud-agents.md b/context/cloud-agents.md index a1830400..77110e32 100644 --- a/context/cloud-agents.md +++ b/context/cloud-agents.md @@ -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.