lgtm-specs 0.0.4

package/docs/README.md

@@ -0,0 +1,13 @@
+# Docs
+
+This directory contains human-facing documentation that explains the design and sources behind the LGTM knowledge graph.
+
+## Index
+
+- [Agent Architecture](agent_architecture.md): Workforce philosophy, roles, and mode diagrams.
+- [Context Lifecycle](context_lifecycle.md): Context artifacts, prompt construction, and injection flow.
+- [Local Policies](local_policies.md): Consumer-repo policy layout and generation prompts.
+- [Engineering Principles](engineering_principles.md): Quality dimensions and first principles.
+- [Philosophy](philosophy.md): Project principles and framing.
+- [Meta (Languages)](meta/languages/README.md): Source material used to derive Laws.
+- [ADRs](adr/README.md): Architectural decisions.

package/docs/adr/0001-knowledge-engineering-workflow.md

@@ -0,0 +1,22 @@
+# 1. The Knowledge Engineering Workflow
+
+Date: 2026-01-30
+Status: Accepted
+
+## Context
+
+Standard AI "Knowledge Bases" are often hallucinations—collections of vague, unverified text that models ignore or misinterpret. To build a "Senior Engineer" agent, we need Ground Truth that is factually correct and intellectually rigorous.
+
+## Decision
+
+We adopt a strict **Knowledge Engineering Workflow** (Research -> Synthesis -> Codification).
+
+1.  **Research First**: No rule is written without citation. We verify primary sources (papers, books) before synthesis.
+2.  **Adversarial Review**: We explicitly critique our own drafts for overlaps and gaps.
+3.  **No Magic**: We reject "common wisdom" if it cannot be defined mechanistically.
+
+## Consequences
+
+- **High Latency**: The Research phase is time-intensive. We prioritize depth over breadth.
+- **High Authority**: Agents can cite sources ("According to Conway's Law...") with confidence.
+- **Traceability**: Every rule links back to its intellectual lineage.

package/docs/adr/0002-rule-hierarchy.md

@@ -0,0 +1,25 @@
+# 2. The Rule Hierarchy
+
+Date: 2026-01-30
+Status: Accepted
+
+## Context
+
+Engineering rules vary in scope. "Don't use global state" is universal. "Don't use `any`" is TypeScript-specific. "Use 2 spaces" is repo-specific. Flattening these confuses the agent context.
+
+## Decision
+
+We implement a three-tier hierarchy:
+
+1.  **Constitution (Universal)**: Immutable truths derived from Systems Theory and Computer Science. (Prefix: `CONS`).
+2.  **Laws (Domain)**: Technology-specific implementations of the Constitution. (Prefix: `TS`, `GO`, `GIT`).
+3.  **Policies (Project)**: Local configuration and preferences.
+
+## Consequences
+
+- **Separation of Concerns**: We can update Universal Rules without breaking specific Language Rules.
+- **Context Efficiency**: A Python agent loads `Constitution + Python Laws`, ignoring `TypeScript Laws`.
+
+## Notes
+
+This ADR defines the hierarchy only. Domain-specific operational policies (e.g., Git merge strategy and commit signing) belong in their own ADRs and meta docs (e.g., `docs/adr/0006-git-workflow-integrity.md`, `docs/meta/domains/git/`).

package/docs/adr/0003-atomic-knowledge-graph.md

@@ -0,0 +1,21 @@
+# 3. The Atomic Knowledge Graph (Zettelkasten)
+
+Date: 2026-01-30
+Status: Accepted
+
+## Context
+
+LLMs suffer from "Lost in the Middle" phenomenon when fed massive markdown files. Monolithic docs make it hard to inject precise context (e.g., "Only tell me about Safety").
+
+## Decision
+
+We adopt a **Zettelkasten** architecture.
+
+1.  **Atomicity**: One Rule = One File.
+2.  **Connectivity**: Files 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.
+
+## Consequences
+
+- **File Explosion**: We will have hundreds of small files.
+- **High Precision**: We can inject exactly `CONS-00015` and `CONS-00020` into a prompt, maximizing token efficiency and attention.

package/docs/adr/0004-identification-schema.md

@@ -0,0 +1,22 @@
+# 4. The Identification Schema
+
+Date: 2026-01-30
+Status: Accepted
+
+## Context
+
+We need a stable, scalable way to reference rules. Names change ("Simplicity" -> "Parsimony"), but references must persist.
+
+## Decision
+
+We use a **5-digit ID Schema** with semantic prefixes.
+
+- Format: `[PREFIX]-[00000]-[slug].md`
+- Example: `CONS-00001-srp.md`
+- Capacity: 99,999 rules per category.
+
+## Consequences
+
+- **Scalability**: Sufficient for any foreseeable future.
+- **Sortability**: Files sort logically on the filesystem.
+- **Stability**: Renaming a file's "slug" does not break the ID linkage (though text links need updates).

