git-policy

name: git-policy description: Commit, branch, and pull request standards - conventional commits, atomic changes, branch naming, commit timing, and PR quality. Use when committing, branching, staging changes, or creating/updating a pull request.

Git & Contribution Policy (Senior Engineering Standards)

Core Principle

• All commits and pull requests must follow professional engineering standards.
• Treat all contributions as production-grade changes.
• Follow repository contribution guidelines strictly (including external docs like CONTRIBUTING.md if present).
• This skill owns commit/branch/PR mechanics. Change-quality gating before committing is owned by code-review-policy; both apply together.

Branching & Commit Timing

• Commit or push only when the user asks for it; do not commit speculatively.
• If currently on the default/protected branch, create a topic branch before committing.
• Use descriptive branch names scoped by type (e.g. feat/, fix/, chore/).
• Keep branches focused on a single concern.

Cloning & Fetch Efficiency

• When cloning or pulling a repository, do not fetch the full history unless it is actually needed. A shallow fetch saves disk space, bandwidth, and time.
• Default to a shallow clone for one-off use (building, inspecting, running, or extracting current files): git clone --depth=1 <url>.
• To narrow further, combine with --single-branch (one branch only) and --no-tags (skip tag refs).
• The full history IS required (do not shallow-clone) when the task depends on it: bisecting, blame/log archaeology, rebasing/cherry-picking across many commits, generating changelogs/release notes, or any operation that walks past commits.
• A shallow clone can be deepened later if history turns out to be needed: git fetch --unshallow (full) or git fetch --depth=<n> (more commits). Prefer this over re-cloning.
• For huge repos where you only need part of the tree, consider --filter=blob:none (blobless partial clone) or sparse-checkout instead of a full clone.

Identity & Git Configuration Safety

• Commits and pull requests must be authored SOLELY by the local user's configured Git identity (user.name / user.email). This is non-negotiable.
• Never use an AI-managed, autogenerated, shared, or assistant-provided Git identity, and never set yourself as author or committer.
• Never add co-author or AI-attribution trailers to commit messages or PR bodies. Specifically, do NOT append "Co-Authored-By: Claude", "Co-Authored-By: ", "Generated with Claude Code", or any equivalent AI credit.
• Do not override the Git identity unless the user explicitly requests it.
• The commit/PR must read as if the user authored it; no trace of the assistant in author fields, trailers, or footers.
• Enforcement note: in Claude Code this is also disabled deterministically via settings.json (attribution.commit / attribution.pr set to "", and includeCoAuthoredBy: false); the enigma installer sets this automatically. The rule here still applies on every runtime, settings or not.

Commit Strategy

Conventional Commit Style (Required)

• Use structured commit formats: :

Allowed types:

• feat: new features
• fix: bug fixes
• chore: maintenance tasks
• refactor: code restructuring without behavior change
• perf: performance improvements
• docs: documentation changes
• test: testing changes
• build: build system changes
• ci: CI/CD changes

Commit Emoji Convention (Ciphera Style, Default On)

• Commit subjects use a leading type emoji by default: <emoji> <type>: <short description>. Example: ✨ feat: add dual-provider matching.
• This is the one sanctioned exception to the global no-emoji rule: it applies ONLY to the commit subject line. Commit bodies, PR text, code, comments, identifiers, and chat responses stay emoji-free. Do not add more than one emoji, and place it only at the start of the subject.
• Use exactly this type-to-emoji map (do not invent others):
  • ✨ feat: new features
  • 🐛 fix: bug fixes
  • 🔧 chore: maintenance tasks
  • ♻️ refactor: code restructuring without behavior change
  • ⚡ perf: performance improvements
  • 📝 docs: documentation changes
  • ✅ test: testing changes
  • 📦 build: build system changes
  • 👷 ci: CI/CD changes
  • 🎨 style: formatting-only changes
  • 🔒 security: security fixes or hardening
  • ⏪ revert: reverting a previous commit
• Always keep a valid Conventional Commit <type>: after the emoji; the emoji augments it, never replaces it.
• If the target repository defines its own commit convention (CONTRIBUTING.md, commitlint), follow the repo.

Opt-out

• A user can disable commit emojis. When disabled, omit the leading emoji and commit as plain <type>: <short description>; everything else in this policy is unchanged.
• Disabled when .enigma.json (in the repo root or the user home) contains "commitEmoji": false, or via enigma config commit-emoji off. Re-enable with enigma config commit-emoji on.
• Check for this opt-out before composing a commit; treat commit emojis as on when no config is present.

Commit Quality Rules

• Commits must be atomic (one logical change per commit).
• Do not mix unrelated changes in a single commit.
• Commit messages must be meaningful and human-readable.
• Avoid vague messages like "fix" or "update".

Pull Request Engineering Standards

PR Creation Rules

• Every PR must include:
  • Clear title describing the change
  • Structured description of what changed and why
  • Context of the problem being solved
  • Any trade-offs or side effects

PR Quality Requirements

• Must be small and reviewable
• Must not include unrelated changes
• Must pass all tests before submission
• Must follow existing repository architecture and style

Automation (Commit Scripts Awareness)

• If a repository includes automation scripts (e.g. commit.sh):
  • Prefer using existing scripts instead of manual commits
  • Ensure scripts are executed in the correct environment (bash, git bash, WSL)
• Validate commit prefix selection before execution

Code of Conduct for Contributions

• Respect project licenses and legal constraints.
• Understand that all merged code becomes part of the project.
• Follow repository coding standards strictly.
• Be open to feedback and peer review without resistance.

Anti-AI Fingerprinting Rule

• Do not introduce patterns that reveal AI origin in commit history.
• Avoid repetitive or generic commit structures.
• Maintain natural, professional, repository-consistent commit descriptions.

PR Communication Rules

• PR communication must assume ownership and responsibility for the changes.

• Never refer to "the author", "the agent", "the AI", or third-person wording.

• Use direct ownership language such as:

  • "I refactored..."
  • "This PR updates..."
  • "I added validation..."

• Avoid meta-commentary about the development process unless strictly relevant.

• Do not mention:

  • Internal scratch files
  • AI workflows
  • Temporary reasoning artifacts
  • Hidden notes files
  • Out-of-band debugging context
  • Internal generation process

• PR descriptions must contain only information relevant for reviewers and maintainers.

Formatting & Writing Rules

• Prefer standard ASCII punctuation in commits, PR titles, and technical communication.

• Avoid typographic punctuation such as "—", smart quotes, or decorative Unicode characters.

• Use "-" instead of "—".

• Do not use arrows (→). Use "->".

• Avoid robotic or overly templated phrasing.

• Keep PR communication concise, natural, and technically relevant.

• Remove filler sections that do not help code review or maintenance.

Reviewer Notes Policy

• Reviewer notes must only include information directly useful for reviewing the change.
• Do not reference private, gitignored, local-only, or inaccessible files.
• Do not instruct reviewers to retrieve external/internal notes outside the PR unless explicitly required by repository policy.
• Avoid documenting debugging history unless it affects architecture, behavior, or future maintenance.

Safety & Final Validation

Before creating a commit or PR:

• Verify only relevant files are included
• Ensure no debug or temporary code is committed
• Ensure no secrets or sensitive data are included
• Ensure the change aligns with repository architecture