@devrik-tools/claude-gates 0.9.0 → 1.0.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 49 gates**; la configuración decide
+> **¿Por qué dos cosas?** El plugin **siempre trae los 50 gates**; la configuración decide
 > **cuáles se ejecutan**. Así puedes prender uno sin reinstalar: es una línea en un JSON.
 
 ---
@@ -67,7 +67,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 
 ---
 
-## Los gates (49, en 11 familias)
+## Los gates (50, en 11 familias)
 
 `[on]` = encendidos por defecto; `[off]` = los prendes si los quieres.
 
@@ -127,6 +127,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 |---|---|---|
 | `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. |
+| `skill-first` | off | Bloquea una escritura/comando/delegación que una **skill** disponible cubre de forma plausible hasta que la pregunta se haya hecho: cargar la skill, o decir por qué no aplica (`no skill covers this` / `using the <name> skill`). Lee el mismo catálogo que inyecta `capability-map`. |
 
 ### 🧠 Research flow — la memoria primero, nunca adivinar una librería
 
@@ -219,12 +220,15 @@ ves y editas cada perilla:
   deliberadamente amplio, no atómico), `comment-ok: <razón>` (un comentario explicativo que
   debe quedarse), `SEQUENTIAL-JUSTIFIED` (una delegación que sí depende de la anterior),
   `MONITOR-PLANNED:` (el comando en background declara cómo se va a monitorear).
-  `dependency-skills` se exime vía su lista `depsWithoutOwnApi`.
+  `dependency-skills` se exime vía su lista `depsWithoutOwnApi`. `skill-first` se despeja
+  con una frase en el contenido/prompt: `no skill covers this`, o `using the <name> skill`.
 - **Inyección de capacidades:** `capability-map` (on por defecto) es totalmente ajustable —
   elegí qué tipos exponer (`"kinds": ["skills", "agents", "commands"]`), limitá cada blurb
   (`maxClauseChars`, default 120), agregá raíces extra por tipo, regulá cada cuánto se
   re-inyecta el catálogo completo (`injectEveryMessages`, default 10 — el archivo persistido
-  se refresca igual en cada mensaje), o apagá la persistencia (`"persist": false`) y apuntá
+  se refresca igual en cada mensaje; el catálogo TAMBIÉN se re-inyecta a mitad del throttle
+  cuando cambia el tipo de trabajo del prompt, por ejemplo depurar → publicar, lo que podés
+  apagar con `"reinjectOnWorkNatureChange": false`), o apagá la persistencia (`"persist": false`) y apuntá
   el mapa a otro archivo (`mapFile`). Las skills también se escanean por defecto en
   `~/.agents/skills`, `<proyecto>/.agents/skills`, `~/.ai/skills` y `<proyecto>/.ai/skills`
   (raíces exclusivas de skills que usan otros instaladores además de `.claude/skills` — sin
@@ -294,6 +298,8 @@ 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 --new               # SOLO los gates sobre los que esta config nunca decidió:
+                                      # actualizás sin volver a contestar ni tocar lo ya definido
 claude-gates init --no-install        # escribe la configuración pero no instala el plugin
 claude-gates init --force             # aplica cambios a gates ya presentes sin preguntar
 
@@ -328,6 +334,35 @@ instalar, o en CI, para detectar un gate enganchado que en silencio deja pasar t
 
 ---
 
+## Artefactos generados
+
+Todo lo que un agente produce que **no es código fuente** — un chequeo determinista que
+escribió para que veas si algo funciona, una auditoría de lo que ya existe, una nota
+explicando qué hizo — tiene una sola forma y un solo lugar, así se encuentra por convención
+y se valida en CI en vez de caer donde al modelo se le ocurra.
+
+```bash
+claude-gates new check mi-afirmacion --title "..." --source "qué pidió esto"
+```
+
+| Tipo    | Vive en       | Para                                                                 |
+| ------- | ------------- | ---------------------------------------------------------------------- |
+| `check` | `.ai/checks/` | Una afirmación verificable: el comando, qué debe imprimir, y la evidencia que realmente imprimió. |
+| `audit` | `.ai/audits/` | Mirar antes de construir: buscado / existe / falta / decisión.       |
+| `note`  | `.ai/notes/`  | Razonamiento que si no quedaría solo en el chat.                     |
+
+Cuando la misma cosa sale mal dos veces, el registro es dato y no documento: se anota la
+**clase** de defecto en `.ai/reincidencias.json`, que `recurrence-lock` lee para bloquear
+trabajo mutante hasta que la clase se cierre de raíz.
+
+El contrato es `cli/artifacts.mjs`; las reglas completas están en
+[`.ai/README.md`](./.ai/README.md). Dos tests lo sostienen — uno cubre el módulo, el otro
+recorre el árbol `.ai/` real de este repo y falla ante cualquier artefacto desviado (sin
+front matter, en el directorio equivocado, sin una sección obligatoria, o un check marcado
+`passed` cuya evidencia sigue siendo el placeholder generado).
+
+---
+
 ## Estructura del repositorio
 
 ```

