lgtm-specs 0.0.4

package/docs/meta/domains/bitcoin/06-relay-policy.md

@@ -0,0 +1,27 @@
+# Bitcoin: Relay Policy Gates (Dust, Min Fee, Feefilter)
+
+**Sources**:
+
+- Bitcoin Dev Guide (dust + standardness): https://developer.bitcoin.org/devguide/transactions.html#non-standard-transactions
+- Bitcoin Dev Guide (minimum relay fee): https://developer.bitcoin.org/devguide/transactions.html#transaction-fees-and-change
+- Bitcoin Core policy constants (dust relay fee / min relay fee): https://raw.githubusercontent.com/bitcoin/bitcoin/master/src/policy/policy.h
+- BIP-0133 (feefilter message): https://raw.githubusercontent.com/bitcoin/bips/master/bip-0133.mediawiki
+
+## Relay Is Policy-Dependent
+
+- Transaction relay is not a consensus guarantee; it depends on node policy and peer-to-peer filtering.
+
+## Gate 1: Dust
+
+- Outputs below the dust threshold may be considered non-standard and not relayed by default.
+- Treat dust checks as part of transaction construction.
+
+## Gate 2: Node Minimum Fee
+
+- Nodes enforce a minimum feerate for relay/mempool admission.
+- This minimum may differ across nodes and can change under mempool pressure.
+
+## Gate 3: Peer feefilter
+
+- Peers may announce a `feefilter` value; transactions below that feerate may not be announced to that peer.
+- The feefilter value is a feerate interpreted as satoshis per kilobyte.

package/docs/meta/domains/bitcoin/README.md

@@ -0,0 +1,12 @@
+# Bitcoin Domain (Meta)
+
+This directory contains source material and distilled patterns for Bitcoin-related engineering.
+
+## Index
+
+- [01-units.md](01-units.md)
+- [02-broadcast-cancellation.md](02-broadcast-cancellation.md)
+- [03-fee-rates-rounding.md](03-fee-rates-rounding.md)
+- [04-confirmations-reorgs.md](04-confirmations-reorgs.md)
+- [05-address-gap-limit.md](05-address-gap-limit.md)
+- [06-relay-policy.md](06-relay-policy.md)

package/docs/meta/domains/git/01-workflow.md

