Merge pull request #306 from fiddlerwoaroof/wave/1xfb-2-conventional-commits

docs(agents): default to a new conventional commit; amend only an unpushed HEAD (improvise-1xfb.2)

.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

.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 <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." [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
 

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

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.