validate-commit.sh: GDD section check uses a list of 8 that disagrees with the GDD template and /design-system, and now warns into the conversation
## What happens At `workflow=full`, `.claude/hooks/validate-commit.sh` warns on any staged `design/gdd/*.md` missing one of these eight substrings: ``` Overview|Player Fantasy|Detailed|Formulas|Edge Cases|Dependencies|Tuning Knobs|Acceptance Criteria ``` In v1.1.2 those warnings go out through `hook_warn` as JSON (`systemMessage` + `additionalContext`), so both the user and the model see them. Before that they went to stderr, where hardly anyone saw them. That makes the three problems below visible on ordinary commits. ## Three inconsistencies (checked against tag `v1.1.2`) 1. **The hook's list is not the template's list.** `.claude/docs/templates/game-design-document.md` has 14 `## ` sections. `/design-system` says `## Summary` "is required at every tier and is not one of the 8". It also makes Visual/Audio and Game Feel REQUIRED for `Gameplay`/`UI` systems, and Cross-References REQUIRED whenever Dependencies names another GDD. So a `Gameplay` GDD at `full` has more required sections than the hook checks. The hook never checks for `Summary`, although several skills grep for `## Summary`. 2. **Every file under `design/gdd/` is treated as a system GDD.** `systems-index.md` (and a game-concept doc, if it lives there) is not a system GDD, and it gets missing-section warnings on every commit that touches it. In our project that is about 1 design commit in 4, because the index changes whenever a system's status changes. 3. **Matching is a substring anywhere in the file**, as the comment in the hook itself says. A GDD that mentions "edge cases" in prose passes, and a heading check would behave differently. This is documented, but it means the check can neither prove that a section exists nor that it is missing. ## Why it matters `/design-review` already judges GDD structure, with the full rules (tiers, categories, conditional sections). The hook is a second copy of the rule. It is incomplete, and it now speaks into the model's context. False "missing section" warnings cost context, and they can lead an agent to "fix" a document that is fine. ## Possible directions (maintainer's call) - **A.** Drop the structure check from the hook and leave it to `/design-review`, the single source of truth. (This is what we did locally: `full) REQUIRED=""`.) - **B.** Keep it, but derive the list from the same place `/design-system` and the template use, check headings (`^## `) rather than substrings, and skip non-system files such as `systems-index.md`. - **C.** At least exclude `systems-index.md`, and give projects a documented way to opt out (for example a `modes` key) without editing a Safe-to-Overwrite hook. Happy to open a PR for whichever direction you prefer.
