@getarbiter/cli 0.5.0

package/dist/templates/root/docs/METHOD/ENGINEERING_DEFAULTS.md.ejs

@@ -0,0 +1,136 @@
+# Engineering Defaults — <%= projectName %>
+
+**Status:** NORMATIVE
+**Location:** `docs/METHOD/ENGINEERING_DEFAULTS.md`
+**Purpose:** SOLID-first engineering baseline. Principles trump patterns. Read before designing new modules.
+
+---
+
+## 1. SOLID-First Policy (Meta-Rule)
+
+**Rule:** Do not apply design patterns unless they solve a specific problem justified by a variation axis or testability constraint.
+
+Deliverables are: invariant compliance, testability, reduced coupling, deterministic behavior.
+Deliverables are NOT: "using the Strategy Pattern" or "adding an Abstract Factory".
+
+**Pattern admission test:**
+- Does this pattern enable a concrete requirement? (e.g., swapping algorithms at runtime)
+- Does this pattern enable testing? (e.g., mocking an external dependency)
+- If NO → reject. Use simple composition or functions instead.
+
+### SRP (Single Responsibility)
+- No "God" services/classes. If a module has >5 public methods or >3 distinct dependencies, split it.
+- Prefer composition over inheritance.
+
+### OCP (Open/Closed)
+- Design for extension only where variability is proven and required.
+- Stable domain entities should be closed to modification.
+
+### LSP (Liskov Substitution)
+- Subtypes must never throw broader exceptions or weaken preconditions.
+- Returning null where the parent contract forbids it is a violation.
+
+### ISP (Interface Segregation)
+- Interfaces should differ based on who uses them.
+- Never force implementers to stub unused methods (`throw new UnsupportedOperationException()` is a smell).
+
+### DIP (Dependency Inversion)
+- High-level modules depend on abstractions, not details.
+- Forbidden: static singletons, service locators, `new ConcreteService()` in high-level code.
+
+---
+
+## 2. Complexity Limits
+
+<% if (language === 'typescript' || language === 'unknown') { %>
+### TypeScript / JavaScript
+
+| Metric | Limit | Target |
+|--------|-------|--------|
+| Cognitive complexity per function | 15 | <10 |
+| Nesting depth | 3 | ≤2 |
+| Parameters per function | 5 | ≤3 |
+| Lines per function | 40 | <25 |
+| Exported symbols per module | 10 | ≤7 |
+
+**Enforcement:** ESLint `complexity` rule + `max-depth` + `max-params`.
+
+<% } else if (language === 'java') { %>
+### Java
+
+| Metric | Limit | Target |
+|--------|-------|--------|
+| Cognitive complexity per method | 15 | <10 |
+| Nesting depth | 2 | ≤2 |
+| Parameters per method/constructor | 7 | ≤5 |
+| Lines per method | 50 | <30 |
+| Public methods per class | 10 | ≤7 |
+
+**Enforcement:** SonarQube + ArchUnit `NamingConventionsTest`.
+
+Use Builders or Value Objects/Records when parameter count exceeds limit.
+
+<% } else if (language === 'rust') { %>
+### Rust
+
+| Metric | Limit | Target |
+|--------|-------|--------|
+| Cognitive complexity per function | 15 | <10 |
+| Nesting depth | 3 | ≤2 |
+| Parameters per function | 6 | ≤4 |
+| Lines per function | 40 | <25 |
+
+**Enforcement:** Clippy `cognitive_complexity` lint.
+
+<% } else if (language === 'go') { %>
+### Go
+
+| Metric | Limit | Target |
+|--------|-------|--------|
+| Cyclomatic complexity per function | 10 | <7 |
+| Nesting depth | 3 | ≤2 |
+| Parameters per function | 5 | ≤4 |
+| Lines per function | 40 | <25 |
+
+**Enforcement:** `gocognit` or `gocyclo` in CI.
+
+<% } else if (language === 'python') { %>
+### Python
+
+| Metric | Limit | Target |
+|--------|-------|--------|
+| Cognitive complexity per function | 15 | <10 |
+| Nesting depth | 3 | ≤2 |
+| Parameters per function | 6 | ≤4 |
+| Lines per function | 40 | <25 |
+
+**Enforcement:** `radon` + `flake8-cognitive-complexity`.
+
+<% } %>
+
+---
+
+## 3. Naming Standards
+
+- Functions/methods: verb-first, describe behavior (`getUserById`, `validateEmail`)
+- Booleans: `is*`, `has*`, `can*` prefix (`isActive`, `hasPermission`)
+- Constants: `SCREAMING_SNAKE_CASE`
+- No abbreviations unless universally understood (`id`, `url`, `http`)
+
+---
+
+## 4. Clean Code Rules
+
+- **No magic values:** Use named constants.
+- **No dead code:** Delete unused fields, methods, or "what if" scaffolding.
+- **No commented-out code:** Delete it. Git remembers.
+- **Guard clauses:** Return early instead of nesting conditions.
+- **Immutability by default:** Prefer immutable structures; mutate only when necessary and clearly named.
+
+---
+
+## 5. Null / Error Handling
+
+- Prefer explicit error types over null/undefined returns.
+- Never swallow exceptions silently — log or re-throw with context.
+- Validate at system boundaries (user input, external APIs) — trust internal code.

