lgtm-specs 0.0.4

package/rules/README.md

@@ -0,0 +1,57 @@
+# The Atomic Rulebook (Zettelkasten)
+
+This directory contains the machine-readable specifications ("Specs") used to inject context into LGTM Agents.
+
+## Methodology
+
+We use a **Zettelkasten** approach to manage engineering knowledge.
+
+1.  **Atomic**: Each file covers exactly one principle. No monolithic "Best Practices" documents.
+2.  **Linked**: Notes reference each other via `Related` links, forming a graph.
+3.  **Machine-First**: The structure is optimized for Retrieval Augmented Generation (RAG). The Metadata header allows precise filtering.
+
+## The Brain Map
+
+- **[The Constitution](constitution/README.md) (Universal Rules)**
+  - **Role**: The immutable "Physics" of software engineering.
+  - **Content**: Principles derived from Systems Theory, Cognitive Science, and formal Computer Science (e.g., Entropy, Complexity, Cognitive Load).
+  - **Usage**: Injected into _every_ agent to ensure high-level architectural integrity.
+
+- **[The Laws](laws/README.md) (Domain Rules)**
+  - **Role**: The "Civil Code" of specific technologies.
+  - **Derivation**: Every Law must effectively implement a Constitutional Principle. (e.g., "No `any`" implements `Safety`).
+  - **Content**: Idioms, safety checks, and patterns specific to a language or framework.
+  - **Usage**: Injected dynamically based on the detected tech stack.
+
+- **[The Policies](policies/README.md) (Project By-Laws)**
+  - **Role**: The "Local Ordinances" of a specific repository.
+  - **Derivation**: Policies optimize Laws/Constitution for a specific team context, but **cannot violate** the Constitution.
+  - **Content**: Configuration choices, style preferences, and workflow requirements.
+  - **Usage**: Loaded from the user's repository config to override or extend defaults.
+
+## How to Use These Rules
+
+The "Perfect Engineer" is constructed by layering these rules into the Agent's context.
+
+### 1. The Assembly Formula
+
+```text
+Agent Prompt =
+  [Role Definition] (e.g., "You are a Reviewer")
+  + [Constitution]  (Universal Truths)
+  + [Laws]          (Language Specifics)
+  + [Policies]      (Repo Specifics)
+```
+
+### 2. Context Injection Mechanism
+
+- **Constitution**: Retrieved via **Tags**.
+  - _Scenario:_ A Reviewer checking architecture will load rules tagged `#structural` and `#coupling` (e.g., SRP, DIP).
+- **Laws**: Selected via **Tech Stack Detection**.
+  - _Scenario:_ If `tsconfig.json` is present, inject `laws/typescript/*.md`.
+- **Policies**: Loaded via **Path Lookup**.
+  - _Scenario:_ If `.lgtm/policies/README.md` exists, append it. If not, use `rules/policies/default.md`.
+
+## The Spec Template
+
+Every rule MUST follow the format defined in [RULE-00000-EXAMPLE.md](RULE-00000-EXAMPLE.md).

package/rules/RULE-00000-EXAMPLE.md

