@devrik-tools/claude-gates 0.3.1 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -11,13 +11,13 @@
       "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.3.1"
+      "version": "0.6.0"
     },
     {
       "name": "tasks",
       "source": "./plugins/tasks",
       "description": "Deterministic task tracking: the model registers tasks via the CLI, a UserPromptSubmit hook reminds of open tasks every few messages, and a SessionStart hook lists active tasks when a session opens.",
-      "version": "0.3.1"
+      "version": "0.6.0"
     }
   ]
 }

package/README.es.md

@@ -30,7 +30,7 @@ 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
+> **¿Por qué dos cosas?** El plugin **siempre trae los 40 gates**; la configuración decide
 > **cuáles se ejecutan**. Así puedes prender uno sin reinstalar: es una línea en un JSON.
 
 ---
@@ -105,6 +105,11 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `no-reconfirm` | on | Nunca vuelve a preguntar lo que ya respondiste. |
 | `neutral-spanish` | on | Bloquea voseo o léxico regional en el texto escrito (marcador `neutral-spanish:allow` para una cita/fixture deliberada). |
 | `diagnosis-before-patch` | on | Avisa cuando se cambian timeouts/reintentos sin evidencia. |
+| `lint-commit` | off | Bloquea `git commit` mientras el script de lint del proyecto falla (autodetecta `npm run lint`; silencioso si no hay). |
+| `staged-lint` | off | Bloquea `git commit` cuando los archivos **en el stage** fallan lint — lintea solo lo que agregaste al stage, así tu cambio no puede meter deuda de lint nueva y la deuda preexistente en archivos que no tocaste nunca te bloquea. Marcador `[skip-lint]` para una excepción deliberada. |
+| `atomic-commit` | off | Bloquea un `git commit` que no es atómico — que mezcla más de N naturalezas de cambio (código/tests/deps/config…) o stagea más archivos revisables de los que un commit debería llevar. Docs/imágenes/generados no cuentan. Marcador `[wip]` para un commit deliberadamente amplio. |
+| `no-coauthor` | on | Bloquea un `git commit` que lleve un trailer de atribución de IA (`Co-Authored-By`, `Generated with`, un trailer de sesión). Marcador `[allow-coauthor]` para un co-autor legítimo. |
+| `no-lint-suppression` | on | Bloquea una escritura que silencia el linter/type-checker (`eslint-disable`, `@ts-ignore`, una regla en `off`) en vez de arreglar el código. Marcador `lint-ok: <razón>` en la misma línea para un falso positivo documentado. |
 
 ### 🔎 Tool discovery — no reinventar la rueda
 | Gate | | Qué hace |
