lgtm-specs 0.0.4

package/rules/constitution/CONS-00015-safety.md

@@ -0,0 +1,46 @@
+# Safety by Design (CONS-00015)
+
+**Source**: [Formal Methods & Correctness](../../docs/meta/industry_best_practices.md#61-safety-by-design)
+**Tags**: #behavioral #correctness #safety
+**Related**: [LSP](CONS-00003-lsp.md), [Determinism](CONS-00023-determinism.md)
+
+## Definition
+
+Illegal states should be unrepresentable. Testing detects bugs; design prevents them.
+
+## Requirements
+
+1.  **Immutability**: Prefer immutable data structures to prevent race conditions.
+2.  **State Machines**: Use an explicit state model (enum/discriminated states) for mutually exclusive states, not
+    boolean flags.
+3.  **Parsing**: Validate all external input at the boundary (schema validation).
+
+## Anti-Patterns
+
+- **Boolean Soup**: `isLoading`, `isError`, `isSuccess` flags that can all be true at once.
+- **Primitive Obsession**: Using `string` for an Email Address instead of a Value Object.
+
+## Examples
+
+**Bad:**
+
+```text
+state = {
+  loading: true|false,
+  error_message: "..."|empty,
+  data: user,
+}
+
+# invalid combinations are possible (e.g., loading=true and error_message set)
+```
+
+**Good:**
+
+```text
+# a single discriminant + payload makes illegal states unrepresentable
+State = one_of(
+  { status: "loading" },
+  { status: "error", message: "..." },
+  { status: "success", data: user },
+)
+```

package/rules/constitution/CONS-00016-cqs.md

@@ -0,0 +1,39 @@
+# Command-Query Separation (CONS-00016)
+
+**Source**: [Formal Methods & Correctness](../../docs/meta/industry_best_practices.md#62-command-query-separation-cqs)
+**Tags**: #behavioral #predictability #design
+**Related**: [Determinism](CONS-00023-determinism.md)
+
+## Definition
+
+Methods must either perform an action (Command) or return data (Query), but not both.
+
+## Requirements
+
+1.  **Side Effects**: A method that returns a value should be "Pure" (no observable side effects).
+2.  **Command Returns**: A method that mutates state should not also return a value.
+
+## Anti-Patterns
+
+- **The Sneaky Get**: `getUser()` that also increments a login counter.
+- **The Talkative Set**: `setUser()` that returns the old user object.
+
+## Examples
+
+**Bad:**
+
+```text
+function login(credentials):
+  update_login_state(credentials.user_id)
+  return current_user()  # command + query mixed
+```
+
+**Good:**
+
+```text
+function login(credentials):
+  update_login_state(credentials.user_id)
+
+function current_user():
+  return user
+```

package/rules/constitution/CONS-00017-postel.md

@@ -0,0 +1,35 @@
+# Postel's Law (Robustness Principle) (CONS-00017)
+
+**Source**: [Formal Methods & Correctness](../../docs/meta/industry_best_practices.md#63-postels-law)
+**Tags**: #runtime #robustness #interface
+**Related**: [Safety by Design](CONS-00015-safety.md), [Resilience](CONS-00026-resilience.md)
+
+## Definition
+
+Be conservative in what you do, be liberal in what you accept.
+
+## Requirements
+
+1.  **Strict Output**: APIs must return strict, validated, predictable data structures.
+2.  **Graceful Input**: Parse inputs tolerantly (ignore unknown fields) where safe, but reject invalid data structures explicitly.
+
+## Anti-Patterns
+
+- **Brittle Parsing**: Crashing the whole app because one JSON field was missing.
+- **Loose Output**: Returning internal DB objects directly to the API consumer.
+
+## Examples
+
+**Bad:**
+
+```text
+# Returning an internal storage record directly (may include secret/internal fields)
+return user_record
+```
+
+**Good:**
+
+```text
+# Returning a strict, sanitized response shape
+return { id: user.id, name: user.name }
+```

package/rules/constitution/CONS-00018-cap.md

@@ -0,0 +1,35 @@
+# CAP & PACELC (CONS-00018)
+
+**Source**: [Distributed Systems](../../docs/meta/industry_best_practices.md#71-cap--pacelc)
+**Tags**: #runtime #distributed-systems #tradeoffs #consistency
+**Related**: [Fallacies](CONS-00019-fallacies.md), [Resilience](CONS-00026-resilience.md)
+
+## Definition
+
+In a distributed system, you cannot have Consistency, Availability, and Partition Tolerance simultaneously. You must choose.
+
+## Requirements
+
+1.  **Explicit Mode**: Distributed components must document their consistency model (Eventual vs Strong).
+2.  **Failure Handling**: Code must handle network partitions (timeouts, retries) explicitly.
+
+## Anti-Patterns
+
+- **Magical Consistency**: Assuming a write to a replicated datastore is instantly visible to a read.
+- **Ignoring Partitions**: Coding as if the network never splits.
+
+## Examples
+
+**Bad:**
+
+```text
+write(x)
+return read(x)  # assumes read-after-write consistency
+```
+
+**Good:**
+
+```text
+write(x, consistency="quorum")
+return read(x, consistency="quorum")
+```

package/rules/constitution/CONS-00019-fallacies.md

@@ -0,0 +1,37 @@
+# Fallacies of Distributed Computing (CONS-00019)
+
+**Source**: [Distributed Systems](../../docs/meta/industry_best_practices.md#72-fallacies-of-distributed-computing)
+**Tags**: #runtime #distributed-systems #resilience
+**Related**: [Resilience](CONS-00026-resilience.md), [Security](CONS-00024-security.md)
+
+## Definition
+
+The 8 false assumptions that lead to distributed system failures.
+
+## Requirements
+
+1.  **Timeouts**: Every network call must have a timeout.
+2.  **Retries**: Idempotent operations should have exponential backoff.
+3.  **Security**: Encrypt all transit; do not trust internal networks.
+4.  **Topology**: Don't hardcode IPs; use Service Discovery.
+
+## Anti-Patterns
+
+- **Infinite Wait**: Network calls without an explicit timeout (and cancellation when applicable).
+- **Assumption of Zero Latency**: Making 100 sequential calls in a loop.
+
+## Examples
+
+**Bad:**
+
+```text
+users = []
+for id in ids:
+  users.append(api.get_user(id))  # sequential
+```
+
+**Good:**
+
+```text
+users = api.batch_get_users(ids)
+```

package/rules/constitution/CONS-00020-shift-left.md

@@ -0,0 +1,28 @@
+# Shift Left (CONS-00020)
+
+**Source**: [Systems Theory & Dynamics](../../docs/meta/industry_best_practices.md#51-shift-left)
+**Tags**: #operational #process #velocity #quality
+**Related**: [Rework Cycle](CONS-00030-rework-cycle.md), [Safety](CONS-00015-safety.md)
+
+## Definition
+
+Verification activities should happen as early as possible. Remediating a defect in production is 100x more expensive than in design.
+
+## Requirements
+
+1.  **Design First**: Complex features require a Design Doc or RFC before code.
+2.  **Impact Analysis**: Check dependencies before refactoring.
+3.  **Static Analysis**: Linting and type checking must run locally (pre-commit) and in CI.
+
+## Anti-Patterns
+
+- **"We'll fix it in QA"**: Pushing known buggy code.
+- **Coding before Thinking**: Writing implementation details without a clear interface.
+
+## Examples
+
+**Bad:**
+Writing a massive feature, then writing tests, then realizing the architecture is wrong.
+
+**Good:**
+Writing the Interface and Tests first (TDD), then implementing.

package/rules/constitution/CONS-00021-congruence.md

@@ -0,0 +1,28 @@
+# Socio-Technical Congruence (CONS-00021)
+
+**Source**: [Systems Theory & Dynamics](../../docs/meta/industry_best_practices.md#52-socio-technical-congruence)
+**Tags**: #operational #organization #architecture
+**Related**: [SRP](CONS-00001-srp.md), [Operability](CONS-00029-operability.md)
+
+## Definition
+
+Align code boundaries with team boundaries. Mismatches cause communication overhead and integration failures.
+
+## Requirements
+
+1.  **Ownership**: Every module must have a clear owner (CODEOWNERS).
+2.  **Team API**: Interfaces between teams must be verified by contracts.
+3.  **Decoupling**: Tight coupling between modules owned by different teams is a high-risk architecture violation.
+
+## Anti-Patterns
+
+- **Distributed Monolith**: Microservices that must be deployed together.
+- **Shared Database**: Two teams writing to the same tables.
+
+## Examples
+
+**Bad:**
+Team A modifying Team B's internal utility library directly.
+
+**Good:**
+Team A using Team B's public, versioned API client.

package/rules/constitution/CONS-00022-orthogonality.md

@@ -0,0 +1,40 @@
+# Orthogonality (CONS-00022)
+
+**Source**: [Universal Fundamentals](../../docs/meta/industry_best_practices.md#33-orthogonality)
+**Tags**: #structural #coupling #independence
+**Related**: [Law of Demeter](CONS-00007-demeter.md), [DIP](CONS-00005-dip.md), [SRP](CONS-00001-srp.md)
+
+## Definition
+
+Changing one component should not affect unrelated components. Components are mathematically independent.
+
+## Requirements
+
+1.  **Interface Isolation**: Components communicate via narrow, stable interfaces.
+2.  **No Global State**: State must be eliminated or strictly isolated.
+3.  **Change Propagation**: Modifications should have minimal blast radius.
+
+## Anti-Patterns
+
+- **Spaghetti Dependencies**: Circular imports, tight coupling.
+- **Global Singletons**: Shared mutable state across modules.
+
+## Examples
+
+**Bad:**
+
+```text
+# UI layer directly queries storage
+function render_user_profile():
+  user = storage.read_current_user()  # violation
+  render(user)
+```
+
+**Good:**
+
+```text
+# UI depends on an interface/service
+function render_user_profile(user_service):
+  user = user_service.current_user()
+  render(user)
+```

package/rules/constitution/CONS-00023-determinism.md

@@ -0,0 +1,38 @@
+# Determinism (CONS-00023)
+
+**Source**: [Explicitness](../../docs/meta/industry_best_practices.md#35-explicitness)
+
+**Tags**: #behavioral #predictability #purity
+**Related**: [CQS](CONS-00016-cqs.md), [Safety](CONS-00015-safety.md)
+
+## Definition
+
+System behavior is consistent and reproducible given the same initial state and inputs.
+
+## Requirements
+
+1.  **Pure Functions**: Same input → Same output, no side effects.
+2.  **Explicit Dependencies**: All dependencies injected, no globals.
+3.  **Reproducibility**: Eliminate sources of non-determinism (time, randomness, external state).
+
+## Anti-Patterns
+
+- **Hidden State**: Functions reading from global config.
+- **Implicit Time**: Using `Date.now()` directly instead of injected clock.
+- **Unseeded Random**: Non-reproducible random values.
+
+## Examples
+
+**Bad:**
+
+```text
+function calculate_price(base):
+  return base * (1 + GLOBAL_TAX_RATE) * current_time()  # non-deterministic
+```
+
+**Good:**
+
+```text
+function calculate_price(base, tax_rate, now):
+  return base * (1 + tax_rate) * now  # deterministic
+```

package/rules/constitution/CONS-00024-security.md

@@ -0,0 +1,42 @@
+# Security (CONS-00024)
+
+**Source**: [Security Engineering](../../docs/meta/industry_best_practices.md#9-security-engineering)
+**Tags**: #behavioral #security #defense
+**Related**: [Postel's Law](CONS-00017-postel.md), [Safety](CONS-00015-safety.md)
+
+## Definition
+
+The system protects information and maintains functionality in the face of malicious acts.
+
+## Requirements
+
+1.  **Least Privilege**: Components have minimum necessary permissions.
+2.  **Defense in Depth**: Multiple security controls, no single point of failure.
+3.  **Secure Defaults**: Systems are secure out-of-the-box.
+4.  **Input Validation**: Never trust external input; validate at boundaries.
+
+## Anti-Patterns
+
+- **Trust by Default**: Assuming internal network is safe.
+- **Secrets in Code**: Hardcoded credentials, API keys.
+- **Over-Privilege**: Services with root/admin access unnecessarily.
+
+## Examples
+
+**Bad:**
+
+```text
+function handle_request(request):
+  id = request.path_params["id"]
+  return database.query("... WHERE id = " + id)  # injection risk
+```
+
+**Good:**
+
+```text
+function handle_request(request):
+  require_authorization(request.user, "user:read")
+
+  id = validate_id(request.path_params["id"])
+  return database.query("... WHERE id = ?", params=[id])  # parameterized
+```

package/rules/constitution/CONS-00025-efficiency.md

@@ -0,0 +1,38 @@
+# Efficiency (CONS-00025)
+
+**Source**: [Performance & Efficiency](../../docs/meta/industry_best_practices.md#12-performance--efficiency)
+**Tags**: #runtime #performance #resources
+**Related**: [Deep Modules](CONS-00009-deep-modules.md), [YAGNI](CONS-00011-yagni.md)
+
+## Definition
+
+Optimal use of bounded computational resources (time, memory, bandwidth).
+
+## Requirements
+
+1.  **Algorithmic Awareness**: Known Big-O complexity for hot paths.
+2.  **Resource Bounds**: Memory/CPU usage must be bounded and measurable.
+3.  **Profiling First**: Optimize only proven bottlenecks.
+4.  **Caching Strategy**: Explicit cache policies (TTL, eviction).
+
+## Anti-Patterns
+
+- **N+1 Queries**: Loading related data in loops.
+- **Unbounded Growth**: Unbounded queues, infinite caches.
+- **Premature Optimization**: Optimizing without profiling.
+
+## Examples
+
+**Bad:**
+
+```text
+users = storage.list_users()
+for user in users:
+  user.orders = storage.list_orders(user.id)  # N+1 queries
+```
+
+**Good:**
+
+```text
+users = storage.list_users_with_orders()  # batched retrieval
+```

package/rules/constitution/CONS-00026-resilience.md

@@ -0,0 +1,41 @@
+# Resilience (CONS-00026)
+
+**Source**: [Distributed Systems](../../docs/meta/industry_best_practices.md#7-distributed-systems)
+**Tags**: #runtime #resilience #failure
+**Related**: [CAP](CONS-00018-cap.md), [Fallacies](CONS-00019-fallacies.md), [Postel](CONS-00017-postel.md)
+
+## Definition
+
+The ability to recover from failure and restore functionality, often with graceful degradation.
+
+## Requirements
+
+1.  **Idempotency**: Operations can be retried safely.
+2.  **Circuit Breakers**: Fail fast when dependencies are unhealthy.
+3.  **Timeouts**: All external calls have explicit timeouts.
+4.  **Graceful Degradation**: Service remains partially available during failures.
+
+## Anti-Patterns
+
+- **Cascading Failures**: No circuit breakers, infinite retries.
+- **Missing Timeouts**: Hanging requests consuming resources.
+- **Non-Idempotent Mutations**: Unsafe retries causing duplicate data.
+
+## Examples
+
+**Bad:**
+
+```text
+result = call_dependency(request)  # no timeout; can hang forever
+```
+
+**Good:**
+
+```text
+result = call_dependency_with_resilience(
+  request,
+  timeout_ms=5000,
+  retries=3,
+  circuit_breaker=true,
+)
+```

package/rules/constitution/CONS-00027-transparency.md

@@ -0,0 +1,40 @@
+# Transparency (CONS-00027)
+
+**Source**: [Observability & Operations](../../docs/meta/industry_best_practices.md#11-observability--operations)
+**Tags**: #operational #observability #telemetry
+**Related**: [Congruence](CONS-00021-congruence.md), [Safety](CONS-00015-safety.md)
+
+## Definition
+
+The ability to understand internal state and runtime behavior by examining outputs.
+
+## Requirements
+
+1.  **Telemetry by Design**: Every service emits metrics (Latency, Errors, Traffic, Saturation).
+2.  **Structured Logging**: JSON logs with correlation IDs for tracing.
+3.  **Distinguishable States**: Failure states must be observable and actionable.
+4.  **Health Endpoints**: Explicit health/readiness checks.
+
+## Anti-Patterns
+
+- **Logging for Humans**: Unstructured text logs.
+- **Silent Failures**: Errors swallowed without visibility.
+- **Missing Correlation**: Cannot trace requests across services.
+
+## Examples
+
+**Bad:**
+
+```text
+log("user logged in: " + user_id)  # unstructured
+```
+
+**Good:**
+
+```text
+log_event("user.login", {
+  user_id: user_id,
+  correlation_id: correlation_id,
+  duration_ms: duration_ms,
+})
+```

package/rules/constitution/CONS-00028-evolvability.md

@@ -0,0 +1,36 @@
+# Evolvability (CONS-00028)
+
+**Source**: [Delivery & Evolution](../../docs/meta/industry_best_practices.md#14-delivery--evolution)
+**Tags**: #operational #lifecycle #change
+**Related**: [OCP](CONS-00002-ocp.md), [Orthogonality](CONS-00022-orthogonality.md)
+
+## Definition
+
+The ease with which the system can be adapted to new requirements or modified to fix defects over time.
+
+## Requirements
+
+1.  **Testability**: Code must be designed to be tested (Dependency Injection).
+2.  **Feature Flags**: Decouple deployment from release to allow safe evolution.
+3.  **Versioning**: Public APIs must be strictly versioned.
+
+## Anti-Patterns
+
+- **Big Bang Rewrites**: "We can't change this without rewriting everything."
+- **Hardcoded Configuration**: Magic numbers or URLs buried in code.
+
+## Examples
+
+**Bad:**
+
+```text
+API_URL = "https://example.com"  # hardcoded
+client = new_client(API_URL)
+```
+
+**Good:**
+
+```text
+API_URL = config["API_URL"]
+client = new_client(API_URL)
+```

package/rules/constitution/CONS-00029-operability.md

@@ -0,0 +1,36 @@
+# Operability (CONS-00029)
+
+**Source**: [Observability & Operations](../../docs/meta/industry_best_practices.md#11-observability--operations)
+**Tags**: #operational #lifecycle #runnability
+**Related**: [Transparency](CONS-00027-transparency.md), [Checklist](CONS-00031-checklist.md)
+
+## Definition
+
+The ease with which the system can be run, monitored, and maintained by the engineering team.
+
+## Requirements
+
+1.  **Runbooks**: Every alert must map to a documented procedure.
+2.  **Congruence**: Team boundaries must match architectural boundaries to ensure clear ownership.
+3.  **Automation**: Rote maintenance tasks (backups, cert renewal) must be automated.
+
+## Anti-Patterns
+
+- **Hero Culture**: Only one person knows how to restart the server.
+- **Manual Deployment**: "SSH and git pull."
+
+## Examples
+
+**Bad:**
+
+```text
+# TODO: restart manually when memory > threshold
+# (no automation)
+```
+
+**Good:**
+
+```text
+restart_policy = "on-failure"
+health_check = enabled
+```

package/rules/constitution/CONS-00030-rework-cycle.md

@@ -0,0 +1,27 @@
+# The Rework Cycle (CONS-00030)
+
+**Source**: [System Dynamics](../../docs/meta/industry_best_practices.md#53-the-rework-cycle)
+**Tags**: #operational #process #velocity #feedback
+**Related**: [Shift Left](CONS-00020-shift-left.md), [Safety](CONS-00015-safety.md)
+
+## Definition
+
+The primary killer of velocity is "Unknown Rework"—work marked "done" that contains hidden defects.
+
+## Requirements
+
+1.  **Debt Paydown**: Prioritize refactoring ("Corrective Gains") to keep the rework fraction low.
+2.  **Fast Feedback**: Verification must happen immediately (CI/CD) to convert Unknown Rework to Known Rework.
+
+## Anti-Patterns
+
+- **The Death Spiral**: Ignoring bugs to meet a deadline, creating more bugs.
+- **Late Testing**: QA happens only at the end of the sprint.
+
+## Examples
+
+**Bad:**
+"We'll write tests next sprint."
+
+**Good:**
+"I can't merge this until the tests pass."

package/rules/constitution/CONS-00031-checklist.md

@@ -0,0 +1,28 @@
+# The Checklist (CONS-00031)
+
+**Source**: [The Checklist Manifesto](../../docs/meta/industry_best_practices.md#44-the-checklist)
+**Tags**: #operational #process #rigor #automation
+**Related**: [Operability](CONS-00029-operability.md), [Safety](CONS-00015-safety.md)
+
+## Definition
+
+Rote verification should be offloaded to machines. Humans are fallible; checklists are consistent.
+
+## Requirements
+
+1.  **Automation**: Formatting, linting, and imports must be automated (e.g., Pre-commit hooks).
+2.  **Cognitive Offloading**: Humans should never have to manually check something a machine can check.
+3.  **Standardization**: We do things the same way every time to reduce mental load.
+
+## Anti-Patterns
+
+- **Manual Nits**: Reviewer commenting "missing semicolon."
+- **Memory-Based Process**: "Oh, I forgot to run the migration script manually."
+
+## Examples
+
+**Bad:**
+A PR review comment: "Please sort these imports."
+
+**Good:**
+A CI job fails: "Lint check failed. Run the lint auto-fix command."

package/rules/constitution/CONS-00032-documentation.md

@@ -0,0 +1,39 @@
+# Documentation & Comments (CONS-00032)
+
+**Source**: [Literate Programming](../../docs/meta/industry_best_practices.md#26-comment-the-why-not-the-how)
+**Tags**: #operational #maintenance #readability
+**Related**: [Clean Packages](CONS-00009-deep-modules.md)
+
+## Definition
+
+Code tells you _how_; comments tell you _why_. Documentation bridges the gap between intent and implementation.
+
+## Requirements
+
+1.  **The "Why" Rule**: Comments must explain the intent, context, or constraints, not the syntax.
+2.  **Public API**: Every public symbol (exported function/class) must have a docstring.
+3.  **No Noise**: Do not add comments that merely restate the code (e.g., delimiters like `// end of function`).
+
+## Anti-Patterns
+
+- **Echo Comments**: `i++ // increment i`.
+- **Superficial Delimiters**: `// --- Helper Functions ---` or `// Act`.
+- **Ghost Docs**: Comments describing parameters that were deleted months ago.
+
+## Examples
+
+**Bad:**
+
+```text
+# Loop through users
+for each user in users:
+  ...
+```
+
+**Good:**
+
+```text
+# Filter out inactive users to prevent billing inactive accounts
+for each user in users:
+  ...
+```