@dsalazardev/ai-hub-cli 0.1.0 → 0.2.0

package/dist/manifest/manifest.d.ts

@@ -1,6 +1,7 @@
 import { ENGINE_COUNTS, type EngineManifest } from '../engine/engine.js';
 import { type ResolvedPreset } from '../presets/resolve.js';
 import type { PresetDangerPattern } from '../presets/schema.js';
+import type { SelectionMode } from '../catalog.js';
 export declare const MANIFEST_FILE = "manifest.yaml";
 export declare const INVENTORY_RELATIVE = "core/manifest.json";
 export { ENGINE_COUNTS };
@@ -38,14 +39,21 @@ export interface ProjectManifest {
     skills: {
         source: string;
         publish: string[];
+        selection?: SelectionMode;
     };
     agents: {
         source: string;
         publish: string[];
+        selection?: SelectionMode;
     };
     rules: {
         source: string;
         publish: string[];
+        selection?: SelectionMode;
+    };
+    catalog?: {
+        version: string;
+        hash: string;
     };
     mcp?: {
         source: string;
@@ -90,6 +98,15 @@ export interface ManifestInventory {
     }>;
     labels: string[];
     targets: string[];
+    selection?: {
+        skills: SelectionMode;
+        agents: SelectionMode;
+        rules: SelectionMode;
+    };
+    catalog?: {
+        version: string;
+        hash: string;
+    } | null;
     agents: string[];
     skills: string[];
     rules: string[];

package/dist/manifest/manifest.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { PACKAGE_NAME } from '../package-info.js';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -148,7 +149,12 @@ export async function validateManifestData(data, root = process.cwd()) {
     return { manifest, engine, preset };
 }
 export function inventoryPath(root) {
-    return path.join(root, INVENTORY_RELATIVE);
+    // En el checkout del motor el inventario vive en core/ porque ese es el paquete que se publica.
+    // En un proyecto consumidor pertenece a .ai-hub/, junto al arnes instalado.
+    const engineMarker = path.join(root, 'core', 'src', 'paths.ts');
+    return existsSync(engineMarker)
+        ? path.join(root, INVENTORY_RELATIVE)
+        : path.join(root, '.ai-hub', 'manifest.json');
 }
 export function buildInventory(manifest, engine) {
     const roles = engine.roles.map((role) => role.id).sort();
@@ -169,6 +175,18 @@ export function buildInventory(manifest, engine) {
         commands,
         labels,
         targets: [...manifest.targets].sort(),
+        ...(manifest.skills.selection !== undefined ||
+            manifest.agents.selection !== undefined ||
+            manifest.rules.selection !== undefined
+            ? {
+                selection: {
+                    skills: manifest.skills.selection ?? 'preset',
+                    agents: manifest.agents.selection ?? 'preset',
+                    rules: manifest.rules.selection ?? 'preset',
+                },
+            }
+            : {}),
+        ...(manifest.catalog !== undefined ? { catalog: manifest.catalog } : {}),
         agents,
         skills,
         rules,

package/dist/presets/materialize.d.ts

@@ -15,4 +15,12 @@ export interface MaterializeResult {
     collisions: string[];
 }
 export declare function readScaffold(root: string): Promise<ScaffoldRecord>;
-export declare function materializePreset(root: string, preset: ResolvedPreset): Promise<MaterializeResult>;
+export declare function materializePreset(root: string, preset: ResolvedPreset, selectedRules?: string[]): Promise<MaterializeResult>;
+/** Copia una skill del catálogo o del preset a `.ai-hub/skills/<id>`. */
+export declare function materializeSkill(root: string, id: string, sourceDir?: string, sourceKey?: string): Promise<MaterializeResult>;
+/** Copia un agente del catálogo o del preset a `.ai-hub/agents/<id>.md`. */
+export declare function materializeAgent(root: string, id: string, sourceFile?: string, sourceKey?: string): Promise<MaterializeResult>;
+/** Copia las 4 rúbricas universales desde el paquete a `.ai-hub/rules/skill-quality/`. */
+export declare function materializeUniversalRules(root: string, preset: ResolvedPreset, selectedRules?: string[]): Promise<MaterializeResult>;
+/** Copia skills y agentes seleccionados del catálogo. */
+export declare function materializeCatalog(root: string, skillIds: string[], agentIds: string[]): Promise<MaterializeResult>;

package/dist/presets/materialize.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { mapLimit } from '../concurrency.js';
+import { ENGINE_SKILLS_DIR } from '../engine/engine.js';
+import { ENGINE_AGENTS_DIR, ENGINE_RULES_DIR, RUBRIC_RULE_IDS, normalizeRuleId, } from '../catalog.js';
 import { sha256 } from '../sync/lock.js';
 import { findPresetAsset } from './resolve.js';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export const ENGINE_AGENTS = path.join(__dirname, '..', '..', 'agents');
+export const ENGINE_AGENTS = ENGINE_AGENTS_DIR;
 export const SCAFFOLD_RELATIVE = '.ai-hub/.scaffold.json';
 async function exists(file) {
     return fs.access(file).then(() => true, () => false);
@@ -38,10 +39,11 @@ export async function readScaffold(root) {
 }
 async function writeScaffold(root, record) {
     const file = path.join(root, SCAFFOLD_RELATIVE);
+    const files = Object.fromEntries(Object.entries(record.files).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
     await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.writeFile(file, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    await fs.writeFile(file, `${JSON.stringify({ version: 1, files }, null, 2)}\n`, 'utf8');
 }
-async function copyOnce(root, source, destination, record, result) {
+async function copyOnce(root, source, destination, record, result, sourceKey = source) {
     const content = await fs.readFile(source, 'utf8');
     const hash = sha256(content);
     const abs = path.join(root, destination);
@@ -49,6 +51,7 @@ async function copyOnce(root, source, destination, record, result) {
         const previous = record.files[destination];
         const current = sha256(await fs.readFile(abs, 'utf8').catch(() => ''));
         if (previous && previous.sha256 === current) {
+            previous.source = sourceKey;
             result.kept.push(destination);
             return;
         }
@@ -57,18 +60,22 @@ async function copyOnce(root, source, destination, record, result) {
     }
     await fs.mkdir(path.dirname(abs), { recursive: true });
     await fs.writeFile(abs, content, 'utf8');
-    record.files[destination] = { sha256: hash, source };
+    record.files[destination] = { sha256: hash, source: sourceKey };
     result.written.push(destination);
 }
-export async function materializePreset(root, preset) {
+export async function materializePreset(root, preset, selectedRules) {
     const result = { written: [], kept: [], collisions: [] };
     const record = await readScaffold(root);
+    const wantedRules = selectedRules === undefined ? null : new Set(selectedRules);
     for (const rule of preset.rules) {
+        if (wantedRules !== null && !wantedRules.has(normalizeRuleId(rule))) {
+            continue;
+        }
         const source = await findPresetAsset(preset.chain, rule);
         if (source === null) {
             throw new Error(`el preset "${preset.id}" declara la regla "${rule}" pero no existe`);
         }
-        await copyOnce(root, source, `.ai-hub/rules/${path.basename(rule)}`, record, result);
+        await copyOnce(root, source, `.ai-hub/rules/${normalizeRuleId(rule)}.md`, record, result, `@preset/${preset.id}/${rule.replace(/\\/g, '/')}`);
     }
     for (const agent of preset.agents) {
         const fromPreset = await findPresetAsset(preset.chain, `agents/${agent}.md`);
@@ -76,13 +83,13 @@ export async function materializePreset(root, preset) {
         if (!(await exists(source))) {
             throw new Error(`el agente "${agent}" no existe ni en el preset ni en el motor`);
         }
-        await copyOnce(root, source, `.ai-hub/agents/${agent}.md`, record, result);
+        await copyOnce(root, source, `.ai-hub/agents/${agent}.md`, record, result, fromPreset ? `@preset/${preset.id}/agents/${agent}.md` : `@engine/agents/${agent}.md`);
     }
     const harness = await findPresetAsset(preset.chain, 'harness');
     if (harness !== null) {
         for (const source of await walk(harness)) {
             const relative = path.relative(harness, source).split(path.sep).join('/');
-            await copyOnce(root, source, `.ai-hub/harness/${relative}`, record, result);
+            await copyOnce(root, source, `.ai-hub/harness/${relative}`, record, result, `@preset/${preset.id}/harness/${relative}`);
         }
     }
     for (const skill of preset.skills) {
@@ -93,9 +100,93 @@ export async function materializePreset(root, preset) {
         const files = await walk(dir);
         for (const source of files) {
             const relative = path.relative(dir, source).split(path.sep).join('/');
-            await copyOnce(root, source, `.ai-hub/skills/${skill}/${relative}`, record, result);
+            await copyOnce(root, source, `.ai-hub/skills/${skill}/${relative}`, record, result, `@preset/${preset.id}/skills/${skill}/${relative}`);
+        }
+    }
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia una skill del catálogo o del preset a `.ai-hub/skills/<id>`. */
+export async function materializeSkill(root, id, sourceDir = path.join(ENGINE_SKILLS_DIR, id), sourceKey = `@engine/skills/shared/${id}`) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    if (!(await exists(sourceDir))) {
+        throw new Error(`la skill "${id}" no existe en ${sourceDir}`);
+    }
+    for (const source of await walk(sourceDir)) {
+        const relative = path.relative(sourceDir, source).split(path.sep).join('/');
+        await copyOnce(root, source, `.ai-hub/skills/${id}/${relative}`, record, result, `${sourceKey}/${relative}`);
+    }
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia un agente del catálogo o del preset a `.ai-hub/agents/<id>.md`. */
+export async function materializeAgent(root, id, sourceFile = path.join(ENGINE_AGENTS, `${id}.md`), sourceKey = `@engine/agents/${id}.md`) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    if (!(await exists(sourceFile))) {
+        throw new Error(`el agente "${id}" no existe en ${sourceFile}`);
+    }
+    await copyOnce(root, sourceFile, `.ai-hub/agents/${id}.md`, record, result, sourceKey);
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia las 4 rúbricas universales desde el paquete a `.ai-hub/rules/skill-quality/`. */
+export async function materializeUniversalRules(root, preset, selectedRules = [...RUBRIC_RULE_IDS]) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    const core = await findPresetAsset(preset.chain, 'rules/core.md');
+    if (core === null) {
+        throw new Error(`el preset "${preset.id}" no declara rules/core.md`);
+    }
+    await copyOnce(root, core, '.ai-hub/rules/core.md', record, result, `@preset/${preset.id}/rules/core.md`);
+    const wanted = new Set(selectedRules.filter((id) => id.startsWith('skill-quality/')));
+    for (const id of RUBRIC_RULE_IDS) {
+        if (!wanted.has(id)) {
+            continue;
+        }
+        const source = path.join(ENGINE_RULES_DIR, `${id}.md`);
+        if (!(await exists(source))) {
+            throw new Error(`falta la rúbrica universal "${id}" en ${ENGINE_RULES_DIR}`);
+        }
+        await copyOnce(root, source, `.ai-hub/rules/${id}.md`, record, result, `@engine/rules/${id}.md`);
+    }
+    await writeScaffold(root, record);
+    return result;
+}
+/** Copia skills y agentes seleccionados del catálogo. */
+export async function materializeCatalog(root, skillIds, agentIds) {
+    const result = { written: [], kept: [], collisions: [] };
+    const record = await readScaffold(root);
+    const copies = [];
+    for (const id of [...skillIds].sort()) {
+        const sourceDir = path.join(ENGINE_SKILLS_DIR, id);
+        if (!(await exists(sourceDir))) {
+            throw new Error(`la skill de catálogo "${id}" no existe en ${ENGINE_SKILLS_DIR}`);
+        }
+        for (const source of await walk(sourceDir)) {
+            const relative = path.relative(sourceDir, source).split(path.sep).join('/');
+            copies.push({
+                source,
+                destination: `.ai-hub/skills/${id}/${relative}`,
+                sourceKey: `@engine/skills/shared/${id}/${relative}`,
+            });
+        }
+    }
+    for (const id of [...agentIds].sort()) {
+        const source = path.join(ENGINE_AGENTS, `${id}.md`);
+        if (!(await exists(source))) {
+            throw new Error(`el agente de catálogo "${id}" no existe en ${ENGINE_AGENTS}`);
         }
+        copies.push({
+            source,
+            destination: `.ai-hub/agents/${id}.md`,
+            sourceKey: `@engine/agents/${id}.md`,
+        });
     }
+    await mapLimit(copies, 24, async (copy) => {
+        await copyOnce(root, copy.source, copy.destination, record, result, copy.sourceKey);
+    });
     await writeScaffold(root, record);
     return result;
 }

package/dist/sync/render.js

@@ -164,7 +164,11 @@ async function renderRules(root, config, out) {
         const isCore = area === 'core';
         for (const [tool, target] of Object.entries(config.rules.targets)) {
             if (target.shape === 'mdc') {
-                putRendered(out, `${target.path}/${area}.mdc`, {
+                const preferred = `${target.path}/${area}.mdc`;
+                const destination = out.has(preferred)
+                    ? `${target.path}/rule-${area}.mdc`
+                    : preferred;
+                putRendered(out, destination, {
                     content: withMarker(frontmatter({
                         description: isCore ? 'Core project rules' : `Rules for ${area}`,
                         globs: isCore ? '**' : `${area}/**`,

package/dist/sync/sync.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { mapLimit } from '../concurrency.js';
 import { isEngineCheckout } from '../source-checkout.js';
 import { loadSyncConfig, resolveSourcePath } from './config.js';
 import { normalize, renderAll } from './render.js';
@@ -54,16 +55,17 @@ export async function runSync(root, options) {
         await fs.rm(path.join(root, rel), { force: true });
         result.removed.push(rel);
     }
-    for (const [rel, file] of sortedEntries(rendered)) {
+    const written = await mapLimit(sortedEntries(rendered), 24, async ([rel, file]) => {
         const abs = path.join(root, rel);
         const current = await readCopy(abs);
         if (current === file.content) {
-            continue;
+            return null;
         }
         await fs.mkdir(path.dirname(abs), { recursive: true });
         await fs.writeFile(abs, file.content, 'utf8');
-        result.written.push(rel);
-    }
+        return rel;
+    });
+    result.written.push(...written.filter((rel) => rel !== null));
     await writeLock(root, nextLock);
     return result;
 }
@@ -73,26 +75,24 @@ function sourceDescription(source) {
         : `fuente: ${source}`;
 }
 async function checkCopies(root, rendered, previous) {
-    const problems = [];
-    for (const [rel, file] of sortedEntries(rendered)) {
+    const problems = await mapLimit(sortedEntries(rendered), 24, async ([rel, file]) => {
         const current = await readCopy(path.join(root, rel));
         if (current === null) {
-            problems.push(`falta ${rel} (${sourceDescription(file.source)})`);
+            return `falta ${rel} (${sourceDescription(file.source)})`;
         }
-        else if (current !== file.content) {
-            const registered = previous?.files[rel];
-            if (registered && sha256(current) !== registered.sha256) {
-                const hint = file.source.startsWith('@engine/')
-                    ? 'viene del motor; actualiza el paquete'
-                    : `edita la fuente: ${file.source}`;
-                problems.push(`editado a mano: ${rel} (${hint}; luego ejecuta ai-hub sync)`);
-            }
-            else {
-                problems.push(`desactualizado: ${rel} (${sourceDescription(file.source)})`);
-            }
+        if (current === file.content) {
+            return null;
         }
-    }
-    return problems;
+        const registered = previous?.files[rel];
+        if (registered && sha256(current) !== registered.sha256) {
+            const hint = file.source.startsWith('@engine/')
+                ? 'viene del motor; actualiza el paquete'
+                : `edita la fuente: ${file.source}`;
+            return `editado a mano: ${rel} (${hint}; luego ejecuta ai-hub sync)`;
+        }
+        return `desactualizado: ${rel} (${sourceDescription(file.source)})`;
+    });
+    return problems.filter((problem) => problem !== null);
 }
 export async function buildLock(root, rendered) {
     const sources = {};

package/manifest.json

@@ -144,6 +144,15 @@
     "opencode",
     "pi"
   ],
+  "selection": {
+    "skills": "full",
+    "agents": "full",
+    "rules": "custom"
+  },
+  "catalog": {
+    "version": "0.2.0",
+    "hash": "f30e2590a4eb078ea520873661b5f10fb3cf9171d1422438c35aafd722abbb23"
+  },
   "agents": [
     "cpp-build-resolver",
     "cpp-reviewer",
@@ -375,7 +384,7 @@
     "worktrees"
   ],
   "rules": [
-    "core",
+    "engine-core",
     "skill-quality/skill-behavior-rubric",
     "skill-quality/skill-harden-rubric",
     "skill-quality/skill-migration-brief",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsalazardev/ai-hub-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": "Daner Alejandro Salazar Colorado",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
     "manifest.json",
     "engine",
     "presets",
+    "rules",
     "agents",
     "skills",
     "LICENSE",

package/presets/angular-express/preset.yaml

@@ -1,8 +1,8 @@
-id: angular-express
+id: angular-express
 version: 1
 extends: generic-ts
 description: Angular frontend with an Express BFF, Vitest and an optional Dolibarr-style REST backend.
-# Sin detect: preset de cliente. Sólo se elige con --preset angular-express.
+# Sin detect: preset de cliente. Sólo se elige con --preset angular-express.
 stack:
   languages:
     - typescript
@@ -51,5 +51,3 @@ skills:
     - onna-architecture-bff
     - onna-architecture-common
     - onna-design-system
-mcp:
-  source: mcp-manifest.yaml

package/presets/base/preset.yaml

@@ -1,4 +1,4 @@
-id: base
+id: base
 version: 1
 description: Minimal harness for any repository, regardless of language or framework.
 detect:
@@ -23,5 +23,3 @@ agents:
   publish: []
 skills:
   publish: []
-mcp:
-  source: mcp-manifest.yaml

package/presets/generic-ts/preset.yaml

@@ -1,4 +1,4 @@
-id: generic-ts
+id: generic-ts
 version: 1
 extends: base
 description: TypeScript repository with npm-compatible scripts and a standard test runner.
@@ -42,5 +42,3 @@ agents:
     - explorer-domain
 skills:
   publish: []
-mcp:
-  source: mcp-manifest.yaml

package/presets/python/preset.yaml

@@ -1,4 +1,4 @@
-id: python
+id: python
 version: 1
 extends: base
 description: Python project with pytest, mypy and ruff.
@@ -43,5 +43,3 @@ agents:
     - explorer-domain
 skills:
   publish: []
-mcp:
-  source: mcp-manifest.yaml

package/rules/skill-quality/skill-behavior-rubric.md

@@ -0,0 +1,63 @@
+# skill-behavior-rubric — how a skill's OUTPUT is graded (the behavioral gate)
+
+Sibling of `skill-rubric.md`. That one scores the skill as a **document**; this one scores what
+the skill **produces when run**. A skill ships only if BOTH gates are green.
+
+## How the behavioral eval works
+
+For each `capability` scenario in the skill's `evals/cases.yaml`, the engine
+(`scripts/skill-behavior-eval.workflow.js`) runs the scenario twice — once with the skill's
+`SKILL.md` injected (**treatment**), once without it (**baseline**) — and an independent, blind
+grader scores both outputs. The grader never learns which output used the skill; outputs are
+presented as X and Y, their slot varied by scenario index parity so a "first output" bias can't
+systematically favor the skill.
+
+## What the grader returns (per output)
+
+1. **must_include coverage.** For each `must_include` item: `satisfied` true/false **and a quoted
+   line** from the output that satisfies it. Evidence, not vibes. If unsure, mark unmet.
+2. **Quality, four axes 0-10:** `completeness`, `actionability`, `correctness`, `grounding`
+   (no invented facts / APIs / numbers).
+
+The grader returns raw signals only. It does **not** compute the score — that keeps the number
+deterministic and auditable.
+
+## Orientation signal (the brújula)
+
+User-facing, conversational skills should keep the user oriented. When a skill's capability scenario ends a turn the user acts on, the grader expects the output to:
+
+- **Situate** the user (where they are / what is built vs missing).
+- **Teach the why**, in the register `technical_level` sets (technical, or with analogies) — the voice is `orient`'s.
+- **Propose a next step phrased as a question** — never end in seco.
+
+Encode this as `must_include` items in those skills' capability scenarios (see `skills/orient/evals/cases.yaml` for the canonical pattern). It scores through the existing coverage axis — no separate formula. Skills that own a purely mechanical task (lint, a single rename) are exempt and should not be penalized.
+
+## How signals become the /10 (computed by `scripts/lib/behavior-score.js`)
+
+- Per output: `score = 0.6 × (satisfied / total × 10) + 0.4 × mean(quality axes)`.
+  Empty output → 0. No checklist → quality only.
+- Per scenario: `absolute` = treatment's score; `delta` = treatment − baseline.
+- Per skill: `absolute_score` = mean of absolutes; `lift` = mean of deltas.
+
+## The gate (both required)
+
+- `absolute_score ≥ 8.5` — the skill genuinely produces a good result.
+- `lift ≥ +1.0` — the skill measurably beats no-skill. `lift ≤ 0` is an automatic FAIL even at a
+  high absolute: the skill adds nothing the bare agent didn't already do.
+
+## Anti-gaming
+
+- Independent, blind grader; default-skeptical on coverage.
+- Errors fail closed: a scenario whose run or grade errored is dropped; if all drop, FAIL.
+- A skill with no `capability` scenario cannot be behaviorally evaluated → FAIL until one exists.
+- v1 uses a single grader per scenario. Upgrade path: N=3 graders, majority vote.
+
+## Running it
+
+```
+# 1) execute + grade — invoke the Workflow tool with the engine script and the skill id:
+#      scriptPath: scripts/skill-behavior-eval.workflow.js   args: "<skill-id>"
+#    capture the workflow's returned object to a JSON file (e.g. /tmp/<skill>-raw.json)
+# 2) score + gate (exit 0 pass / 1 fail):
+node scripts/skill-behavior-eval.js --score /tmp/<skill>-raw.json
+```

package/rules/skill-quality/skill-harden-rubric.md

@@ -0,0 +1,102 @@
+# skill-harden-rubric — how the fix-loop diagnoses and guards a fix
+
+The `skill-harden` workflow turns a FAILING behavioral score into edits, without gaming the eval.
+These are the rules its agents follow.
+
+The three guards below — **diff judge**, **hold-out**, **Generalization gate** — are mandatory *and*
+mechanised: `tests/harden-generalization-gate.test.js` asserts, for each of those three, that the
+loop implements what this file promises. **Adding a fourth guard here means adding its pair to that
+test**; a guard documented but unchecked gives the safety without the protection, which is the
+failure mode this repo has now hit ten times (constitution P2).
+
+## Diagnosis (skill-fault vs eval-fault vs capability)
+
+Given the failing `mustFix`, both A/B outputs, and the grader's per-item evidence, decide the FAULT:
+
+- **skill** — the treatment output genuinely misses real capability (weak method, missing depth,
+  no concrete output). Fix the SKILL.md body and/or references/.
+- **eval** — the failure is the eval's, not the skill's. Two known biases:
+  1. **Self-describing scenario** — the `scenario` text enumerates its own `must_include`, so a
+     bare agent gets the same guidance the skill would give and the lift collapses artificially.
+  2. **Phantom-context must_include** — an item demands workspace artifacts the isolated eval
+     agent cannot have (e.g. `user-profile.md`, a real sibling skill to delegate to), capping the
+     absolute unfairly.
+- **capability** — the gap cannot be closed by words in a skill body. It needs an **executable
+  capability**: something that fires on a real execution event and returns to the agent information
+  it cannot obtain on its own — a hook, a script, a tool, a sub-agent. Advice that merely tells the
+  agent to remember something is **not** a capability: it is not anchored to any observable event, so
+  it can fire when it should not and stay silent when it should not.
+
+This loop can only ever write **guidance** (SKILL.md, references/). So `capability` is not a fix
+route, it is the honest exit: the loop edits nothing, names the missing capability and the surface it
+would live on, and stops. Writing a paragraph that pretends to cover a missing capability raises the
+score without the capability existing — the worst outcome available.
+
+A `capability` verdict **must name** the capability and its surface. One that cannot is an excuse,
+not a diagnosis → choose `skill`.
+
+Default to **skill** when unsure: blaming the eval or the surface area is the easier, less honest path.
+
+## The Generalization gate (ex-ante — it binds before the edit is written)
+
+This gate governs the **content** of every line the fixer writes, and it travels **in the fixer's own
+instruction**, not in a review afterwards. Writing freely and reverting later burns the round, and the
+loop only has two.
+
+Everything added to a skill is global context that will apply to cases the skill has never seen. So:
+
+- **Allowed:** a reusable criterion that carries its own **applicability condition** — something the
+  agent can evaluate on a case it has never encountered.
+- **Banned outright:** identifiers or titles from the eval scenario; names of its files, symbols or
+  fixtures; rules that branch on its specific data; and reciting the finding as if it were a rule
+  ("the last round showed X needs Y" — that is an answer, not a criterion).
+
+**Litmus test, before every line:** *would this still help on a case in this domain I have never
+seen?* If no → rewrite it as a criterion, or drop it. Not knowledge → not in the skill.
+
+Why ex-ante and not only as review: moving this constraint from after-the-edit to
+before-the-edit is what buys generalization cheaply. The measured version of this result — plus the
+warning that richer feedback **without** this gate makes held-out performance *worse* — is in
+[HarnessCompass](https://arxiv.org/abs/2608.01918); the reasoning it drove is recorded in
+`02-DOCS/wiki/sdd/specs/generalization-gate.md`.
+
+## Eval-fix guard (independent judge)
+
+An eval edit ships ONLY if a judge certifies it corrects one of the two biases above and does NOT
+lower the bar — i.e. it makes the scenario less self-describing or removes a phantom-context item,
+but never deletes a legitimate quality criterion to make a weak skill pass. Rejected → treat as a
+skill-fault this round.
+
+## Skill-fix guards (both required)
+
+1. **Diff judge.** Read the SKILL.md/references diff and check BOTH: does it add genuine capability
+   (method, decision rules, concrete guidance) rather than echoing the `must_include` wording into
+   the body? *and* does every added line survive the Generalization gate above? Fail either → revert
+   the edit; it is not a fix.
+2. **Hold-out.** Re-score the EDITED skill on a FRESH scenario from its domain that the fixer never
+   saw. A real improvement generalizes; a memorized one does not.
+   - The eval engine runs every scenario with **and** without the skill, so the fresh scenario
+     already carries its own lift. No pre-fix baseline is needed.
+   - The verdict is computed by `node scripts/skill-behavior-eval.js --holdout <raw.json>` — a
+     comparison of numbers, deterministic and reproducible, never an agent's opinion (P1). Exit 0
+     passes, exit 1 blocks.
+   - **Blocks on `lift <= 0`** (`regression`): on unseen work the edited skill does not beat the bare
+     agent, so the edit did not transfer. Also blocks when the fresh scenario could not be run or
+     graded (`indeterminate`) — failing closed, because an unverified edit is not a verified one.
+   - The bar is deliberately **not** the main gate's `lift >= 1.0`: one fresh scenario graded once is
+     noisy, so only the unambiguous signal acts. Upgrade path if it proves too noisy in practice:
+     N=3 fresh scenarios, majority.
+   - **A block reverts the edit.** The round produced nothing and is recorded with its reason.
+
+## Stopping & honesty
+
+- Max 2 rounds. On give-up, report the honest final score and a recommendation — never a faked pass.
+- **A main-gate pass whose last surviving edit failed the hold-out does not commit.** It is a fix
+  tuned to the cases it was measured against; the loop reverts it and reports why. Conservative on
+  purpose: a lost commit costs one re-run, a certified overfit costs the catalog.
+- A `capability` verdict never commits either: it returns the missing capability and its surface, and
+  routes the work to `specify`.
+- Every non-commit says which condition failed, in the returned result. A denial without its exit is
+  abandonment (P6).
+- Persistent lift-fail at a high absolute → recommend deprecate/merge: the skill does not justify
+  its own existence.