package/docs/adr/0005-agent-specialization.md

@@ -0,0 +1,39 @@
+# 5. Context-Aware Agent Specialization
+
+Date: 2026-01-30
+Status: Accepted
+
+## Context
+
+Standard coding agents suffer from two failures: "Context Overload" (loading 100 pages of rules) and "Implementation Myopia" (writing code without verifying it works).
+
+## Decision
+
+We adopt a specialized **Engineering Team Architecture** based on **Dynamic Injection** and **Role Verification**.
+
+### 1. Dynamic Context Injection
+
+- **Agnosticism**: Worker agents (`@Builder`, `@Reviewer`) do NOT have hardcoded access to the Knowledge Graph.
+- **Injection**: The `@Lead` (via `@Counsel`) selects a minimal subset of relevant rules and instructs the Runtime to
+  hydrate and inject rule content into the worker's prompt.
+- **Benefit**: This maximizes token efficiency and attention. The agent focuses on the specific constraints of the task.
+
+### 2. The "Senior Builder" Pattern
+
+- **Responsibility**: The `@Builder` agent is responsible for the entire "Inner Loop": Implementation AND Verification.
+- **Requirement**: A task is not done until it is coded _and_ proven (via Unit/Integration tests). We do not have a separate "Prover" agent that cleans up after the Builder.
+
+### 3. The "Review Panel" Pattern
+
+- **Adversarial Audit**: We treat code review as a multi-perspective consensus process.
+- **Specialization**: Instead of one general reviewer, we invoke specialized personas based on the task context:
+  - `@Reviewer-Logic`: Correctness & Soundness.
+  - `@Reviewer-Quality`: Maintainability & Standards.
+  - `@Reviewer-Test`: Test quality & Coverage.
+  - `@Reviewer-Security`: (Conditional) Vulnerability audit.
+  - `@Reviewer-Performance`: (Conditional) Efficiency audit.
+
+## Consequences
+
+- **Higher Quality**: Code is verified twice (by Builder, then by Panel).
+- **Focused Execution**: Agents only see what they need to know.

package/docs/adr/0006-git-workflow-integrity.md

@@ -0,0 +1,34 @@
+# 6. Git Workflow & Integrity Policy
+
+Date: 2026-02-03
+Status: Accepted
+
+## Context
+
+Git is the backbone of collaboration for LGTM agents and humans. Without a single, explicit policy, teams drift between merge strategies and integrity practices, which makes audit, rollback, and incident response unreliable.
+
+Git hosting platforms (e.g., GitHub) expose multiple merge methods, and local history rewriting is easy. We need to define what is allowed on `main` and what is allowed on feature branches.
+
+## Decision
+
+We adopt the following Git workflow and integrity policy for repositories managed by LGTM agents:
+
+1.  **Trunk-Based Workflow**: `main` is the only long-lived branch. Work happens on short-lived feature branches.
+2.  **Merge Strategy (Main)**: Changes land on `main` via merge commits. We preserve the commit series rather than flattening it.
+    - Disable squash merging and rebase merging on the hosting platform, unless the repository’s local policy
+      (`.lgtm/policies/README.md`) explicitly permits them.
+    - Never rebase `main`.
+3.  **Rebase Strategy (Feature Branches)**: Feature branches may be rebased onto `main` to keep their history reviewable.
+    - Rebase only branches you own (no one else has pulled).
+    - If a rebased branch was already pushed, update it with `git push --force-with-lease`.
+4.  **History Integrity**: Never force-push shared branches (`main`).
+5.  **Cryptographic Identity**: Commits on `main` must be signed (GPG or SSH). Feature branch commits must be signed.
+    - Enforce via branch protection: require signed commits on `main`.
+6.  **Automation**: Local Git hooks are allowed as fast feedback, but CI is the authoritative gate for merges.
+
+## Consequences
+
+- **Auditability**: `main` retains the full patch series for each change, improving review quality, reverts, and `git bisect`.
+- **Non-Linear History**: `main` history will not be perfectly linear (merge commits are expected).
+- **Operational Discipline**: Feature-branch rebases require care (ownership rules, `--force-with-lease`).
+- **Setup Cost**: Requiring signatures increases developer setup overhead, but improves authorship verification and supply-chain integrity.

package/docs/adr/0007-operating-modes-and-gates.md

