lgtm-specs 0.0.4 → 0.0.5

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Instructions (lgtm-specs)
 
-This repository (`lgtm-specs`) is a versioned **Knowledge Graph** of specs (rules + agent prompts). Treat changes as spec
-edits, not application code.
+This repository (`lgtm-specs`) is a versioned **Knowledge Graph** of specs (rules + agent prompts).
+Treat changes as spec edits, not application code.
 
 Repo-local assistant instructions:
 
@@ -25,6 +25,9 @@ bun run validate
 # or:
 python3 scripts/validate_specs.py
 
+# Unit tests (validator self-tests)
+bun run test
+
 # Formatting (Prettier)
 bun run format
 bun run format:check
@@ -97,7 +100,8 @@ Atomic rule requirements (see `rules/RULE-00000-EXAMPLE.md`):
 Citations and links:
 
 - Source-of-truth material lives in `docs/meta/**`; do not invent citations.
-- Use repo-root-relative links (`/rules/...`, `/docs/...`) and ensure targets exist.
+- Links: prefer repo-root-relative links (`/rules/...`, `/docs/...`) for stability.
+  Relative links are acceptable; follow the local directory convention.
 - `**Source**` links into `docs/meta/**` should include an anchor (`#...`).
 
 Tags and writing:

package/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

package/agents/modes/build.md

@@ -33,8 +33,11 @@ Team:
 ## Phase 1: Clarify & Design (The Blueprint)
 1.  **Orchestrate**: `@Lead` assesses the request and engages `@Explorer` to map the codebase.
 2.  **Compliance**: `@Lead` consults `@Counsel` for Rules and Policies.
-    *   **Inject**: `@Lead` instructs the Runtime to load/hydrate rule content and inject `{{injected_rules}}` into
-        `@Planner` and all reviewers used in this mode (`@Plan-Reviewer`, `@Reviewer-Lite`, Panel).
+    *   **Inject (Dynamic)**: `@Lead` instructs the Runtime to load/hydrate rule content and inject
+        `{{injected_rules}}`.
+        - `@Planner`: plan-level rules/policies.
+        - `@Builder`: step-scoped rules per Task (always include the active Policy rules).
+        - Reviewers: review-scope rules/policies for `@Plan-Reviewer`, `@Reviewer-Lite`, and the specialist panel.
 3.  **Draft**: `@Planner` creates the **Execution Plan**.
     *   *Input*: User Request + Map + Rules.
 4.  **Plan Review**: Call **two** independent `@Plan-Reviewer` instances.
@@ -52,11 +55,18 @@ Team:
 
 For each Task in the Plan:
 
-1.  **Build**: Call `@Builder` with `(Task, Rules, Verification)`.
+1.  **Build**: Call `@Builder` with `(Task, Files, Requirements, Verification)`.
+    - _Constraint_: `Files` MUST come from the Plan step. If missing, `@Lead` routes back to `@Planner` to repair the
+      plan.
     - _Constraint_: Verification is mandatory. The proof level is defined per step (tests and/or other evidence).
+    - _Timeout_: 20 minutes per attempt (default; runtime may override).
+    - _On Timeout_: Re-assign once; if it times out again, treat as a reject and re-plan or abort.
 2.  **Micro-Audit**: Call `@Reviewer-Lite` on the diff.
-    - _Scope_: Fast sanity gate (obvious correctness breakage + basic style/tooling + commit message); deep specialist review happens in Phase 3.
-    - _Input_: Include the PR merge target as `Base Ref` and the atomic `Commit Message` when available.
+    - _Scope_: Fast sanity gate (obvious correctness breakage + basic style/tooling + commit message). Deep specialist
+      review happens in Phase 3.
+    - _Input_: Provide `User Request` + (`Diff` or `Diff Command`).
+      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
+      Include the atomic `Commit Message` when available.
     - _Retry_: Max 3 attempts.
     - _Timeout_: 5 minutes per attempt.
     - _On Timeout_: Treat as a reject and retry.
