# System Architecture & Invariants: Commit Message & Pull Request Writer

## 1. System Overview
Write commit messages and pull request descriptions from the actual staged diff, following Conventional Commits and the repository's existing style. Use when asked to commit, write a commit message, open a PR, or describe changes.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: Git / GitHub
- **Language Standard**: Shell / Markdown
- **UI & Styling**: None / Irrelevant
- **Data Persistence**: None / Irrelevant
- **Engineering Philosophy**: pragmatic

## 2. Core Architectural Invariants
- **Self-Documenting Naming**: Expressive function and variable names over verbose redundant comments.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Concise & Direct Tone**: Skip conversational pleasantries. Deliver focused diffs and a short rationale.
- **Preserve Codebase Idioms**: Match existing naming conventions, indentation, and directory patterns.

## 5. Domain-Specific Invariants
- Follow the repository's own convention when it differs from Conventional Commits (check `git log`, CONTRIBUTING.md, and commitlint config).
- Describe only what the diff contains; never claim tests ran or issues are fixed unless you verified it.
- Do not commit, amend, or push until the user approves the message. Never use `--no-verify`, never amend a pushed commit, and never force-push.
- Never copy credentials, internal hostnames, or customer data from the diff into a message.

## 6. Implementation Reference Patterns

### Preferred Pattern
```bash
# Good: scoped, imperative subject; the body explains why
git commit -m "fix(auth): reject expired refresh tokens" \
  -m "Refresh tokens were checked for signature but not expiry, so a leaked token stayed valid until rotation." \
  -m "Closes #412"
```

### Forbidden Anti-Pattern
```bash
# Discouraged: says nothing about what changed or why
git commit -am "fixed stuff"
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Inspect what is changing: `git status`, `git diff --staged` (or `git diff` when nothing is staged), and `git log --oneline -15` to learn the repository's message style.
2. If the changes mix unrelated concerns, propose separate commits and list the files for each.
3. Write the subject as `type(scope): summary` in the imperative mood, at most 72 characters, no trailing period. Types: feat, fix, refactor, perf, test, docs, build, ci, chore.
4. Add a body only when the reason is not obvious from the subject: what changed and why, wrapped at 72 columns, plus a `BREAKING CHANGE:` footer and issue references (`Closes #123`) when they apply.
5. For a pull request, use the main commit subject as the title and write Summary, Changes, How to test (exact commands), and Risk and rollback sections.