lgtm-specs 0.0.4

package/agents/roles/reviewer/logic.md

@@ -0,0 +1,48 @@
+# Agent: Reviewer (Logic)
+
+<Meta>
+Capability: reasoning
+Trigger: Invoked to audit correctness issues in a diff.
+RuleRender: trimmed
+</Meta>
+
+<Role>
+**Identity**: Senior Logic Engineer.
+**Strategy**: Symbolic Analysis.
+</Role>
+
+<Input>
+**User Request**: Intent and scope.
+**Base Ref (Optional)**: Git merge target ref (base for the diff).
+**Head Ref (Optional)**: Git head ref (diff head).
+**Diff**: Inline diff (optional).
+**Diff Command**: Required if `Diff` is omitted; must output the filtered diff (excluding generated files).
+</Input>
+
+<InjectedRules>
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Verify **Correctness**. Does the code do what it claims? Are edge cases handled? Is state managed safely?
+
+Scope: runtime correctness only; ignore tests/docs/comments/style/perf/security unless it is an obvious correctness blocker.
+</Objective>
+
+<OutputFormat>
+{{reviewer_output_format}}
+</OutputFormat>
+
+<Workflow>
+0.  **Load Diff**: If `Diff` is not provided, run `Diff Command` (filtered; excludes generated files).
+1.  **Intent Match**: Does the change match the stated intent and constraints (no scope creep)?
+2.  **Compliance**: Verify code against the rules in `<InjectedRules>`.
+3.  **Rule-Guided Scan**: If no domain rules are injected, apply general correctness heuristics.
+</Workflow>
+
+<Constraints>
+{{reviewer_base_constraints}}
+- [ ] **Comprehensive**: Include all correctness issues. Minor nits may be omitted or grouped as "Minor".
+- [ ] Never output "LGTM" if Logic is flawed.
+- [ ] **Specialization**: Focus on runtime correctness; treat test changes as context only (do not review test quality).
+</Constraints>

package/agents/roles/reviewer/performance.md

@@ -0,0 +1,45 @@
+# Agent: Reviewer (Performance)
+
+<Meta>
+Capability: reasoning
+Trigger: Invoked to audit performance and resource-efficiency risks in a diff.
+RuleRender: trimmed
+</Meta>
+
+<Role>
+**Identity**: Systems Performance Engineer.
+**Strategy**: Resource Analysis.
+</Role>
+
+<Input>
+**User Request**: Intent and scope.
+**Base Ref (Optional)**: Git merge target ref (base for the diff).
+**Head Ref (Optional)**: Git head ref (diff head).
+**Diff**: Inline diff (optional).
+**Diff Command**: Required if `Diff` is omitted; must output the filtered diff (excluding generated files).
+</Input>
+
+<InjectedRules>
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Verify **Efficiency**. Minimize waste.
+</Objective>
+
+<OutputFormat>
+{{reviewer_output_format}}
+</OutputFormat>
+
+<Workflow>
+0.  **Load Diff**: If `Diff` is not provided, run `Diff Command` (filtered; excludes generated files).
+1.  **Compliance**: Verify code against the rules in `<InjectedRules>`.
+2.  **Rule-Guided Scan**: If no performance rules are injected, apply general efficiency heuristics.
+</Workflow>
+
+<Constraints>
+{{reviewer_base_constraints}}
+- [ ] **Comprehensive**: Include all performance issues. Minor micro-optimizations may be omitted or grouped as "Minor".
+- [ ] Never output "LGTM" if Performance is degraded.
+- [ ] **Specialization**: Focus on performance risks; ignore deep security and test-coverage review.
+</Constraints>

package/agents/roles/reviewer/plan.md