@@ -0,0 +1,29 @@
+# Rule Name (ID)
+
+**Source**: [Link to Industry Best Practice](../docs/meta/industry_best_practices.md#anchor)
+**Tags**: #structural #tag1 #tag2
+**Related**: [Other Rule](constitution/CONS-00001-srp.md)
+
+## Definition
+
+A concise, 1-sentence definition of the principle.
+
+## Requirements
+
+Actionable, testable constraints.
+
+1.  **Requirement Name**: Description.
+
+## Anti-Patterns
+
+Specific bad practices to detect.
+
+- **Pattern Name**: Description.
+
+## Examples
+
+**Bad:**
+(Code snippet)
+
+**Good:**
+(Code snippet)

package/rules/constitution/CONS-00001-srp.md

@@ -0,0 +1,40 @@
+# Single Responsibility Principle (CONS-00001)
+
+**Source**: [SOLID Principles](../../docs/meta/industry_best_practices.md#11-single-responsibility-principle-srp)
+**Tags**: #structural #solid #cohesion #architecture
+**Related**: [Deep Modules](CONS-00009-deep-modules.md), [Socio-Technical Congruence](CONS-00021-congruence.md)
+
+## Definition
+
+A module should have one, and only one, reason to change.
+
+## Requirements
+
+1.  **Separation of Concerns**: A class handling business logic must NOT handle database queries or UI rendering directly.
+2.  **High Cohesion**: All methods in a class should operate on the same set of state variables.
+3.  **Layer Isolation**: Separate "Policy" (Business Rules) from "Mechanism" (IO/Frameworks).
+
+## Anti-Patterns
+
+- **God Classes**: `Manager` or `Handler` classes with mixed responsibilities (Auth + Logging + DB).
+- **Leakage**: UI layer importing storage record types.
+
+## Examples
+
+**Bad:**
+
+```text
+class User:
+  authenticate(...)
+  save_to_storage(...)
+```
+
+**Good:**
+
+```text
+class UserAuth:
+  authenticate(...)
+
+class UserRepository:
+  save(user)
+```

package/rules/constitution/CONS-00002-ocp.md

@@ -0,0 +1,43 @@
+# Open/Closed Principle (CONS-00002)
+
+**Source**: [SOLID Principles](../../docs/meta/industry_best_practices.md#12-openclosed-principle-ocp)
+**Tags**: #structural #solid #extensibility
+**Related**: [Evolvability](CONS-00028-evolvability.md), [YAGNI](CONS-00011-yagni.md)
+
+## Definition
+
+Software entities should be open for extension but closed for modification.
+
+## Requirements
+
+1.  **Extension Points**: Use interfaces or abstract classes to allow behavior changes.
+2.  **Stability**: Do not modify stable classes to add features if Inheritance or Decorators can be used.
+3.  **Strategy Pattern**: Prefer injecting a Strategy object over adding `if/else` blocks for new cases.
+
+## Anti-Patterns
+
+- **Switch on Type**: `if (type === 'A') ... else if (type === 'B')`.
+- **Monkey Patching**: Modifying objects at runtime.
+
+## Examples
+
+**Bad:**
+
+```text
+function area(shape):
+  if shape.type == "circle":
+    ...
+  else if shape.type == "square":
+    ...
+```
+
+**Good:**
+
+```text
+interface Shape:
+  area()
+
+class Circle implements Shape:
+  area():
+    ...
+```

package/rules/constitution/CONS-00003-lsp.md

@@ -0,0 +1,44 @@
+# Liskov Substitution Principle (CONS-00003)
+
+**Source**: [SOLID Principles](../../docs/meta/industry_best_practices.md#13-liskov-substitution-principle-lsp)
+**Tags**: #behavioral #solid #correctness #types
+**Related**: [Safety by Design](CONS-00015-safety.md)
+
+## Definition
+
+Subtypes must be substitutable for their base types without altering correctness.
+
+## Requirements
+
+1.  **Contract Adherence**: A subclass must accept the same inputs and guarantee the same post-conditions.
+2.  **Exception Parity**: A subclass must not throw exceptions that are not part of the parent's contract.
+3.  **Return Consistency**: Do not restrict return types unpredictably.
+
+## Anti-Patterns
+
+- **Refused Bequest**: Implementing a method by throwing `NotImplementedException`.
+- **Type Narrowing Violation**: Returning a specific error code where the parent promised success.
+
+## Examples
+
+**Bad:**
+
+```text
+class Bird:
+  fly()
+
+class Penguin extends Bird:
+  fly():
+    error("cannot fly")
+```
+
+**Good:**
+
+```text
+class Bird
+
+class FlyingBird extends Bird:
+  fly()
+
+class Penguin extends Bird
+```

package/rules/constitution/CONS-00004-isp.md

@@ -0,0 +1,46 @@
+# Interface Segregation Principle (CONS-00004)
+
+**Source**: [SOLID Principles](../../docs/meta/industry_best_practices.md#14-interface-segregation-principle-isp)
+**Tags**: #structural #solid #decoupling #interface
+**Related**: [Deep Modules](CONS-00009-deep-modules.md)
+
+## Definition
+
+Clients should not be forced to depend on interfaces they do not use.
+
+## Requirements
+
+1.  **Narrow Interfaces**: Split "God Interfaces" (e.g., `IUserHandler`) into role-specific ones (`IUserReader`, `IUserWriter`).
+2.  **Role-Based Params**: Functions should accept the smallest interface possible.
+
+## Anti-Patterns
+
+- **Fat Interfaces**: An interface with methods for Auth, DB, and UI.
+- **Unused Impls**: Empty method bodies just to satisfy an interface.
+
+## Examples
+
+**Bad:**
+
+```text
+interface Worker:
+  work()
+  eat()
+
+class Robot implements Worker:
+  work():
+    ...
+  eat():
+    ...  # forced dependency
+```
+
+**Good:**
+
+```text
+interface Workable:
+  work()
+
+class Robot implements Workable:
+  work():
+    ...
+```

package/rules/constitution/CONS-00005-dip.md

@@ -0,0 +1,37 @@
+# Dependency Inversion Principle (CONS-00005)
+
+**Source**: [SOLID Principles](../../docs/meta/industry_best_practices.md#15-dependency-inversion-principle-dip)
+**Tags**: #structural #solid #decoupling #testability
+**Related**: [SRP](CONS-00001-srp.md), [Orthogonality](CONS-00022-orthogonality.md)
+
+## Definition
+
+High-level modules should not depend on low-level modules. Both should depend on abstractions.
+
+## Requirements
+
+1.  **Injection**: Dependencies must be passed in (Constructor/Method Injection).
+2.  **Abstraction**: Imports in domain logic should point to `interfaces/` or `types/`, not concrete `infrastructure/`.
+
+## Anti-Patterns
+
+- **Hardcoded Dependencies**: `new ConcreteDatabase()` inside a Service.
+- **Static Cling**: Direct calls to static helper methods for IO.
+
+## Examples
+
+**Bad:**
+
+```text
+class Service:
+  init():
+    database = ConcreteDatabase()  # hardcoded
+```
+
+**Good:**
+
+```text
+class Service:
+  init(database_dep):
+    database = database_dep  # injected abstraction
+```

package/rules/constitution/CONS-00006-dry.md

@@ -0,0 +1,45 @@
+# DRY (Don't Repeat Yourself) (CONS-00006)
+
+**Source**: [Universal Fundamentals](../../docs/meta/industry_best_practices.md#83-dry-dont-repeat-yourself)
+**Tags**: #structural #complexity #maintenance
+**Related**: [SRP](CONS-00001-srp.md), [OCP](CONS-00002-ocp.md)
+
+## Definition
+
+Every piece of knowledge must have a single, authoritative representation within a system.
+
+## Requirements
+
+1.  **Single Source of Truth**: Data schemas must be defined once (e.g., a single schema definition file) and types
+    generated from it.
+2.  **Logic Reuse**: Complex algorithms (e.g., tax calculation) must exist in one place.
+
+## Anti-Patterns
+
+- **Copy-Paste**: Repeating the same block of code in multiple controllers.
+- **Drift**: Two functions doing almost the same thing but diverging over time.
+
+## Examples
+
+**Bad:**
+
+```text
+# API layer
+type User:
+  id
+
+# Storage layer (duplicated)
+type UserRecord:
+  id
+```
+
+**Good:**
+
+```text
+# Shared types module
+type User:
+  id
+
+# API and storage both depend on the shared type
+use(User)
+```

package/rules/constitution/CONS-00007-demeter.md

@@ -0,0 +1,35 @@
+# Law of Demeter (CONS-00007)
+
+**Source**: [Universal Fundamentals](../../docs/meta/industry_best_practices.md#84-law-of-demeter)
+**Tags**: #structural #coupling #encapsulation
+**Related**: [Deep Modules](CONS-00009-deep-modules.md), [Orthogonality](CONS-00022-orthogonality.md)
+
+## Definition
+
+A module should not know about the innards of the objects it manipulates. Talk to your friends, not your friends' friends.
+
+## Requirements
+
+1.  **One Dot Rule**: Avoid `a.b().c()`. Call methods on `a` that handle the delegation.
+2.  **Encapsulation**: Objects should expose behavior, not data structure.
+
+## Anti-Patterns
+
+- **Train Wrecks**: `order.customer.address.zipCode`.
+- **Inappropriate Intimacy**: Accessing nested private state.
+
+## Examples
+
+**Bad:**
+
+```text
+function shipping_zip_code(order):
+  return order.get_customer().get_address().get_zip_code()
+```
+
+**Good:**
+
+```text
+function shipping_zip_code(order):
+  return order.get_shipping_zip_code()
+```

package/rules/constitution/CONS-00008-composition.md

@@ -0,0 +1,44 @@
+# Composition Over Inheritance (CONS-00008)
+
+**Source**: [Coupling & Cohesion](../../docs/meta/industry_best_practices.md#42-composition-over-inheritance)
+**Tags**: #structural #coupling #flexibility
+**Related**: [OCP](CONS-00002-ocp.md), [Orthogonality](CONS-00022-orthogonality.md)
+
+## Definition
+
+Favor object composition ("has-a") over class inheritance ("is-a") to achieve code reuse and flexibility.
+
+## Requirements
+
+1.  **Flat Hierarchies**: Reject inheritance trees deeper than 2 levels.
+2.  **Delegation**: Use composition/delegation to share code between unrelated classes.
+
+## Anti-Patterns
+
+- **Fragile Base Class**: A base class with many diverse methods that child classes "inherit" but don't need.
+- **Gorilla/Banana Problem**: You wanted a banana but you got the gorilla holding the banana and the entire jungle.
+
+## Examples
+
+**Bad:**
+
+```text
+class Animal:
+  eat()
+  fly()
+
+class Dog extends Animal:
+  fly():
+    error("cannot fly")
+```
+
+**Good:**
+
+```text
+class Dog:
+  init(eater_dep):
+    eater = eater_dep
+
+  eat():
+    return eater.eat()
+```

package/rules/constitution/CONS-00009-deep-modules.md

@@ -0,0 +1,39 @@
+# Deep Modules (CONS-00009)
+
+**Source**: [A Philosophy of Software Design](../../docs/meta/industry_best_practices.md#21-deep-modules)
+**Tags**: #structural #complexity #interface
+**Related**: [Law of Demeter](CONS-00007-demeter.md), [Cohesion](CONS-00001-srp.md)
+
+## Definition
+
+Interfaces must be significantly simpler than their implementations. Complexity should be hidden, not exposed.
+
+## Requirements
+
+1.  **Maximize Depth**: Functionality (Benefit) > Interface (Cost).
+2.  **Hide Complexity**: The implementation should handle the hard work (retries, caching).
+3.  **Reject Pass-Through**: Methods that just delegate to another object without adding value are tech debt.
+
+## Anti-Patterns
+
+- **Shallow Classes**: A class named `FileUtil` that just wraps `filesystem.read` 1:1.
+- **Leakage**: Exposing `cache strategy` in the `read()` method signature.
+
+## Examples
+
+**Bad:**
+
+```text
+class FileReader:
+  read(path, encoding, flags):
+    return filesystem.read(path, encoding, flags)  # pass-through
+```
+
+**Good:**
+
+```text
+class ConfigLoader:
+  load():
+    # Handles finding the file, reading, parsing, and validation
+    return config
+```

package/rules/constitution/CONS-00010-kiss.md

@@ -0,0 +1,47 @@
+# KISS (Keep It Simple, Stupid) (CONS-00010)
+
+**Source**: [Classic Engineering Wisdom](../../docs/meta/industry_best_practices.md#81-kiss-keep-it-simple-stupid)
+**Tags**: #structural #simplicity #readability
+**Related**: [YAGNI](CONS-00011-yagni.md), [Cognitive Limits](CONS-00012-cognitive-limits.md)
+
+## Definition
+
+Complexity is a cost; avoid it unless justified by value. Most systems work best if they are kept simple.
+
+## Requirements
+
+1.  **No Speculative Generality**: Do not build a factory for a single implementation.
+2.  **Boring Code**: Prefer standard library solutions over clever custom logic.
+3.  **Readability**: If a one-liner requires mental parsing, expand it.
+
+## Anti-Patterns
+
+- **Over-Engineering**: Using the Strategy Pattern for a simple `if` statement.
+- **Code Golf**: Minimizing characters at the expense of clarity.
+
+## Examples
+
+**Bad:**
+
+```text
+is_valid = false
+if a:
+  if b:
+    if c:
+      is_valid = true
+    else:
+      is_valid = false
+  else:
+    is_valid = false
+else:
+  is_valid = false
+return is_valid
+```
+
+**Good:**
+
+```text
+if not a or not b:
+  return false
+return c
+```

package/rules/constitution/CONS-00011-yagni.md

@@ -0,0 +1,49 @@
+# YAGNI (You Aren't Gonna Need It) (CONS-00011)
+
+**Source**: [Classic Engineering Wisdom](../../docs/meta/industry_best_practices.md#82-yagni-you-arent-gonna-need-it)
+**Tags**: #structural #simplicity #efficiency
+**Related**: [KISS](CONS-00010-kiss.md), [OCP](CONS-00002-ocp.md)
+
+## Definition
+
+Do not implement functionality until it is necessary.
+
+## Requirements
+
+1.  **Dead Code**: Remove unused functions, variables, or files.
+2.  **No Futures**: Reject "extensibility hooks" or "plugin architectures" that have no immediate use case.
+
+## Anti-Patterns
+
+- **Speculative Features**: "I added an `isAdmin` flag just in case we need it later."
+- **Commented Out Code**: Keeping old code "just in case." Use Git history for that.
+
+## Examples
+
+**Bad:**
+
+```text
+# Speculative abstraction for formats we do not support
+parsers = {
+  current: parse_current_format,
+  future: parse_future_format,  # unused
+}
+
+function parse(input, format):
+  return parsers[format](input)
+
+# TODO: implement when needed
+function parse_future_format(input):
+  ...
+```
+
+**Good:**
+
+```text
+# Code for current requirements only
+function parse_current_format(input):
+  ...
+
+function parse(input):
+  return parse_current_format(input)
+```

package/rules/constitution/CONS-00012-cognitive-limits.md

@@ -0,0 +1,28 @@
+# Cognitive Limits (Batch Size) (CONS-00012)
+
+**Source**: [Pragmatic Programmer & Code Health](../../docs/meta/industry_best_practices.md#43-cognitive-limits-batch-size)
+**Tags**: #operational #human-factors #review
+**Related**: [Deep Modules](CONS-00009-deep-modules.md), [KISS](CONS-00010-kiss.md)
+
+## Definition
+
+Human review effectiveness drops precipitously after 400 LOC. Beyond this, the reviewer switches from "Analytical Mode" to "Pattern Matching Mode."
+
+## Requirements
+
+1.  **Atomic Commits**: A commit must handle one logical change.
+2.  **PR Size**: Pull Requests should stay under 400 LOC.
+3.  **Single Story**: A PR cannot mix Refactoring and Feature work.
+
+## Anti-Patterns
+
+- **The Big Bang**: A 2,000 line PR named "V2 rewrite."
+- **The Kitchen Sink**: A feature PR that also reformats the entire codebase.
+
+## Examples
+
+**Bad:**
+`feat: add auth and reformat utils and upgrade dependency` (Files changed: 45)
+
+**Good:**
+`feat(auth): add login endpoint` (Files changed: 3)

package/rules/constitution/CONS-00013-boy-scout.md

@@ -0,0 +1,27 @@
+# The Boy Scout Rule (CONS-00013)
+
+**Source**: [Pragmatic Programmer & Code Health](../../docs/meta/industry_best_practices.md#41-the-boy-scout-rule)
+**Tags**: #operational #maintenance #refactoring
+**Related**: [Broken Windows](CONS-00014-broken-windows.md), [Congruence](CONS-00021-congruence.md)
+
+## Definition
+
+Always leave the code cleaner than you found it. Continuous, incremental improvement beats "Big Bang" refactors.
+
+## Requirements
+
+1.  **Incidental Cleanup**: If you touch a file, fix existing lint warnings or bad names in the immediate context.
+2.  **No Regression**: Do not introduce new technical debt (TODOs without tickets) in the name of speed.
+
+## Anti-Patterns
+
+- **"Not My Job"**: Seeing a typo and ignoring it because it wasn't part of the ticket.
+- **Drive-By Trashing**: Adding a hack to a clean file because "it was already messy."
+
+## Examples
+
+**Bad:**
+Leaving a variable named `x` when modifying the function it lives in.
+
+**Good:**
+Renaming `x` to `user_index` while updating the loop logic.

package/rules/constitution/CONS-00014-broken-windows.md

@@ -0,0 +1,35 @@
+# Broken Windows Theory (CONS-00014)
+
+**Source**: [Pragmatic Programmer & Code Health](../../docs/meta/industry_best_practices.md#42-broken-windows-theory)
+**Tags**: #operational #maintenance #quality
+**Related**: [The Boy Scout Rule](CONS-00013-boy-scout.md), [Operability](CONS-00029-operability.md)
+
+## Definition
+
+Bad designs, wrong decisions, and poor code, when left unrepaired, encourage more of the same. Normalization of deviance.
+
+## Requirements
+
+1.  **Zero Tolerance**: Do not ignore "warn" level linting errors. Fix them.
+2.  **Debt Repayment**: If a hack is necessary, it must be encapsulated and marked with a deprecation plan.
+
+## Anti-Patterns
+
+- **Disabled Tests**: Commenting out a failing test instead of fixing it.
+- **"Temporary" Hacks**: Code marked `// TODO: Fix this` from 3 years ago.
+
+## Examples
+
+**Bad:**
+
+```text
+# Suppressing a safety/static-analysis warning instead of fixing the cause
+suppress_warning("unsafe_type")
+```
+
+**Good:**
+
+```text
+# Refactor so the code satisfies checks without suppression
+value = parse_and_validate(input)
+```