lgtm-specs 0.0.4

package/docs/meta/languages/go/05-performance.md

@@ -0,0 +1,18 @@
+# Performance & Efficiency
+
+**Source**: [btcwallet Engineering Guide](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/ENGINEERING_GUIDE.md)
+
+## 1. Reduce Allocations
+
+- **Pre-allocation**: If you know the size of a slice/map, allocate it upfront.
+  - `make([]int, 0, 1000)` prevents ~10 re-allocations and copies during append.
+- **Sync.Pool**: For hot paths (e.g., HTTP handlers), reuse complex objects (buffers, encoders) to reduce GC pressure.
+
+## 2. Compiler optimizations
+
+- **Field Alignment**: Order struct fields from largest (int64/ptr) to smallest (bool) to minimize memory padding.
+- **Escape Analysis**: Use `go build -gcflags="-m"` to see if variables escape to the heap unnecessarily.
+
+## 3. I/O Optimization
+
+- **Buffering**: Use `bufio.Reader/Writer` to reduce system calls for network/disk I/O.

package/docs/meta/languages/go/06-safety.md

@@ -0,0 +1,18 @@
+# Implementation Safety
+
+**Source**: [btcwallet Engineering Guide](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/ENGINEERING_GUIDE.md)
+
+## 1. Concurrency Safety
+
+Go's built-in maps and slices are **NOT** thread-safe.
+
+- **Maps/Slices**: If accessed by >1 goroutine, you MUST use a `sync.Mutex` or `sync.RWMutex`.
+- **Copying Locks**: Never copy a struct that contains a Mutex. Pass by pointer (`*MyStruct`).
+
+## 2. Atomic Operations
+
+For simple counters or boolean flags, use `sync/atomic` instead of a Mutex. It is significantly faster and prevents deadlock risks.
+
+## 3. Lazy Initialization
+
+Use `sync.Once` for expensive resources that should only be initialized on first use.

package/docs/meta/languages/go/07-testing.md

@@ -0,0 +1,44 @@
+# Testing Strategy
+
+**Source**: [Unit Testing Guidelines](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/unit_testing_guidelines.md)
+
+## 1. AAA (Arrange, Act, Assert)
+
+Every test body must follow this structure, separated by blank lines.
+
+1.  **Arrange**: Set up inputs and mocks.
+2.  **Act**: Execute the function under test.
+3.  **Assert**: Check results.
+
+## 2. Table-Driven Tests
+
+Best for testing data variance on pure functions.
+
+- **Data Only**: Test case structs must contain _Data Only_ (inputs/outputs). No functions or setup logic allowed in the struct.
+- **Identical Setup**: The `Arrange` block must be identical for all cases. If you need `if tc.flag { mock... }`, do not use a table.
+
+## 3. Standalone Tests
+
+Best for complex orchestration or unique setups.
+
+- **Rule**: When setups differ, use separate, standalone functions. Clarity > DRY in tests.
+- **Scope**: Use for verifying a sequence of side effects (Mock A -> Mock B).
+
+## 4. Libraries
+
+- **Assertions**: Use `testify/require` (Fail Fast) for everything. Only use `assert` if you explicitly want to see multiple failures (rare).
+- **Clarity**: "One test, one concept."
+
+## 5. Documentation
+
+Tests explain _how_ the system is verified.
+
+- **Phase Comments**: Use `// Arrange` (or descriptive equivalents) to label sections.
+- **Descriptive**: `// Setup service with valid config` is better than just `// Arrange`.
+
+## 6. Mocking
+
+Use mocks to isolate the unit under test.
+
+- **Interfaces**: Mock at the interface level using tools like `mockery` or `gomock`.
+- **Expectations**: Define expected calls explicitly in the Arrange phase.

package/docs/meta/languages/go/08-config-layout.md

