lgtm-specs 0.0.4

package/rules/constitution/README.md

@@ -0,0 +1,52 @@
+# The Constitution (Universal Rules)
+
+These are the immutable engineering truths that apply to all software projects. In the LGTM legal framework, each rule file represents an **Article** of the Constitution.
+
+## Index
+
+### Structural Integrity
+
+- [CONS-00001: Single Responsibility Principle](CONS-00001-srp.md): A module should have one, and only one, reason to change.
+- [CONS-00002: Open/Closed Principle](CONS-00002-ocp.md): Open for extension, closed for modification.
+- [CONS-00003: Liskov Substitution Principle](CONS-00003-lsp.md): Subtypes must be substitutable for their base types.
+- [CONS-00004: Interface Segregation Principle](CONS-00004-isp.md): Clients should not depend on interfaces they do not use.
+- [CONS-00005: Dependency Inversion Principle](CONS-00005-dip.md): Depend on abstractions, not concretions.
+- [CONS-00006: DRY](CONS-00006-dry.md): Single Source of Truth; avoid drift.
+- [CONS-00007: Law of Demeter](CONS-00007-demeter.md): Talk to friends, not strangers (one dot rule).
+- [CONS-00008: Composition Over Inheritance](CONS-00008-composition.md): Flatten hierarchies; delegate behavior.
+- [CONS-00022: Orthogonality](CONS-00022-orthogonality.md): Decouple components so changes don't propagate side effects.
+
+### Cognitive Ergonomics
+
+- [CONS-00009: Deep Modules](CONS-00009-deep-modules.md): Simple interface, complex implementation.
+- [CONS-00010: KISS](CONS-00010-kiss.md): Complexity is a cost; avoid speculative generality.
+- [CONS-00011: YAGNI](CONS-00011-yagni.md): Do not implement features until necessary.
+- [CONS-00012: Cognitive Limits](CONS-00012-cognitive-limits.md): Atomic commits; PRs under 400 lines.
+- [CONS-00013: Boy Scout Rule](CONS-00013-boy-scout.md): Leave code cleaner than you found it.
+- [CONS-00014: Broken Windows Theory](CONS-00014-broken-windows.md): Fix bad designs immediately to prevent normalization of deviance.
+- [CONS-00031: The Checklist](CONS-00031-checklist.md): Automate rote verification; offload cognitive load to machines.
+- [CONS-00032: Documentation](CONS-00032-documentation.md): Explain the "Why", not the "How".
+
+### Behavioral Correctness
+
+- [CONS-00015: Safety by Design](CONS-00015-safety.md): Make illegal states unrepresentable (Enums/Unions).
+- [CONS-00016: Command-Query Separation](CONS-00016-cqs.md): Methods should do work OR return data, not both.
+- [CONS-00023: Determinism](CONS-00023-determinism.md): Same input, same output; explicit dependencies.
+- [CONS-00024: Security](CONS-00024-security.md): Least privilege, secure defaults, input validation.
+
+### Runtime Survivability
+
+- [CONS-00017: Postel's Law](CONS-00017-postel.md): Conservative output, liberal input (robustness).
+- [CONS-00018: CAP & PACELC](CONS-00018-cap.md): Choose Consistency or Availability explicitly in distributed systems.
+- [CONS-00019: Fallacies of Distributed Computing](CONS-00019-fallacies.md): Handle timeouts, retries, and network partitions.
+- [CONS-00025: Efficiency](CONS-00025-efficiency.md): Aware of Big-O; bound resource usage.
+- [CONS-00026: Resilience](CONS-00026-resilience.md): Circuit breakers, idempotency, and graceful degradation.
+
+### Operational Lifecycle
+
+- [CONS-00020: Shift Left](CONS-00020-shift-left.md): Verify early (Design/CI) to reduce rework cost.
+- [CONS-00021: Socio-Technical Congruence](CONS-00021-congruence.md): Align code boundaries with team ownership.
+- [CONS-00027: Transparency](CONS-00027-transparency.md): Telemetry, structured logging, and observability.
+- [CONS-00028: Evolvability](CONS-00028-evolvability.md): Testability, Feature Flags, and Versioning.
+- [CONS-00029: Operability](CONS-00029-operability.md): Runbooks, automation, and ease of maintenance.
+- [CONS-00030: Rework Cycle](CONS-00030-rework-cycle.md): Pay down debt to prevent the death spiral.

package/rules/laws/README.md

@@ -0,0 +1,15 @@
+# The Laws (Domain Contexts)
+
+This directory contains the strict engineering standards for specific technologies.
+
+## File Structure
+
+Each file acts as a standalone "Knowledge Module".
+
+## Index of Domains
+
+- **[Go](go/README.md)**: Rules for the Go language.
+- **[TypeScript](typescript/README.md)**: Rules for TypeScript/JavaScript.
+- **[Git](git/README.md)**: Rules for Git version control.
+- **[Bitcoin](bitcoin/README.md)**: Rules for Bitcoin financial engineering.
+- **[Default](default.md)**: Fallback rules for unknown languages.

package/rules/laws/bitcoin/BTC-00001-amounts-as-satoshis.md

@@ -0,0 +1,39 @@
+# Amounts as Satoshis (BTC-00001)
+
+**Source**: [Bitcoin: Units & Amounts](../../../docs/meta/domains/bitcoin/01-units.md#amount-representation)
+**Tags**: #behavioral #bitcoin #finance #safety
+**Related**: [Determinism](../../constitution/CONS-00023-determinism.md), [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Represent monetary values as integer satoshis; convert to display units only at boundaries.
+
+## Requirements
+
+1.  **Integers Only**: Represent amounts as integer satoshis.
+2.  **No Floats**: Do not use floating point types for any monetary computation.
+3.  **Explicit Units**: Encode units in names and types (e.g., `amount_sats`, `fee_rate_sat_vb`).
+4.  **Boundary Conversion**: Parse/format BTC strings only at UI/API boundaries; store and compute in sats.
+
+## Anti-Patterns
+
+- **Float Money**: `float64` BTC math or rounding by formatting.
+- **Unit Ambiguity**: `amount` with no unit, or mixing sats and BTC in one codepath.
+
+## Examples
+
+**Bad:**
+
+```python
+btc = float(input_btc)
+fee_btc = btc * 0.001
+send_btc = btc - fee_btc
+```
+
+**Good:**
+
+```python
+amount_sats = int(input_sats)
+fee_sats = estimate_fee_sats(amount_sats)
+send_sats = amount_sats - fee_sats
+```

package/rules/laws/bitcoin/BTC-00002-broadcast-not-cancelable.md

@@ -0,0 +1,36 @@
+# Broadcast Is Not Cancelable (BTC-00002)
+
+**Source**: [Bitcoin: Broadcast, Cancellation, and Replacement](../../../docs/meta/domains/bitcoin/02-broadcast-cancellation.md#broadcast-is-not-retractable)
+**Tags**: #operational #bitcoin #finance #safety
+**Related**: [Resilience](../../constitution/CONS-00026-resilience.md), [Transparency](../../constitution/CONS-00027-transparency.md)
+
+## Definition
+
+A broadcast transaction cannot be safely canceled; the only practical "cancellation" is a conflicting spend, and it is not final until confirmed.
+
+## Requirements
+
+1.  **No Cancel Assumption**: Do not design flows that assume a broadcast can be withdrawn.
+2.  **Conflict Model**: If you support cancellation, implement it as a conflicting spend of at least one input (replacement), not deletion.
+3.  **Finality Gate**: Treat cancellation as incomplete until one of the conflicting transactions confirms.
+4.  **User Messaging**: Surface the state as "pending" until confirmation; do not claim success early.
+
+## Anti-Patterns
+
+- **Local Delete**: Marking a tx "canceled" because it is not in _your_ mempool.
+- **Instant Cancel**: Treating a replacement attempt as guaranteed.
+
+## Examples
+
+**Bad:**
+
+```text
+"Cancel" = remove tx from local DB; assume it will never confirm
+```
+
+**Good:**
+
+```text
+"Cancel" = create and broadcast a conflicting spend (replacement)
+state remains PENDING until one tx confirms
+```

package/rules/laws/bitcoin/BTC-00003-fee-rate-math-rounding.md

@@ -0,0 +1,37 @@
+# Fee Rate Math & Rounding (BTC-00003)
+
+**Source**: [Bitcoin: Fee Rates, Rational Math, and Rounding](../../../docs/meta/domains/bitcoin/03-fee-rates-rounding.md#rational-fee-rates)
+**Tags**: #behavioral #bitcoin #finance #determinism
+**Related**: [Determinism](../../constitution/CONS-00023-determinism.md), [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Fee rate calculations must be unit-explicit and exact until the final conversion to integer satoshis.
+
+## Requirements
+
+1.  **Rational Math**: Use arbitrary-precision rational math for fee rates and intermediate results.
+2.  **Explicit Units**: Make feerate units explicit (prefer sat/vB) and convert explicitly.
+3.  **Rounding Policy**: Define and test rounding; for fee payment constraints, prefer rounding up.
+4.  **No Silent Conversions**: Do not accept a bare number as a feerate without a unit.
+
+## Anti-Patterns
+
+- **Float Fee Rate**: `float64` feerate calculations.
+- **Magic Feerate**: `fee_rate = 25` without unit.
+
+## Examples
+
+**Bad:**
+
+```text
+fee_rate = 1.5
+fee_sats = int(fee_rate * vbytes)  # implicit unit + truncation
+```
+
+**Good:**
+
+```text
+fee_rate_sat_vb = Rat("1.5")
+fee_sats = ceil(fee_rate_sat_vb * vbytes)
+```

package/rules/laws/bitcoin/BTC-00004-confirmations-and-reorgs.md

@@ -0,0 +1,40 @@
+# Confirmations & Reorg Safety (BTC-00004)
+
+**Source**: [Bitcoin: Confirmations & Reorgs](../../../docs/meta/domains/bitcoin/04-confirmations-reorgs.md#reorg-handling)
+**Tags**: #operational #bitcoin #finance #resilience
+**Related**: [Resilience](../../constitution/CONS-00026-resilience.md), [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Confirmation state must be explicit and reorg-safe; derived state must be reversible.
+
+## Requirements
+
+1.  **Explicit Policy**: Define confirmation thresholds per flow (deposit credit, withdrawal completion).
+2.  **Track Hash+Height**: Record both block height and block hash for each processed block.
+3.  **Rollback**: On reorg detection, rollback derived state to the common ancestor and re-derive.
+4.  **No Finality Claims**: Do not treat 0-conf as final for high-risk flows.
+5.  **Practical Depth**: Design for 1-2 block reorgs as a practical concern; deeper reorgs are possible.
+
+## Anti-Patterns
+
+- **Height-Only Tracking**: Storing only height and assuming the chain never reorganizes.
+- **Irreversible Derivation**: Mutating balances with no ability to revert on reorg.
+
+## Examples
+
+**Bad:**
+
+```text
+processed_height = 840000
+balances += deposits_in_height(840000)
+```
+
+**Good:**
+
+```text
+processed_tip = { height: 840000, hash: H }
+if chain_tip.hash != processed_tip.hash_at_height:
+  rollback_to_common_ancestor()
+  reprocess_forward()
+```

package/rules/laws/bitcoin/BTC-00005-address-gap-limit.md

@@ -0,0 +1,37 @@
+# Address Gap Limit Safety (BTC-00005)
+
+**Source**: [Bitcoin: Address Gap Limit and Recovery Risk](../../../docs/meta/domains/bitcoin/05-address-gap-limit.md#the-gap-limit-problem)
+**Tags**: #operational #bitcoin #finance #resilience
+**Related**: [Resilience](../../constitution/CONS-00026-resilience.md), [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Do not generate large sequences of unused receive addresses without controlling the address gap limit; it can cause recovery to miss funds.
+
+## Requirements
+
+1.  **Gap Awareness**: Track issued-vs-used indices and the effective gap on each receive branch.
+2.  **Bounded Issuance**: Do not exceed the operational gap limit without an explicit policy.
+3.  **Recovery Proof**: Have a documented recovery procedure that will rediscover funds after typical address issuance patterns.
+4.  **Alerting**: Emit warnings when approaching the configured gap limit.
+
+## Anti-Patterns
+
+- **Always New, Unbounded**: Issuing a new address for every request with no gap monitoring.
+- **Assumed Recovery**: Assuming seed restore will find all funds regardless of issuance.
+
+## Examples
+
+**Bad:**
+
+```text
+service generates 100+ unused deposit addresses
+seed restore scans only default lookahead and stops early
+```
+
+**Good:**
+
+```text
+service enforces a gap limit policy and tracks issued-vs-used indices
+recovery procedure includes configured lookahead/rescan bounds
+```

package/rules/laws/bitcoin/BTC-00006-relay-is-policy-dependent.md

@@ -0,0 +1,36 @@
+# Relay Is Policy-Dependent (BTC-00006)
+
+**Source**: [Bitcoin: Relay Policy Gates](../../../docs/meta/domains/bitcoin/06-relay-policy.md#relay-is-policy-dependent)
+**Tags**: #operational #bitcoin #finance #resilience
+**Related**: [Resilience](../../constitution/CONS-00026-resilience.md), [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Transaction propagation is not guaranteed by consensus; it depends on local node policy and peer relay filters.
+
+## Requirements
+
+1.  **No Relay Assumption**: Do not treat "valid" as equivalent to "propagated".
+2.  **Policy Explicitness**: Make relay/mempool policy inputs explicit (dust, minimum feerate, peer filters).
+3.  **Observable Failure**: Treat relay failure as a normal outcome; capture enough context (feerate, size, policy inputs) to debug.
+
+## Anti-Patterns
+
+- **Consensus Confusion**: Assuming "valid" implies "will propagate".
+- **Opaque Policy**: Fee/relay logic with no visibility into which policy gate rejected it.
+
+## Examples
+
+**Bad:**
+
+```text
+tx is valid => it will broadcast
+ignore policy gates and peer filtering
+```
+
+**Good:**
+
+```text
+construct tx with explicit relay policy checks
+expect broadcast/relay to be policy-dependent, not guaranteed
+```

package/rules/laws/bitcoin/BTC-00007-dust-policy.md

@@ -0,0 +1,36 @@
+# Dust Policy (BTC-00007)
+
+**Source**: [Bitcoin: Relay Policy Gates](../../../docs/meta/domains/bitcoin/06-relay-policy.md#gate-1-dust)
+**Tags**: #operational #bitcoin #finance #resilience
+**Related**: [Relay Is Policy-Dependent](BTC-00006-relay-is-policy-dependent.md)
+
+## Definition
+
+Transactions that create dust outputs may be non-standard and not relayed by default.
+
+## Requirements
+
+1.  **Dust Guard**: Do not create outputs that fall below the dust threshold for the prevailing relay policy.
+2.  **Change Discipline**: If change would be dust, either add it to fee or restructure inputs/outputs.
+3.  **Explicit Policy**: Treat dust limits as policy inputs; do not hard-code assumptions without documenting units and sources.
+
+## Anti-Patterns
+
+- **Dust Change**: Creating dust change outputs and expecting propagation.
+- **Silent Fee Absorb**: Dropping dust value without tracking it as fee.
+
+## Examples
+
+**Bad:**
+
+```text
+create change output regardless of size
+"broadcast failed" with no dust accounting
+```
+
+**Good:**
+
+```text
+if change < dust_threshold: add change to fee
+else: create change output
+```

package/rules/laws/bitcoin/BTC-00008-min-relay-fee.md

@@ -0,0 +1,36 @@
+# Minimum Relay Fee (BTC-00008)
+
+**Source**: [Bitcoin: Relay Policy Gates](../../../docs/meta/domains/bitcoin/06-relay-policy.md#gate-2-node-minimum-fee)
+**Tags**: #operational #bitcoin #finance #resilience
+**Related**: [Relay Is Policy-Dependent](BTC-00006-relay-is-policy-dependent.md), [Fee Rate Math & Rounding](BTC-00003-fee-rate-math-rounding.md)
+
+## Definition
+
+Nodes enforce a minimum feerate for relay/mempool admission; transactions below it may not propagate.
+
+## Requirements
+
+1.  **Feerate Computation**: Compute and track feerate with explicit units.
+2.  **Policy-Aware Sending**: Compare feerate against the broadcasting node's current minimum policy.
+3.  **Adaptive Behavior**: Treat minimum fee as dynamic under mempool pressure; do not assume a constant.
+
+## Anti-Patterns
+
+- **Static Fee Assumption**: Hard-coding a minimum feerate and assuming it always relays.
+- **Unit Drift**: Mixing sat/vB with sat/kvB without explicit conversion.
+
+## Examples
+
+**Bad:**
+
+```text
+fee_rate_sat_vb = 1
+assume every node relays 1 sat/vB
+```
+
+**Good:**
+
+```text
+fee_rate_sat_vb computed and logged
+if below node minimum: bump fee or mark as likely-nonrelayed
+```

package/rules/laws/bitcoin/BTC-00009-feefilter.md

@@ -0,0 +1,36 @@
+# Peer feefilter (BTC-00009)
+
+**Source**: [BIP-0133 (feefilter message)](https://raw.githubusercontent.com/bitcoin/bips/master/bip-0133.mediawiki#specification)
+**Tags**: #operational #bitcoin #finance #resilience
+**Related**: [Relay Is Policy-Dependent](BTC-00006-relay-is-policy-dependent.md)
+
+## Definition
+
+Peers may advertise a `feefilter` threshold; they may not announce or relay transactions below that feerate.
+
+## Requirements
+
+1.  **Expectation Setting**: If a peer sets a `feefilter`, do not expect that peer to propagate too-low feerate transactions.
+2.  **Unit Clarity**: Treat the filter as a feerate in satoshis per kilobyte.
+3.  **Propagation Strategy**: Broadcast to multiple peers and observe relays; do not depend on a single peer.
+
+## Anti-Patterns
+
+- **Single Peer Reliance**: Treating one peer's lack of relay as proof the tx is "not broadcast".
+- **Unit Confusion**: Treating feefilter as sat/vB without conversion.
+
+## Examples
+
+**Bad:**
+
+```text
+connected peer sets feefilter=5000 sat/kvB
+send 1 sat/vB tx and expect inv relay
+```
+
+**Good:**
+
+```text
+if peers set feefilter above tx feerate: expect reduced relay
+broadcast to multiple peers and verify propagation via relays
+```

package/rules/laws/bitcoin/README.md

@@ -0,0 +1,29 @@
+# The Law of Bitcoin
+
+These rules define the engineering standards for Bitcoin-related development within the LGTM organization.
+
+## Index
+
+### Money & Units
+
+- [BTC-00001: Amounts as Satoshis](BTC-00001-amounts-as-satoshis.md): Integers only; explicit units at boundaries.
+
+### Mempool & Replacement
+
+- [BTC-00002: Broadcast Is Not Cancelable](BTC-00002-broadcast-not-cancelable.md): Treat broadcast as irrevocable; replacements are conflicting spends.
+
+### Fees
+
+- [BTC-00003: Fee Rate Math & Rounding](BTC-00003-fee-rate-math-rounding.md): Rational feerates; explicit ceiling/floor policy.
+
+### Confirmations & Recovery
+
+- [BTC-00004: Confirmations & Reorg Safety](BTC-00004-confirmations-and-reorgs.md): Explicit confirmation policy; reorg-safe state.
+- [BTC-00005: Address Gap Limit Safety](BTC-00005-address-gap-limit.md): Avoid losing funds due to lookahead limits.
+
+### Relay Policy
+
+- [BTC-00006: Relay Is Policy-Dependent](BTC-00006-relay-is-policy-dependent.md): Validity does not imply propagation.
+- [BTC-00007: Dust Policy](BTC-00007-dust-policy.md): Dust outputs may be non-standard and not relayed.
+- [BTC-00008: Minimum Relay Fee](BTC-00008-min-relay-fee.md): Feerate must meet node policy; minimums can be dynamic.
+- [BTC-00009: Peer feefilter](BTC-00009-feefilter.md): Peers may filter low-fee tx announcements.

package/rules/laws/default.md

@@ -0,0 +1,30 @@
+# The Law of Common Sense (Default)
+
+**Source**: [Industry Best Practices](../../docs/meta/industry_best_practices.md#3-universal-fundamentals)
+**Tags**: #operational #universal #defaults
+**Related**: [Default Policy](../policies/default.md), [KISS](../constitution/CONS-00010-kiss.md)
+**Context**: Used when no specific language law exists.
+
+## Definition
+
+When no specific law applies, follow the collective wisdom of the software engineering industry.
+
+## Requirements
+
+1.  **Linting**: Follow the standard linter for the language (e.g., `flake8` for Python, `clippy` for Rust).
+2.  **Formatting**: Use the standard formatter (e.g., `black`, `rustfmt`, `prettier`).
+3.  **Naming**: Follow the language's naming convention (snake_case for Python, camelCase for JS/Go).
+4.  **Testing**: Write unit tests for all logic. Use the standard test runner.
+
+## Anti-Patterns
+
+- **Bikeshedding**: Arguing about style instead of using the formatter.
+- **No Tests**: "I'll add tests later."
+
+## Examples
+
+**Bad:**
+Manually aligning equals signs.
+
+**Good:**
+Running `format` on save.

package/rules/laws/git/GIT-00001-atomic-commit.md

@@ -0,0 +1,29 @@
+# The Atomic Commit (GIT-00001)
+
+**Source**: [02. The Commit](../../../docs/meta/domains/git/02-commits.md#1-atomicity-the-golden-rule)
+**Tags**: #behavioral #git #git-commit #atomicity #process
+**Related**: [Cognitive Limits](../../constitution/CONS-00012-cognitive-limits.md)
+
+## Definition
+
+A commit must represent a single, indivisible logical change.
+
+## Requirements
+
+1.  **Cognitive Focus**: The change must be understandable in a single mental pass.
+2.  **Revertability**: Reverting the commit must remove the feature/fix cleanly without breaking the build.
+3.  **Independence**: The commit must build and pass tests in isolation (supporting `git bisect`).
+
+## Anti-Patterns
+
+- "Big Ball of Mud": Mixing refactoring, formatting, and logic changes.
+- "WIP": Committing broken code.
+
+## Examples
+
+**Bad:**
+`feat: add login and refactor user model` (Two concerns).
+
+**Good:**
+`refactor(user): decouple auth logic` (Commit 1)
+`feat(pkg): implement login handler` (Commit 2)

package/rules/laws/git/GIT-00002-imperative-subject.md

@@ -0,0 +1,27 @@
+# The Imperative Subject (GIT-00002)
+
+**Source**: [02. The Commit](../../../docs/meta/domains/git/02-commits.md#3-conventional-commits-v100)
+**Tags**: #behavioral #git #git-commit #formatting #communication
+**Related**: [The Checklist](../../constitution/CONS-00031-checklist.md)
+
+## Definition
+
+Commit subjects must use the imperative mood to match Git's internal language.
+
+## Requirements
+
+1.  **Mood**: Use "Add", not "Added" or "Adds".
+2.  **The Sentence Test**: The subject should complete the sentence: "If applied, this commit will... [subject]".
+
+## Anti-Patterns
+
+- `Fixed bug` (Past tense).
+- `Fixes bug` (Present continuous).
+
+## Examples
+
+**Bad:**
+`Updated README`
+
+**Good:**
+`Update README` (matches "If applied, this commit will [Update README]").

package/rules/laws/git/GIT-00003-formatting-50-72.md

@@ -0,0 +1,28 @@
+# The 50/72 Formatting Rule (GIT-00003)
+
+**Source**: [02. The Commit](../../../docs/meta/domains/git/02-commits.md#3-conventional-commits-v100)
+**Tags**: #behavioral #git #git-commit #formatting
+**Related**: [Documentation](../../constitution/CONS-00032-documentation.md)
+
+## Definition
+
+Commit messages must adhere to standard terminal-width constraints.
+
+## Requirements
+
+1.  **Subject**: Max 50 characters. Ensures readability in `git log --oneline`.
+2.  **Separator**: Mandatory blank line between subject and body.
+3.  **Body**: Wrap at 72 characters. Ensures readability in standard terminals (80 cols - indentation).
+
+## Anti-Patterns
+
+- No body.
+- One long line that scrolls horizontally forever.
+
+## Examples
+
+**Bad:**
+`feat(ui): add new button color because the designer said so and it looks better on mobile`
+
+**Good:**
+`feat(ui): update button color`

package/rules/laws/git/GIT-00004-trunk-based.md

@@ -0,0 +1,28 @@
+# Trunk-Based Flow (GIT-00004)
+
+**Source**: [01. The Workflow](../../../docs/meta/domains/git/01-workflow.md#1-the-single-source-of-truth)
+**Tags**: #structural #git #git-branch #workflow #trunk
+**Related**: [Evolvability](../../constitution/CONS-00028-evolvability.md)
+
+## Definition
+
+Development occurs on short-lived branches merged frequently into a single shared trunk.
+
+## Requirements
+
+1.  **Lifespan**: Feature branches should be short-lived (target < 1 week).
+2.  **Toggle**: Incomplete features must be merged behind a Feature Flag.
+3.  **Deployability**: `main` must always be in a deployable state.
+
+## Anti-Patterns
+
+- **GitFlow**: Long-lived `develop` branches.
+- **Merge Hell**: Integrating weeks of divergent code.
+
+## Examples
+
+**Bad:**
+`feature/auth-v2` (Last commit: 3 weeks ago).
+
+**Good:**
+`feat/pkg-scaffold` (Merged the same day).

package/rules/laws/git/GIT-00005-public-immutability.md

@@ -0,0 +1,26 @@
+# Public History Immutability (GIT-00005)
+
+**Source**: [04. History Integrity & Security](../../../docs/meta/domains/git/04-integrity.md#1-immutable-public-history)
+**Tags**: #behavioral #git #git-integrity #history #immutability
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Once a commit is pushed to a shared branch, it is immutable.
+
+## Requirements
+
+1.  **Force Push**: Forbidden on `main` or `master`.
+2.  **Rebase**: Forbidden on shared branches.
+
+## Anti-Patterns
+
+- `git push -f origin main` to fix a typo.
+
+## Examples
+
+**Bad:**
+Rewriting history to remove a secret (rotate the secret instead).
+
+**Good:**
+`git revert <sha>` to undo a mistake.

package/rules/laws/git/GIT-00006-signing.md

@@ -0,0 +1,27 @@
+# Cryptographic Identity (GIT-00006)
+
+**Source**: [04. History Integrity & Security](../../../docs/meta/domains/git/04-integrity.md#3-cryptographic-identity)
+**Tags**: #operational #git #git-security #signing
+**Related**: [Security](../../constitution/CONS-00024-security.md)
+
+## Definition
+
+All commits must be cryptographically attributable to a verified author.
+
+## Requirements
+
+1.  **Signing**: All commits must be signed (GPG or SSH).
+2.  **Main Enforcement**: Protected branches (e.g., `main`) must reject unsigned commits via branch protection.
+3.  **PR Enforcement**: CI must fail pull requests that contain any unsigned commits.
+
+## Anti-Patterns
+
+- Committing with `user.email` set to `root@localhost`.
+
+## Examples
+
+**Bad:**
+Unverified commit.
+
+**Good:**
+Commit with `Verified` badge.

package/rules/laws/git/GIT-00007-reviewer-capital.md

@@ -0,0 +1,26 @@
+# Reviewer Capital (GIT-00007)
+
+**Source**: [03. Collaboration & Etiquette](../../../docs/meta/domains/git/03-collaboration.md#2-reviewer-capital)
+**Tags**: #behavioral #git #git-review #collaboration
+**Related**: [Collaboration](../../constitution/CONS-00027-transparency.md)
+
+## Definition
+
+Code review is a negotiation where social capital is the currency.
+
+## Requirements
+
+1.  **Default to Yes**: Accept reviewer suggestions unless there is a critical technical blocker.
+2.  **Responsiveness**: Acknowledge feedback immediately.
+
+## Anti-Patterns
+
+- Debating style choices (bikeshedding) when the reviewer asks for a change.
+
+## Examples
+
+**Bad:**
+"I prefer my variable name."
+
+**Good:**
+"Done. Updated as suggested."