docs: the nudge-hook pattern, with a worked example, and the approver carve-out cross-reference

[MCKRUZ]

Closes #7. Closes #33.

#7 — the pattern the kit used but never documented

Every hook in kit/hooks/ refuses. This adds the other half: a hook that fires on the same event, returns no decision, and drops a sentence into the agent's context at the moment of action.

The rule it settles is gate vs. nudge. Gate when the rule is absolute and the violation is mechanically provable — build red, receipt missing. Nudge when the judgement belongs to the agent, or when a wrong block would cost more than a missed reminder. Without that middle option, those rules go in CLAUDE.md and get forgotten, which is the argument the README already makes for the gates.

Two corrections to the issue as filed:

• It describes the harvested MAH nudges as PostToolUse. They are PreToolUse, and the difference is load-bearing — a reminder that arrives after the edit is too late to change it.
• The contract is not in the reference. The docs cover additionalContext and cover permissionDecision, but never the case where you omit the decision entirely — which is the whole trick. Given that section is headed "verified — do not 'improve' these", it was probed rather than inferred, and the README records both the result and the date.

The worked example

sensitive-edit-nudge.{ps1,sh} fires when the agent edits an auth, identity, security, migrations, or infra/ path and reminds it the change is risk:high. Installed but not registered — a nudge encodes one team's policy, so the kit ships the mechanism and leaves the rule to the adopter. Registration snippet is in the README.

Two defects found and fixed in it during verification: PowerShell mangled an em dash in the message to a hyphen, and its hashtable emitted JSON keys in arbitrary order (it flipped between runs). The message is ASCII-only now and the JSON is [ordered], both with comments explaining why — the twins have to emit identical bytes or neither can be pinned by a test.

#33 — the sole-approver cross-reference

docs/anti-patterns.md stated the rule as "a hard rule at every team size", the one place it appeared without pointing at the single-maintainer carve-out in docs/team.md. Both statements were true in their own scope — anti-pattern 2 describes delivery pods, where there genuinely is always a second person — and that is exactly why a reader who had seen both could not tell which governed. Now it points. The glossary already did.

Test plan

• Advisory contract probed in a live session: the tool ran and the reminder arrived
• Both twins across nine payloads — sensitive paths, Windows separators, near-miss directories (src/authors/), missing file_path, malformed JSON, empty stdin — byte-identical output, fail-open throughout, exit 0 every time
• Shipped script end-to-end: fired on src/Api/Auth/TokenService.cs, silent on src/Api/Orders/OrderService.cs
• python scripts/check_standard.py — no drift
• pytest scripts/tests — 37 passed
• .sh twin committed mode 755, LF endings, matching the other three

Follow-ups (not in this PR)

• The plugin needs scripts/sync_kit.py re-run so claude-code-sdlc/harness/ picks up the new hook — separate repo, separate PR, being opened alongside this one.
• Gap worth its own issue: nothing verifies the kit's file inventory against the docs that enumerate it. Four lists needed updating by hand here (kit/README.md, two trees in GOLD-STANDARD.md, its HTML twin) and check_standard.py would not have caught a miss — the same class of drift it was built to catch.

Approval

Self-approved under the solo-maintainer carve-out in docs/team.md: internal repo, no second maintainer, mechanical ladder green, named here rather than taken silently.

🤖 Generated with Claude Code

https://claude.ai/code/session_014aesqvsMqJpzEdpDXDTjvF