@@ -67,22 +77,43 @@ For each Task in the Plan:
 
 1.  **Verify**: Ensure required verification passes (including integration tests when required).
 2.  **Audit**: Call the **Full Review Panel**.
-    - Mandatory: `Logic`, `Quality`, `Test`.
-    - Conditional: `Security` (if tagged), `Performance` (if tagged).
+    - Mandatory: [Logic](../roles/reviewer/logic.md), [Quality](../roles/reviewer/quality.md),
+      [Test](../roles/reviewer/test.md).
+    - Conditional: [Security](../roles/reviewer/security.md) when `@Lead` marks the work security-sensitive (or
+      `@Counsel` selected `#security` rules).
+    - Conditional: [Performance](../roles/reviewer/performance.md) when `@Lead` marks the work perf-sensitive (or
+      `@Counsel` selected `#efficiency` rules).
+    - _Input (each)_: Provide `User Request` + (`Diff` or `Diff Command`).
+      Include `Base Ref` whenever the runtime has git metadata (e.g., PR merge target).
+      Include `Head Ref` when available.
 3.  **Gate**: Unanimous Approval Required.
     - _Loop_: Max 10 review->fix cycles.
     - _Timeout_: 10 minutes per reviewer per cycle.
     - _On Timeout_: Re-assign each timed-out reviewer once. If it still times out, treat as a reject for that cycle.
-    - _Clarify_: If a finding is contested or unclear, `@Lead` asks the specific reviewer to justify or withdraw it (one round-trip max) before planning fixes.
-    - _Cycle_: On each rejection, `@Lead` digests the panel feedback and calls `@Planner` to produce a remediation todo list. `@Builder` executes tasks one at a time, then the panel re-reviews.
-    - _Compress_: After each cycle, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts into later cycles.
-    - _Arbitration (Conditional)_: If reviewers deadlock/contradict, runtime injects the minimum Tier 2 contested diff and
+    - _Clarify_: If a finding is contested or unclear, `@Lead` asks the specific reviewer to justify or withdraw it (one
+      round-trip max) before planning fixes.
+    - _Deadlock Escape_: If the panel stalls for 2 consecutive cycles, `@Lead` must either trigger arbitration or abort;
+      do not spin indefinitely.
+    - _Cycle_: On each rejection, `@Lead` digests the panel feedback and calls `@Planner` to produce a remediation todo
+      list.
+      `@Builder` executes tasks one at a time, each passing Phase 2 Micro-Audit before re-entering the panel.
+    - _Compress_: After each cycle, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts
+      into later cycles.
+    - _Arbitration (Conditional)_: If reviewers deadlock/contradict, runtime injects the minimum Tier 2 contested diff
+      and
       full contested rules into `@Lead`; `@Lead` judges citing rule IDs and diff evidence.
     - _Override_: If needed, `@Lead` may override with an explicit risk rationale.
-    - _After Max_: If still not unanimous after 10 cycles, `@Lead` must either abort (recommended) or override with an explicit risk rationale.
+      - _Guardrail_: If overriding a security- or test-related rejection, `@Lead` must surface the residual risk and get
+        explicit user acknowledgement.
+    - _After Max_: If still not unanimous after 10 cycles, `@Lead` must either abort (recommended) or override with an
+      explicit risk rationale.
 
 ## Phase 4: Delivery
 
 - **Finalize**: Produce the Production-Ready PR.
+  - **History Hygiene**: Ensure commit messages follow Git laws; squash fixups/WIP; keep atomic story.
+  - **PR Hygiene**: Title/body explain intent, risks, and verification evidence; mark Draft vs Ready explicitly.
+  - **Merge Plan**: State merge strategy expectations (squash vs merge-commit vs rebase) per repo policy.
+  - **Last Check**: Re-run required verification before marking ready.
 
 </Workflow>

package/agents/roles/lead.md

@@ -50,19 +50,27 @@ Deliver the User Request by coordinating the Engineering Team.
 
 <Workflow>
 1.  **Clarify**: If ambiguous, ask targeted questions.
