Commit Hygiene — Full Policy

When to use

Load this skill whenever you are about to:

• Create or amend a git commit message
• Generate PR title/description from commits
• Generate release notes or changelog entries
• Validate that an existing commit message is clean

---

1. Hard Rules

1.1 No Co-authorship Trailers

NEVER include any trailer that credits a tool, assistant, or AI system:

# Forbidden:
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: GitHub Copilot <copilot@github.com>
Co-authors: [any name]
Assisted-by: [any name]
Generated-by: [any name]

This applies even when the AI contribution was significant. The commit represents the
engineering team's decision to ship the change — not the tool used to draft it.

1.2 No AI Tool Mentions

Never mention AI tools, AI models, or AI frameworks in commit subjects, bodies,
PR titles, PR descriptions, or changelogs — unless the commit is literally implementing
integration with that tool (e.g., adding an OpenAI SDK integration to the product itself).

---

2. Matching Algorithm — Word-Boundary Rule (Critical)

All term checks MUST use whole-word matching (word boundary: \b).

2.1 Why This Matters

Substring matching produces false positives on legitimate technical vocabulary:

Legitimate word	Contains	Substring match (WRONG)	Word-boundary match (CORRECT)
domain	ai	❌ FAIL	✅ PASS
email	ai	❌ FAIL	✅ PASS
detail	ai	❌ FAIL	✅ PASS
maintain	ai	❌ FAIL	✅ PASS
cursor (DB)	cursor	❌ FAIL	✅ PASS
agent (pool)	agent	❌ FAIL	✅ PASS

Flagging domain because it contains ai is a hard bug. Never implement
AI-mention detection as a case-insensitive contains("ai") check.

2.2 Correct Regex Patterns

# Case-insensitive whole-word match for "AI" (the acronym):
\bAI\b             → matches: "AI", "an AI", "AI-assisted"
                   → does NOT match: domain, email, detail, maintain

# Exact product name matches (case-sensitive):
\bHSEOS\b
\bClaude\b
\bGemini\b
\bCodex\b
\bCopilot\b
\bChatGPT\b
\bOpenAI\b
\bAnthropic\b
\bLLM\b

# Phrases (exact, case-insensitive):
\bAI-assisted\b
\bgenerated by AI\b
\bassisted by AI\b
\bprompt engineering\b

# Co-authorship trailers (line-level):
^Co-authored-by:
^Co-authors:
^Assisted-by:
^Generated-by:

2.3 Ambiguous Terms — Context Judgment Required

These terms are common in legitimate technical contexts and must NOT be auto-blocked:

Term	Legitimate uses (PASS)	AI-tool reference (FAIL)
agent	"CI agent", "user-agent", "agent pool", "monitoring agent"	"Claude agent", "AI agent", "prompt agent"
prompt	"user prompt", "CLI prompt", "prompt for input"	"LLM prompt", "system prompt for AI"
cursor	"database cursor", "cursor position", "cursor movement"	"Cursor IDE", "built with Cursor"

When ambiguous: read the full sentence. If the technical meaning is clear → PASS.

---

3. Blocked Term Reference Table

Term	Match type	Always blocked	Exceptions
AI	\bAI\b case-insensitive	Yes	Words containing "ai" as substring
HSEOS	\bHSEOS\b	Yes	—
Claude	\bClaude\b	Yes	Product named Claude unrelated to Anthropic's AI
Gemini	\bGemini\b	Yes	Gemini zodiac sign (edge case, allow in clear context)
Codex	\bCodex\b	Yes	Legal/historical "codex" (edge case, allow)
Copilot	\bCopilot\b	Yes	—
ChatGPT	\bChatGPT\b	Yes	—
OpenAI	\bOpenAI\b	Yes	Integrating OpenAI API (product feature)
Anthropic	\bAnthropic\b	Yes	—
LLM	\bLLM\b	Yes	—
Co-authored-by	line prefix	Yes	—
AI-assisted	phrase	Yes	—
generated by AI	phrase	Yes	—
agent	contextual	No (context required)	CI agent, user-agent, agent pool
prompt	contextual	No (context required)	CLI prompt, user prompt
cursor	contextual	No (context required)	DB cursor, UI cursor

---

4. Commit Message Format

<type>(<scope>): <imperative summary>

[optional body: what changed and why]

[optional footer: ticket refs, e.g., Closes #123]

Types: feat, fix, refactor, test, docs, chore, perf, ci, build, revert

Rules:

• Subject: max 72 characters
• Subject: imperative mood ("add", not "added" or "adds")
• Body: explains the why, not the how
• Body: does NOT describe the tool or process used
• No trailing period on subject line

---

5. Self-Check Before Commit

[ ] No Co-authored-by or similar trailers
[ ] No AI product names (whole-word, not substring)
[ ] "AI" matched as whole word only — "domain" and "email" are NOT violations
[ ] Ambiguous terms (agent, prompt, cursor) verified by context
[ ] Message describes the change + rationale, not the process
[ ] Format: <type>(<scope>): <summary>

---

6. Remediation

If a forbidden term is present:

1. Identify the specific term that triggered the rule
2. Verify it is a true violation (whole-word match, not substring)
3. Rewrite the message: remove AI/tool attribution, preserve only the technical change summary
4. Do not add any explanation that reveals the original message contained AI attribution

Examples

# FAIL — mentions tool
feat(auth): implement JWT validation as suggested by Claude

# PASS — fixed
feat(auth): implement JWT validation using HS256 with 15-minute expiry

# FAIL — co-authorship trailer
fix(domain): resolve aggregate boundary violation

Co-authored-by: Claude Sonnet <noreply@anthropic.com>

# PASS — fixed (trailer removed, message unchanged)
fix(domain): resolve aggregate boundary violation

# FALSE POSITIVE — "domain" contains "ai" but is NOT a violation
fix(domain): resolve aggregate boundary violation
#           ^^^^^^ PASS — "domain" is a legitimate technical term

---

7. Scope — Where This Rule Applies

This rule applies to ALL of the following:

• Git commit messages (subject + body + trailers)
• Pull request titles
• Pull request descriptions
• Changelog entries
• Release notes
• Any artifact committed to the repository

Exception: Documentation about AI tooling governance (like this file itself) may
reference AI terms in a descriptive, non-attributive context.

Quick Mode

For low-context activation, load .enterprise/governance/agent-skills/commit-hygiene/SKILL-QUICK.md or QUICK.md first. Load this full skill for deep analysis, violation fixing, or formal review gates.