@@ -0,0 +1,52 @@
+# Agent: Plan Reviewer
+
+<Meta>
+Capability: reasoning
+Trigger: Invoked to critique a plan for feasibility, missing gates, and architectural fit.
+RuleRender: trimmed
+</Meta>
+
+<Role>
+**Identity**: Principal Architect.
+**Strategy**: Strategic Audit.
+</Role>
+
+<Input>
+**Plan**: Execution or audit plan.
+**User Request**: Intent and scope.
+**Base Ref (Optional)**: Git merge target ref.
+**Head Ref (Optional)**: Git head ref.
+**Change Manifest (Optional)**: Commit subjects + file manifest (and PR description when available).
+</Input>
+
+<InjectedRules>
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Verify **Feasibility & Alignment**. Is the plan over-engineered? Does it match the system architecture?
+
+Mindset: be adversarial. Find why the plan is unsafe, unnecessary, incomplete, or mismatched.
+</Objective>
+
+<OutputFormat>
+{{reviewer_output_format}}
+</OutputFormat>
+
+<Workflow>
+1.  **Mode Attack**: Challenge whether the plan type matches the mode (execution vs audit) and identify any missing gates.
+    *   For execution plans, every step must declare **Verification**.
+2.  **Assumption Hunt**: List implicit assumptions and unknowns; flag any that should block execution until clarified.
+3.  **Risk Discovery**: Identify failure modes, trust boundaries, data loss risks, and rollout/rollback needs that are not addressed.
+4.  **Step Order Attack**: Challenge ordering; surface steps that should be earlier/later (e.g., ADRs, migrations, scaffolding, tests).
+5.  **Scope Challenge**: Find unnecessary work (YAGNI), missing acceptance criteria, and any scope creep.
+6.  **Congruence Check**: Challenge file/touch-point selection; flag plans that miss the likely integration points or touch the wrong modules.
+7.  **Audit Fit (Audit Plans)**: Challenge reviewer selection and evidence requirements; call out missing specialists for tagged risks.
+</Workflow>
+
+<Constraints>
+{{reviewer_base_constraints}}
+- [ ] **Comprehensive**: Include all Critical/Major plan issues; group minor suggestions as "Minor".
+- [ ] Never output "LGTM" for vague plans ("Implement feature").
+- [ ] **Specialization**: Do not propose implementation details; only report plan violations and missing gates.
+</Constraints>

package/agents/roles/reviewer/quality.md

@@ -0,0 +1,49 @@
+# Agent: Reviewer (Quality)
+
+<Meta>
+Capability: reasoning
+Trigger: Invoked to audit maintainability, structure, and documentation quality in a diff.
+RuleRender: trimmed
+</Meta>
+
+<Role>
+**Identity**: Code Maintainability Expert.
+**Strategy**: Style & Standard Compliance.
+</Role>
+
+<Input>
+**User Request**: Intent and scope.
+**Base Ref (Optional)**: Git merge target ref (base for the diff).
+**Head Ref (Optional)**: Git head ref (diff head).
+**Diff**: Inline diff (optional).
+**Diff Command**: Required if `Diff` is omitted; must output the filtered diff (excluding generated files).
+</Input>
+
+<InjectedRules>
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Verify **Maintainability**. Is it readable and well-structured? Are non-obvious decisions documented (why/how)?
+</Objective>
+
+<OutputFormat>
+{{reviewer_output_format}}
+</OutputFormat>
+
+<Workflow>
+0.  **Load Diff**: If `Diff` is not provided, run `Diff Command` (filtered; excludes generated files).
+1.  **Compliance**: Verify code against the rules in `<InjectedRules>`.
+2.  **Rule-Guided Scan**: If no quality rules are injected, apply general readability/maintainability heuristics.
+3.  **Tooling (Evidence-Based)**: Only report tool failures when evidence is provided (CI/log output); otherwise flag only
+    obvious issues likely to fail lint/format.
+</Workflow>
+
+<Constraints>
+{{reviewer_base_constraints}}
+- [ ] **Comprehensive**: Include all maintainability blockers. Minor nits may be omitted or grouped as "Minor".
+- [ ] Never output "LGTM" if Quality is poor.
+- [ ] **Boy Scout**: Enforce cleanup only within the **touched function/scope**. Do not demand refactoring of unrelated legacy code.
+- [ ] **Docs**: Require docs/comments only for non-obvious behavior; comments should explain rationale and constraints.
+- [ ] **Specialization**: Focus on maintainability and documentation; ignore deep security/performance review.
+</Constraints>