package/dist/templates/root/docs/METHOD/KNOWLEDGE_MAP.md.ejs

@@ -0,0 +1,90 @@
+# Knowledge Map — <%= projectName %>
+
+**Purpose:** Index of documentation files with section descriptions for context-efficient agent navigation. Read this before opening large docs — it tells you exactly where to look.
+**Maintenance:** Run `node scripts/knowledge-map-update.mjs` after adding or significantly editing a canonical document to keep line counts current.
+
+---
+
+## AGENTS.md
+
+**Location:** `AGENTS.md`
+**Lines:** 0
+**Purpose:** Canonical agent governance — invariants, coding standards, commit convention, gate commands.
+
+| Section | Description |
+|---------|-------------|
+| Invariants | Non-negotiable constraints (INV-XX). Read before any change. |
+| Coding Standards | Language-specific rules for this project. |
+| Testing Policy | Coverage requirements, test realism rules. |
+| Commit Convention | Type, scope, summary format. |
+
+---
+
+## docs/METHOD/SSOT_CORE_SET.md
+
+**Location:** `docs/METHOD/SSOT_CORE_SET.md`
+**Lines:** 0
+**Purpose:** Authoritative inventory of all SSOT documents. Start here to discover what documentation exists.
+
+| Section | Description |
+|---------|-------------|
+| Governance | Agent governance documents |
+| Method | Process and standards documents |
+| System | Architecture and decision records |
+
+---
+
+## docs/METHOD/CANONICAL_PATHS.md
+
+**Location:** `docs/METHOD/CANONICAL_PATHS.md`
+**Lines:** 0
+**Purpose:** Aliasing registry for moved/renamed documents. Check before reporting a broken link.
+
+| Section | Description |
+|---------|-------------|
+| Aliases | Table of old path → current path redirects |
+| Usage | How to add new redirects when moving documents |
+<% if (governanceLevel !== 'L1') { %>
+---
+
+## docs/METHOD/ENGINEERING_DEFAULTS.md
+
+**Location:** `docs/METHOD/ENGINEERING_DEFAULTS.md`
+**Lines:** 0
+**Purpose:** SOLID principles, coding standards, complexity limits. Read before designing new modules or reviewing code.
+
+| Section | Description |
+|---------|-------------|
+| SOLID-First Policy | Principles over patterns — when to apply each SOLID principle |
+| Complexity Limits | Per-language max cognitive complexity, nesting, parameter counts |
+| Naming Standards | Module, interface, and type naming conventions |
+| Clean Code Rules | Constants, dead code, immutability conventions |
+<% } %><%# #1720 (gap 3): guard was literal governanceLevel === 'L3', which documented
+    this section at L3 even though TRACK_ROUTER.md is generated ONLY at L4
+    (src/generators/ssot.ts:48-49 — "L4 only, compliance-grade context economy") — an
+    L3 phantom section for a file L3 never generates, while L4 (which DOES generate
+    the file) got no section at all. isL4 aligns the doc section with the L4-only
+    file. %><% if (isL4) { %>
+---
+
+## docs/METHOD/TRACK_ROUTER.md
+
+**Location:** `docs/METHOD/TRACK_ROUTER.md`
+**Lines:** 0
+**Purpose:** Query-to-document routing guide. Maps agent query types to the right starting document.
+
+| Section | Description |
+|---------|-------------|
+| Query Routing Table | Maps intent → starting doc → what to read |
+| Context Economy Rules | When to read vs. trust index |
+<% } %>
+---
+
+## How to Use This Map
+
+1. Identify what you need (architecture? invariants? standards?)
+2. Find the matching document above
+3. Use the section table to jump to the relevant part
+4. **Do not read entire documents** — use line ranges or section headers to stay focused
+
+> When you add a new canonical document, add an entry here with its section breakdown.