@@ -117,9 +122,13 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 |---|---|---|
 | `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.
+### 🩺 Sesión y contexto — validaciones al arrancar e inyección de capacidades
+| Gate | | Qué hace |
+|---|---|---|
+| `doctor` | on | Al iniciar la sesión, corre el validador de entorno y solo habla si algo falla. |
+| `ask-adoption` | on | En un proyecto que nunca respondió, hace que el asistente pregunte qué adoptar. |
+| `wiring-check` | on | Avisa cuando un hook registrado falta o un script quedó huérfano. |
+| `capability-map` | off | En cada mensaje, inyecta el catálogo de capacidades del proyecto — skills, agents/subagents, comandos — como dato compacto, y lo persiste en `.ai/capability-map.json` (como el mapa de herramientas). Autosincronizado desde el disco. Nunca bloquea. |
 
 ---
 
@@ -153,6 +162,18 @@ ves y editas cada perilla:
   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.
+- **Válvulas de escape:** algunos gates bloquean (deny) pero aceptan un marcador explícito
+  de exención en el contenido/prompt para un caso legítimo: `neutral-spanish:allow` (una cita
+  regional deliberada), `test-after-impl:allow` (un test de regresión), `memory-not-needed`
+  (una frase que no depende de memoria), `[allow-coauthor]` (un co-autor legítimo en un
+  commit), `lint-ok: <razón>` (un falso positivo documentado del linter), `[skip-lint]`
+  (saltea el chequeo de staged-lint por un commit), `[wip]` (permite un commit
+  deliberadamente amplio, no atómico). `dependency-skills` se exime vía su lista
+  `depsWithoutOwnApi`.
+- **Inyección de capacidades:** `capability-map` (off por defecto) es totalmente ajustable —
+  elegí qué tipos exponer (`"kinds": ["skills", "agents", "commands"]`), limitá cada blurb
+  (`maxClauseChars`), agregá raíces extra por tipo, o apagá la persistencia
+  (`"persist": false`) y apuntá el mapa a otro archivo (`mapFile`).
 
 ---
 

package/README.md

@@ -5,7 +5,7 @@ Claude executes a tool and **block or warn** when something breaks a rule: a des
 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**
+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.
 
@@ -29,7 +29,7 @@ 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
+> **Why two things?** The plugin **always ships all 40 gates**; the config decides **which
 > ones run**. So you can turn one on without reinstalling — it is one line in a JSON file.
 
 ---
@@ -65,60 +65,76 @@ works even if you install one on its own.
 `[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` over protected areas, force push, and killing processes by name. |
-| `block-remote-publish` | on | Blocks `git push`, `gh pr merge`, `gh release create` without authorization. Set `blockRemotePublish: false` to let the agent publish on its own. |
-| `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. |
+
+| Gate                   |     | What it does                                                                                                                                      |
+| ---------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bash-commands`        | on  | Blocks `git reset --hard`, `rm -rf` over protected areas, force push, and killing processes by name.                                              |
+| `block-remote-publish` | on  | Blocks `git push`, `gh pr merge`, `gh release create` without authorization. Set `blockRemotePublish: false` to let the agent publish on its own. |
+| `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 | Blocks a brief that relies on the subagent "remembering" the chat (add `memory-not-needed` to allow a false positive). |
+
+| 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 | Blocks a brief that relies on the subagent "remembering" the chat (add `memory-not-needed` to allow a false positive). |
 
 ### 📋 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. |
+
+| 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). |
+| `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 | Blocks a new direct dependency with no matching skill (declare it in `depsWithoutOwnApi` if it needs none). |
-| `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 | Blocks a test written after its paired implementation (add `test-after-impl:allow` for a regression test). |
-| `no-reconfirm` | on | Never re-ask what you already answered. |
-| `neutral-spanish` | on | Blocks voseo or regional lexicon in written text (add `neutral-spanish:allow` for a deliberate quote/fixture). |
-| `diagnosis-before-patch` | on | Warns when timeouts/retries change without evidence. |
+
+| Gate                        |     | What it does                                                                                                   |
+| --------------------------- | --- | -------------------------------------------------------------------------------------------------------------- |
+| `dependency-skills`         | on  | Blocks a new direct dependency with no matching skill (declare it in `depsWithoutOwnApi` if it needs none).    |
+| `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 | Blocks a test written after its paired implementation (add `test-after-impl:allow` for a regression test).     |
+| `no-reconfirm`              | on  | Never re-ask what you already answered.                                                                        |
+| `neutral-spanish`           | on  | Blocks voseo or regional lexicon in written text (add `neutral-spanish:allow` for a deliberate quote/fixture). |
+| `diagnosis-before-patch`    | on  | Warns when timeouts/retries change without evidence.                                                           |
+| `lint-commit`               | off | Blocks `git commit` while the project's lint script fails (autodetects `npm run lint`; silent if none).        |
+| `staged-lint`               | off | Blocks `git commit` when the **staged** files fail lint — lints only what you staged, so your change can't add new lint debt while pre-existing debt in untouched files never blocks you. Add `[skip-lint]` for a deliberate exception. |
+| `atomic-commit`             | off | Blocks a `git commit` that is not atomic — one mixing more than N natures of change (code/tests/deps/config…) or staging more reviewable files than a commit should carry. Docs/assets/generated aren't counted. Add `[wip]` for a deliberately broad commit. |
+| `no-coauthor`               | on  | Blocks a `git commit` carrying an AI/agent attribution trailer (`Co-Authored-By`, `Generated with`, a session trailer). Add `[allow-coauthor]` for one legitimate co-author. |
+| `no-lint-suppression`       | on  | Blocks a write that silences the linter/type-checker (`eslint-disable`, `@ts-ignore`, a rule set to `off`) instead of fixing the code. Add `lint-ok: <reason>` on the same line for a documented false positive. |
 
 ### 🔎 Tool discovery — don't reinvent the wheel
-| Gate | | What it does |
-|---|---|---|
+
+| 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. |
+| `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 |
-|---|---|---|
+
+| 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.
+### 🩺 Session & context — startup checks and capability injection
+
+| Gate             |     | What it does                                                                                                                                                                                          |
+| ---------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `doctor`         | on  | On session start, runs the environment validator and only speaks on failure.                                                                                                                        |
+| `ask-adoption`   | on  | In a project that never answered, makes the assistant ask what to adopt.                                                                                                                            |
+| `wiring-check`   | on  | Warns when a registered hook is missing or a script is orphaned.                                                                                                                                     |
+| `capability-map` | off | On every message, injects the project's capability catalog — skills, agents/subagents, commands — as compact data, and persists it to `.ai/capability-map.json` (like the tool map). Autosynced from disk. Never blocks. |
 
 ---
 