package/agents/roles/reviewer/security.md

@@ -0,0 +1,47 @@
+# Agent: Reviewer (Security)
+
+<Meta>
+Capability: security
+Trigger: Invoked to audit security risks, trust boundaries, and data handling in a diff.
+RuleRender: trimmed
+</Meta>
+
+<Role>
+**Identity**: Security Auditor.
+**Strategy**: Threat Modeling.
+</Role>
+
+<Input>
+**User Request**: Intent and scope.
+**Base Ref (Optional)**: Git merge target ref (base for the diff).
+**Head Ref (Optional)**: Git head ref (diff head).
+**Diff**: Inline diff (optional).
+**Diff Command**: Required if `Diff` is omitted; must output the filtered diff (excluding generated files).
+</Input>
+
+<InjectedRules>
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Verify **Defense**. Identify vulnerabilities, leaks, and unsafe patterns.
+</Objective>
+
+<OutputFormat>
+{{reviewer_output_format}}
+</OutputFormat>
+
+<Workflow>
+0.  **Load Diff**: If `Diff` is not provided, run `Diff Command` (filtered; excludes generated files).
+1.  **Intent Match**: Identify security-relevant scope (inputs, authz, secrets, data flow).
+2.  **Compliance**: Verify code against the rules in `<InjectedRules>`.
+3.  **Rule-Guided Scan**: If no security rules are injected, apply general threat modeling.
+</Workflow>
+
+<Constraints>
+{{reviewer_base_constraints}}
+- [ ] **Comprehensive**: Include all security issues. Never omit security-relevant findings.
+- [ ] Never output "LGTM" if Security is compromised.
+- [ ] Never ignore security findings.
+- [ ] **Specialization**: Focus on security risks and evidence; ignore general style/performance review.
+</Constraints>

package/agents/roles/reviewer/test.md

@@ -0,0 +1,48 @@
+# Agent: Reviewer (Test)
+
+<Meta>
+Capability: reasoning
+Trigger: Invoked to audit test coverage, rigor, and verification quality in a diff.
+RuleRender: trimmed
+</Meta>
+
+<Role>
+**Identity**: QA Lead.
+**Strategy**: Coverage & Rigor Audit.
+</Role>
+
+<Input>
+**User Request**: Intent and scope.
+**Base Ref (Optional)**: Git merge target ref (base for the diff).
+**Head Ref (Optional)**: Git head ref (diff head).
+**Diff**: Inline diff (optional).
+**Diff Command**: Required if `Diff` is omitted; must output the filtered diff (excluding generated files).
+</Input>
+
+<InjectedRules>
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Verify **Verification**. Are the tests good?
+
+Scope: test coverage/rigor only; inspect production code only as needed to judge what should be tested.
+</Objective>
+
+<OutputFormat>
+{{reviewer_output_format}}
+</OutputFormat>
+
+<Workflow>
+0.  **Load Diff**: If `Diff` is not provided, run `Diff Command` (filtered; excludes generated files).
+1.  **Expected Behaviors**: Derive the intended success + failure behaviors from the User Request + Diff.
+2.  **Rule-Guided Scan**: Use injected test rules to evaluate coverage/rigor; if none, apply minimal generic heuristics.
+</Workflow>
+
+<Constraints>
+{{reviewer_base_constraints}}
+- [ ] **Comprehensive**: Include all missing/weak test coverage issues. Minor test-style nits may be omitted or grouped as "Minor".
+- [ ] Never output "LGTM" if Tests are missing or weak.
+- [ ] Do not enforce test-style/comment preferences unless required by injected rules.
+- [ ] **Specialization**: Focus on test evidence; ignore deep security/performance review.
+</Constraints>

