From b07b1e26665e1f239c5490358dc1789a8f0fdeca Mon Sep 17 00:00:00 2001
From: Yisroel Baum <yisroel.d.baum@gmail.com>
Date: Sat, 2 May 2026 22:14:54 +0300
Subject: [PATCH] add session start protocol and pre-commit checklist

AGENTS.md gains a non-negotiable session start protocol that
forces reading the context files and checking the current
branch before any edits. shared.md gains a pre-commit
checklist covering branch/scope, code rules, mechanical
checks, and commit metadata. both additions exist because
this branch's history shows what happens when the rules are
treated as background information rather than active
checklists.
---
 AGENTS.md    | 18 ++++++++++++++++++
 ai/shared.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5dea88b..73e2226 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,3 +5,21 @@ Read these on every session. Rules in them override defaults.
 @ai/shared.md
 @ai/backend-context.md
 @ai/frontend-context.md
+
+## Session start protocol
+
+Before responding to the first user message in a session, you MUST:
+
+1. Read `ai/shared.md`, `ai/backend-context.md`, `ai/frontend-context.md` in
+   full. Do not skim. Do not skip on the assumption they were read in a
+   prior session - context is not preserved.
+2. Run `git status` and `git branch --show-current`. If on `master` or
+   `main`, do NOT make any edits until a feature branch exists, even if
+   the user's first message looks like a quick read-only question. Many
+   "quick questions" turn into edits.
+3. Confirm in your first response that the rules were read and the branch
+   was checked. Do not narrate the contents - just acknowledge.
+
+Skipping this protocol caused real bugs and rework in past sessions
+(work landed on master, TDD order was lost, formatter not run, banned
+constructs slipped in). Treat the protocol as non-negotiable.
diff --git a/ai/shared.md b/ai/shared.md
index cc85dd1..fb37c12 100644
--- a/ai/shared.md
+++ b/ai/shared.md
@@ -72,3 +72,39 @@ guides (`backend-context.md`, `frontend-context.md`) extend these.
 - NEVER work directly on master/main - always create and work on a branch
 
 Do not push anything. Make commits as you go.
+
+## Pre-commit checklist
+
+Before EVERY commit (no exceptions), verify each item. Treat this as
+mechanical, not aspirational - a "yes" to all is required.
+
+**Branch + scope:**
+- [ ] On a feature branch (not master/main).
+- [ ] This commit is one logical change. If it spans unrelated changes,
+      stop and split it.
+- [ ] Tests for new behavior were committed BEFORE this implementation
+      (or this commit IS the failing-test commit).
+
+**Code rules** (see `backend-context.md` PHP rules,
+`frontend-context.md` JS rules):
+- [ ] No arrow functions (`fn () =>`).
+- [ ] No inline FQCNs in type hints, return types, or `::class`
+      references (`\App\Foo\Bar` -> hoist to `use App\Foo\Bar;`).
+- [ ] No default parameter values on methods/functions/constructors.
+- [ ] Find/lookup repository methods return new instances, not stored
+      references.
+- [ ] No em dashes (use hyphens).
+- [ ] Variable names are explicit (no `$t`, `$n`, `$res`, etc.).
+
+**Mechanical checks:**
+- [ ] `php-cs-fixer fix --config=.php-cs-fixer.dist.php <touched dirs>`
+      run, output reports 0 fixes (or any fixes are committed).
+- [ ] `./vendor/bin/phpunit tests` is green.
+
+**Commit metadata:**
+- [ ] Subject is lowercase, imperative, 3-6 words.
+- [ ] No claude/AI coauthor lines.
+- [ ] Body present iff the subject alone cannot convey the change.
+
+If any item fails, fix it before committing - do not bundle the fix
+into a future commit.