fix(hooks): block amend of pushed commits and non-fast-forward pushes

Add defense-in-depth against rewriting published history:

1. prepare-commit-msg hook: blocks --amend when HEAD is reachable
   from any remote tracking branch. Detects amend via $2="commit"
   $3="HEAD" (--no-edit path). Errs on the side of safety for
   the indistinguishable -c HEAD/-C HEAD edge case.
2. pre-push hook: hard-blocks non-fast-forward pushes as a safety
   net for cases the prepare-commit-msg hook can't catch (e.g.
   --amend -m, where -m masks amend detection).
3. Agent prompt: adds git safety rules — never amend pushed
   commits, use single -m with embedded newlines, retry without
   --amend if a hook rejects the commit.
4. conventional-commits skill: documents the single -m pattern.
5. Shell tests: prepare-commit-msg_test.sh (5 cases) and updated
   install-hooks_test.sh for the new hook.

Plan-by: glm-5.2
Acked-by: deepseek-v4-pro
Signed-off-by: kyau <git@kyaulabs.com>

Author: kyau

.github/hooks/pre-push

@@ -3,27 +3,52 @@
 
 set -euo pipefail
 
+RED=$'\033[1;31m'
 YELLOW=$'\033[1;33m'
 ORANGE=$'\033[38;5;208m'
 DIM=$'\033[2m'
 BOLD=$'\033[1m'
 CYAN=$'\033[36m'
 RESET=$'\033[0m'
 
-# ── No-squash check ──────────────────────────────────────────────────────────
-# Warn if pushing a single-commit branch that looks like a squash.
-# This is a soft gate — the push proceeds, but the warning is prominent.
-# The git history serves as the development and evaluation log; squashing
-# destroys the record of what was tried and abandoned.
-
-while read -r _local_ref local_oid _remote_ref remote_oid; do
+while read -r local_ref local_oid _ remote_oid; do
 	# Skip tag pushes and branch deletions
 	if [ -z "$local_oid" ] || [ "$local_oid" = "0000000000000000000000000000000000000000" ]; then
 		continue
 	fi
 
-	# Compute the range: commits not yet on the remote
-	range=""
+	# ── Non-fast-forward check (hard gate) ─────────────────────────────────
+	# Block pushes that would rewrite published history. amend, rebase, or
+	# reset on a pushed commit triggers this — fix local history before pushing.
+	if [ -n "$remote_oid" ] && [ "$remote_oid" != "0000000000000000000000000000000000000000" ]; then
+		# git merge-base exits 0 if remote_oid is an ancestor of local_oid
+		# (fast-forward). We run it inside an if to avoid triggering set -e.
+		set +e
+		git merge-base --is-ancestor "$remote_oid" "$local_oid" 2>/dev/null
+		ancestor_rc=$?
+		set -e
+		if [ "$ancestor_rc" -ne 0 ]; then
+			branch_name="${local_ref#refs/heads/}"
+			cat >&2 <<EOF
+
+${RED}╭─  BLOCKED  Non-fast-forward push to ${branch_name}${RESET}
+${RED}│${RESET}
+${RED}│${RESET}   Rewriting published history is prohibited.${RESET}
+${RED}│${RESET}   The remote has commits that would be overwritten.${RESET}
+${RED}│${RESET}
+${RED}│${RESET}   This can happen if a pushed commit was amended, rebased,${RESET}
+${RED}│${RESET}   or reset. Fix your local history before pushing.${RESET}
+${RED}│${RESET}
+${RED}╰──────────────────────────────────────────────────────────────────╯${RESET}
+
+EOF
+			exit 1
+		fi
+	fi
+
+	# ── No-squash check (soft gate) ───────────────────────────────────────
+	# Warn if pushing a single-commit branch that looks like a squash.
+	# The push proceeds, but the warning is prominent.
 	if [ -n "$remote_oid" ] && [ "$remote_oid" != "0000000000000000000000000000000000000000" ]; then
 		range="${remote_oid}..${local_oid}"
 	else

.github/hooks/prepare-commit-msg

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# $KYAULabs: prepare-commit-msg kyau@nova 2026/07/07 -0700 Exp $
+
+set -euo pipefail
+
+COMMIT_SOURCE="${2:-}"
+COMMIT_SHA="${3:-}"
+
+# Block --amend of pushed commits.
+#
+# Git passes $2 = "commit" and $3 = "HEAD" (literal) for --amend without
+# -m. However, -c HEAD and -C HEAD also pass $3 = "HEAD" — indistinguishable
+# from --amend here. The hook errs on the side of safety and blocks both when
+# HEAD is pushed. Workaround: use -c <sha> / -C <sha> with an explicit SHA.
+#
+# When -m is used with --amend, $2 is "message" — indistinguishable from a
+# regular commit in this hook. The pre-push hook's non-fast-forward block
+# is the safety net for that case.
+if [ "$COMMIT_SOURCE" = "commit" ] && [ "$COMMIT_SHA" = "HEAD" ]; then
+	# Check if the commit being amended has been pushed to any remote
+	if git branch -r --contains HEAD 2>/dev/null | grep -q .; then
+		cat >&2 <<EOF
+✗ Cannot amend a commit that has been pushed to a remote.
+  HEAD is reachable from a remote tracking branch.
+  Use a regular commit ('git commit', not '--amend') to add changes.
+  If you need to fix the commit message for an unpushed commit, amend
+  is safe — but this commit has already been published.
+EOF
+		exit 1
+	fi
+fi
+
+exit 0
+
+# vim: ft=sh sts=4 sw=4 ts=4 et :

