@dsalazardev/ai-hub-cli 0.2.0 → 0.3.1

package/dist/cli/onboarding.js

@@ -4,7 +4,7 @@ import { stringify } from 'yaml';
 import { createBackup } from '../backup/snapshots.js';
 import { readAiHubRc, writeAiHubRc } from '../paths.js';
 import { detectPreset } from '../presets/detect.js';
-import { materializeCatalog, materializePreset, materializeUniversalRules, } from '../presets/materialize.js';
+import { materializeCatalog, materializePreset, materializeUniversalRules, removeOwned, } from '../presets/materialize.js';
 import { resolvePreset } from '../presets/resolve.js';
 import { listPresetIds } from '../presets/schema.js';
 import { loadManifestContext, writeInventory } from '../manifest/manifest.js';
@@ -15,6 +15,9 @@ import { sha256 } from '../sync/lock.js';
 import { isEngineCheckout } from '../source-checkout.js';
 import { ENGINE_AGENTS_DIR, ENGINE_RULES_DIR, catalogIndex, catalogSeal, expectedRuleIds, hasFullDimension, listCatalogAgents, listCatalogSkills, } from '../catalog.js';
 import { loadEngine } from '../engine/engine.js';
+import { probeEnvironment, runSpeckitSequence, speckitPreflight, } from '../speckit/commands.js';
+import { effectiveSpeckit } from '../speckit/settings.js';
+import { checkExtensions, checkIntegrations, readSpeckitState } from '../speckit/state.js';
 import { flagList, flagString } from './args.js';
 const RC_NAME = '.ai-hubrc.json';
 export async function cliVersion() {
@@ -22,6 +25,87 @@ export async function cliVersion() {
     const pkg = JSON.parse(raw);
     return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
 }
+function speckitPlan(settings) {
+    return {
+        managed: settings.managed,
+        package: settings.package,
+        version: settings.version,
+        excludeNewer: settings.excludeNewer,
+        script: settings.script,
+        defaultIntegration: settings.defaultIntegration,
+        integrations: settings.integrations,
+        extensions: settings.extensions,
+    };
+}
+/** Bloque `speckit` a escribir: conserva las restricciones del proyecto y fija `managed` y el script explícito. */
+function speckitBlock(existing, managed, script) {
+    return { ...(existing ?? {}), managed, ...(script !== undefined ? { script } : {}) };
+}
+/**
+ * Lee `--script <sh|ps>` (design D3): valida antes de cualquier sondeo y nombra el comando concreto.
+ * Devuelve `undefined` cuando la bandera no se usó y `null` cuando es inválida (ya reportado).
+ */
+function parseScriptFlag(args, ctx, command) {
+    if (!('script' in args.flags)) {
+        return undefined;
+    }
+    const value = flagString(args, 'script');
+    if (value === 'sh' || value === 'ps') {
+        return value;
+    }
+    ctx.io.err(`--script acepta sh o ps${value === null ? ' y necesita un valor' : ` (recibido: ${value})`}; ` +
+        `ejecuta ai-hub ${command} --script sh o ai-hub ${command} --script ps`);
+    return null;
+}
+function speckitSettingsFor(targets, block, engine) {
+    return effectiveSpeckit({ targets, speckit: block }, engine);
+}
+async function environmentFor(settings, ctx) {
+    if (!settings.managed) {
+        return { skipped: 'Spec Kit no gestionado (--no-speckit)' };
+    }
+    return probeEnvironment(settings, ctx.exec, ctx.root);
+}
+/** Preflight de Spec Kit; devuelve `false` y explica el motivo si hay que salir con 2. */
+async function preflightOrReport(settings, ctx, command) {
+    const preflight = await speckitPreflight(settings, ctx.exec, ctx.root, command);
+    if (!preflight.ok) {
+        ctx.io.err('preflight de Spec Kit fallido; no se escribió nada:');
+        for (const problem of preflight.problems) {
+            ctx.io.err(`  - ${problem}`);
+        }
+    }
+    return preflight.ok;
+}
+/** Ejecuta la secuencia de Spec Kit; devuelve `false` y explica cómo restaurar si falla. */
+async function installSpeckit(settings, ctx, backupId) {
+    const result = await runSpeckitSequence(settings, ctx.exec, ctx.root);
+    const problems = [];
+    if (!result.ok) {
+        problems.push(result.failure ?? 'fallo desconocido');
+    }
+    else {
+        // Paso 9d: la secuencia solo cuenta si deja las integraciones y extensiones esperadas.
+        const state = await readSpeckitState(ctx.root);
+        problems.push(...checkIntegrations(settings, state), ...(await checkExtensions(ctx.root, settings, state)));
+    }
+    if (problems.length > 0) {
+        ctx.io.err('Spec Kit no quedó instalado como se esperaba:');
+        for (const problem of problems) {
+            ctx.io.err(`  - ${problem}`);
+        }
+        if (backupId !== null) {
+            ctx.io.err(`restaura el estado previo con: ai-hub restore ${backupId}`);
+        }
+        return false;
+    }
+    return true;
+}
+function speckitSummary(settings) {
+    return settings.managed
+        ? `Spec Kit ${settings.version} · script ${settings.script} · integraciones ${settings.integrations.join(', ')}`
+        : 'Spec Kit no gestionado (--no-speckit): el arnés queda degradado; ejecuta ai-hub install para activarlo';
+}
 function projectId(root) {
     const base = path.basename(path.resolve(root)).toLowerCase();
     const id = base.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
@@ -78,13 +162,14 @@ async function buildSelection(args, preset, engine, existing) {
     const exclusions = parseExclusions(args);
     const hasExclusions = exclusions.skills.size > 0 || exclusions.agents.size > 0 || exclusions.rules.size > 0;
     if (existing && !fullFlag && !presetOnly && !hasExclusions) {
+        const retired = new Set(await retiredCatalogSkills(existing.skills.publish));
         return {
             modes: {
                 skills: existing.skills.selection ?? 'preset',
                 agents: existing.agents.selection ?? 'preset',
                 rules: existing.rules.selection ?? 'preset',
             },
-            skills: [...existing.skills.publish],
+            skills: existing.skills.publish.filter((id) => !retired.has(id)),
             agents: [...existing.agents.publish],
             rules: [...existing.rules.publish],
         };
@@ -125,7 +210,7 @@ async function buildSelection(args, preset, engine, existing) {
         rules: [...new Set(filterRules(rulesBase, exclusions.rules))].sort(),
     };
 }
-function manifestFromSelection(id, preset, targets, profilePackageManager, guardMode, includeMcp, selection) {
+function manifestFromSelection(id, preset, targets, profilePackageManager, guardMode, includeMcp, selection, speckit) {
     const manifest = {
         version: 2,
         project: { id, name: id },
@@ -150,6 +235,7 @@ function manifestFromSelection(id, preset, targets, profilePackageManager, guard
         agents: { source: '.ai-hub/agents', publish: selection.agents, selection: selection.modes.agents },
         rules: { source: '.ai-hub/rules', publish: selection.rules, selection: selection.modes.rules },
         ...(includeMcp ? { mcp: { source: 'mcp-manifest.yaml' } } : {}),
+        speckit,
     };
     if (hasFullDimension(manifest)) {
         manifest.catalog = catalogSeal(manifest);
@@ -180,8 +266,9 @@ async function materializeSelection(root, preset, selection) {
 }
 async function buildAssetPlan(selection, engine, targets, includeMcp) {
     const index = await catalogIndex();
-    const engineSkills = engine.commands.map((command) => command.skill);
-    const allSkills = [...new Set([...engineSkills, ...selection.skills])];
+    // Los 17 comandos los proyecta Spec Kit; AI-Hub solo proyecta las skills de proyecto.
+    void engine;
+    const allSkills = [...new Set(selection.skills)];
     const projectSkillFiles = selection.skills.reduce((total, id) => total + (index.skillFiles[id]?.length ?? 0), 0);
     const skillFiles = allSkills.reduce((total, id) => total + (index.skillFiles[id]?.length ?? 0), 0);
     let destinations = 1; // opencode.json
@@ -191,7 +278,7 @@ async function buildAssetPlan(selection, engine, targets, includeMcp) {
         if (target.agents) {
             destinations += selection.agents.length;
         }
-        destinations += selection.rules.length + 1; // reglas materializadas + preflight
+        destinations += selection.rules.length + 2; // reglas materializadas + preflight + regla de enlace de Spec Kit
     }
     if (includeMcp) {
         destinations += 3;
@@ -288,6 +375,10 @@ async function resolveSelection(args, ctx) {
     };
 }
 export async function cmdInit(args, ctx) {
+    const scriptFlag = parseScriptFlag(args, ctx, 'init');
+    if (scriptFlag === null) {
+        return 2;
+    }
     const sourceCheckout = await isEngineCheckout(ctx.root);
     let selection;
     try {
@@ -323,7 +414,14 @@ export async function cmdInit(args, ctx) {
     }
     const includeMcp = await exists(path.join(ctx.root, 'mcp-manifest.yaml'));
     const assets = await buildAssetPlan(spec, engine, selection.targets, includeMcp);
+    const speckit = speckitBlock(existing?.speckit, !args.flags['no-speckit'], scriptFlag);
+    const speckitSettings = speckitSettingsFor(selection.targets, speckit, engine);
+    // El taller nunca ejecuta Spec Kit: su .specify/ es del mantenedor.
+    const runSpeckit = speckitSettings.managed && !sourceCheckout;
     const write = [RC_NAME, 'manifest.yaml', '.gitignore', '.ai-hub/'];
+    if (runSpeckit) {
+        write.push('.specify/');
+    }
     if (selection.migrate) {
         write.push('.planning/state.json');
     }
@@ -333,28 +431,38 @@ export async function cmdInit(args, ctx) {
         preset: selection.preset.id,
         targets: selection.targets,
         ...assets,
-        skillCount: 17 + spec.skills.length,
+        skillCount: spec.skills.length,
+        speckitCommands: engine.commands.length,
         agentCount: spec.agents.length,
         ruleCount: spec.rules.length + 1,
         mcp: includeMcp,
         migrate: selection.migrate,
         write,
+        speckit: speckitPlan(speckitSettings),
     };
     const plan = { ...planBody, hash: sha256(JSON.stringify(planBody)) };
     if (!args.flags.yes || args.flags['dry-run']) {
-        ctx.io.out(JSON.stringify(plan, null, 2));
+        const environment = await environmentFor(speckitSettings, ctx);
+        ctx.io.out(JSON.stringify({ ...plan, environment }, null, 2));
         if (!args.flags['dry-run']) {
             ctx.io.out('Nada escrito. Repite con --yes para aplicar este plan.');
         }
         return 0;
     }
-    if (existing) {
-        await createBackup(ctx.root, 'init');
+    if (runSpeckit && !(await preflightOrReport(speckitSettings, ctx, 'init'))) {
+        return 2;
     }
+    // Backup restaurable antes de que Spec Kit toque un proyecto existente (constitución incluida).
+    const backupId = existing || (await exists(path.join(ctx.root, '.specify')))
+        ? (await createBackup(ctx.root, 'init')).id
+        : null;
     const materialized = await materializeSelection(ctx.root, selection.preset, spec);
-    const manifest = manifestFromSelection(id, selection.preset, selection.targets, selection.profilePackageManager, rc.guardMode ?? 'shadow', includeMcp, spec);
+    const manifest = manifestFromSelection(id, selection.preset, selection.targets, selection.profilePackageManager, rc.guardMode ?? 'shadow', includeMcp, spec, speckit);
     await writeManifest(ctx.root, manifest);
     await writeInventory(ctx.root);
+    if (runSpeckit && !(await installSpeckit(speckitSettings, ctx, backupId))) {
+        return 1;
+    }
     const sync = await runSync(ctx.root, { check: false });
     const existingRc = readAiHubRc(ctx.cwd);
     if (!existingRc || existingRc.version === 1 || args.flags.force) {
@@ -381,10 +489,11 @@ export async function cmdInit(args, ctx) {
         const hook = await installPostMergeHook(ctx.root);
         ctx.io.out(`hooks: ${hook.installed ? 'post-merge instalado' : hook.reason}`);
     }
-    ctx.io.out(`init: ${selection.preset.id} · skills=${spec.modes.skills} agents=${spec.modes.agents} rules=${spec.modes.rules} · ${spec.skills.length + 17} skills · ${spec.agents.length} agentes · ${spec.rules.length + 1} reglas · ${assets.destinations} destinos · ${sync.written.length} sincronizados · ${materialized.written.length} nuevos, ${materialized.kept.length} conservados, ${materialized.collisions.length} colisiones`);
+    ctx.io.out(`init: ${selection.preset.id} · skills=${spec.modes.skills} agents=${spec.modes.agents} rules=${spec.modes.rules} · ${spec.skills.length} skills de proyecto + ${engine.commands.length} comandos Spec Kit · ${spec.agents.length} agentes · ${spec.rules.length + 1} reglas · ${assets.destinations} destinos · ${sync.written.length} sincronizados · ${materialized.written.length} nuevos, ${materialized.kept.length} conservados, ${materialized.collisions.length} colisiones`);
     if (materialized.collisions.length > 0) {
         ctx.io.err(`colisiones (no se sobrescribieron): ${materialized.collisions.join(', ')}`);
     }
+    ctx.io.out(speckitSummary(speckitSettings));
     ctx.io.out(`plan: ${plan.hash}`);
     return 0;
 }
@@ -435,14 +544,24 @@ async function selectionForInstall(args, manifest, preset, engine) {
         : modes.rules === 'preset'
             ? expectedRuleIds('preset', preset)
             : [...manifest.rules.publish];
+    const retired = new Set(await retiredCatalogSkills(skills));
     return {
         modes,
-        skills: [...new Set(skills.filter((id) => !exclusions.skills.has(id)))].sort(),
+        skills: [...new Set(skills.filter((id) => !exclusions.skills.has(id) && !retired.has(id)))].sort(),
         agents: [...new Set(agents.filter((id) => !exclusions.agents.has(id)))].sort(),
         rules: [...new Set(filterRules(rulesBase, exclusions.rules))].sort(),
     };
 }
+/** Ids de `ids` que el catálogo publica con `runtime: false` (no instalables). */
+async function retiredCatalogSkills(ids) {
+    const retired = new Set((await catalogIndex()).retiredSkills);
+    return ids.filter((id) => retired.has(id));
+}
 export async function cmdInstall(args, ctx) {
+    const scriptFlag = parseScriptFlag(args, ctx, 'install');
+    if (scriptFlag === null) {
+        return 2;
+    }
     let context;
     try {
         context = await loadManifestContext(ctx.root);
@@ -460,6 +579,10 @@ export async function cmdInstall(args, ctx) {
         return 2;
     }
     const includeMcp = await exists(path.join(ctx.root, 'mcp-manifest.yaml'));
+    // install sin --no-speckit reactiva Spec Kit en un arnés degradado; con la bandera lo mantiene apagado.
+    const speckit = speckitBlock(context.manifest.speckit, !args.flags['no-speckit'], scriptFlag);
+    const speckitSettings = speckitSettingsFor(context.manifest.targets, speckit, context.engine);
+    const runSpeckit = speckitSettings.managed && !(await isEngineCheckout(ctx.root));
     if (args.flags['dry-run']) {
         const assets = await buildAssetPlan(spec, context.engine, context.manifest.targets, includeMcp);
         ctx.io.out(JSON.stringify({
@@ -472,10 +595,20 @@ export async function cmdInstall(args, ctx) {
             agents: spec.agents.length,
             rules: spec.rules.length + 1,
             destinations: assets.destinations,
+            speckit: speckitPlan(speckitSettings),
         }, null, 2));
         return 0;
     }
+    if (runSpeckit && !(await preflightOrReport(speckitSettings, ctx, 'install'))) {
+        return 2;
+    }
+    const backupId = runSpeckit ? (await createBackup(ctx.root, 'install')).id : null;
     const materialized = await materializeSelection(ctx.root, context.preset, spec);
+    // Migración: las skills `runtime: false` salen de .ai-hub/ si las escribió ai-hub;
+    // sync retira después sus copias de los destinos.
+    for (const id of await retiredCatalogSkills(context.manifest.skills.publish)) {
+        await removeOwned(ctx.root, path.join(context.manifest.skills.source, id), true);
+    }
     const next = {
         ...context.manifest,
         skills: { ...context.manifest.skills, publish: spec.skills, selection: spec.modes.skills },
@@ -494,7 +627,11 @@ export async function cmdInstall(args, ctx) {
     else {
         delete next.catalog;
     }
+    next.speckit = speckit;
     await writeManifest(ctx.root, next);
+    if (runSpeckit && !(await installSpeckit(speckitSettings, ctx, backupId))) {
+        return 1;
+    }
     const sync = await runSync(ctx.root, { check: false });
     await writeInventory(ctx.root);
     await ensureProjectIgnores(ctx.root);
@@ -502,10 +639,11 @@ export async function cmdInstall(args, ctx) {
         const hook = await installPostMergeHook(ctx.root);
         ctx.io.out(`hooks: ${hook.installed ? 'post-merge instalado' : hook.reason}`);
     }
-    ctx.io.out(`install: skills=${spec.modes.skills} agents=${spec.modes.agents} rules=${spec.modes.rules} · ${spec.skills.length + 17} skills · ${spec.agents.length} agentes · ${spec.rules.length + 1} reglas · ${materialized.written.length} nuevos · ${materialized.kept.length} conservados · ${sync.written.length} sincronizados`);
+    ctx.io.out(`install: skills=${spec.modes.skills} agents=${spec.modes.agents} rules=${spec.modes.rules} · ${spec.skills.length} skills de proyecto + ${context.engine.commands.length} comandos Spec Kit · ${spec.agents.length} agentes · ${spec.rules.length + 1} reglas · ${materialized.written.length} nuevos · ${materialized.kept.length} conservados · ${sync.written.length} sincronizados`);
     if (!Object.values(spec.modes).includes('full')) {
         ctx.io.out('full: no aplica; usa install --full para expandir el catálogo');
     }
+    ctx.io.out(speckitSummary(speckitSettings));
     return 0;
 }
 export async function cmdRepair(args, ctx) {

package/dist/cli/run.d.ts

@@ -1,4 +1,5 @@
 import type { CliContext, CliIO, CommandHandler } from './types.js';
+import { type ProcessRunner } from '../speckit/runner.js';
 interface CommandSpec {
     summary: string;
     handler: CommandHandler;
@@ -6,10 +7,11 @@ interface CommandSpec {
 export declare const COMMANDS: Record<string, CommandSpec>;
 export declare const COMMAND_NAMES: string[];
 export declare function printHelp(io: CliIO): void;
-export declare function createContext(cwd: string, io: CliIO): Promise<CliContext>;
+export declare function createContext(cwd: string, io: CliIO, exec?: ProcessRunner): Promise<CliContext>;
 export interface RunCliOptions {
     cwd?: string;
     io?: CliIO;
+    exec?: ProcessRunner;
 }
 export declare function runCli(argv: string[], options?: RunCliOptions): Promise<number>;
 export {};

package/dist/cli/run.js

@@ -14,6 +14,7 @@ import { cmdWorktrees } from './worktrees.js';
 import { cliVersion } from './onboarding.js';
 import { sourceCheckout } from './source.js';
 import { processIO } from './types.js';
+import { defaultRunner } from '../speckit/runner.js';
 function printLockCheck(result, ctx) {
     const header = `destinos esperados ${result.expectedCount} / actuales ${result.actualCount} · sources ${result.expectedSourceCount}/${result.actualSourceCount}`;
     const extraCategories = result.breakdown.other > 0 ? `, other ${result.breakdown.other}` : '';
@@ -136,14 +137,14 @@ export function printHelp(io) {
     io.out('Publicación: prepublishOnly ejecuta build, manifest:build y npm test (unit + integración).');
     io.out('Compatibilidad: verify, judge (fuera del catálogo).');
 }
-export async function createContext(cwd, io) {
+export async function createContext(cwd, io, exec = defaultRunner) {
     try {
         const location = resolveAiHubDir(cwd);
-        return { cwd, root: location.dir, source: location.source, io };
+        return { cwd, root: location.dir, source: location.source, io, exec };
     }
     catch (error) {
         if (error instanceof AiHubDirNotFoundError) {
-            return { cwd, root: cwd, source: null, io };
+            return { cwd, root: cwd, source: null, io, exec };
         }
         throw error;
     }
@@ -152,7 +153,7 @@ export async function runCli(argv, options = {}) {
     const io = options.io ?? processIO;
     const cwd = options.cwd ?? process.cwd();
     const [command, ...rest] = argv;
-    const ctx = await createContext(cwd, io);
+    const ctx = await createContext(cwd, io, options.exec);
     if (!command) {
         printHelp(io);
         return 2;

package/dist/cli/types.d.ts

@@ -1,4 +1,5 @@
 import type { AiHubSource } from '../paths.js';
+import type { ProcessRunner } from '../speckit/runner.js';
 export interface CliIO {
     out(message: string): void;
     err(message: string): void;
@@ -8,6 +9,8 @@ export interface CliContext {
     root: string;
     source: AiHubSource | null;
     io: CliIO;
+    /** Ejecutor de procesos externos (uvx, bash); los tests lo sustituyen. */
+    exec: ProcessRunner;
 }
 export interface ParsedArgs {
     positionals: string[];

package/dist/engine/engine.d.ts

@@ -28,15 +28,33 @@ export interface EngineCommand {
     exit: string[];
     role: string;
     co_roles?: string[];
-    skill: string;
+    /** Id canónico del comando en Spec Kit, en notación con punto (`speckit.bug.assess`). */
+    speckit: string;
 }
+export type SpeckitScript = 'sh' | 'ps';
+/** Dependencia de Spec Kit fijada por el paquete; un proyecto solo puede restringirla. */
+export interface EngineSpeckit {
+    package: string;
+    pin: string;
+    supported: string;
+    excludeNewer: string;
+    script: SpeckitScript;
+    extensions: Record<string, string>;
+}
+/** Extensiones de Spec Kit que proveen los 8 comandos de assessment y bug fix. */
+export declare const REQUIRED_SPECKIT_EXTENSIONS: readonly ["assess", "bug"];
 export interface EngineManifest {
     version: 2;
     roles: EngineRole[];
     commands: EngineCommand[];
+    /** Efecto de cada estado de salida sobre las etiquetas; tabla única proyectada en la regla de enlace. */
+    exit_effects: Record<string, string>;
     labels: string[];
     targets: string[];
+    speckit: EngineSpeckit;
 }
+/** Estados de salida que el vocabulario normalizado de Spec Kit retiró. */
+export declare const RETIRED_EXIT_STATES: readonly ["ROOT_CAUSE", "NEEDS_DATA", "FIXED", "RESOLVED", "OPEN", "DRAFT", "READY"];
 export declare class EngineError extends Error {
     readonly errors: string[];
     constructor(errors: string[]);

package/dist/engine/engine.js

@@ -3,12 +3,17 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Ajv } from 'ajv';
 import { parse } from 'yaml';
+import { satisfiesRange } from '../speckit/version.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ENGINE_PATH = path.join(__dirname, '..', '..', 'engine', 'engine.yaml');
 const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schema', 'engine.schema.json');
 export const ENGINE_SKILLS_DIR = path.join(__dirname, '..', '..', 'skills', 'shared');
 export const ENGINE_COUNTS = { roles: 8, commands: 17, labels: 7 };
 export const ENGINE_LANES = { assessment: 5, feature: 9, bug: 3 };
+/** Extensiones de Spec Kit que proveen los 8 comandos de assessment y bug fix. */
+export const REQUIRED_SPECKIT_EXTENSIONS = ['assess', 'bug'];
+/** Estados de salida que el vocabulario normalizado de Spec Kit retiró. */
+export const RETIRED_EXIT_STATES = ['ROOT_CAUSE', 'NEEDS_DATA', 'FIXED', 'RESOLVED', 'OPEN', 'DRAFT', 'READY'];
 export class EngineError extends Error {
     errors;
     constructor(errors) {
@@ -104,6 +109,53 @@ export function crossValidate(engine) {
             errors.push(`lane "${lane}" debe tener ${count} comandos (tiene ${actual})`);
         }
     }
+    for (const id of findDuplicateIds(engine.commands.map((command) => command.speckit))) {
+        errors.push(`id de Spec Kit duplicado: ${id}`);
+    }
+    const retired = new Set(RETIRED_EXIT_STATES);
+    const states = new Set();
+    for (const command of engine.commands) {
+        for (const state of command.exit) {
+            states.add(state);
+            if (retired.has(state)) {
+                errors.push(`commands "${command.id}".exit usa el estado retirado ${state}`);
+            }
+        }
+    }
+    const effects = engine.exit_effects ?? {};
+    for (const state of [...states].sort()) {
+        if (!(state in effects)) {
+            errors.push(`exit_effects no define el efecto de ${state}`);
+        }
+    }
+    for (const state of Object.keys(effects).sort()) {
+        if (!states.has(state)) {
+            errors.push(`exit_effects.${state} no corresponde a ningún estado de salida`);
+        }
+    }
+    errors.push(...validateEngineSpeckit(engine.speckit));
+    return errors;
+}
+function validateEngineSpeckit(speckit) {
+    if (speckit === undefined) {
+        return ['falta el bloque speckit'];
+    }
+    const errors = [];
+    for (const field of ['package', 'pin', 'supported', 'excludeNewer', 'script']) {
+        if (typeof speckit[field] !== 'string' || speckit[field] === '') {
+            errors.push(`falta speckit.${field}`);
+        }
+    }
+    for (const extension of REQUIRED_SPECKIT_EXTENSIONS) {
+        if (typeof speckit.extensions?.[extension] !== 'string') {
+            errors.push(`falta speckit.extensions.${extension}`);
+        }
+    }
+    if (typeof speckit.pin === 'string' &&
+        typeof speckit.supported === 'string' &&
+        !satisfiesRange(speckit.pin, speckit.supported)) {
+        errors.push(`speckit.pin ${speckit.pin} está fuera de speckit.supported "${speckit.supported}"`);
+    }
     return errors;
 }
 export function commandById(engine, id) {

package/dist/engine/gates.d.ts

@@ -1,2 +1,18 @@
 export declare function scanLegacyArtifacts(root: string): Promise<string[]>;
 export declare function scanCoupling(root: string, terms: string[]): Promise<string[]>;
+/** Prefijos que Spec Kit reserva en los directorios de comandos de cada destino. */
+export declare const SPECKIT_RESERVED_PREFIXES: readonly ["speckit-", "speckit."];
+/**
+ * Gate del catálogo publicado: ninguna skill, agente o regla puede proyectarse con un nombre
+ * del espacio reservado de Spec Kit (`speckit-*` / `speckit.*`).
+ */
+export declare function scanReservedNamespace(dirs?: {
+    skills: string;
+    agents: string;
+    rules: string;
+}): Promise<string[]>;
+/**
+ * Gate del vocabulario de estados retirado (`ROOT_CAUSE`, `FIXED`, `READY`…): devuelve
+ * `ruta:línea vocabulario obsoleto "TOKEN"` relativo a `root`.
+ */
+export declare function scanRetiredStates(files: string[] | undefined, root: string): Promise<string[]>;

package/dist/engine/gates.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { isEngineCheckout } from '../source-checkout.js';
-import { ENGINE_AGENTS_DIR, catalogIndex } from '../catalog.js';
+import { ENGINE_AGENTS_DIR, ENGINE_RULES_DIR, catalogIndex } from '../catalog.js';
 import { ENGINE_SKILLS_DIR } from './engine.js';
 const LEGACY_SOURCE_DIRS = ['core/presets', 'core/skills', 'core/agents'];
 const LEGACY_TARGET_DIRS = [
@@ -129,3 +129,104 @@ export async function scanCoupling(root, terms) {
     }
     return findings.sort();
 }
+/** Prefijos que Spec Kit reserva en los directorios de comandos de cada destino. */
+export const SPECKIT_RESERVED_PREFIXES = ['speckit-', 'speckit.'];
+function reservedName(name) {
+    return SPECKIT_RESERVED_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/**
+ * Gate del catálogo publicado: ninguna skill, agente o regla puede proyectarse con un nombre
+ * del espacio reservado de Spec Kit (`speckit-*` / `speckit.*`).
+ */
+export async function scanReservedNamespace(dirs = {
+    skills: ENGINE_SKILLS_DIR,
+    agents: ENGINE_AGENTS_DIR,
+    rules: ENGINE_RULES_DIR,
+}) {
+    const findings = [];
+    for (const entry of await fs.readdir(dirs.skills, { withFileTypes: true }).catch(() => [])) {
+        if (entry.isDirectory() && reservedName(entry.name)) {
+            findings.push(`skills/shared/${entry.name} (espacio reservado de Spec Kit)`);
+        }
+    }
+    for (const [kind, dir] of [['agents', dirs.agents], ['rules', dirs.rules]]) {
+        for (const name of await listNames(dir)) {
+            if (reservedName(path.basename(name))) {
+                findings.push(`${kind}/${name} (espacio reservado de Spec Kit)`);
+            }
+        }
+    }
+    return findings.sort();
+}
+async function listNames(dir, prefix = '') {
+    const names = [];
+    for (const entry of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            names.push(...(await listNames(path.join(dir, entry.name), rel)));
+        }
+        else if (entry.isFile()) {
+            names.push(rel);
+        }
+    }
+    return names;
+}
+/** Estados retirados que solo existían como estado de salida: se marcan en cualquier contexto. */
+const RETIRED_ALWAYS = ['ROOT_CAUSE', 'NEEDS_DATA'];
+/** Estados retirados que también son palabras corrientes: se marcan solo usados como estado. */
+const RETIRED_IN_STATE_CONTEXT = ['FIXED', 'RESOLVED', 'OPEN', 'DRAFT', 'READY'];
+const STATE_CONTEXT = /\b(estados?|exit|exits|termina(n)? en|ends? in|outcome|veredicto|verdict)\b/i;
+function retiredInLine(line) {
+    const found = [];
+    const words = new Set(line.split(/[^A-Za-z0-9_-]+/));
+    for (const token of RETIRED_ALWAYS) {
+        if (words.has(token)) {
+            found.push(token);
+        }
+    }
+    for (const token of RETIRED_IN_STATE_CONTEXT) {
+        const quoted = line.includes(`\`${token}\``);
+        const inContext = STATE_CONTEXT.test(line) && words.has(token);
+        if (quoted || inContext) {
+            found.push(token);
+        }
+    }
+    return found;
+}
+/** Archivos que el gate revisa en el checkout del motor: motor, documentación y catálogo publicado. */
+async function retiredStateFiles(root) {
+    const files = [
+        path.join(root, 'core', 'engine', 'engine.yaml'),
+        path.join(root, 'AGENTS.md'),
+        path.join(root, 'README.md'),
+        path.join(root, 'core', 'README.md'),
+    ];
+    for (const dir of ['core/rules', 'core/agents', 'core/skills/shared']) {
+        for (const rel of await listNames(path.join(root, ...dir.split('/')))) {
+            if (TEXT_FILE.test(rel)) {
+                files.push(path.join(root, ...dir.split('/'), ...rel.split('/')));
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Gate del vocabulario de estados retirado (`ROOT_CAUSE`, `FIXED`, `READY`…): devuelve
+ * `ruta:línea vocabulario obsoleto "TOKEN"` relativo a `root`.
+ */
+export async function scanRetiredStates(files, root) {
+    const findings = [];
+    for (const file of files ?? (await retiredStateFiles(root))) {
+        const text = await fs.readFile(file, 'utf8').catch(() => null);
+        if (text === null) {
+            continue;
+        }
+        const rel = path.relative(root, file).split(path.sep).join('/');
+        text.split(/\r?\n/).forEach((line, index) => {
+            for (const token of retiredInLine(line)) {
+                findings.push(`${rel}:${index + 1} vocabulario obsoleto "${token}"`);
+            }
+        });
+    }
+    return findings;
+}

package/dist/harness/memory/ledger.d.ts

@@ -49,5 +49,11 @@ export interface ResumeSummary {
         done: number;
     };
     state: ProjectState | null;
+    /** Feature de Spec Kit activa y de dónde salió: `state` (versionado) o `local` (.specify/feature.json). */
+    feature: {
+        dir: string;
+        source: 'state' | 'local';
+        pending: number;
+    } | null;
 }
 export declare function resumeLedger(root: string): Promise<ResumeSummary>;