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".

---

Removing Leaked or Sensitive Data (Discreet-Commit Carve-Out)

Applies ONLY when remediating sensitive data the user wants removed from a repository - a committed secret, credential, private path, internal/customer name, PII value, or an asset rendered from one (e.g. a screenshot). For every other commit, including ordinary security fixes and hardening, ignore this section and use the normal descriptive conventional-commit rules above.

When such a removal is requested, FIRST present the remediation choices and let the user decide (visibility and irreversibility are their call), then act:

1. Rewrite history (git filter-repo / BFG + force-push) - the only option that truly removes the data. Warn that it is destructive, rewrites shared history (all later SHAs change), needs a force-push (often to a protected branch), and that mirrors, forks, CDN/raw caches and archives may still retain copies.
2. Discreet removal commit on HEAD - delete or replace the data in a normal-looking commit. Non-destructive and low-effort, but the data stays recoverable in older commits and caches; it is hidden in plain sight, not erased.

Whichever path is chosen, the remediation commit (and any PR) MUST be unremarkable. A message that announces the exposure is itself a vulnerability: it points anyone scanning the history at exactly which commit to diff and what to look for, and - if it quotes the values - re-leaks them permanently into the message. So, in this case only:

• Do NOT put leak, secret, credential, exposure, PII, "sensitive", "redact", "scrub" or "hidden" in the subject or body, and do NOT use the 🔒 security type. Frame it as the mundane, truthful surface change it also is (a chore/refactor/docs/build cleanup, a preview refresh, an asset removal) so it blends into the surrounding history.
• NEVER reproduce the leaked values anywhere - not in the message, branch name, or PR - and do not even name which identifiers or paths were removed.
• Keep it atomic, but if it helps the change not stand out, fold it into a plausible neighbouring change rather than letting it sit alone as "the commit that removed something".
• The message must still be accurate about WHAT changed at the file level (never a bare "fix"/"update"); it simply omits WHY.

Communicate the security context (what was exposed, that history and caches still hold it, and any required credential rotation - a committed secret is burned even after deletion) to the user in chat, NOT in the commit, PR title, or branch name.

---

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