-    *   **Research Trigger**: If the request depends on external truth (official docs/specs/API details), invoke `@Librarian`.
-2.  **Assemble Team**: If `<InjectedSubAgents>` contains entries (non-empty), treat it as the allowed subagent set for this run.
+    *   **Research Trigger**: If the request depends on external truth (official docs/specs/API details),
+        invoke `@Librarian`.
+2.  **Assemble Team**: If `<InjectedSubAgents>` contains entries (non-empty), treat it as the allowed subagent set for
+    this run.
 3.  **Execute Mode**: Follow the selected mode workflow contract (provided by the Runtime) as the canonical workflow:
     *   `@Build`
     *   `@Hack`
     *   `@Review`
-    *   **Rule Pipeline**: When `@Counsel` returns rule paths, instruct the Runtime to load/hydrate rule content and inject `{{injected_rules}}` into `@Planner` and any reviewers used.
-        - Inject a **role-appropriate subset** of rules per reviewer (Logic vs Test vs Security vs Performance vs Quality); do not inject all rules into every reviewer.
+    *   **Rule Pipeline**: When `@Counsel` returns rule paths, instruct the Runtime to load/hydrate rule content and
+        inject `{{injected_rules}}` into `@Planner`, `@Builder` (step-scoped per plan step; always include active Policy
+        rules), and any reviewers used.
+        - Inject a **role-appropriate subset** of rules per reviewer (Logic vs Test vs Security vs Performance vs
+          Quality); do not inject all rules into every reviewer.
 4.  **Track Provenance**: Track which reviewer produced which finding so follow-up questions can be routed correctly.
-5.  **Clarify Findings (Optional)**: For contested/unclear findings, request one-round clarification from the original reviewer (justify or withdraw).
-6.  **Arbitrate (Conditional)**: If reviewers deadlock, contradict each other, or repeatedly reject, request the Runtime to inject full contested rules into `<InjectedRules>` and provide minimal Tier 2 diff context for tie-breaking.
+5.  **Clarify Findings (Optional)**: For contested/unclear findings, request one-round clarification from the original
+    reviewer (justify or withdraw).
+6.  **Arbitrate (Conditional)**: If reviewers deadlock, contradict each other, or repeatedly reject, request the Runtime
+    to inject full contested rules into `<InjectedRules>` and provide minimal Tier 2 diff context for tie-breaking.
     *   *Precedence*: The selected mode spec defines which gates are overridable.
-7.  **Compress Loops**: In multi-cycle review loops, keep a compact "Resolved / Remaining" summary; do not carry full prior transcripts.
+7.  **Compress Loops**: In multi-cycle review loops, keep a compact "Resolved / Remaining" summary; do not carry full
+    prior transcripts.
 </Workflow>
 
 <Constraints>

package/contribute/README.md

@@ -15,6 +15,7 @@ This directory contains the Standard Operating Procedures (SOPs) for expanding t
 
 ## Procedures
 
+- **[Verification](verification.md)**: Formal integrity checks for the Knowledge Graph.
 - **[Update Models](update-models.md)**: Update `models/registry.yaml` recommendations.
 - **[Add a Constitution Article](add-constitution.md)**: For universal principles.
 - **[Add a Domain Law](add-law.md)**: For language-specific rules.

package/contribute/checklist.md

@@ -32,11 +32,15 @@
 - [ ] **Domain Index**: Added to `rules/laws/[domain]/README.md` (if Law).
 - [ ] **Master Index**: Added to `rules/constitution/README.md` (if Constitution).
 - [ ] **Agent Spec**: If adding an Agent, it is listed in `agents/README.md`.