@@ -0,0 +1,89 @@
+# 01. The Workflow: Trunk-Based Development
+
+**Source**: [Trunk Based Development](https://trunkbaseddevelopment.com/)
+
+## 1. The Single Source of Truth
+
+We adhere to **Trunk-Based Development (TBD)**.
+
+- **Trunk**: `main` is the only long-lived branch. It must always be deployable.
+- **Branches**: Feature branches should be short-lived.
+  - **Guideline**: Target a lifespan of < 1 week.
+  - **Rationale**: The longer a branch lives, the higher the probability of complex merge conflicts ("Merge Hell").
+  - **Exceptions**: Longer-lived branches may be acceptable for large coordinated work (e.g., multi-repo changes, research spikes), but they require explicit coordination and frequent integration from `main`.
+  - **Naming**: Use `<type>/<short-description>` (kebab-case). Prefer `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`.
+  - **Atomic Rules**: GIT-00004, GIT-00009
+
+## 2. The Atomic Commit Philosophy
+
+Treat the **Commit** as the primary unit of communication.
+
+- **Cognitive Focus**: A commit should be understandable in a single mental pass.
+- **Logical Progression**: Submit changes as a series of commits (Logical Commit Series).
+  - _Tooling_: We use pull requests / merge requests (e.g., GitHub PRs, GitLab MRs, Bitbucket PRs) to review the Logical Commit Series. We do not use `git send-email`.
+- **Independence**: Ideally, every commit in the series should be buildable to support review, safe reverts, and `git bisect`.
+- **Atomic Rules**: GIT-00008, GIT-00010
+
+Pull requests are the unit of integration into `main`.
+
+- **Description**: A PR description **SHOULD** include intent, testing performed, and any rollout/flagging notes.
+- **Scope**: Keep PRs small enough that reviewers can complete a high-quality review.
+
+## 3. The Release Lifecycle
+
+- **Tagging**: Releases are SemVer tags (`v1.2.3`) on `main`.
+- **Breaking Changes**: Breaking changes must follow Semantic Versioning (major version increment) and include migration documentation.
+- **Feature Flags**: Merge incomplete features behind a toggle to maintain the "Always Deployable" invariant.
+- **Atomic Rules**: GIT-00022, GIT-00023
+
+## 4. Feature Flags
+
+Feature flags preserve trunk discipline by separating _merge time_ from _release time_.
+
+- **Principle**: Merge early. Release deliberately.
+- **Guideline**: Flags should default to safe/off, be configurable per environment, and support rapid rollback.
+- **Anti-Pattern**: Long-lived branches used to "hide" unfinished work.
+- **Atomic Rules**: GIT-00022
+
+### Implementation Patterns
+
+#### Boolean Toggles
+
+```typescript
+// feature-flags.ts
+export const FEATURE_FLAGS = {
+  NEW_CHECKOUT: process.env.FF_NEW_CHECKOUT === "true",
+  EXPERIMENTAL_API: process.env.FF_EXPERIMENTAL_API === "true",
+} as const;
+
+// Usage
+if (FEATURE_FLAGS.NEW_CHECKOUT) {
+  renderNewCheckout();
+} else {
+  renderLegacyCheckout();
+}
+```
+
+#### Rollout Percentages
+
+```typescript
+// Use a consistent hashing strategy for user-based rollouts
+function isUserInRollout(userId: string, percentage: number): boolean {
+  const hash = crypto.createHash("sha256").update(userId).digest("hex");
+  const value = parseInt(hash.slice(0, 8), 16) % 100;
+  return value < percentage;
+}
+```
+
+#### Configuration Management
+
+- **Environment Variables**: Simple boolean flags via env vars.
+- **Feature Flag Services**: Dedicated services (LaunchDarkly, Flagsmith) for dynamic, real-time control.
+- **Database-backed Flags**: Store flags in a database for admin UI control.
+
+#### Example: Gradual Rollout with Feature Flags
+
+1.  Merge feature behind a flag defaulting to `false`.
+2.  Enable flag for internal testing (staging environment).
+3.  Gradually enable for percentage of users (1% → 10% → 50% → 100%).
+4.  Once stable, remove flag conditional code and delete flag.

package/docs/meta/domains/git/02-commits.md

@@ -0,0 +1,57 @@
+# 02. The Commit: The Atomic Unit
+
+**Source**: [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/#specification)
+
+## 1. Atomicity (The Golden Rule)
+
+A commit must represent **one** logical change.
+
+- **The Audit Test**: Can a reviewer fully understand the intent and verify the correctness of this commit in a single mental pass?
+- **The Revert Test**: Can I revert _only_ this commit without breaking the build or unrelated features?
+- **Debugging**: Atomic commits enable `git bisect` (See [06-advanced](06-advanced.md)) to find bugs.
+- **Atomic Rules**: GIT-00001, GIT-00021
+
+## 2. Commit Often, Perfect Later
+
+- **Outcome**: A PR should present a clean, reviewable Logical Commit Series.
+- **Guideline**: Before requesting review, you **SHOULD** rewrite your feature-branch history to remove noisy commits (`wip`, `typo`, `fix`) and group changes into logical steps.
+- **Tooling**: Use `git commit --fixup <sha>` (and `git rebase -i --autosquash`) or consider `git absorb` to generate `fixup!` commits automatically. (See https://github.com/tummychow/git-absorb)
+- **Constraint**: Never rewrite shared branches. If you rebase a pushed feature branch, use `--force-with-lease`.
+- **Amend (Before Push)**: If you forgot a file or need to fix the message, use `git commit --amend` only before pushing. Never amend commits that are already shared.
+- **Atomic Rules**: GIT-00005
+
+## 3. Conventional Commits (v1.0.0)
+
+**Structure**:
+
+```text
+feat(pkg): add login handler
+
+This adds the /login endpoint using OAuth2.
+
+Closes #123
+```
+
+**Annotations**:
+
+- **Type**: `feat` (user-facing change).
+- **Scope**: `pkg` (the package/module affected).
+- **Subject**: `add login handler` (imperative mood).
+- **Body**: explains why (and any non-obvious tradeoffs), not just what.
+- **Footer**: references issues (`Closes #123`).
+
+**Types**:
+
+- `feat`, `fix` (User facing).
+- `build`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`, `chore` (Internal).
+- **Breaking**: `feat!: drop support for v1` or `BREAKING CHANGE:` footer.
+- **Atomic Rules**: GIT-00002, GIT-00003
+
+## 4. Issue References
+
+Issue references make intent and traceability explicit.
+
+- **Guideline**: Prefer explicit closing keywords when applicable (`Closes`, `Fixes`, `Resolves`).
+- **Guideline**: Use non-closing references for context when appropriate (`Refs`, `Related-to`).
+- **Anti-Pattern**: PRs/commits with no linkage to the motivating issue.
+- **Atomic Rules**: GIT-00020

package/docs/meta/domains/git/03-collaboration.md

@@ -0,0 +1,40 @@
+# 03. Collaboration & Etiquette
+
+**Source**: [Upstream Merge: What Not To Do](https://kernelnewbies.org/UpstreamMerge/WhatNotToDo)
+
+## 1. The Social Contract
+
+Merging code transfers maintenance responsibility to the team. Ensure your contribution is maintainable.
+
+## 2. Reviewer Capital
+
+"Reviewer capital" is the team's limited attention and review capacity. Spend it intentionally.
+
+- **Cost**: Every minute a reviewer spends understanding your code is a cost.
+- **Compliance**: If a reviewer suggests a change, accept it unless you have a specific technical objection.
+- **Arbitration**: In cases of unresolvable disagreement, the **Team Lead** makes the final decision.
+  - _Escalation_: For architectural disputes, open a Request for Comments (RFC) issue.
+- **Atomic Rules**: GIT-00007
+
+## 3. Handling Critique
+
+- **Focus**: Focus on the technical debt being pointed out, not the tone.
+- **Response**: Never reply with anger. Address the technical points objectively.
+
+## 4. Conflict Resolution
+
+- **Owner**: The author resolves merge conflicts.
+- **Protocol**: Resolve conflicts in small, reviewable commits. If the conflict materially changes behavior, call it out in the PR description.
+- **Escalation**: If resolution is unclear or high-risk, escalate to the Team Lead and/or open an RFC issue.
+- **Atomic Rules**: GIT-00012
+
+## 5. Review Checklist
+
+Reviews are where quality is enforced.
+
+- **Correctness**: The change matches intent and edge cases are handled.
+- **Security**: No secrets, unsafe defaults, or new attack surface without justification.
+- **Performance**: No obvious regressions (hot paths, N+1 patterns, unnecessary allocations).
+- **Maintainability**: Readable, minimal complexity, good naming.
+- **Verification**: Tests/CI evidence matches the risk.
+- **Atomic Rules**: GIT-00019

package/docs/meta/domains/git/04-integrity.md

@@ -0,0 +1,26 @@
+# 04. History Integrity & Security
+
+**Source**: [Pro Git: Signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
+
+## 1. Immutable Public History
+
+- **Rule**: Never `git push --force` on shared branches (e.g., `main`).
+- **Safety**: If you must force push a feature branch, use `--force-with-lease`.
+- **Atomic Rules**: GIT-00005
+
+## 2. Merge Strategy
+
+- **Main Branch**: Merge into `main` using a merge commit to preserve commit history.
+- **No Squash**: Do not squash-merge into `main`. Our policy is to preserve the Logical Commit Series. See `docs/meta/domains/git/05-configuration.md`.
+- **No Rebase-Merge**: Do not use rebase-merge for `main`.
+- **Feature Branches**: Rebase your feature branch onto `main` to keep it clean before merging.
+- **Rebase**: Rebase only branches you own (no one else has pulled). Rebasing a shared branch rewrites history and breaks clones.
+- **When to Rebase**: Rebase after pulling updates from `main`, before requesting review, and before merging if the branch has drifted.
+- **Atomic Rules**: GIT-00011
+
+## 3. Cryptographic Identity
+
+- **Signing**: Commits on `main` **MUST** be signed (GPG/SSH). Feature branch commits **MUST** be signed.
+- **Enforcement**: Enforce on `main` via branch protection (require signed commits).
+- **SHA-256**: Git is migrating from SHA-1 to SHA-256 to prevent collisions. Signing provides immediate authorship verification.
+- **Atomic Rules**: GIT-00006

package/docs/meta/domains/git/05-configuration.md

@@ -0,0 +1,209 @@
+# 05. Configuration & Governance
+
+**Source**: [Pro Git: Customizing Git](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration)
+
+## 1. Git Hooks
+
+- **pre-commit**: Run fast linters (Biome, Ruff).
+- **prepare-commit-msg**: Generate or prefill commit message templates (e.g., add a PR/issue reference).
+- **commit-msg**: Validate Conventional Commits syntax.
+- **pre-push**: Run unit tests to prevent broken builds on CI.
+- **post-checkout**: Refresh generated files or local tooling after branch switches.
+- **post-merge**: Sync dependencies after merges (e.g., `npm install` when lockfiles change).
+
+**CI/CD Integration**: Hooks are a fast local gate; CI is the authoritative gate. Prefer hooks that are quick and deterministic, and keep CI checks superset-compatible (avoid hook-only rules).
+
+- **Atomic Rules**: GIT-00015
+
+### Example: Pre-commit Hook
+
+```bash
+#!/usr/bin/env bash
+# .git/hooks/pre-commit
+set -e
+
+# Run fast linters
+if command -v ruff >/dev/null 2>&1; then
+    ruff check --fix --exit-zero
+fi
+
+# Ensure no secrets are accidentally committed
+if command -v trufflehog >/dev/null 2>&1; then
+    trufflehog git file://. --since-commit HEAD --fail >/dev/null 2>&1 || {
+        echo "ERROR: Potential secrets found. Aborting commit."
+        exit 1
+    }
+fi
+```
+
+### Example: Commit-msg Hook
+
+```bash
+#!/usr/bin/env bash
+# .git/hooks/commit-msg
+MSG_FILE="$1"
+
+# Validate subject line length
+subject=$(head -1 "$MSG_FILE")
+if [ ${#subject} -gt 50 ]; then
+    echo "ERROR: Subject line exceeds 50 characters."
+    exit 1
+fi
+
+# Validate imperative mood (basic heuristic)
+if echo "$subject" | grep -qE '^(Added|Fixed|Updated|Removed|Changed)'; then
+    echo "WARNING: Subject line appears to be in past tense. Use imperative mood (e.g., 'Add', 'Fix', 'Update')."
+fi
+```
+
+## 2. Branch Protection (Hosting Platform)
+
+- **Require Pull Requests**: No direct pushes to `main`.
+- **Require Status Checks**: CI must pass before merging.
+- **Require Signed Commits**: Require signed commits on `main` (GPG/SSH).
+- **Merge Method**: Allow merge commits. Disable squash merging and rebase merging.
+  - **Rationale**: Preserve the Logical Commit Series on `main` to improve auditability, enable precise reverts, and make `git bisect` useful.
+- **Atomic Rules**: GIT-00016
+
+### Example: GitHub Actions Workflow for Signed Commits
+
+```yaml
+name: Verify Signed Commits
+on: [pull_request]
+jobs:
+  verify-signed:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Verify all commits are signed
+        run: |
+          git log --oneline HEAD^..HEAD | while read commit; do
+            if ! git verify-commit $(echo $commit | cut -d' ' -f1) 2>/dev/null; then
+              echo "ERROR: Unsigned commit detected: $commit"
+              exit 1
+            fi
+          done
+```
+
+## 3. Ignore Standards
+
+- **Blocklist**: Explicitly ignore generated artifacts and secrets.
+- **Patterns**: `node_modules/`, `dist/`, `.env`, `.DS_Store`.
+- **Atomic Rules**: GIT-00013
+
+### Example: .gitignore
+
+```gitignore
+# Dependencies
+node_modules/
+vendor/
+*.pyc
+
+# Build artifacts
+dist/
+build/
+*.o
+*.so
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Editor files
+.vscode/
+.idea/
+*.swp
+
+# OS files
+.DS_Store
+Thumbs.db
+```
+
+## 4. Secrets and Credential Hygiene
+
+Secrets must not enter Git history.
+
+- **Principle**: Treat any committed secret as compromised.
+- **Guideline**: Use platform secret scanning and/or a pre-commit secret detector. If a secret is committed, rotate it immediately.
+- **Anti-Pattern**: Relying on "private repo" as a security control.
+- **Atomic Rules**: GIT-00017
+
+### Recommended Tools
+
+- **trufflehog**: Scans Git history and diffs for high-entropy strings and known secret patterns.
+- **gitleaks**: Lightweight secret scanner with configurable rule sets.
+- **GitHub Secret Scanning**: Native scanning for public repositories; enable for private repos via GitHub Advanced Security.
+
+### Example: Pre-commit Hook with gitleaks
+
+```bash
+#!/usr/bin/env bash
+if command -v gitleaks >/dev/null 2>&1; then
+    gitleaks protect --staged --verbose
+    if [ $? -ne 0 ]; then
+        echo "ERROR: gitleaks detected potential secrets. Commit aborted."
+        exit 1
+    fi
+fi
+```
+
+## 5. CI Enforcement
+
+CI is the authoritative gate for merge policy.
+
+- **Guideline**: CI should enforce tests, lint, and policy checks that cannot be reliably enforced locally.
+- **Guideline**: For policies that hosting cannot enforce (e.g., verifying all PR commits are signed), CI should fail the PR.
+- **Atomic Rules**: GIT-00018
+
+### Example: GitHub Actions Workflow for Branch Protection
+
+```yaml
+name: PR Compliance
+on: [pull_request]
+jobs:
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check branch naming
+        run: |
+          BRANCH_NAME="${{ github.head_ref }}"
+          if [[ ! "$BRANCH_NAME" =~ ^(feat|fix|refactor|docs|test|chore)/[a-z0-9-]+$ ]]; then
+            echo "ERROR: Branch name '$BRANCH_NAME' does not follow pattern <type>/<short-description> (kebab-case)."
+            exit 1
+          fi
+      - name: Check commit message format
+        run: |
+          git log --oneline --no-merges ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }} | while read line; do
+            commit_hash=$(echo "$line" | cut -d' ' -f1)
+            subject=$(echo "$line" | cut -d' ' -f2-)
+            if [ ${#subject} -gt 50 ]; then
+              echo "ERROR: Commit $commit_hash subject line >50 chars: '$subject'"
+              exit 1
+            fi
+          done
+```
+
+## 6. Dependency Management
+
+- **Lockfiles**: Version lockfiles must be committed to ensure reproducible builds.
+- **Atomic Updates**: Dependency updates should be isolated in dedicated commits.
+- **Security Patches**: Critical security updates must be prioritized and applied promptly.
+- **Transitive Dependencies**: Regularly review transitive dependencies for vulnerabilities.
+- **Atomic Rules**: GIT-00024
+
+### Example: Dependency Update Commit
+
+```bash
+# Update a dependency and commit lockfile
+npm update package-name --save
+git add package.json package-lock.json
+git commit -m "chore(deps): update package-name to v2.1.0
+
+- Security fix for CVE-2023-XXXXX
+- Performance improvements
+- Tested with existing test suite"
+```

package/docs/meta/domains/git/06-advanced.md

@@ -0,0 +1,130 @@
+# 06. Advanced Operations
+
+**Sources**: [Pro Git: Tools](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection), [GitHub: Large files](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github)
+
+## 1. Partial Staging (`git add -p`)
+
+- **Principle**: A commit represents one logical change.
+- **Guideline**: If a file contains multiple logical changes, you **SHOULD** stage only the relevant hunks so the resulting commit stays atomic.
+- **Anti-Pattern**: One commit that mixes refactors, formatting, and behavior changes.
+- **Atomic Rules**: GIT-00021
+
+### Example: Interactive Staging
+
+```bash
+# Stage specific hunks
+git add -p path/to/file.js
+
+# Review staged changes
+git diff --cached
+
+# Commit only the staged changes
+git commit -m "Fix validation logic for email field"
+```
+
+## 2. Recovery & Maintenance
+
+- **Reflog**: If you lost work, you **SHOULD** check the reflog before assuming it is gone.
+- **Bisect**: For regressions, you **SHOULD** use bisect to identify the first bad commit.
+  - **Prerequisite**: The Logical Commit Series should be buildable and testable to keep bisect effective.
+- **Stash**: You **SHOULD** prefer commits or worktrees for context switching. Use stash for short-lived, local-only interruption handling.
+  - **Guideline**: Do not keep long-lived stashes; they rot and create hidden merge conflicts.
+- **Cherry-Pick**: You **SHOULD** cherry-pick for backports/hotfix propagation when you need to apply a specific fix without merging unrelated history.
+- **Revert**: On public branches, you **SHOULD** revert instead of rewriting history.
+- **LFS**: Repositories **MUST** not store large binary artifacts directly in Git history. Track large or non-diffable binaries via Git LFS and commit the corresponding `.gitattributes` changes.
+  - **Platform Constraint (e.g., GitHub)**: Hosting platforms may warn above 50 MiB and block above 100 MiB. Treat warning thresholds as hard guidelines and hard limits as hard blocks.
+- **Atomic Rules**: GIT-00014
+
+### Example: Git LFS Setup
+
+```bash
+# Install Git LFS
+git lfs install
+
+# Track large binary files
+git lfs track "*.psd"
+git lfs track "*.zip"
+git lfs track "*.bin"
+
+# Commit .gitattributes
+git add .gitattributes
+git commit -m "track large files with LFS"
+
+# Push as usual
+git push origin main
+```
+
+## 3. Worktrees
+
+- **Principle**: Separate concurrent work to reduce accidental cross-task edits.
+- **Guideline**: If you are working on more than one task/branch at once, you **SHOULD** use worktrees instead of stashing and constantly switching your working directory.
+- **Constraint**: Keep one branch checked out per worktree.
+
+### Example: Creating a Worktree
+
+```bash
+# Create a new worktree for feature branch
+git worktree add ../myrepo-feature feat/new-widget
+
+# Switch to the worktree
+cd ../myrepo-feature
+
+# Later, remove the worktree
+git worktree remove ../myrepo-feature
+```
+
+## 4. Large Repos & Dependencies
+
+- **Sparse Checkout**: You **SHOULD** use sparse checkout when a repo is large enough that full checkouts meaningfully slow iteration.
+  - **Constraint**: Ensure tooling (build/test/scripts) still works with the reduced working set.
+- **Submodules**: You **SHOULD** avoid submodules by default; they make clones, CI, and dependency updates harder.
+  - **If Required**: You **MUST** pin exact SHAs, document the update workflow, and never rely on floating refs.
+
+### Example: Sparse Checkout
+
+```bash
+# Enable sparse checkout
+git config core.sparseCheckout true
+
+# Specify which directories to keep
+echo "src/frontend/" >> .git/info/sparse-checkout
+echo "config/" >> .git/info/sparse-checkout
+
+# Read the configured sparse checkout
+git read-tree -mu HEAD
+```
+
+### Example: Submodule Update Workflow
+
+```bash
+# Update submodule to latest commit of a specific branch
+cd submodule-path
+git checkout main
+git pull origin main
+cd ..
+git add submodule-path
+git commit -m "Update submodule to latest main"
+```
+
+- **Atomic Rules**: GIT-00025
+
+## 5. Code Archaeology & Debugging
+
+- **Principle**: Prefer understanding history over rewriting it.
+- **Guideline**: You **SHOULD** use history inspection (diff/log/show/blame) to explain changes, identify regressions, and support reviews.
+
+### Example: Finding When a Bug Was Introduced
+
+```bash
+# Use git bisect to find the commit that introduced a bug
+git bisect start
+git bisect bad HEAD
+git bisect good v1.0.0
+
+# Test current commit (mark bad/good)
+git bisect bad  # if bug present
+git bisect good # if bug absent
+
+# After bisect completes, reset
+git bisect reset
+```

package/docs/meta/domains/git/README.md

@@ -0,0 +1,29 @@
+# Git Meta-Documentation
+
+**Domain**: Version Control & Collaboration Protocol.
+**Scope**: All repositories managed by LGTM agents.
+
+These documents define the operational standard for Git usage. They are written for humans and agents, and they serve as the cited sources for atomic rules under `rules/laws/git/*`.
+
+## Table of Contents
+
+## Atomic Rule Mapping
+
+- 1.  Workflow: GIT-00004, GIT-00009, GIT-00010, GIT-00022, GIT-00023
+- 2.  Commit: GIT-00001, GIT-00002, GIT-00003, GIT-00008, GIT-00020, GIT-00021
+- 3.  Collaboration: GIT-00007, GIT-00012, GIT-00019
+- 4.  Integrity: GIT-00005, GIT-00006, GIT-00011
+- 5.  Configuration: GIT-00013, GIT-00015, GIT-00016, GIT-00017, GIT-00018, GIT-00024
+- 6.  Advanced Ops: GIT-00014, GIT-00025
+
+### Core Principles
+
+- **[01. The Workflow](01-workflow.md)**: Trunk-Based Development, Branch Lifecycles, Branch Naming, and PR hygiene.
+- **[02. The Commit](02-commits.md)**: Atomicity, Conventional structure, and the Cognitive Pass.
+- **[03. Collaboration](03-collaboration.md)**: Reviewer capital, Etiquette, and Escalation.
+- **[04. Integrity](04-integrity.md)**: Signing, Merge Strategies, and Immutable History.
+
+### Operational Guides
+
+- **[05. Configuration & Governance](05-configuration.md)**: Hooks, Ignore standards, and Branch Protection.
+- **[06. Advanced Operations](06-advanced.md)**: Atomic staging, recovery, LFS, worktrees, and large repo practices.