@@ -163,7 +179,14 @@ see and edit every knob:
 - **Escape hatches:** a few gates block (deny) but accept an explicit opt-out marker in the
   content/prompt for a legitimate case: `neutral-spanish:allow` (a deliberate regional
   quote), `test-after-impl:allow` (a regression test), `memory-not-needed` (a
-  non-memory phrase). `dependency-skills` opts out via its `depsWithoutOwnApi` list.
+  non-memory phrase), `[allow-coauthor]` (one legitimate co-author on a commit),
+  `lint-ok: <reason>` (a documented linter false positive), `[skip-lint]` (skip the
+  staged-lint check for one commit), `[wip]` (allow one deliberately broad,
+  non-atomic commit). `dependency-skills` opts out via its `depsWithoutOwnApi` list.
+- **Capability injection:** `capability-map` (off by default) is fully tunable — pick which
+  kinds to surface (`"kinds": ["skills", "agents", "commands"]`), cap each blurb
+  (`maxClauseChars`), add extra roots per kind, or turn off persistence (`"persist": false`)
+  and point the map file elsewhere (`mapFile`).
 
 ---
 
@@ -180,8 +203,17 @@ claude-gates init --no-install        # write the config but do not install the
 # Inspect the catalog:
 claude-gates registry --list          # list families and gates
 claude-gates registry --check         # validate registry.json