-- [ ] **Capability**: If adding a role agent, `<Meta>` includes `Capability: ...` and it exists in `models/registry.yaml`.
-- [ ] **Rule Injection Placeholder**: If an agent requires rules, it includes a literal `{{injected_rules}}` placeholder.
-- [ ] **Mode Teams**: If the agent is used by a Mode, it is listed in that Mode's `<Team>` section (`agents/modes/build.md`, `agents/modes/hack.md`, `agents/modes/review.md`).
+- [ ] **Capability**: If adding a role agent, `<Meta>` includes `Capability: ...` and it exists in
+      `models/registry.yaml`.
+- [ ] **Rule Injection Placeholder**: If an agent requires rules, it includes a literal `{{injected_rules}}`
+      placeholder.
+- [ ] **Mode Teams**: If the agent is used by a Mode, it is listed in that Mode's `Team:` block inside `<Meta>`
+      (`agents/modes/build.md`, `agents/modes/hack.md`, `agents/modes/review.md`).
 
 ## Phase 5: CI (If applicable)
 
-- [ ] **Validation**: `python3 scripts/validate_specs.py` passes locally.
+- [ ] **CI Parity**: `bun run check` passes locally (validator + Prettier check).
+- [ ] **Validation (Optional)**: `python3 scripts/validate_specs.py` passes locally.
 - [ ] **Workflow Index**: New workflows are listed in `.github/workflows/README.md`.

package/contribute/verification.md

@@ -0,0 +1,122 @@
+# Verification & Integrity Checks
+
+This repo is a specification Knowledge Graph (Zettelkasten). "Verification" means proving the graph is:
+
+- structurally valid (atomic nodes, required metadata/sections),
+- correctly indexed (discoverable from directory READMEs),
+- correctly linked (no broken internal links; meta anchors exist),
+- consistent with integration contracts (capabilities + spec version).
+
+## Quick Start (CI Parity)
+
+Run exactly what CI runs:
+
+```bash
+bun run check
+```
+
+This executes:
+
+```bash
+bun run validate
+bun run test
+bun run format:check
+```
+
+## Validator: What It Enforces
+
+`python3 scripts/validate_specs.py` fails the build on any WARN/ERROR (unless baselined).
+
+### Spec Versioning
+
+- `VERSION` must match `integrate/README.md` `**Spec Version**:`.
+
+### Rules (`rules/**`)
+
+Validated files:
+
+- Atomic rules: `rules/constitution/**`, `rules/laws/**` (excluding directory `README.md`)
+- Rule-like scaffolding: `rules/policies/**`, `rules/laws/default.md`, `rules/RULE-00000-EXAMPLE.md`
+
+Checks:
+
+- Required shape: H1 title + `**Source**`, `**Tags**`, `**Related**`
+- Required sections: `## Definition`, `## Requirements`, `## Anti-Patterns`, `## Examples`
+- Examples must include both `**Bad:**` and `**Good:**`
+- Dimension tagging: `**Tags**` must include at least one of `#structural #behavioral #runtime #operational`
+- Indexing: every validated file must be listed in its parent directory `README.md`
+- Metadata links: internal `**Source**` and `**Related**` links must resolve to real files
+- Meta anchors: `**Source**` links into `docs/meta/**` must include a `#anchor`, and that anchor must exist as a heading
+- Law derivation: every `rules/laws/**` file must include at least one Constitution link in `**Related**`
+
+### Agents (`agents/**`)
+
+- Every role agent `<Meta>` must declare `Capability: <id>`
+- Capabilities must exist in `models/registry.yaml`
+
+## Fast Single-File Checks
+
+Useful when authoring a new/edited rule node:
+
+```bash
+FILE="rules/constitution/CONS-00027-transparency.md"
+
+bunx prettier --check "$FILE"
+python3 scripts/validate_specs.py
+```
+
+For ultra-fast local sanity (shape + indexing only):
+
+```bash
+test -f "$FILE" && echo "OK: exists"
+grep -q "$(basename "$FILE")" "$(dirname "$FILE")/README.md" && echo "OK: indexed"
+```
+
+## Optional: External URL Checks
+
+External link validation is network-dependent and opt-in:
+
+```bash
+python3 scripts/validate_specs.py --check-urls
+python3 scripts/validate_specs.py --check-urls --url-timeout 12
+python3 scripts/validate_specs.py --check-urls --url-ignore "https://example.com/badge.svg"
+```
+
+## Optional: Temporary Baseline (Migrations Only)
+
+If the repo is mid-migration and you need to land incremental fixes:
+
+```bash
+python3 scripts/validate_specs.py --write-baseline scripts/validate_baseline.txt
+python3 scripts/validate_specs.py --baseline scripts/validate_baseline.txt
+```
+
+Baseline rules:
+
+- Use baselines only temporarily.
+- Prefer fixing the underlying issues.
+- Keep the baseline deterministic (no timestamps).
+
+## Common Failure Modes
+
+- "File not indexed": add the filename to the parent `README.md` index.
+- "Broken **Source**/**Related** link": fix relative depth or use repo-root-relative links (`/docs/...`, `/rules/...`).
+- "Internal Source link missing #anchor" / "Broken Source anchor": open the target `docs/meta/**` file, find the
+  heading, and update the link to match the heading anchor.
+- "Law missing Constitution link": add the most relevant `CONS-xxxxx` article to `**Related**`.
+
+## Optional: Review Artifacts (Runtime)
+
+Some runtimes persist review artifacts (reviewer outputs, rule injection logs) to help debug long review loops.
+
+- Spec: `integrate/artifacts.md`
+- Recommended location: `.lgtm-local/` (ignored by git; also excluded from Prettier checks)
+- Recommended lifecycle: keep during the active panel loop; auto-delete on completion unless retention/stats mode is
+  enabled
+
+## Related
+
+- `contribute/checklist.md`
+- `rules/RULE-00000-EXAMPLE.md`
+- `scripts/README.md`
+- `integrate/artifacts.md`