package/dist/templates/root/docs/METHOD/PATTERNS_CATALOG.md.ejs

@@ -0,0 +1,51 @@
+<% if (governanceLevel !== 'L1') { %>---
+title: '<%= projectName %> Patterns Catalog'
+doc_version: '1.0.0'
+status: active
+canonical_id: 'PATTERNS_CATALOG'
+tags: ['audience/dev', 'kind/method']
+related: ['REUSE_REGISTRY_SPEC']
+---
+
+# <%= projectName %> Patterns Catalog
+
+**Purpose:** A curated register of reusable code patterns surveyed from this repository.
+Each entry is anchored to a literal directory under `src/` (or the project's source root) and
+answers the same six questions, so a contributor can decide reuse-vs-new without reading code.
+
+**Location:** `docs/METHOD/PATTERNS_CATALOG.md`
+**Spec:** `docs/METHOD/REUSE_REGISTRY_SPEC.md` (the CANON-16 existing-code survey protocol)
+
+Read this — and search `REUSE_REGISTRY.md` — before opening a new file under `src/`.
+This register is owned by the project: `arbiter update` never overwrites it once it exists.
+
+---
+
+## Purpose
+
+The catalog names the patterns worth reusing so they are extended, not re-invented. It is not a
+tutorial: each entry is a pointer plus the design decisions worth knowing before you copy it.
+
+---
+
+## Entry schema
+
+Each entry is a level-2 heading `## <n>. <pattern name>` followed by six labelled fields:
+
+- **Use when:** the situation the pattern is the right answer to.
+- **Avoid when:** the situation where reaching for it is a mistake.
+- **Registry path:** the literal directory the pattern lives in, in backticks (no globs).
+- **Variation axis:** what legitimately differs between instances of the pattern.
+- **Test approach:** how instances of the pattern are tested.
+- **Rejected alternatives:** the design that was considered and dropped, and why.
+
+Keep the catalog small (a dozen entries at most): it lists load-bearing patterns, not every helper.
+
+---
+
+## Catalog
+
+_No patterns catalogued yet._ Add the first entry when a reusable pattern emerges — a shape that
+appears in two or more places and is worth surveying before writing a third. Record the survey in
+your plan per `REUSE_REGISTRY_SPEC.md`.
+<% } %>

package/dist/templates/root/docs/METHOD/REUSE_REGISTRY.md.ejs

@@ -0,0 +1,26 @@
+<% if (governanceLevel !== 'L1') { %># REUSE_REGISTRY — <%= projectName %>
+
+Registro dei moduli riutilizzabili e della ricerca documentata dell'esistente
+(INV-70 / CANON-16). Prima di creare un nuovo file sotto `src/` o `scripts/`,
+**cercare qui** e in `docs/METHOD/PATTERNS_CATALOG.md`: un hit significa riusare
+o estendere; un miss giustifica il file nuovo, ma la PR DEVE aggiungere la riga
+a questo registro prima del merge.
+
+**Spec:** `docs/METHOD/REUSE_REGISTRY_SPEC.md` — protocollo completo del survey.
+
+## Moduli registrati
+
+| Modulo | Percorso | Note | Data |
+| --- | --- | --- | --- |
+| _(nessun modulo ancora registrato)_ | | | |
+
+## Ricerca documentata dell'esistente
+
+| Data | Ricerca | Esito | Decisione |
+| --- | --- | --- | --- |
+| _(nessuna ricerca ancora registrata)_ | | | |
+
+> `scripts/check-reuse-registry.mjs` (gate attivo con `invariants_catalog:
+> extended`) fallisce se questo registro è assente o vuoto: la disciplina di
+> astrazione (INV-69/70) richiede traccia, non solo intenzione.
+<% } %>

package/dist/templates/root/docs/METHOD/REUSE_REGISTRY_SPEC.md.ejs

@@ -0,0 +1,80 @@
+<% if (governanceLevel !== 'L1') { %># REUSE_REGISTRY Specification — <%= projectName %>
+
+**Purpose:** Define the file-level registry of shared reusable modules and the
+protocol for consulting it before creating new code (CANON-16 survey).
+
+**Location:** `docs/METHOD/REUSE_REGISTRY_SPEC.md`
+**Registry:** `docs/METHOD/REUSE_REGISTRY.md`
+
+---
+
+## Purpose
+
+The registry is the first lookup stop for the CANON-16 refactor-first survey.
+Before opening any new file under `src/` or `scripts/`, a contributor checks
+this registry to determine whether the needed utility already exists.
+
+A registry hit means: reuse or extend the registered module. A registry miss
+justifies creating a new file, but the new PR MUST add its entry before merge.
+
+---
+
+## Acceptance criteria
+
+A module qualifies for registration when ALL of the following hold:
+
+1. **Exported** — provides named exports consumed via `import` or `require`.
+2. **Shared** — used by ≥2 distinct source files, OR extracted by explicit
+   policy.
+3. **Tested** — has at least one unit test, or is covered by integration tests.
+
+---
+
+## Entry schema
+
+Each entry is a third-level heading with a flat bullet list:
+
+```text
+### <module-slug>
+- path: <repo-relative path>
+- purpose: <one-sentence description>
+- key_exports: <comma-separated, max 5>
+- when_to_use: <scenario>
+- when_to_avoid: <scenario>
+- tests: <test file path(s) or "indirect via <file>">
+- since: <semver>
+- deprecated_in: <semver; omit if still active>
+- replaced_by: <path; required when deprecated_in is present>
+```
+
+All fields required except `deprecated_in` and `replaced_by`.
+
+---
+
+## CANON-16 survey integration
+
+Before creating any new file under `src/` or `scripts/`, the contributor MUST:
+
+1. Search `REUSE_REGISTRY.md` for entries whose purpose or exports match the
+   intended functionality.
+2. If a match is found: reuse or extend; record in plan:
+   `"Existing Code Survey: found <path> in REUSE_REGISTRY; reused."`
+3. If no match: record in plan:
+   `"Existing Code Survey: checked REUSE_REGISTRY, no similar entry."`
+
+---
+
+## Registration protocol
+
+The PR that introduces a new shared module MUST include the registry entry in
+the same diff.
+
+To deprecate: add `deprecated_in` + `replaced_by`; do NOT delete the entry.
+
+---
+
+## Non-goals
+
+Does NOT cover: external npm packages, EJS templates (CANON-04), generators
+(CANON-11), CLI commands (CANON-06), test fixtures, or docs.
+<% } %>

package/dist/templates/root/docs/METHOD/SSOT_CORE_SET.md.ejs

@@ -0,0 +1,62 @@
+# SSOT Core Set — <%= projectName %>
+
+**Status:** ENFORCED
+**Archetype:** `<%= archetype %>`<% if (architectureStyle && architectureStyle !== 'none') { %> / `<%= architectureStyle %>`<% } %>
+
+**Location:** `docs/METHOD/SSOT_CORE_SET.md`
+**Purpose:** Authoritative inventory of all Single Source of Truth documents in this project. Every canonical document governing product, system, or process MUST be listed here.
+
+---
+
+## Governance (HOW Agents Must Behave)
+
+- `AGENTS.md` — Canonical agent governance: invariants, coding standards, commit convention, gate commands
+
+## Method (HOW We Execute)
+
+- `docs/METHOD/KNOWLEDGE_MAP.md` — Navigation index for heavy documentation; read this before opening large docs
+- `docs/METHOD/SSOT_CORE_SET.md` — This file (authoritative SSOT inventory)
+- `docs/METHOD/CANONICAL_PATHS.md` — Aliasing registry for moved/renamed documents; check before reporting broken links
+<% if (governanceLevel !== 'L1') { %>
+- `docs/METHOD/ENGINEERING_DEFAULTS.md` — SOLID principles, coding standards, complexity limits
+- `docs/METHOD/REUSE_REGISTRY_SPEC.md` — CANON-16 existing-code survey spec; consult before creating a new module
+- `docs/METHOD/PATTERNS_CATALOG.md` — Curated register of reusable code patterns surveyed from this repo
+<% } %><% if (governanceLevel === 'L4') { %>
+- `docs/METHOD/TRACK_ROUTER.md` — Query-to-document routing guide for context-efficient navigation
+<% } %>
+## System (HOW We Build It)
+
+> Add architecture, ADR, and decision records here as the project grows.
+>
+> Examples:
+> - `docs/SYSTEM/ARCHITECTURE.md` — Technical architecture overview
+> - `docs/SYSTEM/DECISIONS.md` — Architectural Decision Records
+<% if (architectureStyle && architectureStyle !== 'none') { %>
+> - `docs/ADR/` — Architectural Decision Records (architecture style: <%= architectureStyle %>)
+<% } %>
+<% if (hasDatabase) { %>
+## Data (HOW We Manage Persistent State)
+
+> Entries required when `hasDatabase: true`:
+>
+> - `docs/DATA/SCHEMA.md` — Canonical database schema overview
+> - `docs/DATA/MIGRATIONS.md` — Migration history and rollback procedures
+> - `docs/DATA/DATA_DICTIONARY.md` — Field-level glossary for all entities
+
+<% } %><% if (hasPublicApi) { %>
+## API Contracts (WHAT Callers Can Depend On)
+
+> Entries required when `hasPublicApi: true`:
+>
+> - `docs/API/OPENAPI.yaml` or equivalent — Machine-readable API contract
+> - `docs/API/CHANGELOG.md` — API versioning and breaking-change history
+
+<% } %>
+---
+
+## Maintenance Rules
+
+1. Every canonical document added to the project MUST get an entry in this file.
+2. Entries must include the path and a one-line purpose description.
+3. Removed documents must be removed from this index.
+4. Run a SSOT integrity check when the index and filesystem diverge.

package/dist/templates/root/docs/METHOD/TRACK_ROUTER.md.ejs

@@ -0,0 +1,39 @@
+# Track Router — <%= projectName %>
+
+**Purpose:** Maps agent query types to the right starting document. Use this to navigate efficiently without reading everything.
+**Rule:** Read this first, then open only the section you need.
+
+---
+
+## Query Routing Table
+
+| Query type | Start here | Then read |
+|------------|------------|-----------|
+| What are the invariants? | `AGENTS.md` → Invariants section | Stop — invariants are self-contained |
+| What's the coding standard for X? | `AGENTS.md` → Coding Standards | `docs/METHOD/ENGINEERING_DEFAULTS.md` for depth |
+| How complex can this function be? | `docs/METHOD/ENGINEERING_DEFAULTS.md` → Complexity Limits | Stop |
+| What SOLID principle applies here? | `docs/METHOD/ENGINEERING_DEFAULTS.md` → SOLID-First Policy | Stop |
+| What docs exist on topic X? | `docs/METHOD/KNOWLEDGE_MAP.md` | Jump to specific doc |
+| What documents are canonical? | `docs/METHOD/SSOT_CORE_SET.md` | Jump to specific section |
+| How do I commit / run gates? | `AGENTS.md` → Project section | Stop |
+| What tests are required? | `AGENTS.md` → Testing Policy | Stop |
+| What's the architecture? | `docs/SYSTEM/ARCHITECTURE.md` (if it exists) | `docs/METHOD/KNOWLEDGE_MAP.md` for navigation |
+
+---
+
+## Context Economy Rules
+
+1. **Index before opening.** Always check `KNOWLEDGE_MAP.md` before reading a large doc.
+2. **Section-first.** Use the routing table above to jump to the right section, not the whole file.
+3. **Trust invariants.** AGENTS.md invariants are self-contained — no need to cross-reference.
+4. **Don't re-read unchanged files.** Once you've read a doc this session, trust your context.
+5. **Confirm before acting.** If a decision is ambiguous, cite the governing document and ask — don't guess.
+
+---
+
+## Adding New Routes
+
+When a new canonical document is added to the project:
+1. Add it to `docs/METHOD/SSOT_CORE_SET.md`
+2. Add an entry in `docs/METHOD/KNOWLEDGE_MAP.md` with section breakdown
+3. Add a routing row to the table above for the query types it answers