lgtm-specs 0.0.4

package/rules/laws/git/GIT-00008-patch-series.md

@@ -0,0 +1,28 @@
+# Logical Commit Series Structure (GIT-00008)
+
+**Source**: [01. The Workflow](../../../docs/meta/domains/git/01-workflow.md#2-the-atomic-commit-philosophy)
+**Tags**: #structural #git #git-commit #workflow #series
+**Related**: [Composition](../../constitution/CONS-00008-composition.md)
+
+## Definition
+
+Complex changes must be broken into a Logical Commit Series of independent commits.
+
+## Requirements
+
+1.  **Ordering**: Abstraction first, Implementation second.
+2.  **Independence**: Commit N must compile without Commit N+1.
+
+## Anti-Patterns
+
+- Commit 1: "Add half of the feature (broken)".
+- Commit 2: "Finish feature (fixes build)".
+
+## Examples
+
+**Bad:**
+Big PR.
+
+**Good:**
+Commit 1: `feat: add IService interface`
+Commit 2: `feat: implement Service`

package/rules/laws/git/GIT-00009-branch-naming.md

@@ -0,0 +1,28 @@
+# Branch Naming (GIT-00009)
+
+**Source**: [01. The Workflow](../../../docs/meta/domains/git/01-workflow.md#1-the-single-source-of-truth)
+**Tags**: #structural #git #git-branch #naming
+**Related**: [The Checklist](../../constitution/CONS-00031-checklist.md)
+
+## Definition
+
+Branch names are a structured communication channel. They must be readable, searchable, and automation-friendly.
+
+## Requirements
+
+1.  **Prefix**: Use `<type>/...` to express intent (`feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`).
+2.  **Format**: Use kebab-case for the description (`feat/user-login`, not `feat/UserLogin`).
+3.  **Clarity**: The description must explain the work without requiring additional context.
+
+## Anti-Patterns
+
+- `tmp/try-stuff` (unclear intent)
+- `feature/1234` (ticket-only names)
+
+## Examples
+
+**Good:**
+`fix/api-timeout`
+
+**Bad:**
+`branch1`

package/rules/laws/git/GIT-00010-pr-hygiene.md

@@ -0,0 +1,51 @@
+# Pull Request Hygiene (GIT-00010)
+
+**Source**: [01. The Workflow](../../../docs/meta/domains/git/01-workflow.md#2-the-atomic-commit-philosophy)
+**Tags**: #operational #git #git-review #pr #workflow
+**Related**: [Cognitive Limits](../../constitution/CONS-00012-cognitive-limits.md)
+
+## Definition
+
+A pull request is the unit of integration into `main`. It must be reviewable and safe to merge.
+
+## Requirements
+
+1.  **Description**: The PR description should state intent, testing performed, and any rollout/flagging notes.
+2.  **Scope**: The PR should be small enough to enable a high-quality review.
+3.  **Transparency**: If conflict resolution materially changes behavior, it must be called out in the PR description.
+
+## Anti-Patterns
+
+- "misc fixes" with no testing notes.
+- PRs that bundle unrelated changes.
+
+## Examples
+
+**Bad:**
+
+```markdown
+Title: misc fixes
+
+Description:
+
+- changed stuff
+```
+
+**Good:**
+
+```markdown
+Title: Add widget creation behind flag
+
+Intent:
+
+- Add widget creation flow behind `WIDGETS_V2`.
+
+Testing:
+
+- Unit: `go test ./...`
+- Manual: created widget via UI and verified persisted state.
+
+Rollout:
+
+- Flag default OFF; canary enable in staging.
+```

package/rules/laws/git/GIT-00011-merge-method.md

@@ -0,0 +1,35 @@
+# Merge Method (No Squash) (GIT-00011)
+
+**Source**: [04. History Integrity & Security](../../../docs/meta/domains/git/04-integrity.md#2-merge-strategy)
+**Tags**: #operational #git #git-branch #merge #integrity
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+`main` preserves the Logical Commit Series for auditability and debugging.
+
+## Requirements
+
+1.  **Merge Commit**: PRs must be merged into `main` with a merge commit.
+2.  **No Squash**: Squash-merge into `main` is forbidden.
+3.  **No Rebase-Merge**: Rebase-merging into `main` is forbidden.
+
+## Anti-Patterns
+
+- Flattening a multi-commit PR into one commit on `main`.
+
+## Examples
+
+**Bad:**
+
+```text
+Merge method: Squash and merge
+Result: PR commit series collapsed into 1 commit on main
+```
+
+**Good:**
+
+```text
+Merge method: Create a merge commit
+Result: main retains the PR's logical commit series for audit/debug
+```

package/rules/laws/git/GIT-00012-conflict-resolution.md

@@ -0,0 +1,35 @@
+# Conflict Resolution (GIT-00012)
+
+**Source**: [03. Collaboration & Etiquette](../../../docs/meta/domains/git/03-collaboration.md#4-conflict-resolution)
+**Tags**: #behavioral #git #git-collaboration #conflicts
+**Related**: [Transparency](../../constitution/CONS-00027-transparency.md)
+
+## Definition
+
+Merge conflicts are resolved by the author, with changes kept reviewable and explicitly communicated.
+
+## Requirements
+
+1.  **Owner**: The author resolves merge conflicts.
+2.  **Reviewability**: Conflict resolutions must be made in small, reviewable commits.
+3.  **Escalation**: If resolution is unclear or high-risk, escalate to the Team Lead and/or open an RFC issue.
+
+## Anti-Patterns
+
+- Resolving conflicts by blindly accepting "incoming" changes.
+
+## Examples
+
+**Bad:**
+
+```text
+Resolved conflicts by accepting "incoming" without understanding.
+Pushed a single large conflict-resolution commit with no explanation.
+```
+
+**Good:**
+
+```text
+Commit message: resolve conflicts: preserve API signature; keep new tests
+PR description: calls out any behavior changes introduced by resolution
+```

package/rules/laws/git/GIT-00013-ignore-standards.md

@@ -0,0 +1,38 @@
+# Ignore Standards (GIT-00013)
+
+**Source**: [05. Configuration & Governance](../../../docs/meta/domains/git/05-configuration.md#3-ignore-standards)
+**Tags**: #operational #git #git-hygiene #ignore
+**Related**: [Security](../../constitution/CONS-00024-security.md)
+
+## Definition
+
+Repositories must not version generated artifacts or secrets.
+
+## Requirements
+
+1.  **Generated Artifacts**: Generated build outputs must be ignored.
+2.  **Secrets**: Secret-bearing files (e.g., `.env`) must be ignored.
+3.  **Noise**: Platform cruft (e.g., `.DS_Store`) should be ignored.
+
+## Anti-Patterns
+
+- Committing `.env` files.
+- Committing `dist/` build outputs.
+
+## Examples
+
+**Bad:**
+
+```text
+Committed: .env, dist/, node_modules/
+Result: secrets exposure + noisy diffs + slow clones
+```
+
+**Good:**
+
+```gitignore
+node_modules/
+dist/
+.env
+.DS_Store
+```

package/rules/laws/git/GIT-00014-lfs-large-binaries.md

@@ -0,0 +1,37 @@
+# Large Binaries via LFS (GIT-00014)
+
+**Source**: [06. Advanced Operations](../../../docs/meta/domains/git/06-advanced.md#2-recovery--maintenance)
+**Tags**: #operational #git #git-tooling #lfs #performance
+**Related**: [Evolvability](../../constitution/CONS-00028-evolvability.md)
+
+## Definition
+
+Large binary artifacts must not enter Git history; they must be tracked via Git LFS.
+
+## Requirements
+
+1.  **Policy**: Repositories must not store large or non-diffable binaries directly in Git history.
+2.  **Mechanism**: Use Git LFS and commit the corresponding `.gitattributes` changes.
+3.  **Platform Constraint**: On hosting platforms (e.g., GitHub), treat warning thresholds as hard guidelines and hard limits as hard blocks.
+
+## Anti-Patterns
+
+- Committing archives/media directly to the repo.
+
+## Examples
+
+**Bad:**
+
+```text
+Committed: release.zip, demo.mp4
+Result: bloated Git history; slow clone/fetch; poor diffs
+```
+
+**Good:**
+
+```bash
+git lfs track "*.zip" "*.mp4"
+git add .gitattributes
+git add release.zip
+git commit -m "chore: track large artifacts with LFS"
+```

package/rules/laws/git/GIT-00015-git-hooks.md

@@ -0,0 +1,35 @@
+# Git Hooks as a Fast Gate (GIT-00015)
+
+**Source**: [05. Configuration & Governance](../../../docs/meta/domains/git/05-configuration.md#1-git-hooks)
+**Tags**: #operational #git #git-tooling #hooks #automation
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Git hooks provide fast local feedback to prevent avoidable review and CI failures.
+
+## Requirements
+
+1.  **Deterministic**: Hooks must be fast and deterministic.
+2.  **Coverage**: Hooks should include commit message validation and quick lint/test gates.
+3.  **No Bypass**: Hook bypassing must be exceptional and explicitly justified.
+
+## Anti-Patterns
+
+- Hooks that take minutes to run.
+- Hooks that depend on network access.
+
+## Examples
+
+**Bad:**
+
+```text
+pre-commit: runs a full integration suite (10+ minutes) and downloads deps
+```
+
+**Good:**
+
+```text
+commit-msg: validates commit subject format
+pre-commit: runs fast lint/format + a small unit-test subset (<30s)
+```

package/rules/laws/git/GIT-00016-branch-protection.md

@@ -0,0 +1,34 @@
+# Branch Protection Policy (GIT-00016)
+
+**Source**: [05. Configuration & Governance](../../../docs/meta/domains/git/05-configuration.md#2-branch-protection-hosting-platform)
+**Tags**: #operational #git #git-governance #branch-protection #security
+**Related**: [Security](../../constitution/CONS-00024-security.md)
+
+## Definition
+
+Protected branches ensure that integration happens through review and verified checks.
+
+## Requirements
+
+1.  **PR Only**: Direct pushes to `main` are forbidden.
+2.  **Checks**: Required status checks must pass before merge.
+3.  **Signatures**: Protected branches must require signed commits.
+4.  **Merge Method**: Merge commits must be allowed; squash and rebase-merge must be disabled.
+
+## Anti-Patterns
+
+- Admins bypassing protections for convenience.
+
+## Examples
+
+**Bad:**
+
+```text
+main allows direct pushes; merges allowed with failing checks; unsigned commits allowed
+```
+
+**Good:**
+
+```text
+main requires PRs + passing status checks + signed commits; admins do not bypass without incident-level justification
+```

package/rules/laws/git/GIT-00017-secrets-management.md

@@ -0,0 +1,34 @@
+# Secrets Management (GIT-00017)
+
+**Source**: [05. Configuration & Governance](../../../docs/meta/domains/git/05-configuration.md#4-secrets-and-credential-hygiene)
+**Tags**: #operational #git #git-security #secrets
+**Related**: [Security](../../constitution/CONS-00024-security.md)
+
+## Definition
+
+Secrets must not be committed to Git.
+
+## Requirements
+
+1.  **No Secrets**: Secret material must not enter Git history.
+2.  **Assume Compromise**: Any committed secret must be treated as compromised and rotated.
+3.  **Detection**: Repos should use secret scanning (platform scanning and/or pre-commit tooling).
+
+## Anti-Patterns
+
+- "It was only in a private repo".
+
+## Examples
+
+**Bad:**
+
+```text
+Committed: .env with API_KEY=...
+Response: "we'll delete it later" (treat as compromised)
+```
+
+**Good:**
+
+```text
+Enable secret scanning + pre-commit checks; if a secret leaks: rotate immediately and document the incident
+```

package/rules/laws/git/GIT-00018-ci-enforcement.md

@@ -0,0 +1,33 @@
+# CI Enforcement (GIT-00018)
+
+**Source**: [05. Configuration & Governance](../../../docs/meta/domains/git/05-configuration.md#5-ci-enforcement)
+**Tags**: #operational #git #git-ci #automation #policy
+**Related**: [The Checklist](../../constitution/CONS-00031-checklist.md)
+
+## Definition
+
+CI is the authoritative gate for merge policy.
+
+## Requirements
+
+1.  **Superset**: CI checks must be a superset of local hooks for merge-critical rules.
+2.  **Policy Checks**: CI must enforce policies that hosting cannot enforce (e.g., verifying all PR commits are signed).
+3.  **Evidence**: CI results are the evidence used to approve merges.
+
+## Anti-Patterns
+
+- Hook-only rules that CI does not enforce.
+
+## Examples
+
+**Bad:**
+
+```text
+Local hooks enforce formatting, but CI does not; main accepts merges with failing checks
+```
+
+**Good:**
+
+```text
+CI runs lint/format/tests and blocks merge on failure; branch protection requires these checks
+```

package/rules/laws/git/GIT-00019-review-checklist.md

@@ -0,0 +1,39 @@
+# Code Review Checklist (GIT-00019)
+
+**Source**: [03. Collaboration & Etiquette](../../../docs/meta/domains/git/03-collaboration.md#5-review-checklist)
+**Tags**: #behavioral #git #git-review #quality
+**Related**: [The Checklist](../../constitution/CONS-00031-checklist.md)
+
+## Definition
+
+Code review enforces correctness, security, performance, and maintainability.
+
+## Requirements
+
+1.  **Correctness**: Review for intent and edge cases.
+2.  **Security**: Review for secrets, unsafe defaults, and new attack surface.
+3.  **Performance**: Review for regressions on hot paths.
+4.  **Maintainability**: Review for clarity and complexity.
+5.  **Verification**: Review that tests/CI evidence matches risk.
+
+## Anti-Patterns
+
+- Rubber-stamp approvals.
+
+## Examples
+
+**Bad:**
+
+```text
+"LGTM" with no notes, no evidence, and no review of tests/risk
+```
+
+**Good:**
+
+```text
+Checklist notes:
+- Correctness: edge cases X/Y
+- Security: input validated at boundary
+- Tests: added cases for failure paths
+- Performance: no new O(n^2) in hot loop
+```

package/rules/laws/git/GIT-00020-issue-references.md

@@ -0,0 +1,34 @@
+# Issue Reference Standards (GIT-00020)
+
+**Source**: [02. The Commit](../../../docs/meta/domains/git/02-commits.md#4-issue-references)
+**Tags**: #behavioral #git #git-traceability #issues
+**Related**: [Transparency](../../constitution/CONS-00027-transparency.md)
+
+## Definition
+
+Issue references connect changes to motivation and enable traceability.
+
+## Requirements
+
+1.  **Closing Keywords**: Use `Closes`/`Fixes`/`Resolves` when the change completes the issue.
+2.  **Context Links**: Use `Refs`/`Related-to` when the change is partial or exploratory.
+
+## Anti-Patterns
+
+- No issue reference for non-trivial changes.
+
+## Examples
+
+**Bad:**
+
+```text
+Commit message: fix bug
+PR description: (no links)
+```
+
+**Good:**
+
+```text
+PR: Refs #123 (partial); follow-up tracked in #124
+Commit: Refs #123: handle empty input safely
+```

package/rules/laws/git/GIT-00021-partial-staging.md

@@ -0,0 +1,38 @@
+# Partial Staging for Atomic Commits (GIT-00021)
+
+**Source**: [06. Advanced Operations](../../../docs/meta/domains/git/06-advanced.md#1-partial-staging-git-add-p)
+**Tags**: #behavioral #git #git-commit #atomicity
+**Related**: [Cognitive Limits](../../constitution/CONS-00012-cognitive-limits.md)
+
+## Definition
+
+Partial staging is a mechanism to keep commits atomic when a file contains multiple logical changes.
+
+## Requirements
+
+1.  **Atomicity**: If a file contains multiple logical changes, the commit must include only the relevant hunks.
+2.  **No Mixed Commits**: Refactors, formatting, and behavior changes must not be mixed in one commit.
+
+## Anti-Patterns
+
+- One commit that mixes formatting and logic changes.
+
+## Examples
+
+**Bad:**
+
+```text
+Commit includes: rename variables + reformat file + change behavior + add tests
+```
+
+**Good:**
+
+```bash
+# Stage only the relevant hunks for the behavior change
+git add -p
+git commit -m "fix: handle empty input"
+
+# Stage formatting separately (if needed)
+git add -p
+git commit -m "chore: format"
+```

package/rules/laws/git/GIT-00022-feature-flags.md

@@ -0,0 +1,33 @@
+# Feature Flags for Trunk Discipline (GIT-00022)
+
+**Source**: [01. The Workflow](../../../docs/meta/domains/git/01-workflow.md#4-feature-flags)
+**Tags**: #structural #git #git-release #flags #workflow
+**Related**: [Evolvability](../../constitution/CONS-00028-evolvability.md)
+
+## Definition
+
+Feature flags preserve "always deployable" trunk invariants by separating merge from release.
+
+## Requirements
+
+1.  **Merge Behind Flags**: Incomplete features must be merged behind a flag.
+2.  **Safe Defaults**: Flags must default to safe/off.
+3.  **Rollback**: Flags must support rapid rollback.
+
+## Anti-Patterns
+
+- Long-lived branches used to avoid feature flagging.
+
+## Examples
+
+**Bad:**
+
+```text
+Kept feature on a long-lived branch to avoid merging incomplete work; main diverged and integration became risky
+```
+
+**Good:**
+
+```text
+Merged incremental changes behind `FEATURE_X` (default OFF); enabled in staging first; can roll back by disabling flag
+```

package/rules/laws/git/GIT-00023-breaking-changes.md

@@ -0,0 +1,41 @@
+# Breaking Change Management (GIT-00023)
+
+**Source**: [01. The Workflow](../../../docs/meta/domains/git/01-workflow.md#3-the-release-lifecycle)
+**Tags**: #structural #git #git-release #versioning #compatibility #breaking-change
+**Related**: [Feature Flags for Trunk Discipline](GIT-00022-feature-flags.md), [Evolvability](../../constitution/CONS-00028-evolvability.md)
+
+## Definition
+
+Breaking changes must be managed through versioned releases with clear communication and migration paths.
+
+## Requirements
+
+1.  **Semantic Versioning**: Breaking changes must increment the major version (following SemVer).
+2.  **Changelog Documentation**: All breaking changes must be documented in a changelog with migration instructions.
+3.  **Feature Flag Transition**: When possible, breaking changes should be introduced behind feature flags with deprecation periods.
+4.  **Parallel Support**: For API-breaking changes, consider maintaining backward compatibility until consumers can migrate.
+
+## Anti-Patterns
+
+- **Silent Breaking Change**: Introducing a breaking change without version bump or documentation.
+- **Forced Migration**: Requiring immediate upgrade without migration path.
+- **Version Skipping**: Making breaking changes without incrementing major version.
+
+## Examples
+
+**Bad:**
+
+```
+git commit -m "Update API to remove deprecated endpoint"
+# No version bump, no migration instructions
+```
+
+**Good:**
+
+```
+git commit -m "feat(api): remove deprecated /v1/endpoint"
+# Accompanied by:
+# - CHANGELOG.md entry with migration guide
+# - Version tag v2.0.0
+# - Feature flag to toggle old/new behavior during transition
+```

package/rules/laws/git/GIT-00024-dependency-management.md

@@ -0,0 +1,44 @@
+# Dependency Management in Version Control (GIT-00024)
+
+**Source**: [05. Configuration & Governance](../../../docs/meta/domains/git/05-configuration.md#4-secrets-and-credential-hygiene)
+**Tags**: #operational #git #git-dependencies #security #maintenance #lockfiles
+**Related**: [Secrets Management](GIT-00017-secrets-management.md), [CI Enforcement](GIT-00018-ci-enforcement.md)
+
+## Definition
+
+Dependency updates must be managed atomically with proper version control practices to ensure reproducibility and security.
+
+## Requirements
+
+1.  **Lockfile Commitment**: Version lockfiles (package-lock.json, yarn.lock, Gemfile.lock, Cargo.lock, etc.) must be committed to the repository.
+2.  **Atomic Updates**: Dependency updates should be isolated in dedicated commits, separate from feature changes.
+3.  **Security Patches**: Critical security updates must be prioritized and applied as soon as possible.
+4.  **Update Documentation**: Major dependency updates should include rationale and testing notes in commit messages.
+5.  **Transitive Dependency Review**: Regularly review and update transitive dependencies for security vulnerabilities.
+
+## Anti-Patterns
+
+- **Floating Dependencies**: Using version ranges without lockfiles, leading to non-reproducible builds.
+- **Mixed Changes**: Combining dependency updates with feature development in the same commit.
+- **Ignored Security Alerts**: Dismissing security vulnerability reports for dependencies.
+- **Manual Editing**: Manually editing lockfiles instead of using package manager commands.
+
+## Examples
+
+**Bad:**
+
+```
+git commit -m "Add new feature and update dependencies"
+# Mixed concerns, no clear audit trail
+```
+
+**Good:**
+
+```
+git commit -m "chore(deps): update React to v18.2.0
+
+- Improves concurrent rendering performance
+- Includes security fixes for CVE-2023-XXXXX
+- Tested with existing component suite"
+# Followed by separate feature commit
+```

package/rules/laws/git/GIT-00025-large-repository-optimization.md

@@ -0,0 +1,54 @@
+# Large Repository Optimization (GIT-00025)
+
+**Source**: [06. Advanced Operations](../../../docs/meta/domains/git/06-advanced.md#4-large-repos--dependencies)
+**Tags**: #operational #git #git-performance #large-repo #monorepo #optimization
+**Related**: [Large Binaries via LFS](GIT-00014-lfs-large-binaries.md), [Partial Staging for Atomic Commits](GIT-00021-partial-staging.md)
+
+## Definition
+
+Large repositories must use optimization techniques to maintain developer productivity and CI efficiency.
+
+## Requirements
+
+1.  **Sparse Checkout**: Repositories exceeding 1GB should consider sparse checkout configurations for focused development.
+2.  **Shallow Clones**: CI systems should use shallow clones (`--depth=1`) where appropriate to reduce clone times.
+3.  **LFS for Binaries**: Large binary files (>50MB) must be tracked via Git LFS.
+4.  **History Optimization**: Consider periodic history cleanup (git gc, repack) for repositories with extensive history.
+5.  **Monorepo Structure**: If using monorepo structure, enforce clear directory boundaries and ownership.
+
+## Anti-Patterns
+
+- **Full History Cloning**: Always cloning full history in CI when shallow would suffice.
+- **Binary Bloat**: Committing large binaries directly to Git history.
+- **Unbounded Growth**: Allowing repository size to grow without optimization considerations.
+- **Cross-Cutting Dependencies**: Creating circular dependencies between monorepo packages.
+
+## Examples
+
+**Bad:**
+
+```
+# CI configuration cloning full 10GB repository history every build
+git clone https://github.com/company/monorepo
+```
+
+**Good:**
+
+```
+# CI configuration with optimization
+git clone --depth=1 --filter=blob:none https://github.com/company/monorepo
+cd monorepo
+git sparse-checkout set packages/frontend
+```
+
+**Monorepo Structure Example:**
+
+```
+monorepo/
+├── packages/
+│   ├── frontend/     # Owned by Frontend Team
+│   ├── backend/      # Owned by Backend Team
+│   └── shared/       # Shared ownership
+├── tools/            # Build tooling
+└── docs/             # Documentation
+```