package/docs/meta/industry_best_practices.md

@@ -1,6 +1,7 @@
 # Engineering Best Practices & Master Rule List
 
-This document is the "Source of Truth" for all engineering standards enforced by LGTM. It groups principles by their intellectual lineage and provides primary source references.
+This document is the "Source of Truth" for all engineering standards enforced by LGTM.
+It groups principles by their intellectual lineage and provides primary source references.
 
 **Table of Contents**
 
@@ -98,7 +99,8 @@ A tactical approach to managing complexity by focusing on module depth and infor
 
 ## 2.4 Defining Errors Out of Existence
 
-**Definition**: The best way to handle errors is to design APIs so the error condition is impossible or part of the normal flow.
+**Definition**: The best way to handle errors is to design APIs so the error condition is impossible.
+Alternatively, make the condition a first-class part of the normal flow.
 
 - **Requirement**: Use sensible defaults (e.g., empty string instead of error).
 - **Requirement**: Design interfaces so the "error case" is a valid branch of logic.
@@ -163,11 +165,20 @@ _Source: [Zen of Python](https://peps.python.org/pep-0020/)_
 - **Requirement**: Explicit is better than implicit. No global state.
 - **Requirement**: Dependencies and side effects must be visible in signatures.
 
+## 3.6 Composition Over Inheritance
+
+_Source: [Composition over inheritance](https://en.wikipedia.org/wiki/Composition_over_inheritance)_
+**Definition**: Prefer composition and delegation over deep inheritance trees to reduce coupling.
+
+- **Requirement**: Favor small composable components with explicit dependencies.
+- **Requirement**: Use interfaces + composition to vary behavior without fragile base classes.
+
 ---
 
 # 4. Pragmatic Programmer & Code Health
 
-_Source: [Hunt & Thomas](https://en.wikipedia.org/wiki/The_Pragmatic_Programmer) / [Atul Gawande](https://en.wikipedia.org/wiki/The_Checklist_Manifesto)_
+_Source: [Hunt & Thomas](https://en.wikipedia.org/wiki/The_Pragmatic_Programmer)_
+_Source: [Atul Gawande](https://en.wikipedia.org/wiki/The_Checklist_Manifesto)_
 Tactical rules for maintaining code quality over time.
 
 ## 4.1 The Boy Scout Rule
@@ -203,7 +214,8 @@ _Source: [The Checklist Manifesto](https://en.wikipedia.org/wiki/The_Checklist_M
 
 # 5. Systems Theory & Dynamics
 
-_Source: [Melvin Conway](https://en.wikipedia.org/wiki/Conway%27s_law) / [Jay Forrester](https://en.wikipedia.org/wiki/System_dynamics)_
+_Source: [Melvin Conway](https://en.wikipedia.org/wiki/Conway%27s_law)_
+_Source: [Jay Forrester](https://en.wikipedia.org/wiki/System_dynamics)_
 Understanding software development as a complex adaptive system.
 
 ## 5.1 Shift Left
@@ -231,7 +243,8 @@ _Source: [System Dynamics Modeling](https://en.wikipedia.org/wiki/The_Mythical_M
 
 # 6. Formal Methods & Correctness
 
-_Source: [Type Theory](https://en.wikipedia.org/wiki/Type_theory) / [Jon Postel](https://en.wikipedia.org/wiki/Robustness_principle)_
+_Source: [Type Theory](https://en.wikipedia.org/wiki/Type_theory)_
+_Source: [Jon Postel](https://en.wikipedia.org/wiki/Robustness_principle)_
 Ensuring code behaves correctly by construction.
 
 ## 6.1 Safety by Design
@@ -260,12 +273,14 @@ _Source: [Robustness Principle](https://en.wikipedia.org/wiki/Robustness_princip
 
 # 7. Distributed Systems
 
-_Source: [Eric Brewer](https://en.wikipedia.org/wiki/CAP_theorem) / [L. Peter Deutsch](https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing)_
+_Source: [Eric Brewer](https://en.wikipedia.org/wiki/CAP_theorem)_
+_Source: [L. Peter Deutsch](https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing)_
 Rules for code that crosses network boundaries.
 
 ## 7.1 CAP & PACELC
 
-_Source: [CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem) / [PACELC](https://en.wikipedia.org/wiki/PACELC_theorem)_
+_Source: [CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem)_
+_Source: [PACELC](https://en.wikipedia.org/wiki/PACELC_theorem)_
 **Definition**: Distributed systems must explicitly choose between Consistency and Availability.
 
 - **Requirement**: Document the consistency model for every distributed component.
@@ -273,7 +288,8 @@ _Source: [CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem) / [PACELC](htt
 ## 7.2 Fallacies of Distributed Computing
 
 _Source: [The 8 Fallacies](https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing)_
-**Definition**: False assumptions that L. Peter Deutsch and colleagues identified as the root of most distributed system failures.
+**Definition**: False assumptions identified by L. Peter Deutsch and colleagues.
+They are the root of many distributed system failures.
 
 - **Requirement**: You must actively design mitigation for _each_ of these false assumptions:
   1.  **The network is reliable.** (Mitigation: Retries, Acknowledgements)
@@ -289,7 +305,8 @@ _Source: [The 8 Fallacies](https://en.wikipedia.org/wiki/Fallacies_of_distribute
 
 # 8. Classic Engineering Wisdom
 
-_Source: [Extreme Programming](https://en.wikipedia.org/wiki/Extreme_programming) / [Lockheed Skunk Works](https://en.wikipedia.org/wiki/KISS_principle)_
+_Source: [Extreme Programming](https://en.wikipedia.org/wiki/Extreme_programming)_
+_Source: [Lockheed Skunk Works](https://en.wikipedia.org/wiki/KISS_principle)_
 
 ## 8.1 KISS (Keep It Simple, Stupid)
 
@@ -325,7 +342,8 @@ _Source: [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter)_
 
 # 9. Security Engineering
 
-_Source: [OWASP](https://owasp.org/www-project-top-ten/) / [Saltzer and Schroeder](https://en.wikipedia.org/wiki/Saltzer_and_Schroeder%27s_design_principles)_
+_Source: [OWASP](https://owasp.org/www-project-top-ten/)_
+_Source: [Saltzer and Schroeder](https://en.wikipedia.org/wiki/Saltzer_and_Schroeder%27s_design_principles)_
 
 ## 9.1 Principle of Least Privilege