@@ -0,0 +1,54 @@
+# ADR-0007: Operating Modes and Safety Gates
+
+Date: 2026-02-04
+Status: Accepted
+
+## Context
+
+The LGTM system defines specialized Roles (Lead/Planner/Counsel/Builder/Reviewer/etc.) and top-level Operating Modes (`@Build`, `@Hack`, `@Review`).
+
+We observed spec drift and ambiguity when orchestration rules were duplicated across:
+
+- Mode specs (`agents/modes/*.md`)
+- Role specs (especially `agents/roles/lead.md`)
+- Narrative docs ([docs/agent_architecture.md](../agent_architecture.md))
+
+We also need a principled policy for when a user requests `@Hack` on critical paths.
+
+## Decision
+
+### 1) Source of truth
+
+- **Mode specs** (`agents/modes/build.md`, `agents/modes/hack.md`, `agents/modes/review.md`) are the canonical orchestration definitions.
+- **Role specs** (`agents/roles/**`) define contracts (inputs/outputs/constraints) and selection logic, but must not redefine full end-to-end orchestration.
+- **Architecture docs** ([docs/agent_architecture.md](../agent_architecture.md)) explain roles and workflows and link to canonical mode/role specs.
+
+### 2) Hack on critical paths
+
+If the user selects `@Hack`, the system must not override the mode.
+
+There is no automatic escalation within Hack. If the user chooses this mode, the workflow runs as-is.
+
+### 3) Planning is default-on
+
+`@Planner` runs by default in all modes:
+
+- In `@Build` and `@Hack`, it produces an execution plan.
+- In `@Review`, it produces an audit plan.
+
+Exception:
+
+- In `@Review`, tools MAY skip planning for trivial, low-risk diffs (after generated-file exclusion) and proceed directly
+  to audit using a default specialist set.
+
+### 4) Plan review count is mode-dependent
+
+- `@Build`: two independent plan reviewers.
+- `@Hack`: 0-1 plan reviewers based on risk and scope.
+- `@Review`: at least 1 plan reviewer when planning runs.
+
+## Consequences
+
+- Reduced spec drift by clearly assigning ownership.
+- Maintains user mode intent without automatic escalation in `@Hack`.
+- Keeps worker agents agnostic: reviewers do not retrieve rules; they receive injected requirements.

package/docs/adr/0008-rules-vs-workflows-boundary.md

@@ -0,0 +1,64 @@
+# ADR-0008: Rules vs Workflows Boundary
+
+Date: 2026-02-10
+Status: Accepted
+
+## Context
+
+This repository contains two kinds of specifications that can look similar at a glance:
+
+- Atomic rules in `rules/**` (Constitution/Laws/Policies)
+- Procedural workflows in `agents/**` (Modes and Roles)
+
+During review, we observed drift risk when:
+
+- normative engineering requirements were written into role workflows (bypassing `@Counsel` selection), and
+- orchestration/tooling details were written into atomic rules (polluting the Zettelkasten).
+
+We need a crisp boundary so contributors know where new knowledge belongs.
+
+## Decision
+
+We define three layers with distinct responsibilities.
+
+### 1) Atomic Rules (`rules/**`): "What must be true"
+
+Atomic rules are normative constraints that can be selected and injected dynamically.
+
+- Content: `## Definition`, `## Requirements`, `## Anti-Patterns`, `## Examples`
+- Properties: stable, reusable, domain-scoped via tags, source-cited via `docs/meta/**`
+- Usage: selected by `@Counsel` and injected into downstream agents via `{{injected_rules}}`
+
+Rule of thumb:
+
+- If it is a timeless principle you would want to cite independently, it is a rule.
+- If it needs a source, tags, and examples to avoid ambiguity, it is a rule.
+
+### 2) Role Specs (`agents/roles/**`): "How this worker operates"
+
+Role specs are procedural prompt contracts for a single worker.
+
+- Content: inputs, outputs, workflow steps, boundaries, and how to apply injected rules
+- Properties: role-specific, tool-agnostic where possible, minimal heuristics as fallback
+
+Role workflows MUST NOT embed broad normative guidance that should be injected as rules.
+If a role needs a norm (e.g., "tests should document the scenario"), that norm should live in `rules/**` and be injected.
+
+Role workflows MAY include:
+
+- ordering constraints (e.g., "load diff via Diff Command when Diff is omitted")
+- output contracts (format, evidence requirements)
+- focus boundaries (what to ignore)
+
+### 3) Mode Specs (`agents/modes/**`): "How roles are orchestrated"
+
+Mode specs define end-to-end orchestration: which roles run, gates/loops, escalation/arbitration, and delivery.
+
+- Canonical orchestration lives in mode specs.
+- Roles must not redefine mode orchestration.
+
+## Consequences
+
+- Reduced drift: norms live in one place (`rules/**`) and are injected selectively.
+- Cleaner prompts: role specs stay procedural; rules stay normative.
+- Better tooling: integration can shape inputs per role (diff scoping, rule filtering) without rewriting principles.

