git:20260816.b22df34 to git:20260816.da968ed

9 added, 8 removed. Audit A to A.

---

name: commit

description: Use before writing any git commit message or reviewing one, and when the user asks for "commit requirements", "commit message guidelines", "/ar:commit", or "/ar:gc". Carries the 17-step pre-commit analysis, the concrete-subject rules that ban vague verbs and session-internal jargon, and the checks that keep a message reviewable from the repository alone.

+ aliases: [gc]

---

# Git Commit Requirements

**Third-party repos**: Use `.git/info/exclude` for local-only ignores (e.g., `notes/`) without modifying `.gitignore`.

**IMPORTANT: Read this entire process (steps 1-17) before starting any git commit work and you must carefully re-analyze the actual for regressions and errors and complete each numbered item and sub-item step-by-step.**

</purpose>

---

## Pre-Git Commit Analysis Process

### 1. Command Execution

- `git status` - see all untracked files

- `git diff --staged` - see exactly what changes will be committed

- `git log -5` - see recent commit messages for style consistency and for context

### 2. Complete Change Analysis

Must analyze **ALL commits and changes** that will be included:

- **Not just latest commit** - analyze entire scope

- Both staged and unstaged changes

- All commits from branch divergence point (for PRs)

- Previously staged work, not just immediate changes

### 3. Mandatory Regression Check

Before writing commit message, review `git diff --staged` to ensure:

- Every claim in commit message has evidence in the actual diff

- No assumptions about previous behavior - only describe what the diff shows changed

- Subject line accurately reflects the files and scope of actual changes

- All described functionality changes match what's visible in the code diff

- **If regressions found**: record a task with the harness's task tool and fix it before writing the message

---

## Pre-Git Commit Structure & Format

### 4. Subject Line Format

- **Few/grouped files**: `<files>: concrete description of what specifically changed`

- - Example: `tsb-launcher.ts,test.ts: enable automatic argument passthrough`

- - Example: `test_*.ts: fix mocking infrastructure for argument parsing` (pattern grouping)

- - Example: `src/security/*.sb: add AI config file access permissions` (directory grouping)

+ - Example: `scoped_allow.py,test_scoped_allow.py: accept day units in scope durations`

+ - Example: `test_install_*.py: pin tree publication under two processes` (pattern grouping)

+ - Example: `plugins/autorun/commands/*.md: run every bash block through uv run --project` (directory grouping)

- **Many files**: `type(scope): concrete description of what specifically changed` (scope can be app name)

- - Example: `fix(TSB): enable CLI argument passthrough by defaulting sandbox to enabled`

+ - Example: `fix(installer): retire a hashless legacy tree under --force after a backup`

- **Mixed**: `type(scope) <files>: concrete description`

- - Example: `fix(TSB) advanced-sandbox-config.ts: enable sandbox-exec by default`

+ - Example: `fix(installer) fs.py: republish a hashless legacy tree after backing it up`

- **Always include**: Concrete and actionable description of what specifically changed

- - **Avoid vague terms**: "improve performance" → "cache API responses in RequestManager.fetch()", "enhance security" → "validate file paths in loadSandboxConfig()", "update system" → "default sandbox to enabled in AdvancedSecurityManager"

+ - **Avoid vague terms**: "improve performance" → "hydrate ThreadSafeDB once per session instead of once per hook", "enhance security" → "reject relative export paths in plan_export before writing", "update system" → "default the cache gate to off in its FeatureToggle"

### 5. Message Structure

- **Summary first**: Concise summary line at top (following format above)

- **Previous behavior**: Describe what existed before (based on actual git diff, not assumptions)

- **What changed**: Specific changes made

- **Why**: Rationale for the changes

- **Specific files**: List affected files and what changed in each

---

## Pre-Git Commit Content Requirements

### 6. Concrete & Actionable

- Use specific, measurable descriptions

- Describe functionality that can be tested/verified

- **AVOID vague terms**: "improved", "enhanced", "HYBRID approach", invented jargon

- **USE concrete action words**: "fix", "add", "remove", "enable", "disable"

- **"update" requires specificity**: Use "update X to Y" or "update X by doing Y" - never just "update"

- Include actionable details about what the code now does

- **Show exact changes**: Before/after comparisons with specific file paths, line numbers

### 7. Technical Specificity

- Name specific functions, classes, methods affected

- Include file paths and what changed in each file

- Describe technical implementation details

- Mention configuration changes, new dependencies, etc.

### 8. Accurate Change Classification

- "add" = wholly new feature

- "update X to Y" or "update X by doing Y" = enhancement to existing feature (must specify what changed)

- "fix" = bug fix

- "refactor" = code restructuring

- Must accurately reflect the nature of changes

---

## Pre-Git Commit Context & Documentation

### 9. Complete Context

- Describe both before/after states

- Explain the problem being solved