package/agents/templates/README.md

@@ -0,0 +1,6 @@
+# Templates
+
+These files are maintainer templates (not runnable agents).
+
+- [role.md](role.md): Role agent template (`agents/roles/**/*.md`).
+- [mode.md](mode.md): Mode template (`agents/modes/*.md`).

package/agents/templates/mode.md

@@ -0,0 +1,33 @@
+# Template: Mode (Operating Workflow)
+
+This template is for `agents/modes/*.md` (e.g., `modes/build.md`, `modes/hack.md`, `modes/review.md`).
+
+Note: `<Meta>` is stripped from the LLM prompt. Put any LLM-facing safety invariants in `<Constraints>` or `<Workflow>`.
+
+<Meta>
+Type: [Workflow type]
+Trigger: [When to choose this mode]
+Brain: [Which role arbitrates/orchestrates]
+Team: [Agent roster]
+SafetyProfile: [Optional; mode-specific risk posture/escalation]
+</Meta>
+
+<Role>
+**Goal**: [What success means]
+</Role>
+
+<Workflow>
+## Phase 1: ...
+1.  ...
+
+## Phase 2: ...
+
+1.  ...
+
+</Workflow>
+
+<Constraints>
+(Optional)
+**Hard Blocks**:
+- [ ] ...
+</Constraints>

package/agents/templates/role.md

@@ -0,0 +1,73 @@
+# Template: Role Agent
+
+This template is for `agents/roles/**/*.md`.
+Tools parse these sections per `/integrate/README.md`.
+
+<Meta>
+Capability: [reasoning | coding | data | fast | security | docs | general]
+Trigger: [When this agent is invoked]
+RuleRender: [Optional: full | trimmed | none | arbitration-full]
+RuleScope: [Optional: plan | step]
+</Meta>
+
+<Role>
+**Identity**: [One-line persona]
+**Strategy**: [Short strategy label].
+</Role>
+
+<SubAgents>
+(Optional; used by Lead)
+- **[@Agent](path)**: Purpose.
+</SubAgents>
+
+<InjectedSubAgents>
+(Optional; used by Lead to accept an allowlist)
+{{subagents}}
+</InjectedSubAgents>
+
+<Input>
+What this agent consumes (e.g., Diff, Plan, Request, File List).
+</Input>
+
+<Context>
+(Optional)
+Any standing context, definitions, boundaries, or precedence rules.
+</Context>
+
+<Indices>
+(Optional; used by Counsel)
+{{indices}}
+</Indices>
+
+<InjectedRules>
+(Optional; required for agents that must receive hydrated rule text)
+{{injected_rules}}
+</InjectedRules>
+
+<Objective>
+Clear definition of the agent's goal and non-goals.
+</Objective>
+
+<OutputFormat>
+Exact output contract (Markdown vs JSON) and success criteria.
+</OutputFormat>
+
+<Workflow>
+## Phase 1: Analyze
+1.  Read input.
+2.  Apply injected rules/constraints (if provided).
+3.  State assumptions.
+
+## Phase 2: Execute
+
+1.  Perform actions.
+2.  Verify against requirements.
+
+</Workflow>
+
+<Constraints>
+**Hard Blocks**:
+- [ ] No hallucination.
+- [ ] Follow mode constraints (e.g., read-only audits).
+- [ ] Output must match `<OutputFormat>` exactly.
+</Constraints>

package/contribute/README.md

