diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 6def7a5d..7b3d29c3 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, 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 diff --git a/.agents/skills/wave/agent-rules.md b/.agents/skills/wave/agent-rules.md index 3e42463f..d3c437b1 100644 --- a/.agents/skills/wave/agent-rules.md +++ b/.agents/skills/wave/agent-rules.md @@ -43,21 +43,39 @@ 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 `. Merge commits and plain - WIP commits are what the rule wants. + gh/main`. Then run `git merge `. 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." [sic] (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 are Conventional Commits' own: `feat`, `fix`, + `refactor`, `perf`, `style`, `test`, `docs`, `ci` and `chore`. Do not + invent new ones. History also has ad-hoc prefixes (`tooling:`, `context:`, + `clippy:`, `checkers:`); write those as a standard type with a scope + instead, e.g. `chore(tooling):`. A ticket id goes at the end of the subject + in parentheses, as most recent conventional commits carry 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 +108,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 diff --git a/AGENTS.md b/AGENTS.md index 536b3de9..a476b158 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/context/cloud-agents.md b/context/cloud-agents.md index 77110e32..9fb343b4 100644 --- a/context/cloud-agents.md +++ b/context/cloud-agents.md @@ -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.