- Include enough detail for future developers to understand

- Connect changes to overall system architecture

- Show how changes fit into broader development work

### 10. Repository Consistency

- Follow existing commit message style from `git log`

- Match repository's commit message patterns

- - The subject names what changed (step 4); the body's summary explains why in 1-2 sentences

+ - Focus on "why" rather than "what" (1-2 sentences for summary)

---

## Pre-Git Commit Security & Quality

### 11. Security Check

Explicitly check for and prevent committing:

- Secrets or API keys

- Passwords or tokens

- Any sensitive information

### 12. Testable Outcomes

- Include specific ways to verify changes work

- Mention new functionality that can be tested

- Reference specific commands or use cases enabled

---

## Pre-Git Commit Validation & Quality Control

### 13. Accuracy Validation Checklist

Before committing, verify:

- [ ] Subject format matches `<files>:`, `type(scope):`, or `type(scope) <files>:` convention

- [ ] Every "previous behavior" claim is supported by git diff evidence

- [ ] All "what changed" statements match actual lines in git diff --staged

- [ ] No claims about functionality that isn't visible in the diff

- [ ] Testable outcomes can be verified by running the described commands

- [ ] File paths and line numbers are accurate

- [ ] Technical details (function names, configurations) match the actual code changes

---

## Pre-Git Development Process Exclusions

### 14. Avoid Development Methodology References

- Don't mention Claude or AI assistance in development process

- Don't mention multi-agent development methodology used to create the code

- Don't describe HOW the code was developed by assistants

- Don't describe conversational changes or internal commit development process

- Focus on WHAT was built and WHY (multi-agent systems as software features are fine)

### 15. Avoid Overconfidence & Vague Language

- **Never use vague qualifiers**: "comprehensive", "complete", "thorough", "HYBRID approach"

- **Don't invent terminology**: Avoid made-up technical terms that aren't standard

- **Avoid abstract descriptions**: Use concrete language instead of conceptual descriptions

- **Don't bury the main point**: Put the key change upfront, not buried in paragraphs

- Avoid absolute claims unless verifiable in the diff

- Don't claim to have "fixed all issues" or "improved everything"

- Use specific, measurable language about actual changes made

- **Balance user impact with technical details**: Describe both what broke/was fixed AND the implementation approach used

- Acknowledge limitations and scope of changes when relevant

### 16. Focus on Commit Outcome vs Process

- Describe the **whole commit outcome** compared to the previous commit state

- Avoid describing incremental conversation steps or iterative development

- Present the final state achieved rather than the journey to get there

- Focus on the complete functional change delivered

---

## Pre-Git Commit Hook Handling

### 17. Hook Integration

- If pre-commit hooks modify files during commit, retry commit ONCE

- If commit succeeds but hooks modified files, MUST amend commit

- Never use interactive git commands (`-i` flag)

</requirements>

---

## Common Git Commit Message Pitfalls & Solutions

Based on analysis of problematic commit messages, avoid these common mistakes:

### ❌ Bad Commit Message Patterns

1. **Vague subject lines**: "HYBRID approach", "improve system", "enhance features"

- **Problem**: Meaningless to someone reading git log

- **Solution**: Use concrete actions like "fix authentication", "add config validation"

2. **Invented jargon**: Creating terms like "HYBRID approach" that aren't standard

- **Problem**: Readers can't understand what was actually implemented

- **Solution**: Use established technical terms or explain new concepts clearly

3. **Missing application context**: Subject could apply to any project

- **Problem**: Lost context about which application was changed

- - **Solution**: Put the application in the scope — `fix(TSB) advanced-sandbox-config.ts: ...` — or lead with its files

+ - **Solution**: Name the component in the scope or lead with its files: `fix(installer): ...`, `fs.py,traversal.py: ...`

4. **Buried file impact**: Mentioning files deep in message body

- **Problem**: Hard to understand scope of changes

- **Solution**: List affected files prominently with brief descriptions

5. **Abstract problem descriptions**: Conceptual language instead of concrete issues

- **Problem**: Unclear what the fix actually accomplished

- **Solution**: Describe specific symptoms and measurable outcomes

### ✅ Good Git Commit Message Template

```

type(scope) <files>: [concrete action] [specific component] by [exact method]

Summary: [Concrete action oriented brief high-level description of the change and why it matters]

Previous behavior: [Concrete description of observable behavior and/or limitation(s) being addressed based on git diff]

What changed: [Bulleted list of exact changes with file paths]

- file1.ext: [specific change made]

- file2.ext: [specific change made]

Why: [Root cause explanation in simple terms]

Files affected:

- [list of all modified files with brief description]

Testable: [Specific commands to verify the fix works]

```

This process ensures git commits are **self-documenting**, **technically precise**, **security-conscious**, and **contextually complete** while maintaining proper git workflow practices.

</pitfalls>