@devrik-tools/claude-gates 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "claude-gates",
+  "owner": {
+    "name": "claude-gates"
+  },
+  "metadata": {
+    "description": "Installable deterministic gates (hooks) for Claude Code, selectable per project or globally with `npx @devrik99/claude-gates init`."
+  },
+  "plugins": [
+    {
+      "name": "gates",
+      "source": "./plugins/gates",
+      "description": "PreToolUse gates: destructive-command blocks, protected paths, delegation/spec/quality rules, tool-discovery and forge-pipeline enforcement. Which gates run is decided by .ai/config.json (project) or ~/.claude/claude-gates/config.json (global).",
+      "version": "0.1.0"
+    }
+  ]
+}

package/README.es.md

@@ -0,0 +1,219 @@
+# claude-gates
+
+**Barreras (gates) instalables y deterministas para Claude Code.** Se ejecutan
+automáticamente antes de que Claude use una herramienta y **bloquean o avisan** cuando algo
+viola una regla: un comando destructivo, una escritura a un archivo protegido, una
+delegación sin brief, y más. Todo es **configurable por proyecto** y **se puede
+prender/apagar** cuando quieras.
+
+La idea de fondo: en vez de confiar en que el modelo *recuerde* las reglas, un hook
+**determinista** las hace cumplir. Un `git reset --hard` no se ejecuta porque el modelo
+haya decidido portarse bien; se bloquea porque un gate lo intercepta.
+
+🇬🇧 [Read it in English](./README.md)
+
+---
+
+## Instalación
+
+Dos pasos. El **plugin** engancha los hooks en Claude Code; el **CLI** elige qué gates se
+ejecutan y con qué configuración.
+
+```bash
+# 1. Registrar el marketplace e instalar el plugin (engancha los hooks)
+claude plugin marketplace add https://github.com/DevRik99/claude-gates
+claude plugin install gates@claude-gates
+
+# 2. Elegir qué gates adoptar (menú interactivo) — o usar npx sin clonar
+npx @devrik-tools/claude-gates init
+```
+
+Reinicia la sesión de Claude Code (o ejecuta `/plugin`) para que los hooks carguen.
+
+> **¿Por qué dos cosas?** El plugin **siempre trae los 30 gates**; la configuración decide
+> **cuáles se ejecutan**. Así puedes prender uno sin reinstalar: es una línea en un JSON.
+
+---
+
+## Cómo funciona (el modelo en 30 segundos)
+
+```
+Claude va a usar una herramienta (Write, Bash, Agent…)
+        │
+        ▼
+Claude Code dispara los hooks PreToolUse en paralelo
+        │
+        ▼
+Cada gate que aplica (según su "matcher") se ejecuta en su propio proceso:
+   · lee el payload          · lee su configuración del proyecto
+   · si está apagado → sale  · si la regla se viola → DENY (bloquea) o WARN (avisa)
+        │
+        ▼
+Si algún gate bloquea, la herramienta no se ejecuta.
+```
+
+- **DENY**: la acción es determinísticamente incorrecta → se bloquea.
+- **WARN**: la acción necesita criterio → el gate inyecta un aviso y deja seguir.
+- **Silencio**: el caso común. Un gate no molesta si no hay nada que objetar.
+
+Cada gate es **autocontenido** (solo Node built-ins, sin dependencias en tiempo de
+ejecución), así que funciona aunque instales uno suelto por fuera.
+
+---
+
+## Los gates (30, en 7 familias)
+
+`[on]` = encendidos por defecto; `[off]` = los prendes si los quieres.
+
+### 🔒 Security — bloqueos duros sobre lo destructivo
+| Gate | | Qué hace |
+|---|---|---|
+| `bash-commands` | on | Bloquea `git reset --hard`, `rm -rf`, force push, matar procesos por nombre, y publicar al remoto sin autorización. |
+| `protected-paths` | on | Bloquea escrituras a `.env`, lockfiles y el propio harness. |
+| `root-whitelist` | on | Bloquea crear archivos/carpetas nuevos en la raíz fuera de una lista blanca. |
+| `no-blocking` | off | Bloquea `sleep`, `tail -f`, bucles de sondeo y servidores en primer plano. |
+
+### 🤝 Delegation — exigencias sobre el brief al delegar a un subagente
+| Gate | | Qué hace |
+|---|---|---|
+| `brief-before-delegate` | off | Exige objetivo, pasos y criterio de "listo" en el prompt. |
+| `intent-flow` | off | Exige secciones QUÉ SÍ / QUÉ NO / EDGE CASES. |
+| `risk-level` | off | Exige declarar el nivel (QUESTION/MICRO/STANDARD/HIGH-RISK). |
+| `circuit-breaker` | off | Corta la misma delegación reintentada sin cambios reales. |
+| `no-memory-dependency` | off | Avisa si el brief depende de que el subagente "recuerde" la conversación. |
+
+### 📋 Spec-driven flow — solo aplican si el proyecto adoptó desarrollo por specs
+| Gate | | Qué hace |
+|---|---|---|
+| `feature-catalog` | on | Una sola feature en progreso; cerrar exige asserts y revisión. |
+| `sdd-specs` | off | Exige requirements/design/tasks no vacíos antes de implementar. |
+| `implementation-pipeline` | off | Exige declarar definición → escritura → validación → QA → cierre. |
+| `mandatory-flow` | off | Exige una tarea activa con contrato antes de implementar. |
+| `test-matrix` | off | Exige una matriz de tests (los tipos que el requerimiento vuelve obligatorios). |
+
+### ✨ Quality — higiene de código, diagnóstico y lenguaje
+| Gate | | Qué hace |
+|---|---|---|
+| `dependency-skills` | on | Una dependencia directa nueva exige una skill vigente. |
+| `root-cause-first` | off | Exige un diagnóstico origen→síntoma antes de un parche. |
+| `audit-before-build` | off | Antes de un script/gate nuevo, exige declarar que nada existente lo cubre. |
+| `never-assume` | off | Marca suposiciones sin verificar en briefs y código. |
+| `rule-skill-autodiscovery` | off | Carga los gates que el proyecto declara en sus `rules/` y `skills/`. |
+| `recurrence-lock` | on | La segunda aparición de un defecto exige su bloqueo determinista. |
+| `test-after-implementation` | off | Avisa cuando se escribe un test después de su implementación. |
+| `no-reconfirm` | on | Nunca vuelve a preguntar lo que ya respondiste. |
+| `neutral-spanish` | on | Avisa sobre voseo o léxico regional en el texto escrito. |
+| `diagnosis-before-patch` | on | Avisa cuando se cambian timeouts/reintentos sin evidencia. |
+
+### 🔎 Tool discovery — no reinventar la rueda
+| Gate | | Qué hace |
+|---|---|---|
+| `reuse-before-build` | off | Antes de construir una herramienta, consulta el mapa de herramientas del proyecto; bloquea si no auditaste (local → Context7 → web). |
+| `tool-map` | off | Registra las herramientas descubiertas en `.ai/tool-map.json` para no volver a explorar. |
+
+### 🏭 Forge pipeline — obliga a seguir el flujo de forge
+| Gate | | Qué hace |
+|---|---|---|
+| `forge-flow` | off | En un proyecto que adoptó [forge](https://github.com/DevRik99/forge-mcp), bloquea editar/ejecutar si no hay un run de forge activo. Cierra el hueco que el MCP no puede: te obliga a pasar por el pipeline. |
+
+### 🩺 Session start — validaciones al arrancar la sesión *(en construcción)*
+`doctor`, `ask-adoption`, `wiring-check` — declarados en el catálogo; sus scripts se migran
+a continuación.
+
+---
+
+## Configuración: prender, apagar y ajustar cada gate
+
+Todo vive en un solo archivo. **El proyecto manda sobre el global:**
+
+- **Proyecto:** `<raíz>/.ai/config.json`
+- **Global (fallback):** `~/.claude/claude-gates/config.json`
+
+`init` escribe ahí la selección **y materializa los valores por defecto de cada gate**, así
+ves y editas cada perilla:
+
+```json
+{
+  "adopted": "partial",
+  "gateVersion": "3.0.0",
+  "gates": {
+    "blockDestructiveShellCommands": {
+      "enabled": true,
+      "rmRfProtectedAreas": ["/", "*", "src", "tests"],
+      "denyPatterns": ["git reset --hard", "…"]
+    },
+    "requireBriefBeforeDelegating": { "enabled": false }
+  }
+}
+```
+
+- **Apagar un gate:** `"enabled": false`. Se apaga al instante, sin reinstalar.
+- **Ajustar su comportamiento:** editas sus parámetros (la lista blanca, los patrones, los
+  umbrales). Lo que declara el proyecto **reemplaza** el default del gate.
+- Un gate que no aparece en la configuración usa su default del catálogo. Las claves que ya
+  tuvieras en el archivo (por ejemplo `autoCommit`) se conservan intactas.
+
+---
+
+## Comandos del CLI
+
+```bash
+# Menú interactivo: elige plugins, familias o gates, por proyecto o global, e instala.
+npx @devrik-tools/claude-gates init
+
+# Sin menú (para CI o scripts):
+claude-gates init --project|--global  --defaults|--all|--none|--families a,b|--gates x,y  --yes  --dry-run
+claude-gates init --no-install        # escribe la configuración pero no instala el plugin
+
+# Inspeccionar el catálogo:
+claude-gates registry --list          # lista familias y gates
+claude-gates registry --check         # valida registry.json
+```
+
+---
+
+## Estructura del repositorio
+
+```
+registry.json                     Catálogo: familias → gates (id, configKey, default, tools, params).
+                                  Es la única fuente de verdad; el menú y los hooks derivan de él.
+cli/                              El CLI de npm (commander + @clack/prompts + zod).
+  registry.mjs · selection.mjs    Cargar/validar el catálogo; convertir la selección en configuración.
+  config.mjs · materialize.mjs    Dónde vive la configuración, merge, y volcar los defaults de cada gate.
+  init.mjs · install.mjs          Flujo interactivo + instalar el plugin.
+plugins/gates/                    El plugin de gates.
+  .claude-plugin/plugin.json
+  hooks/hooks.json                Una entrada por gate (matcher + comando). Lo carga Claude Code.
+  hooks/lib/                      Código compartido de los hooks (Node built-ins only).
+  hooks/gates/<id>/               Un gate por carpeta: index.mjs (la regla) + test.mjs (su test).
+plugins/tasks/                    El plugin de tareas (en construcción): persiste tareas por proyecto.
+.claude-plugin/marketplace.json   Lista los plugins del marketplace.
+```
+
+**Agregar un gate** = una carpeta en `plugins/gates/hooks/gates/<id>/` (con `index.mjs` y
+`test.mjs`) + una entrada en `registry.json`. El resto se deriva solo.
+
+---
+
+## Desarrollo
+
+```bash
+npm test                  # ejecuta todos los tests (node --test)
+npm run registry:check    # valida el catálogo
+npm run lint              # eslint (boundaries, no-magic-numbers, sonarjs, cspell…)
+```
+
+Cada gate se testea aislado: `node --test plugins/gates/hooks/gates/<id>/test.mjs`.
+
+> Este repositorio trae su propio `.ai/config.json` que apaga localmente los gates que
+> darían falso positivo al **editar los gates mismos** (por ejemplo, `audit-before-build`
+> cree que estás "construyendo una herramienta" cuando en realidad editas un gate
+> existente). Por eso está versionado: el repo se comporta igual en cualquier máquina.
+
+## Requisitos
+
+Node **≥ 22.5** (el gate `forge-flow` usa `node:sqlite`, disponible desde esa versión).
+
+## Licencia
+
+MIT.

package/README.md

@@ -0,0 +1,222 @@
+# claude-gates
+
+**Installable, deterministic gates (hooks) for Claude Code.** They run automatically before
+Claude executes a tool and **block or warn** when something breaks a rule: a destructive
+command, a write to a protected file, a delegation with no brief, and more. Everything is
+**configurable per project** and can be **turned on/off** whenever you want.
+
+The core idea: instead of trusting the model to *remember* the rules, a **deterministic**
+hook enforces them. A `git reset --hard` does not run because the model chose to behave —
+it is blocked because a gate intercepts it.
+
+🇪🇸 [Léelo en español](./README.es.md)
+
+---
+
+## Install
+
+Two steps. The **plugin** wires the hooks into Claude Code; the **CLI** picks which gates
+run and with what configuration.
+
+```bash
+# 1. Register the marketplace and install the plugin (wires the hooks)
+claude plugin marketplace add https://github.com/DevRik99/claude-gates
+claude plugin install gates@claude-gates
+
+# 2. Choose which gates to adopt (interactive menu) — or use npx without cloning
+npx @devrik-tools/claude-gates init
+```
+
+Restart the Claude Code session (or run `/plugin`) so the hooks load.
+
+> **Why two things?** The plugin **always ships all 30 gates**; the config decides **which
+> ones run**. So you can turn one on without reinstalling — it is one line in a JSON file.
+
+---
+
+## How it works (the model in 30 seconds)
+
+```
+Claude is about to use a tool (Write, Bash, Agent…)
+        │
+        ▼
+Claude Code fires the PreToolUse hooks in parallel
+        │
+        ▼
+Each gate that applies (by its "matcher") runs in its own process:
+   · reads the payload       · reads its project config
+   · if off → exits          · if the rule is broken → DENY (block) or WARN (advise)
+        │
+        ▼
+If any gate blocks, the tool does not run.
+```
+
+- **DENY**: the action is deterministically wrong → it is blocked.
+- **WARN**: the action needs judgment → the gate injects a note and lets it proceed.
+- **Silence**: the common path. A gate never nags when there is nothing to object to.
+
+Every gate is **self-contained** (Node built-ins only, no runtime dependencies), so it
+works even if you install one on its own.
+
+---
+
+## The gates (30, in 7 families)
+
+`[on]` = enabled by default; `[off]` = enable it if you want it.
+
+### 🔒 Security — hard blocks on destructive actions
+| Gate | | What it does |
+|---|---|---|
+| `bash-commands` | on | Blocks `git reset --hard`, `rm -rf`, force push, killing processes by name, and publishing to a remote without authorization. |
+| `protected-paths` | on | Blocks writes to `.env`, lockfiles and the harness itself. |
+| `root-whitelist` | on | Blocks new root-level files/folders outside a whitelist. |
+| `no-blocking` | off | Blocks `sleep`, `tail -f`, polling loops and foreground servers. |
+
+### 🤝 Delegation — requirements on the brief when delegating to a subagent
+| Gate | | What it does |
+|---|---|---|
+| `brief-before-delegate` | off | Requires goal, steps and done-when criteria in the prompt. |
+| `intent-flow` | off | Requires IN SCOPE / OUT OF SCOPE / EDGE CASES sections. |
+| `risk-level` | off | Requires a declared level (QUESTION/MICRO/STANDARD/HIGH-RISK). |
+| `circuit-breaker` | off | Cuts the same delegation retried without real changes. |
+| `no-memory-dependency` | off | Warns when the brief relies on the subagent "remembering" the chat. |
+
+### 📋 Spec-driven flow — only relevant if the project adopted spec-driven development
+| Gate | | What it does |
+|---|---|---|
+| `feature-catalog` | on | A single feature in progress; closing requires asserts and review. |
+| `sdd-specs` | off | Requires non-empty requirements/design/tasks before implementing. |
+| `implementation-pipeline` | off | Requires declaring definition → writing → validation → QA → closure. |
+| `mandatory-flow` | off | Requires an active task with a contract before implementing. |
+| `test-matrix` | off | Requires a test matrix (the types the requirement makes mandatory). |
+
+### ✨ Quality — code hygiene, diagnosis and language
+| Gate | | What it does |
+|---|---|---|
+| `dependency-skills` | on | A new direct dependency requires a current skill. |
+| `root-cause-first` | off | Requires an origin→symptom diagnosis before a patch. |
+| `audit-before-build` | off | Before a new script/gate, requires stating that nothing existing covers it. |
+| `never-assume` | off | Flags unverified assumptions in briefs and code. |
+| `rule-skill-autodiscovery` | off | Loads gates the project declares in its `rules/` and `skills/`. |
+| `recurrence-lock` | on | A second occurrence of a defect class requires its deterministic block. |
+| `test-after-implementation` | off | Warns when a test is written after its paired implementation. |
+| `no-reconfirm` | on | Never re-ask what you already answered. |
+| `neutral-spanish` | on | Warns about voseo or regional lexicon in written text. |
+| `diagnosis-before-patch` | on | Warns when timeouts/retries change without evidence. |
+
+### 🔎 Tool discovery — don't reinvent the wheel
+| Gate | | What it does |
+|---|---|---|
+| `reuse-before-build` | off | Before building a tool, consults the project tool map; blocks if you did not audit (local → Context7 → web). |
+| `tool-map` | off | Records discovered tools in `.ai/tool-map.json` so exploration is not repeated. |
+
+### 🏭 Forge pipeline — enforces the forge workflow
+| Gate | | What it does |
+|---|---|---|
+| `forge-flow` | off | In a project that adopted [forge](https://github.com/DevRik99/forge-mcp), blocks editing/running unless an active forge run exists. Closes the hole the MCP cannot: it forces you through the pipeline. |
+
+### 🩺 Session start — startup checks *(work in progress)*
+`doctor`, `ask-adoption`, `wiring-check` — declared in the catalog; their scripts are being
+migrated next.
+
+---
+
+## Configuration: turn gates on, off, and tune them
+
+Everything lives in one file. **Project overrides global:**
+
+- **Project:** `<root>/.ai/config.json`
+- **Global (fallback):** `~/.claude/claude-gates/config.json`
+
+`init` writes the selection there **and materializes each gate's default values**, so you
+see and edit every knob:
+
+```json
+{
+  "adopted": "partial",
+  "gateVersion": "3.0.0",
+  "gates": {
+    "blockDestructiveShellCommands": {
+      "enabled": true,
+      "rmRfProtectedAreas": ["/", "*", "src", "tests"],
+      "denyPatterns": ["git reset --hard", "…"]
+    },
+    "warnNonNeutralSpanish": {
+      "enabled": true,
+      "regionalMarkers": ["tenés", "podés", "…"]
+    },
+    "requireBriefBeforeDelegating": { "enabled": false }
+  }
+}
+```
+
+- **Turn a gate off:** `"enabled": false`. Off instantly, no reinstall.
+- **Tune its behavior:** edit its parameters (the whitelist, the patterns, the thresholds).
+  What the project declares **replaces** the gate's default.
+- A gate absent from the config uses its catalog default. Keys you already had in the file
+  (e.g. `autoCommit`) are kept intact.
+
+---
+
+## CLI commands
+
+```bash
+# Interactive menu: pick plugins, families or gates, per project or global, and install.
+npx @devrik-tools/claude-gates init
+
+# Non-interactive (for CI or scripts):
+claude-gates init --project|--global  --defaults|--all|--none|--families a,b|--gates x,y  --yes  --dry-run
+claude-gates init --no-install        # write the config but do not install the plugin
+
+# Inspect the catalog:
+claude-gates registry --list          # list families and gates
+claude-gates registry --check         # validate registry.json
+```
+
+---
+
+## Repository layout
+
+```
+registry.json                     Catalog: families → gates (id, configKey, default, tools, params).
+                                  The single source of truth; the menu and the hooks derive from it.
+cli/                              The npm CLI (commander + @clack/prompts + zod).
+  registry.mjs · selection.mjs    Load/validate the catalog; turn a selection into config.
+  config.mjs · materialize.mjs    Where config lives, merge, and dump each gate's defaults.
+  init.mjs · install.mjs          Interactive flow + install the plugin.
+plugins/gates/                    The gates plugin.
+  .claude-plugin/plugin.json
+  hooks/hooks.json                One entry per gate (matcher + command). Loaded by Claude Code.
+  hooks/lib/                      Shared hook code (Node built-ins only).
+  hooks/gates/<id>/               One gate per folder: index.mjs (the rule) + test.mjs (its test).
+plugins/tasks/                    The tasks plugin (work in progress): persists per-project tasks.
+.claude-plugin/marketplace.json   Lists the marketplace plugins.
+```
+
+**Adding a gate** = one folder in `plugins/gates/hooks/gates/<id>/` (with `index.mjs` and
+`test.mjs`) + one entry in `registry.json`. Everything else derives automatically.
+
+---
+
+## Development
+
+```bash
+npm test                  # run all tests (node --test)
+npm run registry:check    # validate the catalog
+npm run lint              # eslint (boundaries, no-magic-numbers, sonarjs, cspell…)
+```
+
+Each gate is tested in isolation: `node --test plugins/gates/hooks/gates/<id>/test.mjs`.
+
+> This repo ships its own `.ai/config.json` that locally disables the gates that would
+> false-positive when **editing the gates themselves** (e.g. `audit-before-build` thinks
+> you are "building a tool" when you are really editing an existing gate). It is versioned
+> so the repo behaves the same on any machine.
+
+## Requirements
+
+Node **≥ 22.5** (the `forge-flow` gate uses `node:sqlite`, available from that version).
+
+## License
+
+MIT.

package/cli/__tests__/config.test.mjs

@@ -0,0 +1,101 @@
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import {
+  SCOPES,
+  findProjectRoot,
+  configPathFor,
+  readConfig,
+  mergeConfig,
+  writeConfig,
+} from '../config.mjs';
+
+function temporaryDirectory() {
+  return mkdtempSync(join(tmpdir(), 'claude-gates-'));
+}
+
+test('findProjectRoot climbs to the .git directory and falls back to the start', () => {
+  const root = temporaryDirectory();
+  mkdirSync(join(root, '.git'));
+  const nested = join(root, 'src', 'deep');
+  mkdirSync(nested, { recursive: true });
+  assert.equal(findProjectRoot(nested), root);
+
+  const loose = temporaryDirectory();
+  assert.equal(findProjectRoot(loose), loose);
+});
+
+test('findProjectRoot never climbs into the home directory', () => {
+  const fakeHome = temporaryDirectory();
+  mkdirSync(join(fakeHome, '.ai'));
+  const project = join(fakeHome, 'repos', 'app');
+  mkdirSync(project, { recursive: true });
+  assert.equal(findProjectRoot(project, { home: fakeHome }), project);
+});
+
+test('configPathFor resolves both scopes', () => {
+  const home = temporaryDirectory();
+  const project = temporaryDirectory();
+  mkdirSync(join(project, '.ai'));
+  assert.equal(
+    configPathFor(SCOPES.GLOBAL, { home }),
+    join(home, '.claude', 'claude-gates', 'config.json'),
+  );
+  assert.equal(
+    configPathFor(SCOPES.PROJECT, { cwd: project }),
+    join(project, '.ai', 'config.json'),
+  );
+  assert.throws(() => configPathFor('nope'), /Unknown scope/);
+});
+
+test('readConfig distinguishes missing, valid and corrupt', () => {
+  const directory = temporaryDirectory();
+  const path = join(directory, 'config.json');
+  assert.deepEqual(readConfig(path), {
+    exists: false,
+    data: {},
+    corrupt: false,
+  });
+  writeFileSync(path, '{"autoCommit":true}');
+  assert.deepEqual(readConfig(path), {
+    exists: true,
+    data: { autoCommit: true },
+    corrupt: false,
+  });
+  writeFileSync(path, '{nope');
+  assert.equal(readConfig(path).corrupt, true);
+});
+
+test('mergeConfig keeps unrelated keys and unknown gates, overrides known ones', () => {
+  const existing = {
+    autoCommit: true,
+    gates: { oldGate: true, blockX: false },
+  };
+  const merged = mergeConfig(existing, {
+    adopted: 'partial',
+    gates: { blockX: true, blockY: false },
+    gateVersion: '3.0.0',
+  });
+  assert.deepEqual(merged, {
+    autoCommit: true,
+    adopted: 'partial',
+    gateVersion: '3.0.0',
+    gates: { oldGate: true, blockX: true, blockY: false },
+  });
+});
+
+test('writeConfig creates parent folders and writes pretty JSON with trailing newline', () => {
+  const directory = temporaryDirectory();
+  const path = join(directory, 'a', 'b', 'config.json');
+  writeConfig(path, { adopted: true });
+  assert.ok(existsSync(path));
+  assert.equal(readFileSync(path, 'utf8'), '{\n  "adopted": true\n}\n');
+});

package/cli/__tests__/init-flags.test.mjs

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { normalizeOptions } from '../init.mjs';
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', 'index.mjs');
+
+test('normalizeOptions maps commander options', () => {
+  assert.deepEqual(
+    normalizeOptions({
+      global: true,
+      families: ['security', 'quality'],
+      yes: true,
+      dryRun: true,
+    }),
+    {
+      scope: 'global',
+      mode: 'families',
+      families: ['security', 'quality'],
+      gates: [],
+      yes: true,
+      dryRun: true,
+      install: undefined,
+    },
+  );
+  assert.equal(normalizeOptions({ gates: ['bash-commands'] }).mode, 'granular');
+  assert.equal(normalizeOptions({}).mode, null);
+  assert.throws(() => normalizeOptions({ all: true, none: true }), /Pick one/);
+  assert.throws(
+    () => normalizeOptions({ project: true, global: true }),
+    /Pick one/,
+  );
+});
+
+test('non-interactive init writes .ai/config.json at the project root', () => {
+  const project = mkdtempSync(join(tmpdir(), 'claude-gates-proj-'));
+  mkdirSync(join(project, '.git'));
+  const nested = join(project, 'src');
+  mkdirSync(nested);
+
+  execFileSync(
+    process.execPath,
+    [
+      CLI,
+      'init',
+      '--project',
+      '--families',
+      'security',
+      '--yes',
+      '--no-install',
+    ],
+    { cwd: nested, encoding: 'utf8' },
+  );
+
+  const path = join(project, '.ai', 'config.json');
+  assert.ok(existsSync(path), 'config written at git root, not at cwd');
+  const config = JSON.parse(readFileSync(path, 'utf8'));
+  assert.equal(config.adopted, 'partial');
+  // Gates with params are materialized as { enabled, ...defaults } so the knobs are editable.
+  assert.equal(config.gates.blockDestructiveShellCommands.enabled, true);
+  assert.equal(config.gates.requireBriefBeforeDelegating.enabled, false);
+  assert.match(config.gateVersion, /^\d+\.\d+\.\d+$/);
+});
+
+test('--dry-run writes nothing', () => {
+  const project = mkdtempSync(join(tmpdir(), 'claude-gates-dry-'));
+  execFileSync(
+    process.execPath,
+    [CLI, 'init', '--project', '--all', '--yes', '--dry-run'],
+    { cwd: project, encoding: 'utf8' },
+  );
+  assert.ok(!existsSync(join(project, '.ai', 'config.json')));
+});
+
+test('--none records an explicit refusal', () => {
+  const project = mkdtempSync(join(tmpdir(), 'claude-gates-none-'));
+  execFileSync(
+    process.execPath,
+    [CLI, 'init', '--project', '--none', '--yes', '--no-install'],
+    { cwd: project, encoding: 'utf8' },
+  );
+  const config = JSON.parse(
+    readFileSync(join(project, '.ai', 'config.json'), 'utf8'),
+  );
+  assert.equal(config.adopted, false);
+});
+
+test('a corrupt existing config aborts without writing', () => {
+  const project = mkdtempSync(join(tmpdir(), 'claude-gates-corrupt-'));
+  mkdirSync(join(project, '.ai'));
+  const path = join(project, '.ai', 'config.json');
+  writeFileSync(path, '{broken');
+  assert.throws(() =>
+    execFileSync(
+      process.execPath,
+      [CLI, 'init', '--project', '--all', '--yes'],
+      { cwd: project, encoding: 'utf8', stdio: 'pipe' },
+    ),
+  );
+  assert.equal(readFileSync(path, 'utf8'), '{broken');
+});