package/docs/adr/README.md

@@ -0,0 +1,14 @@
+# Architecture Decision Records (ADR)
+
+This directory documents the meta-architectural decisions for the `lgtm-specs` repository.
+
+## Index
+
+- [ADR-0001: The Knowledge Engineering Workflow](0001-knowledge-engineering-workflow.md)
+- [ADR-0002: The Rule Hierarchy](0002-rule-hierarchy.md)
+- [ADR-0003: The Atomic Knowledge Graph (Zettelkasten)](0003-atomic-knowledge-graph.md)
+- [ADR-0004: The Identification Schema](0004-identification-schema.md)
+- [ADR-0005: Context-Aware Agent Specialization](0005-agent-specialization.md)
+- [ADR-0006: Git Workflow & Integrity Policy](0006-git-workflow-integrity.md)
+- [ADR-0007: Operating Modes and Safety Gates](0007-operating-modes-and-gates.md)
+- [ADR-0008: Rules vs Workflows Boundary](0008-rules-vs-workflows-boundary.md)

package/docs/agent_architecture.md

@@ -0,0 +1,164 @@
+# Agent Architecture
+
+This document defines the **Cognitive Architecture** and **Organizational Structure** of the LGTM autonomous workforce. It is derived from the principles of [Collaborative Dynamics](meta/collaborative_dynamics.md).
+
+---
+
+# 1. Philosophy: Agents as Staff Engineers
+
+We do not build "Chatbots" that respond to prompts. We build **Autonomous Engineers** that execute workflows.
+
+- **Role-Based**: Agents have distinct identities, responsibilities, and constraints.
+- **Context-Aware**: Agents do not load the entire universe. They receive precise, dynamically injected context relevant to their immediate task.
+- **Adversarial**: Quality is achieved through consensus, not individual brilliance. Builders build; Reviewers critique.
+
+---
+
+# 2. The Professional Engineering Team
+
+We organize agents into a high-performance **Engineering Team** optimized for velocity and rigor.
+
+| Badge | Role          | Capability | Responsibility                                                                                              |
+| :---- | :------------ | :--------- | :---------------------------------------------------------------------------------------------------------- |
+| 🧠    | **Lead**      | reasoning  | **Orchestrator**. Analyzes requests, consults Counsel, decomposes tasks, and manages the lifecycle.         |
+| 🗺️    | **Planner**   | reasoning  | **Architect**. Designs the execution plan or audit plan.                                                    |
+| ⚖️    | **Counsel**   | data       | **Legal**. Retrieval system that selects the correct Laws/Rules for the context.                            |
+| 🔨    | **Builder**   | coding     | **Maker**. Implements the code and the required proof (tests and/or other evidence). Owns the "Inner Loop." |
+| 🔍    | **Explorer**  | fast       | **Cartographer**. Maps the codebase structure and finds existing patterns.                                  |
+| 📚    | **Librarian** | docs       | **Researcher**. External knowledge and library references.                                                  |
+| 👮    | **Reviewer**  | reasoning  | **Gatekeeper**. A panel of specialists who audit code against specific rules.                               |
+
+Notes:
+
+- The Review Panel includes sub-roles with different capabilities (e.g., `reviewer/lite` uses `fast`, `reviewer/security` uses `security`).
+
+---
+
+# 3. Core Dynamics
+
+## 3.1 Dynamic Context Injection
+
+Agents are **Agnostic**. They do not know domain- or language-specific rules (or repo-local policies) by default.
+
+1.  **Lead** calls **Counsel** to scan the Knowledge Graph indices.
+2.  **Counsel** selects specific atomic rules (e.g., `GO-00001`, `CONS-00015`).
+3.  **Lead** instructs the **Runtime** to retrieve/hydrate rule content and inject it into the **Planner**, **Builder**,
+    and any **Reviewers** invoked by the selected Mode.
+
+- **Benefit**: Maximizes token efficiency and attention focus.
+
+## 3.2 The Consensus Protocol
+
+Code is never accepted on the first draft.
+
+- **Plan Gate (Build)**: Execution plans are reviewed by two independent plan reviewers.
+- **Micro-Review**: Every atomic commit is audited by the **Reviewer-Lite** (Fast Track).
+- **Panel Gate (Build)**: The final PR is audited by the specialist **Review Panel** (Deep Track).
+- **Veto Power**: If _any_ Reviewer rejects the change, the Builder enters a **Self-Correction Loop**.
+
+## 3.3 The "Senior Builder" Pattern
+
+We do not use a separate "QA" agent to clean up messes.
+
+- **Ownership**: The Builder is responsible for **Proving** their code works.
+- **Requirement**: In `@Build`, tasks are incomplete without the required proof (often unit tests). In `@Hack`, tests are optional.
+
+---
+
+# 4. The Workflows (Operating Modes)
+
+LGTM exposes three top-level workflows ("Agents" / Modes). Each Mode orchestrates the Roles.
+
+Note: The diagrams below are illustrative. The canonical workflow definitions and loop limits live in `agents/modes/*.md`.
+
+## 4.1 @Build (Production)
+
+- **Goal**: High-assurance changes.
+- **Properties**: Plan sign-off gate, two plan reviewers, micro-review on each atomic diff, full review panel before delivery.
+- **Spec**: [`agents/modes/build.md`](../agents/modes/build.md)
+
+```mermaid
+flowchart TD
+    U[User Request] --> L[Lead]
+    L --> E[Explorer]
+    E --> L
+    L --> C[Counsel]
+    C --> L
+    L --> P[Planner]
+
+    P --> PR1[Plan Reviewer 1]
+    P --> PR2[Plan Reviewer 2]
+    PR1 --> G1{Plan Approved}
+    PR2 --> G1
+    G1 -->|no| P
+    G1 -->|yes| UG[User Signoff]
+
+    UG --> B[Builder]
+    B --> RL[Reviewer Lite]
+    RL -->|reject| B
+    RL -->|pass| NEXT{More tasks?}
+    NEXT -->|yes| B
+    NEXT -->|no| PANEL[Review Panel]
+    PANEL -->|reject| B
+    PANEL -->|approve| DONE[Deliver PR]
+    PANEL -->|deadlock| ARB[Lead Arbitration]
+```
+
+## 4.2 @Hack (Prototype)
+
+- **Goal**: Rapid experiments and lightweight changes.
+- **Properties**: Sketch plan (`@Planner`) with optional plan review; micro-review on atomic diffs.
+- **Critical Paths**: Hack remains allowed. No automatic escalation.
+- **Spec**: [`agents/modes/hack.md`](../agents/modes/hack.md)
+
+```mermaid
+flowchart TD
+    U[User Request] --> L[Lead]
+    L --> E[Explorer]
+    E --> L
+    L -->|optional| C[Counsel]
+    C --> L
+    L --> P[Planner]
+    P -->|optional| PR[Plan Reviewer]
+    PR -->|revise| P
+    PR -->|approve| B[Builder]
+    P -->|skip| B
+    B --> RL[Reviewer Lite]
+    RL -->|reject| B
+    RL -->|approve| DONE[Draft Branch]
+```
+
+## 4.3 @Review (Audit)
+
+- **Goal**: Read-only critique and analysis.
+- **Properties**: Default-on planning (`@Planner`) with a trivial-diff exception; plan review when planning runs; inject rules
+  into reviewers; execute reviewers in parallel; synthesize findings.
+- **Spec**: [`agents/modes/review.md`](../agents/modes/review.md)
+
+```mermaid
+flowchart TD
+    U[Target Scope] --> L[Lead]
+    L --> E[Explorer]
+    E --> L
+    L --> C[Counsel]
+    C --> L
+    L --> T{Trivial?}
+    T -->|yes| R[Review Panel Parallel]
+    T -->|no| P[Planner Audit Plan]
+    P -->|min 1| PR[Plan Reviewer]
+    PR -->|approve| R
+    PR -->|reject| P
+    R --> REP[Report]
+```
+
+## 4.4 Role Specs
+
+The canonical contracts for each role live under `agents/roles/`.
+
+- Lead: [`agents/roles/lead.md`](../agents/roles/lead.md)
+- Planner: [`agents/roles/planner.md`](../agents/roles/planner.md)
+- Counsel: [`agents/roles/counsel.md`](../agents/roles/counsel.md)
+- Builder: [`agents/roles/builder.md`](../agents/roles/builder.md)
+- Explorer: [`agents/roles/explorer.md`](../agents/roles/explorer.md)
+- Librarian: [`agents/roles/librarian.md`](../agents/roles/librarian.md)
+- Review Panel: [`agents/roles/reviewer/README.md`](../agents/roles/reviewer/README.md)