+
+# Verify the gates actually react (not just that they are wired):
+claude-gates smoke                    # feed each gate a known violation; exits non-zero if any does not block/warn
 ```
 
+`smoke` is the behavioral check `registry --check` (structure) and the doctor hook (files
+exist) do not do: it feeds every gate a known violation and confirms it really denies/warns.
+Gates whose violation needs seeded state (a db, a git repo, cross-call state) report `skip`,
+never a false pass. Run it after install, or in CI, to catch a gate that is wired but silently
+allows.
+
 ---
 
 ## Repository layout

package/cli/config.mjs

@@ -1,124 +1,126 @@
-// Where the selection is persisted and how it merges with what is already there.
-//
-// Scope "project": `<project root>/.ai/config.json` — the file the hooks read
-//   per project. Other keys the project already has (autoCommit, etc.) are kept.
-// Scope "global": `~/.claude/claude-gates/config.json` — the fallback the hooks
-//   use when a project has no answer of its own.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { findUpSync } from 'find-up';
-import {
-  CLAUDE_USER_DIRECTORY,
-  CONFIG_FILE,
-  GLOBAL_STATE_DIRECTORY,
-  HOME_DIRECTORY,
-  JSON_INDENT,
-  PROJECT_ROOT_MARKERS,
-  PROJECT_STATE_DIRECTORY,
-} from './constants.mjs';
-
-export const SCOPES = Object.freeze({ GLOBAL: 'global', PROJECT: 'project' });
-
-/**
- * Climbs from `startDirectory` to the nearest project marker (`.git`/`.ai`).
- * The home directory (and anything above it) is never a project root: a stray
- * `~/.ai` would otherwise turn every folder under home into "the project" and the
- * config would land in the wrong place silently. `.git` may be a file (worktrees),
- * so the matcher checks existence, not type.
- */
-export function findProjectRoot(
-  startDirectory,
-  { home = HOME_DIRECTORY } = {},
-) {
-  if (startDirectory === home) return startDirectory;
-  const markerDirectory = findUpSync(
-    (directory) => {
-      if (directory === home) return findUpSync.stop;
-      const hasMarker = PROJECT_ROOT_MARKERS.some((marker) =>
-        existsSync(join(directory, marker)),
-      );
-      return hasMarker ? directory : undefined;
-    },
-    { cwd: startDirectory, stopAt: home, type: 'directory' },
-  );
-  return markerDirectory ?? startDirectory;
-}
-
-export function configPathFor(
-  scope,
-  { cwd = process.cwd(), home = HOME_DIRECTORY } = {},
-) {
-  if (scope === SCOPES.GLOBAL)
-    return join(
-      home,
-      CLAUDE_USER_DIRECTORY,
-      GLOBAL_STATE_DIRECTORY,
-      CONFIG_FILE,
-    );
-  if (scope === SCOPES.PROJECT)
-    return join(
-      findProjectRoot(cwd, { home }),
-      PROJECT_STATE_DIRECTORY,
-      CONFIG_FILE,
-    );
-  throw new Error(`Unknown scope: ${scope}`);
-}
-
-// A leading UTF-8 BOM (EF BB BF, decoded as U+FEFF) is not stripped by readFileSync('utf8'),
-// and JSON.parse rejects a string that starts with it. Without stripping it, a config saved
-// by a BOM-adding editor or `PowerShell Set-Content -Encoding utf8` would read back as
-// `corrupt: true` — a valid, user-edited config (with its gate overrides) mistaken for
-// unreadable. init.mjs bails loudly on `corrupt`, but a caller relying on `data` alone (as
-// `mergeConfig` does) would otherwise merge onto `{}` and silently drop every existing gate
-// override the user made. This is the same failure mode fixed in the gates' own config.mjs.
-function stripBom(text) {
-  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-
-export function readConfig(path) {
-  if (!existsSync(path)) return { exists: false, data: {}, corrupt: false };
-  try {
-    return {
-      exists: true,
-      data: JSON.parse(stripBom(readFileSync(path, 'utf8'))),
-      corrupt: false,
-    };
-  } catch {
-    return { exists: true, data: {}, corrupt: true };
-  }
-}
-
-/**
- * Merges one gate's new value onto whatever the project already had, preserving the user's
- * edits. A gate with params arrives as `{ enabled, ...defaults }`; if the user already
- * tuned those params, their values win and only `enabled` follows the new selection. A
- * paramless gate is a plain boolean. This is what keeps a re-run of `init` additive: it
- * never overwrites a whitelist or pattern list the user changed by hand.
- */
-function mergeGate(existingValue, newValue) {
-  if (typeof newValue === 'boolean') return newValue;
-  if (existingValue && typeof existingValue === 'object') {
-    return { ...newValue, ...existingValue, enabled: newValue.enabled };
-  }
-  return newValue;
-}
-
-/**
- * Merges the new selection into an existing config without touching unrelated keys. Gates
- * are merged key by key: a gate absent from the new map keeps its old value (a registry
- * that dropped a gate must not silently flip it), and a gate the user configured keeps its
- * params (see mergeGate).
- */
-export function mergeConfig(existing, { adopted, gates, gateVersion }) {
-  const mergedGates = { ...(existing.gates ?? {}) };
-  for (const [key, value] of Object.entries(gates)) {
-    mergedGates[key] = mergeGate(mergedGates[key], value);
-  }
-  return { ...existing, adopted, gateVersion, gates: mergedGates };
-}
-
-export function writeConfig(path, data) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(data, null, JSON_INDENT)}\n`, 'utf8');
-}
+// Where the selection is persisted and how it merges with what is already there.
+//
+// Scope "project": `<project root>/.ai/config.json` — the file the hooks read
+//   per project. Other keys the project already has (autoCommit, etc.) are kept.
+// Scope "global": `~/.claude/claude-gates/config.json` — the fallback the hooks
+//   use when a project has no answer of its own.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { findUpSync } from 'find-up';
+import {
+  CLAUDE_USER_DIRECTORY,
+  CONFIG_FILE,
+  GLOBAL_STATE_DIRECTORY,
+  HOME_DIRECTORY,
+  JSON_INDENT,
+  PROJECT_ROOT_MARKERS,
+  PROJECT_STATE_DIRECTORY,
+} from './constants.mjs';
+
+export const SCOPES = Object.freeze({ GLOBAL: 'global', PROJECT: 'project' });
+
+/**
+ * Climbs from `startDirectory` to the nearest project marker (`.git`/`.ai`).
+ * The home directory (and anything above it) is never a project root: a stray
+ * `~/.ai` would otherwise turn every folder under home into "the project" and the
+ * config would land in the wrong place silently. `.git` may be a file (worktrees),
+ * so the matcher checks existence, not type.
+ */
+export function findProjectRoot(
+  startDirectory,
+  { home = HOME_DIRECTORY } = {},
+) {
+  if (startDirectory === home) return startDirectory;
+  const markerDirectory = findUpSync(
+    (directory) => {
+      if (directory === home) return findUpSync.stop;
+      const hasMarker = PROJECT_ROOT_MARKERS.some((marker) =>
+        existsSync(join(directory, marker)),
+      );
+      return hasMarker ? directory : undefined;
+    },
+    { cwd: startDirectory, stopAt: home, type: 'directory' },
+  );
+  return markerDirectory ?? startDirectory;
+}
+
+export function configPathFor(
+  scope,
+  { cwd = process.cwd(), home = HOME_DIRECTORY } = {},
+) {
+  if (scope === SCOPES.GLOBAL)
+    return join(
+      home,
+      CLAUDE_USER_DIRECTORY,
+      GLOBAL_STATE_DIRECTORY,
+      CONFIG_FILE,
+    );
+  if (scope === SCOPES.PROJECT)
+    return join(
+      findProjectRoot(cwd, { home }),
+      PROJECT_STATE_DIRECTORY,
+      CONFIG_FILE,
+    );
+  throw new Error(`Unknown scope: ${scope}`);
+}
+
+// A leading UTF-8 BOM (EF BB BF, decoded as U+FEFF) is not stripped by readFileSync('utf8'),
+// and JSON.parse rejects a string that starts with it. Without stripping it, a config saved
+// by a BOM-adding editor or `PowerShell Set-Content -Encoding utf8` would read back as
+// `corrupt: true` — a valid, user-edited config (with its gate overrides) mistaken for
+// unreadable. init.mjs bails loudly on `corrupt`, but a caller relying on `data` alone (as
+// `mergeConfig` does) would otherwise merge onto `{}` and silently drop every existing gate
+// override the user made. This is the same failure mode fixed in the gates' own config.mjs.
+const BOM_CODE_POINT = 0xfeff;
+
+function stripBom(text) {
+  return text.charCodeAt(0) === BOM_CODE_POINT ? text.slice(1) : text;
+}
+
+export function readConfig(path) {
+  if (!existsSync(path)) return { exists: false, data: {}, corrupt: false };
+  try {
+    return {
+      exists: true,
+      data: JSON.parse(stripBom(readFileSync(path, 'utf8'))),
+      corrupt: false,
+    };
+  } catch {
+    return { exists: true, data: {}, corrupt: true };
+  }
+}
+
+/**
+ * Merges one gate's new value onto whatever the project already had, preserving the user's
+ * edits. A gate with params arrives as `{ enabled, ...defaults }`; if the user already
+ * tuned those params, their values win and only `enabled` follows the new selection. A
+ * paramless gate is a plain boolean. This is what keeps a re-run of `init` additive: it
+ * never overwrites a whitelist or pattern list the user changed by hand.
+ */
+function mergeGate(existingValue, newValue) {
+  if (typeof newValue === 'boolean') return newValue;
+  if (existingValue && typeof existingValue === 'object') {
+    return { ...newValue, ...existingValue, enabled: newValue.enabled };
+  }
+  return newValue;
+}
+
+/**
+ * Merges the new selection into an existing config without touching unrelated keys. Gates
+ * are merged key by key: a gate absent from the new map keeps its old value (a registry
+ * that dropped a gate must not silently flip it), and a gate the user configured keeps its
+ * params (see mergeGate).
+ */
+export function mergeConfig(existing, { adopted, gates, gateVersion }) {
+  const mergedGates = { ...(existing.gates ?? {}) };
+  for (const [key, value] of Object.entries(gates)) {
+    mergedGates[key] = mergeGate(mergedGates[key], value);
+  }
+  return { ...existing, adopted, gateVersion, gates: mergedGates };
+}
+
+export function writeConfig(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, JSON_INDENT)}\n`, 'utf8');
+}