--- 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. --- ## Branch Cleanup - Short-lived topic branches (fix/*, feat/*, chore/*) created for one change are disposable. Once that change has landed in the default branch - or the branch is otherwise dead (abandoned experiment, superseded work) - delete it, both local and remote, so the branch list does not rot. - Delete a branch only when its work is safely preserved. Safe: the branch is fully merged into the default branch (`git branch --merged ` lists it). Careful: a squash-merged or rebase-merged branch does NOT show up as merged even though its content is already in the default branch - confirm the change is really there (compare content, or check the merged PR) before deleting. - When in ANY doubt that a branch still holds unmerged, unreleased, or otherwise relevant commits, do NOT delete it - ask the user first. Leaving a stale branch is cheap; losing a branch that held unique work is not. - Never delete a protected or long-lived branch (the default branch, release/*, or any branch the repo marks as protected) unless the user explicitly asks. - Prune deleted upstreams periodically with `git fetch --prune` so gone remote branches stop lingering locally. --- ## 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 `. - 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=` (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: ` : `. 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 `:` 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 `: `; 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