lgtm-specs 0.0.4

package/docs/context_lifecycle.md

@@ -0,0 +1,228 @@
+# Context and Prompt Lifecycle
+
+This document explains the lifecycle of the two fundamental components of the LGTM workforce:
+
+1.  **Prompt Lifecycle**: The mechanism of how agents are invoked, how they call tools, and how the Runtime orchestrates the loop.
+2.  **Context Lifecycle**: The state of knowledge—how artifacts (maps, rules, diffs) are discovered, filtered, and injected into those prompts.
+
+Mode specs (`agents/modes/**`) define orchestration (gates/loops). Role specs (`agents/roles/**`) define worker behavior.
+The implementer contract lives in `/integrate/README.md`.
+
+---
+
+## 1. Prompt Lifecycle (The Mechanism)
+
+The "Prompt" is the interface between the Runtime and the Model. It is dynamically constructed for every turn of the conversation.
+
+### 1.1 The Interaction Loop (Who Talks to Whom)
+
+The Runtime acts as the central message bus. Agents never communicate directly; they emit **Tool Calls** (structured requests) or **Final Responses** (text/JSON). The Runtime intercepts these signals, executes the requested action (e.g., run a sub-agent, read a file), and feeds the result back to the caller.
+
+- **User**: Initiates the Request.
+- **Runtime**: The infinite loop that executes tools and manages state.
+- **Lead**: The root agent that orchestrates other agents.
+- **Sub-Agents**: Worker agents (Explorer, Planner, etc.) invoked by Lead via Tool Calls.
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant R as Runtime
+    participant L as "@Lead"
+    participant S as SubAgent ("@Explorer/@Planner")
+    participant T as Tools (Git/FS)
+
+    U->>R: Request
+    R->>L: Invoke (with Mode + Request)
+
+    loop Orchestration
+        L->>R: Tool Call (e.g., delegate to @Explorer)
+        R->>S: Invoke (with tailored Input Packet)
+
+        loop Sub-Agent Execution
+            S->>R: Tool Call (e.g., read file)
+            R->>T: Execute
+            T-->>R: Result
+            R-->>S: Tool Output
+        end
+
+        S-->>R: Final Response (Text/JSON)
+        R-->>L: Tool Output (SubAgent Result)
+    end
+
+    L-->>R: Final Response
+    R-->>U: Result
+```
+
+### 1.2 Prompt Construction (How a Spec becomes a Prompt)
+
+The Runtime builds the System Prompt by combining the static Agent Spec (`agents/**/*.md`) with dynamic runtime data.
+
+1.  **Parse**: The Runtime reads the Markdown spec and extracts tagged sections (e.g., `<Role>`, `<Workflow>`, `<Constraints>`).
+2.  **Strip**: Metadata sections (`<Meta>`, `<Input>`) are stripped out.
+3.  **Template**: Placeholders are replaced with actual content (see Context Lifecycle), including:
+    - `{{injected_rules}}` (hydrated rules)
+    - `{{reviewer_base_constraints}}` and `{{reviewer_output_format}}` (shared reviewer blocks)
+4.  **Compose**: The final System Prompt is sent to the LLM along with the Conversation History (Messages).
+
+For the authoritative section parsing rules and semantics, see `/integrate/README.md`.
+
+```mermaid
+flowchart TD
+    SPEC["Agent Spec (agents/**)"] --> PARSE[Runtime: Parse Sections]
+
+    subgraph Context Injection
+    RULES[Hydrated Rules] --> TEMPLATE
+    MAP[Context Map] --> TEMPLATE
+    end
+
+    PARSE --> TEMPLATE[Runtime: Template Placeholders]
+    TEMPLATE --> PROMPT[Final System Prompt]
+    PROMPT --> LLM[Model Invocation]
+```
+
+---
+
+## 2. Context Lifecycle (The Knowledge)
+
+"Context" is the data available to an agent. It is not global; it is discovered, filtered, and injected on a need-to-know basis to manage token costs and focus.
+
+### 2.1 The Context Map (The Terrain)
+
+The **Context Map** is the foundation. `@Explorer` acts as the cartographer, converting a raw directory tree into a
+semantic map of "Domains" (languages), "Policies" (repo-local guidance), and "Risks".
+
+Policy discovery includes repo-local policies at `.lgtm/policies/README.md` (when present) and other governing docs
+surfaced as **Project Policy Files**.
+
+- **Produced by**: `@Explorer`.
+- **Consumed by**: `@Lead` (routing), `@Counsel` (rule selection), `@Planner` (touchpoints).
+
+```mermaid
+flowchart TD
+    U[User Request] --> L("@Lead")
+    L -- "Tool Call: explore(scope)" --> R[Runtime]
+    R -- "Invoke: Query + Scope" --> E("@Explorer")
+
+    subgraph Discovery
+    E -- "list/search/read" --> FS[(Filesystem)]
+    FS -- "Paths + Content" --> E
+    end
+
+    E -- "Return: Context Map (JSON/MD)" --> R
+    R -- "Tool Output: Context Map" --> L
+
+    L -.-> NOTE[The Map is now in @Lead context]
+
+    L -- "Pass Map in Input" --> P("@Planner")
+    L -- "Pass Map in Input" --> C("@Counsel")
+```
+
+### 2.2 Rule Context (The Law)
+
+Rule context is a two-stage pipeline: **Selection** and **Hydration**.
+
+1.  **Selection**: `@Counsel` selects relevant _paths_ based on the Context Map. It does not read the rule content.
+2.  **Hydration**: The **Runtime** reads the files, strips headers (metadata), and renders the body text.
+3.  **Injection**: The Runtime injects the text into the `{{injected_rules}}` placeholder of downstream agents.
+    Shared placeholders (reviewer blocks) are also expanded during prompt templating.
+
+```mermaid
+flowchart TD
+    L("@Lead") -- "Tool Call: counsel(task, map, indices)" --> R[Runtime]
+    R -- "Invoke: Task + Context Map + Indices" --> C("@Counsel")
+    C -- "Return: JSON paths" --> R
+
+    subgraph Hydration [Runtime Responsibility]
+    R -- "Read files" --> FS[(Filesystem)]
+    FS -- "Raw markdown" --> R
+    R -- "Strip + render (trimmed/full)" --> TEXT[Rule bodies]
+    end
+
+    subgraph Injection
+    TEXT -- "Inject subset" --> P("@Planner")
+    TEXT -- "Inject per-reviewer subset" --> REV("@Reviewers")
+    TEXT -- "Inject subset" --> B("@Builder")
+    end
+```
+
+### 2.3 Tiered Git Context (The Change)
+
+Git context is heavy. To maintain speed and reduce costs, we deliver it in tiers.
+Default routing is by role; the Runtime may override based on mode and task.
+
+- **Tier 0 (Intent)**: Commit subjects. Cheap. Default: Lead/Counsel; may also appear in `Change Manifest` for others.
+- **Tier 1 (Scope)**: File manifest. Moderate. Default: Planner; optional for Explorer/Lead/Counsel.
+- **Tier 2 (Detail)**: Filtered diff. Expensive. Default: Reviewers; optional for Builder when addressing findings; Lead
+  sees Tier 2 only during arbitration.
+  - _Optimization_: Tier 2 is often provided as a `Diff Command` rather than inline text, letting the agent fetch it only if needed.
+
+```mermaid
+flowchart TD
+    GIT[(Git)] --> T0[Tier 0: Commit Log]
+    GIT --> T1[Tier 1: File Manifest]
+    GIT --> T2[Tier 2: Filtered Diff]
+
+    L("@Lead")
+    C("@Counsel")
+    E("@Explorer")
+    P("@Planner")
+    REV("@Reviewers")
+    B("@Builder")
+
+    subgraph "High Level (Intent)"
+    T0 --> L
+    T0 --> C
+    end
+
+    subgraph "Mid Level (Scope)"
+    T1 -. Optional .-> E
+    T1 --> P
+    end
+
+    subgraph "Low Level (Details)"
+    T2 -- "Inline or Command" --> REV
+    T2 -. Optional .-> B
+    T2 -. Arbitration .-> L
+    end
+```
+
+### 2.4 Arbitration Context (The Escalation)
+
+When consensus fails (e.g., Reviewers reject a plan, or disagree on a finding), the `@Lead` enters **Arbitration Mode**. The context window expands to resolve the conflict.
+
+1.  **Full Rules**: Contested rules are re-injected with full examples/rationale (overriding the "Trimmed" default).
+2.  **Tier 2 Context**: The Lead, who normally sees only high-level signals, is granted access to the specific diff lines in question to make a ruling.
+
+```mermaid
+stateDiagram-v2
+    state "Standard Mode" as S
+    state "Arbitration Mode" as A
+
+    S --> A: Deadlock / Timeout
+
+    state S {
+        [*] --> Lead
+        Lead --> Reviewers: Sparse Context
+        Reviewers --> Lead: Conflict
+    }
+
+    state A {
+        [*] --> Lead
+        Lead --> Runtime: Request Arbitration
+        Runtime --> Lead: Inject full contested rules + Tier 2 diff (targeted)
+        Lead --> User: Final Verdict
+    }
+```
+
+---
+
+## 3. What Goes Where (Quick Reference)
+
+| Actor       | Produces                               | Consumed by               | Notes                                                 |
+| ----------- | -------------------------------------- | ------------------------- | ----------------------------------------------------- |
+| `@Explorer` | Context Map (Summary + Full)           | Lead, Counsel, Planner    | Summary should include domains + policy files.        |
+| `@Counsel`  | Rule/policy paths (JSON)               | Runtime (tool logs)       | Counsel never outputs rule bodies.                    |
+| Runtime     | Hydrated rules + shared blocks         | Planner/Builder/Reviewers | Inject role-appropriate subsets; expand placeholders. |
+| `@Planner`  | Execution plan / audit plan            | Lead, Plan-Reviewer       | Plan references rule IDs, not rule text.              |
+| Reviewers   | Findings (bullets)                     | Lead                      | Evidence required (paths + line numbers).             |
+| `@Lead`     | Synthesis / report / next-step routing | User, Runtime             | Clarifies disputes; triggers arbitration when needed. |

package/docs/engineering_principles.md

@@ -0,0 +1,128 @@
+# Engineering Principles
+
+This document abstracts the "First Principles" of software engineering. It groups the 12 core properties into four dimensions, defining the complete quality space of a software system. It is derived from state-of-the-art industry standards recorded in [Industry Best Practices](meta/industry_best_practices.md).
+
+### Quality Dimensions at a Glance
+
+| Dimension                                                         | Phase   | Question               | Qualities                                                                                                                                  |
+| :---------------------------------------------------------------- | :------ | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Structural Design](#structural-design-the-code)**              | Design  | "How is it organized?" | [Orthogonality](#1-orthogonality-decoupling), [Cohesion](#2-cohesion-focus), [Parsimony](#3-parsimony-simplicity)                          |
+| **[Behavioral Correctness](#behavioral-correctness-the-logic)**   | Verify  | "Does it work?"        | [Correctness](#4-correctness-safety), [Determinism](#5-determinism-predictability), [Security](#6-security-defense)                        |
+| **[Runtime Survivability](#runtime-survivability-the-execution)** | Execute | "Will it survive?"     | [Robustness](#7-robustness-hardness), [Resilience](#8-resilience-elasticity), [Efficiency](#9-efficiency-performance)                      |
+| **[Operational Lifecycle](#operational-lifecycle-the-future)**    | Evolve  | "Can we maintain it?"  | [Transparency](#10-transparency-observability), [Operability](#11-operability-runnability), [Evolvability](#12-evolvability-changeability) |
+
+---
+
+# Structural Design (The Code)
+
+**Thesis**: Complexity is managed by decoupling components (Orthogonality), keeping related code together (Cohesion), and minimizing parts (Parsimony).
+
+## 1. Orthogonality (Decoupling)
+
+**Definition**: A system design where changing one component does not create side effects or require changes in other, unrelated components. It is the mathematical independence of system variables.
+
+- **Requirements**: Narrow interfaces, no global state.
+- **References**: [SOLID](meta/industry_best_practices.md#1-solid-principles), [Law of Demeter](meta/industry_best_practices.md#84-law-of-demeter).
+
+## 2. Cohesion (Focus)
+
+**Definition**: The degree to which the elements inside a module belong together. A highly cohesive module performs one task and contains most of the data and logic required to perform it.
+
+- **Requirements**: Fields participate in primary responsibility, locality of behavior.
+- **References**: [SRP](meta/industry_best_practices.md#11-single-responsibility-principle-srp), [Deep Modules](meta/industry_best_practices.md#21-deep-modules).
+
+## 3. Parsimony (Simplicity)
+
+**Definition**: The principle that the simplest solution that suffices is the correct one. It prioritizes the reduction of moving parts and cognitive load.
+
+- **Requirements**: Reject speculative generality, prefer standard libraries.
+- **References**: [KISS](meta/industry_best_practices.md#81-kiss-keep-it-simple-stupid), [YAGNI](meta/industry_best_practices.md#82-yagni-you-arent-gonna-need-it), [Cognitive Limits](meta/industry_best_practices.md#43-cognitive-limits-batch-size).
+
+---
+
+# Behavioral Correctness (The Logic)
+
+**Thesis**: A system must fulfill its contract (Correctness), behave predictably (Determinism), and protect its assets (Security).
+
+## 4. Correctness (Safety)
+
+**Definition**: The guarantee that the system behaves according to its specification and that illegal states are mathematically unrepresentable.
+
+- **Requirements**: State space encoded in types (Enums/Unions), invariants enforced by construction.
+- **References**: [Safety by Design](meta/industry_best_practices.md#61-safety-by-design), [LSP](meta/industry_best_practices.md#13-liskov-substitution-principle-lsp).
+
+## 5. Determinism (Predictability)
+
+**Definition**: The property that a system's behavior is consistent and reproducible given the same initial state and inputs.
+
+- **Requirements**: Pure functions, explicit dependencies (injected).
+- **References**: [CQS](meta/industry_best_practices.md#62-command-query-separation-cqs), [Explicitness](meta/industry_best_practices.md#35-explicitness).
+
+## 6. Security (Defense)
+
+**Definition**: The ability of the system to protect information and maintain functionality in the face of malicious acts.
+
+- **Requirements**: Least Privilege, Zero Trust, Secure Defaults.
+- **References**: [Security Engineering](meta/industry_best_practices.md#9-security-engineering), [Privacy](meta/industry_best_practices.md#17-privacy--compliance).
+
+---
+
+# Runtime Survivability (The Execution)
+
+**Thesis**: A running system must resist local failure (Robustness), recover from systemic failure (Resilience), and respect resource constraints (Efficiency).
+
+## 7. Robustness (Hardness)
+
+**Definition**: The ability to resist local failure by handling erroneous inputs or unexpected states gracefully without crashing.
+
+- **Requirements**: Input sanitization at boundary, defining errors out of existence.
+- **References**: [Postel's Law](meta/industry_best_practices.md#63-postels-law), [Input Validation](meta/industry_best_practices.md#94-input-validation).
+
+## 8. Resilience (Elasticity)
+
+**Definition**: The ability of a system to recover from failure and restore functionality, often involving degradation of service rather than total collapse.
+
+- **Requirements**: Idempotency, circuit breakers, timeouts.
+- **References**: [Fallacies](meta/industry_best_practices.md#72-fallacies-of-distributed-computing), [Operational Reliability](meta/industry_best_practices.md#18-operational-reliability).
+
+## 9. Efficiency (Performance)
+
+**Definition**: The optimal use of bounded computational resources (time, memory, bandwidth) to achieve the desired result.
+
+- **Requirements**: Known Big-O complexity, bounded resource usage.
+- **References**: [Performance](meta/industry_best_practices.md#12-performance--efficiency), [Data Engineering](meta/industry_best_practices.md#13-data-engineering).
+
+---
+
+# Operational Lifecycle (The Future)
+
+**Thesis**: A system must be visible (Transparency), runnable (Operability), and adaptable (Evolvability) to survive long-term.
+
+## 10. Transparency (Observability)
+
+**Definition**: The ability to understand the internal state and runtime behavior of a system by examining its outputs.
+
+- **Requirements**: Telemetry by design, distinguishable failure states.
+- **References**: [Observability](meta/industry_best_practices.md#11-observability--operations).
+
+## 11. Operability (Runnability)
+
+**Definition**: The ease with which the system can be run, monitored, and maintained by the engineering team.
+
+- **Requirements**: Runbooks, congruent team boundaries, automated checklists.
+- **References**: [Socio-Technical Congruence](meta/industry_best_practices.md#52-socio-technical-congruence), [Checklist](meta/industry_best_practices.md#44-the-checklist).
+
+## 12. Evolvability (Changeability)
+
+**Definition**: The ease with which the system can be adapted to new requirements or modified to fix defects over time.
+
+- **Requirements**: Testability, Feature Flags, API Versioning.
+- **References**: [OCP](meta/industry_best_practices.md#12-openclosed-principle-ocp), [Delivery](meta/industry_best_practices.md#14-delivery--evolution).
+
+---
+
+## Interplay of Qualities
+
+- **Structural Design** enables **Evolvability**: If code is orthogonal, it is easier to change safely.
+- **Behavioral Correctness** enables **Robustness**: If invariants are enforced by types, runtime validation has less work to do.
+- **Transparency** enables **Operability**: You cannot run what you cannot see.

package/docs/local_policies.md

@@ -0,0 +1,59 @@
+# Local Policies (Consumer Repos)
+
+Local policies are repo-specific by-laws that LGTM tools can load from the user's repository to override/extend defaults.
+
+Primary entrypoint:
+
+- `.lgtm/policies/README.md`
+
+If it does not exist, tools fall back to `rules/policies/default.md`.
+
+## Recommended Layout (Zettelkasten)
+
+Create `.lgtm/policies/` with a Primary index file.
+
+- `.lgtm/policies/README.md`: the Primary policy entrypoint (summary + links).
+- `.lgtm/policies/*.md`: atomic policy notes (one policy per file).
+
+Rule of thumb: keep the Primary file short and link out to atomic notes.
+
+## Policy File Format (Tool-Consumable)
+
+To be safely injectable, local policy files SHOULD follow the same section structure as rules in this repo:
+
+- `## Definition`
+- `## Requirements`
+- `## Anti-Patterns`
+- `## Examples`
+
+This makes it possible for tools to treat policies like other injected rules.
+
+## Prompt Template (Generate Local Policies)
+
+Use this prompt in the consumer repo to generate `.lgtm/policies/README.md` and a small set of atomic notes.
+
+```text
+You are generating repo-local LGTM policy files.
+
+Inputs you will be given:
+- Repository tree (paths)
+- Key config files (CI, lint, format, language toolchains)
+- Contribution/release docs (CONTRIBUTING, SECURITY, CODEOWNERS, docs)
+
+Output requirements:
+1) Create `.lgtm/policies/README.md` as the Primary entrypoint.
+2) Create 3-8 atomic policy note files under `.lgtm/policies/` for specific topics that matter in this repo.
+3) Each policy file MUST contain: `## Definition`, `## Requirements`, `## Anti-Patterns`, `## Examples`.
+4) Requirements must be concrete and testable (commands, checks, or observable behaviors).
+5) Keep the Primary file short: summarize the top rules and link to atomic notes.
+6) Avoid duplicating generic best practices; focus on repo-specific by-laws (tooling choices, workflow rules,
+   directory conventions, review requirements).
+
+Return:
+- A file list with paths.
+- The full contents for each file.
+```
+
+## Related
+
+- [`contribute/add-policy.md`](/contribute/add-policy.md): How to add shared policies to `lgtm-specs`.

package/docs/meta/collaborative_dynamics.md

@@ -0,0 +1,142 @@
+# Collaborative Dynamics & Team Architecture
+
+This document defines the principles of **Socio-Technical Congruence** and **High-Performance Collaboration**. It serves as the standard for how Agents (and Humans) interact within the LGTM organization.
+
+**Sources**: [Team Topologies](https://teamtopologies.com/), [Google SRE](https://sre.google/), [GitLab Handbook](https://about.gitlab.com/handbook/).
+
+---
+
+# 1. Cognitive Load Theory
+
+_Source: [John Sweller](https://en.wikipedia.org/wiki/Cognitive_load_theory) / [Matthew Skelton & Manuel Pais](https://teamtopologies.com/)_
+
+The fundamental constraint on software delivery is not CPU cycles, but human working memory.
+
+## 1.1 Types of Load
+
+- **Intrinsic Load**: The difficulty of the task itself (e.g., recursive logic). _Goal: Manage it._
+- **Extraneous Load**: The environment noise (e.g., confusing API, manual deployment). _Goal: Eliminate it._
+- **Germane Load**: The effort of learning and schema formation. _Goal: Optimize it._
+
+## 1.2 The Strategy
+
+- **Minimize Extraneous Load**: Agents/Tools must handle rote tasks (Linting, Formatting, Imports). If a human has to "remember" to format code, the tool has failed.
+- **Match Team to Stream**: A team's cognitive capacity must match the complexity of their owned software subsystem.
+
+---
+
+# 2. Team Topologies & Ownership
+
+_Source: [Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law) / [Inverse Conway Maneuver](https://martinfowler.com/bliki/ConwaysLaw.html)_
+
+## 2.1 The Stream-Aligned Team (The "Squad")
+
+- **Purpose**: Aligned to a single stream of work. Empowered to deliver value independently.
+- **Composition**: Cross-functional (Dev + QA + Ops). No hand-offs.
+- **Agent Mapping**: The default "LGTM Engineering Team" (Lead, Builder, Reviewer).
+
+## 2.2 The Two-Pizza Rule
+
+- **Principle**: A team should be small enough (5-7 agents/people) to maintain high-bandwidth communication without combinatorial explosion.
+
+## 2.3 The Team API
+
+- **Definition**: Teams interact only through defined, versioned interfaces.
+- **SLA Schema**:
+  - **Response Time**: (e.g., "Critical: 1h, Normal: 24h")
+  - **Versioning**: (e.g., "v1.0 stable, v2.0 beta")
+  - **Support Channel**: (e.g., "#team-auth-help")
+
+---
+
+# 3. Decision Making & Escalation
+
+_Source: [Thinking in Bets](https://en.wikipedia.org/wiki/Annie_Duke#Thinking_in_Bets) / [Amazon Leadership Principles](https://www.amazon.jobs/en/principles)_
+
+## 3.1 The Tie-Breaker Rule
+
+When principles conflict, we prioritize:
+
+1.  **Correctness** over Efficiency.
+2.  **Robustness** over Features.
+3.  **Transparency** over Convenience.
+
+## 3.2 The Disagreement Protocol
+
+When Agents (e.g., Builder vs. Reviewer) disagree:
+
+1.  **State the Tradeoff**: Explicitly name the conflict (e.g., "Trading Parsimony for Performance").
+2.  **Consult the Principle**: Which dimension (Structure vs Behavior) takes precedence?
+3.  **Escalation**: Technical -> Tech Lead. Priority -> Product Owner.
+4.  **Record Decision**: If the decision is significant/irreversible, it MUST be recorded in an **Architecture Decision Record (ADR)**.
+
+---
+
+# 4. Context Continuity & Onboarding
+
+_Source: [Cognitive Load Theory](https://en.wikipedia.org/wiki/Cognitive_load_theory)_
+
+## 4.1 The Handoff Protocol
+
+When passing work between Agents:
+
+- **Outgoing Agent**: Summarize Current State, Decisions Made, and Open Questions.
+- **Incoming Agent**: Acknowledge receipt, Validate understanding, Identify missing context within 5 minutes.
+
+## 4.2 The Context Budget
+
+Every interaction has a cost (Tokens/Time). Prioritize recent changes. Link to full details (Artifacts), do not inline them.
+
+## 4.3 Agent Onboarding
+
+When an Agent joins a new codebase:
+
+- **Read**: Engineering Principles (`docs/engineering_principles.md`) and Best Practices (`docs/meta/industry_best_practices.md`).
+- **Study**: 3 representative PRs and key ADRs.
+- **Task**: Complete 1 guided verification task before writing code.
+
+---
+
+# 5. Collaborative Mechanics
+
+_Source: [GitLab Handbook](https://about.gitlab.com/handbook/) / [Deep Work (Cal Newport)](https://www.calnewport.com/books/deep-work/)_
+
+## 5.1 Async First & Written Culture
+
+- **Principle**: "If it isn't written down, it didn't happen."
+- **Implementation**: Agents communicate via **Artifacts** (PRs, Design Docs), not transient chat.
+
+## 5.2 The Maker's Schedule
+
+- **Principle**: Interruptions destroy deep work context.
+- **Protocol**: Batch communications. Do not interrupt execution loops. Wait for "Ready" signals.
+
+## 5.3 Communication Standards
+
+- **No Hello**: State the request immediately.
+- **Structured Updates**: STATUS | BLOCKERS | NEXT.
+
+---
+
+# 6. Operational Resilience
+
+_Source: [Google SRE Book](https://sre.google/sre-book/table-of-contents/)_
+
+## 6.1 Agent Failure Modes
+
+- **Context Overflow**: Exceeding token limits.
+- **Hallucination**: Producing incorrect info.
+- **Stall**: No progress.
+
+## 6.2 Circuit Breakers
+
+After N failures:
+
+1.  **Halt** the agent.
+2.  **Preserve** context/state.
+3.  **Escalate** to human or Lead Agent.
+
+## 6.3 Psychological Safety
+
+- **Principle**: **Blameless Postmortems.**
+- **Implementation**: Analyze the _Process_ (Prompt/Context), not the _Agent_. Assume rationality.

package/docs/meta/domains/README.md

@@ -0,0 +1,8 @@
+# Engineering Domains
+
+**Scope**: High-level systems, infrastructure, and cross-cutting concerns.
+
+## Index
+
+- **[Git](git/README.md)**: The protocol of version control and collaboration.
+- **[Bitcoin](bitcoin/README.md)**: Consensus and financial engineering.

package/docs/meta/domains/bitcoin/01-units.md

@@ -0,0 +1,21 @@
+# Bitcoin: Units & Amounts
+
+**Sources**:
+
+- Bitcoin Core `amount.h` (CAmount / satoshis): https://github.com/bitcoin/bitcoin/blob/master/src/amount.h
+
+## Amount Representation
+
+- **MUST** represent money as integers representing **satoshis**.
+- **MUST NOT** use floating point for monetary values.
+
+## Fee Math
+
+- Fee rates may be fractional (e.g., sat/vB). Use exact rational math until the final conversion to sats.
+- When converting a fee rate and size into a final fee in sats, be explicit about rounding.
+  - For fee payment constraints, prefer **rounding up** to avoid underpaying.
+
+## Unit Clarity
+
+- Make units explicit in names and boundaries (e.g., `amount_sats`, `fee_rate_sat_vb`).
+- Convert to display units (BTC) only at UI boundaries.

package/docs/meta/domains/bitcoin/02-broadcast-cancellation.md

@@ -0,0 +1,20 @@
+# Bitcoin: Broadcast, Cancellation, and Replacement
+
+**Sources**:
+
+- Bitcoin RPC `abandontransaction`: https://developer.bitcoin.org/reference/rpc/abandontransaction.html
+- Bitcoin Dev Guide (Transaction broadcasting / mempool): https://developer.bitcoin.org/devguide/p2p_network.html#transaction-broadcasting
+- Bitcoin Dev Guide (reissue by invalidating inputs): https://developer.bitcoin.org/devguide/transactions.html#transaction-malleability
+- BIP-0125 (Opt-in Full RBF): https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki
+
+## Broadcast Is Not Retractable
+
+- Once a transaction is broadcast, you cannot reliably "cancel" it by deleting it locally.
+- If your node/wallet does not show it in the mempool, it may still exist on other peers and reach miners.
+- Unconfirmed transactions are not a permanent part of the network state (mempools are non-persistent).
+
+## Practical Replacement
+
+- The only practical way to "cancel" is to create a **conflicting spend** that double-spends at least one input.
+- Replacement is not guaranteed until one of the conflicting transactions confirms.
+- If you rely on replacement, ensure your wallet/node policy supports it (e.g., opt-in RBF).

package/docs/meta/domains/bitcoin/03-fee-rates-rounding.md

@@ -0,0 +1,21 @@
+# Bitcoin: Fee Rates, Rational Math, and Rounding
+
+**Sources**:
+
+- btcwallet/btcunit README: https://raw.githubusercontent.com/btcsuite/btcwallet/sql-wallet/pkg/btcunit/README.md
+- btcwallet/btcunit fee math (round up): https://raw.githubusercontent.com/btcsuite/btcwallet/sql-wallet/pkg/btcunit/rates.go
+
+## Rational Fee Rates
+
+- Fee rates may be fractional; represent them as arbitrary-precision rationals (e.g., `math/big.Rat`).
+- Keep a canonical internal unit and convert explicitly.
+
+## Rounding Policy
+
+- Define a single rounding policy when converting rational fee math into integer sats.
+- For paying fees, prefer **ceiling** (round up) to avoid falling below minimum relay/mempool policy.
+
+## Units
+
+- Make feerate units explicit (commonly sat/vB).
+- Do not mix sat/vB, sat/B, and sat/kw without explicit conversion.

package/docs/meta/domains/bitcoin/04-confirmations-reorgs.md

@@ -0,0 +1,20 @@
+# Bitcoin: Confirmations & Reorgs
+
+**Sources**:
+
+- Bitcoin Dev Guide (Chain / confirmations): https://developer.bitcoin.org/devguide/block_chain.html
+
+## Confirmation Policy
+
+- Confirmations are a risk control; treat 0-conf as reversible.
+- Define explicit thresholds per asset/risk tier.
+
+## Reorg Handling
+
+- Track both block height and block hash when recording confirmation state.
+- On reorg, be able to rollback derived state and re-derive.
+
+## Practical Depth
+
+- Design for 1-2 block reorgs as a practical concern.
+- Deeper reorgs are possible; ensure rollback code is safe under repeated application.

package/docs/meta/domains/bitcoin/05-address-gap-limit.md

@@ -0,0 +1,16 @@
+# Bitcoin: Address Gap Limit and Recovery Risk
+
+**Sources**:
+
+- BIP-0044 (Address gap limit = 20): https://raw.githubusercontent.com/bitcoin/bips/master/bip-0044.mediawiki
+- btcwallet issue (gap limit failure mode): https://github.com/btcsuite/btcwallet/issues/1167
+
+## The Gap Limit Problem
+
+- HD wallet recovery typically scans forward until it sees N consecutive unused addresses.
+- If an application generates many unused addresses, restored wallets may stop scanning early and miss funds.
+
+## Operational Guidance
+
+- Avoid generating large volumes of unused deposit addresses without tracking issued-vs-used indices.
+- If privacy policy requires frequent new addresses, make the gap limit an explicit, tested operational parameter.