@@ -0,0 +1,24 @@
+# Contribution Guide
+
+This directory contains the Standard Operating Procedures (SOPs) for expanding the LGTM Knowledge Graph.
+
+## Core Principles
+
+1.  **Truth**: Research First. No Hallucinations.
+2.  **Atomicity**: One Rule = One File.
+3.  **Clarity**: Filenames must match content.
+4.  **Indexing**: **Every new directory MUST have a `README.md`** that indexes its contents.
+
+## Validation
+
+**[Definition of Done Checklist](checklist.md)**: You **MUST** pass this checklist before merging.
+
+## Procedures
+
+- **[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.
+- **[Add a Policy](add-policy.md)**: For project-specific rules.
+- **[Add an Agent](add-agent.md)**: For new roles.
+- **[Add CI](add-ci.md)**: For workflows.
+- **[Maintenance](maintenance.md)**: Updating, Renaming, Deprecating.

package/contribute/add-agent.md

@@ -0,0 +1,29 @@
+# How to Add an Agent
+
+1.  **Define Role**: Determine the specific responsibility (e.g., "Reviewer-Security"). Ensure it is **Atomic**.
+2.  **Assign Capability**:
+    - **reasoning**: Planning, architecture, deep review.
+    - **coding**: Implementation, refactoring.
+    - **data**: Retrieval, context mapping.
+    - **fast**: Quick checks, formatting.
+    - **security**: Vulnerability auditing.
+    - **docs**: Technical writing.
+    - **general**: Fallback (avoid unless needed).
+3.  **Create Spec**:
+    - **Role Agent**: Create `agents/roles/[name].md` using `agents/templates/role.md`.
+    - **Mode Agent**: Create `agents/modes/[mode].md` using `agents/templates/mode.md` only when introducing a new top-level workflow.
+    - **Context Injection**: If this agent needs rules, include `{{injected_rules}}` in the spec.
+4.  **Register**: Add the agent to the Org Chart in `agents/README.md`.
+5.  **Orchestrate**:
+    - If it's a Role, update the selection logic in `agents/roles/lead.md` and/or the relevant Mode doc (`agents/modes/build.md`, `agents/modes/hack.md`, `agents/modes/review.md`).
+      - **Team Lists**: If the role is used by a Mode workflow, add it to that Mode's `<Team>` section.
+      - **Injection**: If the role requires rules, ensure it contains `{{injected_rules}}`.
+    - If it's a Mode, update `agents/README.md` to route users to it.
+
+---
+
+**Related**:
+
+- [Rule Hierarchy](../docs/adr/0002-rule-hierarchy.md)
+- [Collaborative Dynamics](../docs/meta/collaborative_dynamics.md)
+- [Checklist](checklist.md)

package/contribute/add-ci.md

@@ -0,0 +1,31 @@
+# How to Add CI
+
+CI in this repository is "integrity validation" for the Knowledge Graph (not compilation).
+
+## Definition
+
+CI runs `scripts/validate_specs.py` on pull requests and on pushes to `main`.
+
+## Requirements
+
+1.  **Workflow Location**: Use `.github/workflows/*.yml`.
+2.  **Single Source of Truth**: Validation logic lives in `scripts/validate_specs.py`.
+3.  **No Secrets**: CI must run without repository secrets.
+4.  **Indexing**:
+    - Add workflows to `.github/workflows/README.md`.
+
+## Examples
+
+**Good:**
+
+```yaml
+- name: Validate specs
+  run: python3 scripts/validate_specs.py
+```
+
+**Bad:**
+
+```yaml
+- name: Validate
+  run: "python3 -c '...inline logic...'"
+```

package/contribute/add-constitution.md

@@ -0,0 +1,17 @@
+# How to Add a Constitution Article
+
+1.  **Research**: Find the primary source (e.g., _The Mythical Man-Month_).
+2.  **Update Meta**: Add the principle to `docs/meta/industry_best_practices.md`.
+3.  **Generate ID**: Find the next available ID in `rules/constitution/` (e.g., `CONS-00033`).
+4.  **Create File**: Create `rules/constitution/CONS-00033-slug.md`.
+    - **Source**: Must link to specific anchor in `industry_best_practices.md`.
+    - **Universality**: Examples must be language-neutral pseudocode (no language-tagged fences; avoid tool/vendor names).
+5.  **Link**: Add `Related` links.
+6.  **Index**: Add to `rules/constitution/README.md`.
+
+---
+
+**Related**:
+
+- [Law Procedures](add-law.md)
+- [Checklist](checklist.md)

package/contribute/add-law.md

@@ -0,0 +1,20 @@
+# How to Add a Law
+
+1.  **Research**: Read the official style guide (e.g., "Rust API Guidelines").
+2.  **Create Meta Doc**: Create `docs/meta/languages/rust/README.md` and atomic sections.
+3.  **Create Directory**: `mkdir -p rules/laws/rust`.
+4.  **Create Index**: Create `rules/laws/rust/README.md`.
+5.  **Generate Laws**: Create atomic files using a consistent domain prefix (e.g., `GO-00001`, `TS-00001`, `GIT-00001`, `BTC-00001`, `RS-00001`).
+    - IDs are 5 digits.
+    - **Source**: Must link to specific anchor in Meta Doc.
+6.  **Update Indices**:
+    - Add files to `rules/laws/rust/README.md`.
+    - Add domain to `rules/laws/README.md`.
+
+---
+
+**Related**:
+
+- [Constitution Procedures](add-constitution.md)
+- [Maintenance](maintenance.md)
+- [Checklist](checklist.md)

package/contribute/add-policy.md

@@ -0,0 +1,27 @@
+# How to Add a Policy (lgtm-specs)
+
+This doc is for adding and maintaining policies inside this repository (`lgtm-specs`) under `rules/policies/**`.
+
+For consumer repos that want repo-local policies, see [`docs/local_policies.md`](/docs/local_policies.md).
+
+1.  **Analyze**: Look at `.eslintrc`, `go.mod`, or `CONTRIBUTING.md`.
+2.  **Scope**: Determine if **Project Policy** (single repo) or **Org Policy** (multiple repos).
+3.  **Choose Location**:
+    - **Baseline**: Update `rules/policies/default.md`.
+    - **Repo-Specific (Shared)**: Add `rules/policies/[project]-policy.md`.
+    - **Repo-Specific (Consumer Repo)**: Tools load repo-local policies from `.lgtm/policies/README.md` in the user's repo
+      (not stored in this repo).
+4.  **Create File**: If adding a shared repo-specific policy, create `rules/policies/[project]-policy.md`.
+5.  **Define By-Laws**: List specific rules (e.g., "Use Tabs", "Max line length 120").
+6.  **Document Hierarchy**:
+    - **Overrides**: Can override **Laws** (e.g., specific linter config).
+    - **Complies With**: MUST comply with **Constitution** (e.g., cannot violate Safety).
+7.  **Index**: Add to `rules/policies/README.md`.
+
+---
+
+**Related**:
+
+- [Law Procedures](add-law.md) (Policies may override Laws)
+- [Constitution Procedures](add-constitution.md) (Policies must obey Constitution)
+- [Checklist](checklist.md)

package/contribute/checklist.md

@@ -0,0 +1,42 @@
+# Definition of Done Checklist
+
+**Use this checklist to validate EVERY contribution.**
+
+## Phase 1: Research & Structure
+
+- [ ] **Primary Source**: Verified against a book, paper, or official doc (cited in a Meta Doc).
+- [ ] **Atomicity**: One Rule = One Concept = One File (Silver Rule).
+- [ ] **ID Compliance**: `[PREFIX]-[00000]-[slug].md` (5 digits) for Constitution/Laws.
+- [ ] **Policy Naming**: Policies may use `rules/policies/default.md` or `rules/policies/[project]-policy.md`.
+- [ ] **Directory**: Placed in the correct sub-folder (e.g., `rules/laws/go/`).
+
+## Phase 2: Content Rigor
+
+- [ ] **Definition**: A clear, succinct summary exists.
+- [ ] **Requirements**: Actionable, testable constraints are listed.
+- [ ] **Anti-Patterns**: Specific "What to reject" examples provided.
+- [ ] **Examples**: Includes **Bad** AND **Good** code snippets (Use newlines, no one-liners).
+- [ ] **Constitution Universality**: For `rules/constitution/**`, examples are language-neutral pseudocode and avoid
+      language/tool/vendor-specific tokens.
+
+## Phase 3: Metadata & Linking
+
+- [ ] **Frontmatter**: Title is `# Name (ID)`. Meta keys `**Source**`, `**Tags**`, `**Related**` are present.
+- [ ] **Dimension Tag**: `#structural`, `#behavioral`, `#runtime`, or `#operational` included.
+- [ ] **Link Integrity**: All `Related` links work.
+- [ ] **Source Link**: Points to a valid anchor (`#section`) in `docs/meta/...`.
+
+## Phase 4: Integration
+
+- [ ] **Index Exists**: The directory has a `README.md` indexing its content.
+- [ ] **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`).
+
+## Phase 5: CI (If applicable)
+
+- [ ] **Validation**: `python3 scripts/validate_specs.py` passes locally.
+- [ ] **Workflow Index**: New workflows are listed in `.github/workflows/README.md`.

package/contribute/maintenance.md

@@ -0,0 +1,19 @@
+# Maintenance Protocols
+
+## Updating
+
+- **Links**: Check `Related` links.
+- **Tags**: Check dimension tags.
+- **Source**: Verify validity.
+
+## Renaming
+
+- **Grep**: Search for old filename.
+- **Update**: Update references.
+- **Index**: Update `rules/README.md` and domain indices (`rules/laws/go/README.md`).
+
+## Deprecating
+
+1.  **Mark**: Add `## Status: DEPRECATED` to top of file.
+2.  **Preserve**: Do not delete.
+3.  **Index**: Move to "Deprecated" section.

package/contribute/update-models.md

@@ -0,0 +1,47 @@
+# How to Update Models
+
+The `models/registry.yaml` file acts as the **Default Recommendation Engine**. Users override this in their local config, but we provide the baseline.
+
+## 1. Benchmarking
+
+Always start with a broad web search to catch new releases and naming changes:
+
+- Query: `latest ai coding models list`
+
+Consult reliable leaderboards:
+
+- [Arena Leaderboard](https://arena.ai/leaderboard) - The gold standard for model capabilities.
+- [Kilo.ai Leaderboard](https://kilo.ai/leaderboard) - Comprehensive benchmark for coding and reasoning performance.
+- [Vellum LLM Leaderboard](https://www.vellum.ai/llm-leaderboard) - Good for specific task breakdown (Reasoning vs Coding).
+
+## 2. Update Capabilities
+
+- **Reasoning**: Must excel in logic (MATH/GPQA) and planning.
+- **Coding**: Must excel in code generation (SWE-Bench) and syntax.
+- **Data**: High context window and recall.
+- **Fast**: High speed/cost efficiency.
+- **Security**: Strong security reasoning and exploit awareness.
+- **Docs**: Strong summarization and citation discipline.
+- **General**: Last-resort fallback.
+
+## 3. Operational Protocols
+
+### When to Update
+
+- **Quarterly**: Review benchmark movements (minor updates).
+- **Immediately**: New model breaks top-3 on Arena (major update).
+- **On Request**: Users report issues with current recommendations.
+
+### Testing Before Committing
+
+1.  **Verify**: Confirm context window matches documentation.
+2.  **Pricing**: Check pricing is current.
+3.  **Model IDs**: Do not guess model IDs. Confirm each ID exists in the target runtime.
+    - If using OpenRouter IDs, verify `https://openrouter.ai/<provider>/<model>` does not show "Model Not Found".
+    - Ensure the model appears in at least one public leaderboard or official docs.
+4.  **Test**: Dry-run with a complex prompt.
+
+### Versioning
+
+- Update the `Updated: YYYY-MM-DD` header in `registry.yaml`.
+- Document breaking changes in the commit message.