feat: add commit-docs-reminder hook to enforce checklist before commits

Adds a PreToolUse Bash hook that reminds AI agents to verify
status-update-checklist.md before running git commit. Also adds
the corresponding constraint to RULES.md section 3.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/hooks/commit-docs-reminder.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Remind Claude to check status-update-checklist before committing
+# Event: PreToolUse | Matcher: Bash
+# Exit 0 = allow (non-blocking reminder)
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Only trigger on git commit commands (not git add, git status, etc.)
+if echo "$COMMAND" | grep -qE 'git\s+commit'; then
+  echo "REMINDER: Before committing, verify that .claude/status-update-checklist.md was followed." >&2
+  echo "If this commit changes project status, audit findings, or phase progress," >&2
+  echo "you MUST synchronize: RULES.md, RECOMMENDATIONS.md, README.md, DOCS.md." >&2
+  echo "If this is a code-only change with no status impact, proceed." >&2
+fi
+
+exit 0

.claude/settings.json

@@ -16,6 +16,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/bash-firewall.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/commit-docs-reminder.sh"
           }
         ]
       }

DOCS.md

@@ -5,6 +5,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 ---
 
 ## Documentation Languages
+
 - Technical docs: English (`docs/` and subfolders).
 - Repository summary: `README.md` (English).
   New documents should be added in English unless noted.
@@ -14,6 +15,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 ## Documentation Structure (root: `docs/`)
 
 ### 1) General Project Docs
+
 - `docs/archetypes.md` — product archetypes and optional modules; pick what applies.
 - `docs/project-overview.md` — goals, target users, chosen archetype, key flows (pick relevant), non-functional requirements.
 - `docs/phases-plan.md` — Phase 0–4 plan with tasks across product, frontend, backend, infra, data/LLM.
@@ -21,10 +23,12 @@ Technical index for developers and AI agents. Use this as the entry point to all
 - `docs/dev-setup.md` — local/CI setup once code exists.
 
 ### 1c) Architecture Decision Records (`/docs/adr`)
+
 - `docs/adr/README.md` — how ADRs work.
 - `docs/adr/0000-template.md` — ADR template.
 
 ### 1b) LLM / AI System (`/docs/llm`)
+
 - `docs/llm/prompting.md` — prompt structure, versioning, output schemas.
 - `docs/llm/evals.md` — evaluation strategy, datasets, regression gates.
 - `docs/llm/safety.md` — privacy, injection defenses, `reasoning_trace` policy.
@@ -32,6 +36,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 - `docs/llm/rag-embeddings.md` — RAG/embeddings design and evaluation.
 
 ### 2) Frontend (`/docs/frontend`)
+
 - `docs/frontend/overview.md` — frontend scope and key user journeys (depends on archetype/modules).
 - `docs/frontend/architecture.md` — **canonical, locked frontend decisions** (after Phase 1).
 - `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` — working architecture notes; **archive/delete after Phase 1**.
@@ -39,6 +44,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 - `docs/frontend/seo-performance.md` — performance and SEO recommendations.
 
 ### 3) Backend (`/docs/backend`)
+
 - `docs/backend/overview.md` — backend scope (integrations, AI capability, optional pipelines/approvals/billing).
 - `docs/backend/architecture.md` — **canonical, locked backend decisions** (after Phase 1).
 - `docs/backend/api-design.md` — API resources and conventions (entities, rules, approvals, reports, billing, events).
@@ -46,6 +52,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 - `docs/backend/payment-flow.md` — payment integration (provider-agnostic template; single source of truth for payment flows and webhooks).
 
 ### 4) Examples (`/docs/examples`)
+
 - `docs/examples/RECOMMENDATIONS-example.md` — filled-in example of `RECOMMENDATIONS.md` for a compliance classifier (Archetype C).
 
 ---
@@ -95,6 +102,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 - `.claude/hooks/bash-firewall.sh` — blocks destructive commands (`rm -rf /`, `git reset --hard`, etc.).
 - `.claude/hooks/post-edit-format.sh` — auto-formats files with Prettier after edits.
 - `.claude/hooks/audit-log.sh` — logs all Bash commands with timestamp to `audit.log`.
+- `.claude/hooks/commit-docs-reminder.sh` — reminds to check `status-update-checklist.md` before `git commit`.
 - `.claude/settings.json` — hooks configuration (also: Notification, SessionStart compact context).
 
 ## GitHub Templates (`/.github`)
@@ -107,6 +115,7 @@ Technical index for developers and AI agents. Use this as the entry point to all
 ---
 
 ## How to Use This Index
+
 - **New to the project:** read `project-overview.md` and `phases-plan.md` first.
 - **Designing features:** use frontend/backend architecture docs plus API/security/payment flow specs.
 - **Expanding docs:** add new English `*.md` files under `docs/` and update this index with links.

RULES.md

@@ -31,8 +31,8 @@ conflict.
 4. **Prefer minimal, surgical changes.** Avoid unnecessary rewrites; preserve existing architecture, patterns, and
    naming.
 5. **Respect security and privacy.**
-    - Never include secrets, tokens, or API keys in code or output.
+   - Never include secrets, tokens, or API keys in code or output.
-    - Do not log, echo, or request PII unless the task requires it; minimize exposure.
+   - Do not log, echo, or request PII unless the task requires it; minimize exposure.
 6. **Avoid destructive actions without consent.** Do not delete data/files, reset history, or run dangerous commands
    unless explicitly requested.
 7. **Do not add dependencies lightly.** Introduce new packages/tools only with clear justification and after checking
@@ -61,6 +61,7 @@ conflict.
 2. **Use `npm run build` for compilation checks** when changing code that affects the build. Re‑run after meaningful
    changes.
 3. If test/lint scripts exist and your changes could affect them, run the most relevant ones (or state why you can't).
+4. **Before committing** — if changes affect project status, audit findings, or phase progress, read and follow `.claude/status-update-checklist.md` to synchronize all documentation files in one commit.
 
 ---
 
@@ -68,10 +69,10 @@ conflict.
 
 - Agent profiles live in `agents/` and define role‑specific behavior (metadata + detailed instructions).
 - Before starting a task:
-    1. Scan available profiles in `agents/`.
+  1. Scan available profiles in `agents/`.
-    2. Select the primary agent whose `name/description` best matches the task (frontend, backend, security, testing,
+  2. Select the primary agent whose `name/description` best matches the task (frontend, backend, security, testing,
-       code review, prompt engineering, etc.).
+     code review, prompt engineering, etc.).
-    3. Apply that profile in addition to these core rules.
+  3. Apply that profile in addition to these core rules.
 - If a task spans domains, follow Section 5 for coordination.
 
 ---
@@ -80,10 +81,10 @@ conflict.
 
 1. Identify all relevant domains/agents.
 2. Choose a primary agent based on the main intent:
-    - **Design/architecture** → architect‑type agent.
+   - **Design/architecture** → architect‑type agent.
-    - **Implementation** → domain architect (frontend/backend).
+   - **Implementation** → domain architect (frontend/backend).
-    - **Review/audit** → reviewer/security agent.
+   - **Review/audit** → reviewer/security agent.
-    - **Prompt/workflow** → prompt‑engineer agent.
+   - **Prompt/workflow** → prompt‑engineer agent.
 3. Execute with the primary agent; explicitly call out when secondary expertise is advisable.
 4. If the request mixes distinct phases (e.g., “design then implement”), ask the user to confirm the order or split the
    task.