.opencode/skills/conventional-commits/SKILL.md

@@ -122,3 +122,22 @@ The hook blocks the commit if the format is invalid.
 Config: `commitlint.config.js` extends `@commitlint/config-conventional`,
 with a custom `type-enum` that adds `build`, `patch`, and `ignore` to the
 standard set.
+
+## Passing the Message to Git
+
+> [!IMPORTANT]
+> Pass the full commit message as a **single `-m`** argument with embedded
+> newlines. Do **not** use multiple `-m` flags — git inserts blank lines
+> between them, which breaks commitlint's trailer detection (`git interpret-trailers --parse` requires that trailers be contiguous with the body).
+
+```bash
+# CORRECT — single -m with $'...\n...' embedded newlines
+git commit -S -m $'type[scope]: subject\n\nBody paragraph.\n\nPlan-by: model\nAcked-by: model\nSigned-off-by: user <email>'
+
+# WRONG — multiple -m flags insert blank lines between each, breaking trailers
+git commit -S -m "type[scope]: subject" -m "Body." -m "Plan-by: model" -m "Acked-by: model"
+```
+
+If the commit fails due to the commit-msg hook, the commit was **not created**.
+Retry with `git commit` (not `--amend`), fixing the message format. There is
+nothing to amend because the commit was never made.

opencode.json

@@ -19,7 +19,7 @@
           "git push *": "deny"
         }
       },
-      "prompt": "You are the primary build agent for a KYAULabs PHP project.\n\nStack: PHP 8.5+ (no MVC, no router), MariaDB, nginx, SCSS + vanilla JS, Pest v4.\n\n`AGENTS.md` (loaded every session) is the authoritative source for stack, boundaries, directory structure, hard boundaries, indentation, and the skills/agents/commands available. Do not restate those rules to the user — just enforce them.\n\nEnforcement posture (these are the triggers you actively gate on):\n- Any new feature or bug fix requiring tests → invoke the @tdd agent (Red → Green → Refactor, vertical slices).\n- Before creating or modifying any source file → load the rcs-header skill (RCS header + vim modeline on every file).\n- Before domain-coupled work → read CONTEXT.md; if missing, suggest /prime. Update it when domain terms or entities change.\n- Non-trivial or cross-cutting change → suggest an @architect review before implementing; write an ADR when a decision is hard to reverse.\n- Frontend visual work → load the frontend-design skill first.\n- Auth, session, SQL, or user-input handling → load the security-coding skill first.\n- Follow the full pipeline when applicable: brainstorming → prototype (if needed) → writing-plans → executing-plans → @tdd → verification-before-completion → /check → @code-review. See AGENTS.md for the complete flow.\n- Context management → if the session is approaching degradation (long conversation, many file reads), load .opencode/docs/context-management.md and follow its guidance (compact with a hint, use subagents, or /handoff and start fresh)."
+      "prompt": "You are the primary build agent for a KYAULabs PHP project.\n\nStack: PHP 8.5+ (no MVC, no router), MariaDB, nginx, SCSS + vanilla JS, Pest v4.\n\n`AGENTS.md` (loaded every session) is the authoritative source for stack, boundaries, directory structure, hard boundaries, indentation, and the skills/agents/commands available. Do not restate those rules to the user — just enforce them.\n\nEnforcement posture (these are the triggers you actively gate on):\n- Any new feature or bug fix requiring tests → invoke the @tdd agent (Red → Green → Refactor, vertical slices).\n- Before creating or modifying any source file → load the rcs-header skill (RCS header + vim modeline on every file).\n- Before domain-coupled work → read CONTEXT.md; if missing, suggest /prime. Update it when domain terms or entities change.\n- Non-trivial or cross-cutting change → suggest an @architect review before implementing; write an ADR when a decision is hard to reverse.\n- Frontend visual work → load the frontend-design skill first.\n- Auth, session, SQL, or user-input handling → load the security-coding skill first.\n- Follow the full pipeline when applicable: brainstorming → prototype (if needed) → writing-plans → executing-plans → @tdd → verification-before-completion → /check → @code-review. See AGENTS.md for the complete flow.\n- Context management → if the session is approaching degradation (long conversation, many file reads), load .opencode/docs/context-management.md and follow its guidance (compact with a hint, use subagents, or /handoff and start fresh).\n- Git safety → never amend a pushed commit (check: `git branch -r --contains HEAD`). Never use multiple `-m` flags — pass the full message as a single `-m` with `$'...\n...'` embedded newlines (multiple `-m` insert blank lines that break commitlint's trailer detection). If a commit fails due to a hook, retry with `git commit` (not `--amend`) — the commit was never created, so there is nothing to amend."
     },
     "plan": {
       "mode": "primary",

tests/Shell/install-hooks_test.sh

@@ -89,7 +89,7 @@ rm -rf "$T1"
 # ── Test 2: All hooks committed as 100755 ─────────────────────────────────────
 
 echo "── Test 2: Hooks committed as 100755 ──"
-for hook in commit-msg post-checkout post-merge pre-commit pre-push; do
+for hook in commit-msg post-checkout post-merge pre-commit pre-push prepare-commit-msg; do
 	mode=$(git -C "$REPO_ROOT" ls-files -s ".github/hooks/$hook" 2>/dev/null | awk '{print $1}')
 	if [ "$mode" = "100755" ]; then
 		pass "$hook is 100755"