@@ -0,0 +1,23 @@
+# Project Layout & Configuration
+
+**Source**: [Standard Go Project Layout](https://github.com/golang-standards/project-layout)
+
+## 1. The Standard Layout
+
+- `/cmd`: Main applications (entry points). No business logic.
+- `/internal`: Private application and library code. Enforced by compiler.
+- `/pkg`: Library code that is safe for _external_ consumption. (Commitment to stability).
+- `/api`: IDL definitions (Proto, OpenAPI).
+- `/configs`: Configuration files (templates).
+
+## 2. Dependency Management
+
+- **Modules**: Use `go.mod`.
+- **Minimal Version Selection (MVS)**: Go selects the _oldest_ allowed version. Explicit upgrades (`go get -u`) are required.
+- **Vendoring**: Use `go mod vendor` for hermetic builds in critical environments.
+
+## 3. Configuration (12-Factor)
+
+- **Source**: Config comes from the Environment (Env Vars), not hardcoded constants.
+- **Tools**: Use `viper` (complex) or `env` (simple).
+- **Defaults**: Define sensible defaults in code.

package/docs/meta/languages/go/README.md

@@ -0,0 +1,14 @@
+# The Law of Go (Meta)
+
+This directory contains the detailed engineering patterns for Go.
+
+## Index
+
+- [01-concurrency.md](01-concurrency.md)
+- [02-api-design.md](02-api-design.md)
+- [03-resilience.md](03-resilience.md)
+- [04-errors.md](04-errors.md)
+- [05-performance.md](05-performance.md)
+- [06-safety.md](06-safety.md)
+- [07-testing.md](07-testing.md)
+- [08-config-layout.md](08-config-layout.md)

package/docs/meta/languages/typescript/01-strictness.md

@@ -0,0 +1,19 @@
+# Type System Strictness
+
+**Source**: [Total TypeScript](https://www.totaltypescript.com)
+
+## 1. No Any
+
+The usage of `any` is strictly forbidden. It defeats the purpose of the type system.
+
+- **Alternative**: Use `unknown` and narrow it with Type Guards (Zod).
+
+## 2. Strict Null Checks
+
+`null` and `undefined` must be handled explicitly.
+
+- **Config**: Ensure `strictNullChecks: true` in `tsconfig.json`.
+
+## 3. No Implicit Any
+
+All variables and return types must be explicitly typed if inference is ambiguous.

package/docs/meta/languages/typescript/02-immutability.md

@@ -0,0 +1,15 @@
+# Immutability & State
+
+**Source**: [Functional Core, Imperative Shell](https://www.destroyallsoftware.com/screencasts/catalog/functional-core-imperative-shell)
+
+## 1. Const by Default
+
+Use `let` only when re-assignment is logically necessary (e.g., accumulators). Never use `var`.
+
+## 2. Readonly
+
+Prefer `readonly` arrays (`readonly T[]`) and `readonly` interface properties to prevent accidental mutation passed by reference.
+
+## 3. Functional Core
+
+Prefer pure functions that return new state over classes that mutate internal state.

package/docs/meta/languages/typescript/03-async.md

@@ -0,0 +1,18 @@
+# Asynchronous Patterns
+
+**Source**: [Modern TypeScript](https://google.github.io/styleguide/tsguide.html)
+
+## 1. Async/Await
+
+Use `async/await` exclusively. Avoid `.then()` and `.catch()` chains unless interfacing with legacy APIs.
+
+## 2. Floating Promises
+
+Every Promise must be awaited or explicitly voided.
+
+- **Bad**: `doAsyncWork();`
+- **Good**: `await doAsyncWork();` or `void doAsyncWork();`
+
+## 3. Error Handling
+
+Use `try/catch` blocks for async errors. For expected failures, consider returning a Result type (`{ success: boolean, error?: Error }`).

package/docs/meta/languages/typescript/04-design.md

@@ -0,0 +1,19 @@
+# Component & API Design
+
+**Source**: [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
+
+## 1. Interface vs Type
+
+- **Interface**: Use for public APIs, object shapes, and class contracts. They support merging and better error messages.
+- **Type**: Use for Unions, Intersections, and Primitives.
+
+## 2. Generics
+
+Use generics to create reusable logic, but always constrain them (`T extends User`). Unconstrained generics (`T`) are often a code smell for `any`.
+
+## 3. Module Organization
+
+Organize code by Feature/Domain, not by technical type.
+
+- **Bad**: `src/types`, `src/utils`.
+- **Good**: `src/features/auth`, `src/features/payment`.

package/docs/meta/languages/typescript/05-control-flow.md

@@ -0,0 +1,11 @@
+# Control Flow
+
+**Source**: [Type Challenges](https://github.com/type-challenges/type-challenges)
+
+## 1. Discriminated Unions
+
+Use a `kind` or `type` literal field to distinguish union members. This allows TypeScript to narrow types automatically in `switch` statements.
+
+## 2. Exhaustiveness Checking
+
+When switching on a discriminated union, ensure all cases are covered. Use a `assertNever(x)` helper in the `default` case to catch future additions at compile time.

package/docs/meta/languages/typescript/README.md

@@ -0,0 +1,11 @@
+# The Law of TypeScript (Meta)
+
+This directory contains the detailed engineering patterns for TypeScript.
+
+## Index
+
+- [01-strictness.md](01-strictness.md)
+- [02-immutability.md](02-immutability.md)
+- [03-async.md](03-async.md)
+- [04-design.md](04-design.md)
+- [05-control-flow.md](05-control-flow.md)

package/docs/meta/workflow.md

@@ -0,0 +1,68 @@
+# The LGTM Knowledge Engineering Workflow
+
+This document records the methodology used to create the LGTM engineering standards. It serves as a guide for contributors proposing new principles or modifying existing ones. We do not just "write docs"; we engineer knowledge.
+
+## The 4-Phase Process
+
+### Phase 1: Research & Discovery (The Divergent Phase)
+
+_Goal: Gather high-quality raw material._
+
+1.  **Canon Review**: Start with established, battle-tested wisdom (SOLID, Pragmatic Programmer, SRE Books).
+2.  **Deep Dive**: Ingest high-density research (Formal Methods, System Dynamics, Control Theory).
+3.  **Source Verification**: Never rely on hearsay. Find the primary source (e.g., Ousterhout, Conway, Brewer).
+
+### Phase 2: Analysis & Synthesis (The Convergent Phase)
+
+_Goal: Distill noise into signal._
+
+1.  **Deconstruction**: Break monolithic concepts into atomic constituents. (e.g., SOLID -> SRP, OCP, LSP...).
+2.  **Adversarial Critique**: Rigorously question overlaps. "Is Robustness distinct from Resilience?"
+3.  **Filter**: Remove "fluff" and "magic." Focus on First Principles.
+
+### Phase 3: Codification (The Structuring Phase)
+
+_Goal: Create the Source of Truth._
+
+1.  **The Master Registry (`docs/meta/industry_best_practices.md`)**: Catalog every atomic principle with a Definition, Requirements, and Source.
+2.  **The Abstraction Layer (`docs/engineering_principles.md`)**: Group principles into orthogonal dimensions.
+3.  **The Constitution (`docs/philosophy.md`)**: Synthesize the "Why" into a cohesive narrative.
+
+### Phase 4: Distribution (The Engineering Phase)
+
+_Goal: Make it executable._
+
+1.  **Atomic Specs (`specs/`)**: Explode the Master Registry into machine-readable Zettelkasten nodes for AI context injection.
+2.  **Separation**: Maintain the Standards (`lgtm-specs`) independently of the Implementation (`opencode-lgtm`).
+
+---
+
+## Validation Checklist
+
+Before a principle is adopted:
+
+- [ ] **Source**: Is it primary (book, paper, original author)?
+- [ ] **Testable**: Is the definition measurable?
+- [ ] **Orthogonal**: Does it overlap with existing principles?
+- [ ] **Universal**: Is it applicable to at least 2 programming languages?
+- [ ] **Anti-Pattern**: Does it have a clear "What violates this?" example?
+
+---
+
+## Meta-Process: Improving the Workflow
+
+This workflow itself evolves.
+
+**Quarterly Review**:
+
+- Which principles were rejected? Why?
+- Where did agents get stuck?
+- What conflicts arose most?
+
+**Change Process**:
+Changes to `workflow.md` require:
+
+1.  **RFC** (Request for Comments).
+2.  **2-week trial period**.
+3.  **Retrospective**.
+4.  **Merge or Revert**.

package/docs/philosophy.md

@@ -0,0 +1,36 @@
+# Philosophy
+
+This document outlines the core values and mission of the LGTM project.
+
+## 1. The Mission
+
+To raise the global standard of software engineering by making **Rigorous Verification** cheaper than **Hasty Implementation**.
+
+## 2. The Core Values
+
+### Truth over Convenience
+
+We do not optimize for "Time to First Token." We optimize for "Time to Correctness."
+
+- **Implication**: Our agents will refuse to write code if they don't understand the system.
+
+### Structure over Speed
+
+We believe that rigorous structure is the fastest way to build complex systems.
+
+- **Implication**: We enforce Zettelkasten, Atomic Commits, and Strict Capabilities.
+  - **Definition**: Every agent declares a `Capability` that the runtime uses to resolve a model from `models/registry.yaml`.
+
+### Machines over Humans (for Rote Work)
+
+Humans should focus on **Germane Load** (Learning, Strategy). Machines should handle **Extraneous Load** (Formatting, Imports, Context Switching).
+
+- **Implication**: If a machine can check it, a human shouldn't have to.
+
+## 3. The Implementation Strategy
+
+We implement these values through a **Knowledge Graph** architecture.
+
+- **Zettelkasten**: Rules are atomic nodes (e.g., `CONS-00015-safety.md`).
+- **RAG**: We inject only relevant nodes into agent context.
+- **Agentic Consensus**: No single agent has the authority to merge code.