package/README.md

@@ -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 49 gates**; the config decides **which
+> **Why two things?** The plugin **always ships all 50 gates**; the config decides **which
 > ones run**. So you can turn one on without reinstalling — it is one line in a JSON file.
 
 ---
@@ -65,7 +65,7 @@ works even if you install one on its own.
 
 ---
 
-## The gates (49, in 11 families)
+## The gates (50, in 11 families)
 
 `[on]` = enabled by default; `[off]` = enable it if you want it.
 
@@ -130,6 +130,7 @@ works even if you install one on its own.
 | -------------------- | --- | ------------------------------------------------------------------------------------------------------------ |
 | `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.                              |
+| `skill-first`        | off | Blocks a write/command/delegation an available **skill** plausibly covers until the question was asked: load the skill, or say why it does not fit (`no skill covers this` / `using the <name> skill`). Reads the same catalog `capability-map` injects. |
 
 ### 🧠 Research flow — memory first, never guess a library
 
@@ -232,12 +233,15 @@ see and edit every knob:
   non-atomic commit), `comment-ok: <reason>` (one explanatory comment that must stay),
   `SEQUENTIAL-JUSTIFIED` (a delegation that genuinely depends on the previous one),
   `MONITOR-PLANNED:` (the background command declares how it will be monitored).
-  `dependency-skills` opts out via its `depsWithoutOwnApi` list.
+  `dependency-skills` opts out via its `depsWithoutOwnApi` list. `skill-first` clears on
+  one sentence in the content/prompt: `no skill covers this`, or `using the <name> skill`.
 - **Capability injection:** `capability-map` (on by default) is fully tunable — pick which
   kinds to surface (`"kinds": ["skills", "agents", "commands"]`), cap each blurb
   (`maxClauseChars`, default 120), add extra roots per kind, throttle how often the full
   catalog is re-injected (`injectEveryMessages`, default 10 — the persisted map file itself
-  still refreshes every message), or turn off persistence (`"persist": false`) and point the
+  still refreshes every message; the catalog is ALSO re-injected mid-throttle whenever the
+  prompt's kind of work changes, e.g. debugging → releasing, which you can turn off with
+  `"reinjectOnWorkNatureChange": false`), or turn off persistence (`"persist": false`) and point the
   map file elsewhere (`mapFile`). Skills are also scanned by default under `~/.agents/skills`,
   `<project>/.agents/skills`, `~/.ai/skills` and `<project>/.ai/skills` (skill-only roots some
   installers use besides `.claude/skills` — no config needed), in addition to any
@@ -252,6 +256,35 @@ see and edit every knob:
 
 ---
 
+## Generated artifacts
+
+Everything an agent produces that is **not source code** — a deterministic check it wrote
+so you can see whether something works, an audit of what already exists, a note explaining
+what it did — has one shape and one home, so it can be found by convention and validated
+in CI instead of landing wherever the model felt like.
+
+```bash
+claude-gates new check my-claim --title "..." --source "what asked for this"
+```
+
+| Kind    | Lives in      | For                                                              |
+| ------- | ------------- | ------------------------------------------------------------------ |
+| `check` | `.ai/checks/` | One verifiable claim: the command, what it must print, the evidence it actually printed. |
+| `audit` | `.ai/audits/` | Looking before building: searched / exists / missing / decision.  |
+| `note`  | `.ai/notes/`  | Reasoning that would otherwise live only in a chat log.           |
+
+When the same thing goes wrong twice, the record is data rather than a document: register
+the defect **class** in `.ai/reincidencias.json`, which `recurrence-lock` reads to block
+mutating work until the class is closed at the root.
+
+The contract is `cli/artifacts.mjs`; the full rules are in
+[`.ai/README.md`](./.ai/README.md). Two tests keep it honest — one covers the module, the
+other walks this repo's own `.ai/` tree and fails on any artifact that drifted (missing
+front matter, wrong directory, a missing section, or a check marked `passed` whose
+evidence is still the generated placeholder).
+
+---
+
 ## Decision log
 
 Every deny, warn and Stop-block is appended as one JSON line to
@@ -306,6 +339,8 @@ 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 --new               # ONLY gates this config never decided about — upgrade
+                                      # without re-answering or changing anything already set
 claude-gates init --no-install        # write the config but do not install the plugin
 claude-gates init --force             # apply changes to gates already in the file without asking
 

package/cli/artifacts.mjs

@@ -0,0 +1,213 @@
+// artifacts.mjs — the one definition of what a GENERATED artifact looks like and where it
+// goes. Everything an agent produces that is not source code lands in one of a few shapes:
+// a deterministic check it wrote so we can see whether something works, an audit result, a
+// note explaining what it did, or an entry in the recurrence registry when it tripped on
+// the same thing twice. Before this module each of those existed exactly once, in its own
+// ad-hoc shape and its own ad-hoc place — GATES.md at the repo root, `.ai/tasks/
+// .audit-reuse.md` hidden inside the task store, `impl.md` buried under a feature's task
+// directory — so nothing could be found by convention and nothing could be checked.
+//
+// The module is deliberately shaped like registry.mjs, the pattern this repo already uses
+// for "declare it once, validate it with zod": the KINDS table below is the contract, the
+// generator renders from it, and the conformance test validates against it. A new required
+// section is added in one place and both halves follow.
+//
+// Front matter is the machine-readable half and is identical across kinds, so a tool can
+// answer "what is this file, who asked for it, is it still open" without parsing prose.
+// The required SECTIONS are the human half, and they differ per kind because what makes a
+// check trustworthy (a command, an expectation, the evidence it actually produced) is not
+// what makes an audit trustworthy (what was searched, what exists, what was decided).
+
+import { z } from 'zod';
+import {
+  ARTIFACT_DIRECTORIES,
+  ARTIFACT_EXTENSION,
+  PROJECT_STATE_DIRECTORY,
+} from './constants.mjs';
+
+const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Statuses an artifact can carry. `open` is the only one a generator ever writes. */
+export const ARTIFACT_STATUSES = ['open', 'passed', 'failed', 'closed'];
+
+/**
+ * The contract, per kind. `sections` are the level-2 headings the body must contain, in
+ * any order; `summary` is what the kind is for, shown by `new --help` and in the docs.
+ */
+export const KINDS = Object.freeze({
+  check: {
+    directory: ARTIFACT_DIRECTORIES.check,
+    summary:
+      'A deterministic verification: the command to run, what it must print, and the ' +
+      'evidence it actually printed. Written so a claim can be re-checked by anyone.',
+    sections: ['Check', 'Expect', 'Evidence'],
+  },
+  audit: {
+    directory: ARTIFACT_DIRECTORIES.audit,
+    summary:
+      'The result of looking before building: what was searched, what already exists, ' +
+      'what is genuinely missing, and the decision that followed.',
+    sections: ['Searched', 'Exists', 'Missing', 'Decision'],
+  },
+  note: {
+    directory: ARTIFACT_DIRECTORIES.note,
+    summary:
+      'What was done and why, for work whose reasoning would otherwise live only in a ' +
+      'chat log: the situation, what changed, and what it cost or left open.',
+    sections: ['Context', 'Change', 'Outcome'],
+  },
+});
+
+export const ARTIFACT_KINDS = Object.keys(KINDS);
+
+export const frontMatterSchema = z.object({
+  kind: z.enum(ARTIFACT_KINDS),
+  slug: z.string().regex(SLUG_PATTERN, 'slug must be kebab-case'),
+  title: z.string().min(1, 'title must not be empty'),
+  created: z.string().regex(ISO_DATE_PATTERN, 'created must be YYYY-MM-DD'),
+  status: z.enum(ARTIFACT_STATUSES),
+  source: z.string().min(1, 'source must say what asked for this artifact'),
+});
+
+// The recurrence registry is not a document but a record, so it is a JSON schema rather
+// than front matter. The shape is READ FROM the recurrence-lock gate, not invented here:
+// the gate counts `classes[].occurrences[]` and reopens on anything whose `status` is not
+// closed, so those three fields are what a generated entry must carry.
+export const recurrenceSchema = z.object({
+  class: z.string().min(1, 'class names the defect class, not one instance'),
+  occurrences: z
+    .array(z.object({ id: z.string().min(1), note: z.string().optional() }))
+    .min(1),
+  status: z.enum(['open', 'closed', 'cerrada']),
+  block: z
+    .string()
+    .min(1, 'block names the deterministic guard that closes the class')
+    .optional(),
+});
+
+export const recurrenceRegistrySchema = z.object({
+  classes: z.array(recurrenceSchema),
+});
+
+/** Where an artifact of this kind and slug belongs, relative to the project root. */
+export function artifactPathFor(kind, slug) {
+  const definition = KINDS[kind];
+  if (!definition) throw new Error(`unknown artifact kind: ${kind}`);
+  if (!SLUG_PATTERN.test(slug))
+    throw new Error(`slug must be kebab-case: ${slug}`);
+  return [
+    PROJECT_STATE_DIRECTORY,
+    definition.directory,
+    `${slug}${ARTIFACT_EXTENSION}`,
+  ].join('/');
+}
+
+// ── Parsing ─────────────────────────────────────────────────────────────────────────
+// Line by line, no multi-line regex, so a long body can never backtrack — the same
+// approach lib/capabilities.mjs uses on skill front matter.
+function splitFrontMatter(text) {
+  const lines = String(text ?? '').split(/\r?\n/);
+  if (lines[0]?.trim() !== '---') return { fields: null, body: text ?? '' };
+  const fields = {};
+  let index = 1;
+  for (; index < lines.length; index += 1) {
+    if (lines[index].trim() === '---') break;
+    const separator = lines[index].indexOf(':');
+    if (separator < 0) continue;
+    const key = lines[index].slice(0, separator).trim();
+    fields[key] = lines[index]
+      .slice(separator + 1)
+      .trim()
+      .replace(/^["']|["']$/g, '');
+  }
+  return { fields, body: lines.slice(index + 1).join('\n') };
+}
+
+const SECTION_PREFIX = '## ';
+
+function headingsIn(body) {
+  return body
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith(SECTION_PREFIX))
+    .map((line) => line.slice(SECTION_PREFIX.length).trim());
+}
+
+/**
+ * Every way an artifact file breaks the contract, as human-readable strings. Empty means
+ * it conforms. Returning a list (never throwing) is what lets the conformance test report
+ * every drifted file in one run instead of stopping at the first.
+ */
+export function artifactProblems(text, { kind, slug } = {}) {
+  const { fields, body } = splitFrontMatter(text);
+  if (fields === null)
+    return ['missing front matter (the file must open with `---`)'];
+
+  const parsed = frontMatterSchema.safeParse(fields);
+  const problems = parsed.success
+    ? []
+    : parsed.error.issues.map(
+        (issue) =>
+          `front matter ${issue.path.join('.') || '(root)'}: ${issue.message}`,
+      );
+
+  if (kind && fields.kind !== kind)
+    problems.push(
+      `kind is "${fields.kind}" but the file sits in the ${kind} directory`,
+    );
+  if (slug && fields.slug !== slug)
+    problems.push(`slug is "${fields.slug}" but the file is named "${slug}"`);
+
+  const definition = KINDS[fields.kind];
+  if (definition) {
+    const present = new Set(headingsIn(body));
+    const missing = definition.sections.filter(
+      (section) => !present.has(section),
+    );
+    if (missing.length > 0)
+      problems.push(`missing required section(s): ${missing.join(', ')}`);
+  }
+  return problems;
+}
+
+// ── Generation ──────────────────────────────────────────────────────────────────────
+const PLACEHOLDERS = {
+  Check: 'The exact command, copy-pasteable, that decides this.',
+  Expect:
+    'What that command must print or exit with for this to count as passing.',
+  Evidence:
+    'What it ACTUALLY printed when run. Never fill this in before running it.',
+  Searched:
+    'Where you looked: this repo, installed deps, the registry, the web.',
+  Exists: 'What you found that already covers part of this.',
+  Missing:
+    'What genuinely does not exist yet, and is therefore worth building.',
+  Decision: 'What was decided and why, in one or two sentences.',
+  Context: 'The situation this work started from.',
+  Change: 'What actually changed, concretely.',
+  Outcome: 'The result, including what it cost or left open.',
+};
+
+function todayIso(now = new Date()) {
+  return now.toISOString().slice(0, 'YYYY-MM-DD'.length);
+}
+
+/** The skeleton for a new artifact: valid front matter plus every required section. */
+export function renderArtifact({ kind, slug, title, source, now }) {
+  const definition = KINDS[kind];
+  if (!definition) throw new Error(`unknown artifact kind: ${kind}`);
+  const frontMatter = [
+    '---',
+    `kind: ${kind}`,
+    `slug: ${slug}`,
+    `title: ${title}`,
+    `created: ${todayIso(now)}`,
+    'status: open',
+    `source: ${source}`,
+    '---',
+  ];
+  const sections = definition.sections.map(
+    (section) => `## ${section}\n\n${PLACEHOLDERS[section] ?? 'TODO'}\n`,
+  );
+  return `${frontMatter.join('\n')}\n\n# ${title}\n\n${sections.join('\n')}`;
+}

package/cli/constants.mjs

@@ -23,6 +23,20 @@ export const CONFIG_FILE = 'config.json';
 /** Markers that identify a project root while climbing from the cwd. */
 export const PROJECT_ROOT_MARKERS = ['.git', PROJECT_STATE_DIRECTORY];
 
+/**
+ * Where each kind of GENERATED artifact lives, relative to the project's `.ai/` root.
+ * Declared here (not inside artifacts.mjs) for the same reason every other path is: one
+ * place to read, one place to change. These four directories are the whole answer to
+ * "where does this go" — an artifact that fits no kind does not get invented a home.
+ */
+export const ARTIFACT_DIRECTORIES = Object.freeze({
+  check: 'checks',
+  audit: 'audits',
+  note: 'notes',
+});
+export const RECURRENCES_FILE = 'reincidencias.json';
+export const ARTIFACT_EXTENSION = '.md';
+
 /** Global-scope config lives under Claude Code's own user directory. */
 export const CLAUDE_USER_DIRECTORY = '.claude';
 export const GLOBAL_STATE_DIRECTORY = 'claude-gates';

package/cli/doctor.mjs

@@ -53,7 +53,8 @@ function withoutTrailingSlashes(text) {
   return text.slice(0, end).toLowerCase();
 }
 
-function compareVersions(a, b) {
+/** Semver-ish numeric compare, shared with install.mjs so both judge staleness alike. */
+export function compareVersions(a, b) {
   const left = String(a).split('.').map(Number);
   const right = String(b).split('.').map(Number);
   for (let index = 0; index < Math.max(left.length, right.length); index += 1) {

package/cli/index.mjs

@@ -2,10 +2,17 @@
 // Entry point (commander). Commands:
 //   init      interactive (or flag-driven) selection of gates, per project or globally
 //   registry  --check validates registry.json; --list prints the catalog
+//   new       scaffold a generated artifact (check/audit/note) in the standard shape
 
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { Command } from 'commander';
+import {
+  ARTIFACT_KINDS,
+  KINDS,
+  artifactPathFor,
+  renderArtifact,
+} from './artifacts.mjs';
 import { SCOPES, configPathFor } from './config.mjs';
 import {
   EXIT_CODE,
@@ -174,6 +181,10 @@ program
   .option('--defaults', 'enable the recommended defaults')
   .option('--all', 'enable every gate')
   .option('--none', "record a 'no' so you are not asked again")
+  .option(
+    '--new',
+    'only gates this config has never decided about; nothing already in the file is shown, asked about or changed',
+  )
   .option(
     '--families <ids>',
     'enable whole families, comma-separated',
@@ -267,6 +278,47 @@ program
   )
   .action(() => smokeGates());
 
+// Width the kind name is padded to in `new --help`, so the summaries line up.
+const ARTIFACT_KIND_COLUMN_WIDTH = 6;
+
+function kindHelp() {
+  return ARTIFACT_KINDS.map(
+    (kind) =>
+      `  ${kind.padEnd(ARTIFACT_KIND_COLUMN_WIDTH)} ${KINDS[kind].summary}`,
+  ).join('\n');
+}
+
+function newArtifact(kind, slug, options) {
+  if (!ARTIFACT_KINDS.includes(kind))
+    return fail(`unknown kind "${kind}". Known kinds:\n${kindHelp()}`);
+  const title = options.title ?? slug.replaceAll('-', ' ');
+  const source = options.source ?? 'unspecified';
+
+  let relativePath;
+  try {
+    relativePath = artifactPathFor(kind, slug);
+  } catch (error) {
+    return fail(error.message);
+  }
+  const path = join(process.cwd(), relativePath);
+  if (existsSync(path) && !options.force)
+    return fail(`${relativePath} already exists. Pass --force to overwrite.`);
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, renderArtifact({ kind, slug, title, source }), 'utf8');
+  process.stdout.write(`Wrote ${relativePath}\n`);
+}
+
+program
+  .command('new <kind> <slug>')
+  .description(
+    `Create a generated artifact with the standard shape. Kinds:\n${kindHelp()}`,
+  )
+  .option('--title <text>', 'one-line title (default: the slug, spaced)')
+  .option('--source <text>', 'what asked for this artifact')
+  .option('--force', 'overwrite an existing file')
+  .action((kind, slug, options) => newArtifact(kind, slug, options));
+
 registerTaskCommand(program);
 
 program.parseAsync(process.argv).catch((error) => fail(error.message));

package/cli/init.mjs

@@ -19,6 +19,7 @@ import {
 import { loadRegistry, allGates } from './registry.mjs';
 import {
   MODES,
+  newGatesFor,
   resolveSelection,
   adoptionOf,
   namedGatesFor,
@@ -32,6 +33,11 @@ const MODE_OPTIONS = [
     hint: 'gates marked default in the registry',
   },
   { value: MODES.ALL, label: 'Everything', hint: 'every gate in every family' },
+  {
+    value: MODES.NEW,
+    label: 'Only what is new',
+    hint: 'lists just the gates this config has never decided about',
+  },
   { value: MODES.FAMILIES, label: 'By family', hint: 'pick whole families' },
   { value: MODES.GRANULAR, label: 'Granular', hint: 'pick individual gates' },
   {
@@ -46,6 +52,7 @@ const MODE_BY_OPTION = {
   defaults: MODES.DEFAULTS,
   all: MODES.ALL,
   none: MODES.NONE,
+  new: MODES.NEW,
   families: MODES.FAMILIES,
   gates: MODES.GRANULAR,
 };
@@ -153,21 +160,89 @@ async function askGates(registry) {
   );
 }
 
+/**
+ * The "only what is new" prompt: the same grouped picker as `askGates`, but built from
+ * `newGatesFor` so nothing already decided in this config is even shown — the point is to
+ * adopt what a release added without re-answering, or accidentally flipping, the rest.
+ * Everything starts checked when it is a recommended default, matching the other pickers.
+ */
+async function askNewGates(io, registry, existingGates) {
+  const fresh = newGatesFor(registry, existingGates);
+  if (fresh.length === 0) return { picks: [], none: true };
+
+  const options = {};
+  for (const gate of fresh) {
+    const family = registry.families.find((entry) => entry.id === gate.family);
+    const label = family?.name ?? gate.family;
+    options[label] ??= [];
+    options[label].push({
+      value: gate.id,
+      label: gate.id,
+      hint: gate.description,
+    });
+  }
+  const picks = bail(
+    await io.groupMultiselect({
+      message: `${fresh.length} gate(s) this config has never decided about (space to toggle, enter to confirm)`,
+      options,
+      initialValues: fresh
+        .filter((gate) => gate.default)
+        .map((gate) => gate.id),
+      required: false,
+    }),
+  );
+  return { picks, none: false };
+}
+
 /** `claude plugin install <plugin>@<marketplace>`, read from the marketplace manifest, never hard-coded. */
 
 /** Fills in whatever the flags left undecided, asking only when there is a TTY. */
-async function decide(flags, registry, cwd, interactive) {
+/**
+ * Fills `picks.gates` for the "only what is new" mode. Needs the config that is about to be
+ * written, so it is resolved here rather than in the generic prompt step: the list of new
+ * gates is a function of what that file already decided. Scripted runs (`--new --yes`) take
+ * the new gates that are recommended defaults — "adopt what the release added" is the only
+ * sensible unattended reading of the mode.
+ */
+async function decideNewPicks(io, registry, path, interactive) {
+  const existingGates = readConfig(path).data.gates ?? {};
+  if (!interactive)
+    return {
+      picks: newGatesFor(registry, existingGates)
+        .filter((gate) => gate.default)
+        .map((gate) => gate.id),
+      none: newGatesFor(registry, existingGates).length === 0,
+    };
+  return askNewGates(io, registry, existingGates);
+}
+
+/** Fills the picks the FAMILIES/GRANULAR modes need, when a flag did not already supply them. */
+async function askPicksFor(mode, registry, picks, interactive) {
+  if (!interactive) return;
+  if (mode === MODES.FAMILIES && picks.families.length === 0)
+    picks.families = await askFamilies(registry);
+  if (mode === MODES.GRANULAR && picks.gates.length === 0)
+    picks.gates = await askGates(registry);
+}
+
+async function decide(flags, registry, cwd, interactive, io) {
   const scope =
     flags.scope ?? (interactive ? await askScope(cwd) : SCOPES.PROJECT);
   const mode = flags.mode ?? (interactive ? await askMode() : MODES.DEFAULTS);
   const picks = { families: flags.families, gates: flags.gates };
-  if (interactive && mode === MODES.FAMILIES && picks.families.length === 0) {
-    picks.families = await askFamilies(registry);
-  }
-  if (interactive && mode === MODES.GRANULAR && picks.gates.length === 0) {
-    picks.gates = await askGates(registry);
-  }
-  return { scope, mode, picks };
+  await askPicksFor(mode, registry, picks, interactive);
+
+  if (mode !== MODES.NEW || picks.gates.length > 0)
+    return { scope, mode, picks, nothingNew: false };
+
+  const fresh = await decideNewPicks(
+    io,
+    registry,
+    configPathFor(scope, { cwd }),
+    interactive,
+  );
+  picks.gates = fresh.picks;
+  return { scope, mode, picks, nothingNew: fresh.none };
 }
 
 function renderSummary(registry, gatesMap) {
@@ -330,12 +405,23 @@ export async function runInit(
 
   if (interactive) io.intro('claude-gates');
 
-  const { scope, mode, picks } = await decide(
+  const { scope, mode, picks, nothingNew } = await decide(
     flags,
     registry,
     cwd,
     interactive,
+    io,
   );
+  if (nothingNew) {
+    io.outro(
+      'Nothing new: this config already decides about every gate in the registry.',
+    );
+    return {
+      path: configPathFor(scope, { cwd }),
+      config: null,
+      written: false,
+    };
+  }
   const gates = resolveSelection(registry, mode, picks);
   const path = configPathFor(scope, { cwd });
   const existing = readConfig(path);