agent-rules-init 0.4.0 → 0.5.0

package/dist/cli.d.ts

@@ -2,7 +2,7 @@ import { type GeneratedFile, type WriteResult } from "./core/writer.js";
 import { type Lang } from "./core/i18n.js";
 import { type AgentRulesConfig } from "./core/config.js";
 import { type PromptFn } from "./core/prompt-engine.js";
-import { type ExecFn } from "./core/llm-bridge.js";
+import { type AssistantId, type ExecFn } from "./core/llm-bridge.js";
 import type { RepoFacts } from "./core/types.js";
 export interface RunCliOptions {
     promptFn?: PromptFn;
@@ -11,8 +11,14 @@ export interface RunCliOptions {
     lang?: Lang;
     /** Generate results without changing the filesystem. */
     dryRun?: boolean;
-    /** Do not prompt or offer AI polishing. */
+    /** Do not prompt or offer AI enrichment. */
     nonInteractive?: boolean;
+    /** Run AI enrichment without asking, even without a TTY. Ignored when skipLlm or noAi apply. */
+    enrich?: boolean;
+    /** Assistant to enrich with; defaults to the first one installed. */
+    assistant?: AssistantId;
+    /** Model forwarded verbatim to the assistant CLI; its default when omitted. */
+    model?: string;
     /** Receives the rendered files before they are written (or planned). */
     onGeneratedFiles?: (files: readonly GeneratedFile[]) => void;
     /** Preloaded repository configuration; loaded from disk when omitted. */
@@ -28,6 +34,9 @@ export interface CliRunOptions {
     check?: true;
     json?: true;
     nonInteractive?: true;
+    enrich?: true;
+    assistant?: AssistantId;
+    model?: string;
 }
 export type CliAction = ({
     kind: "run";
@@ -38,6 +47,12 @@ export type CliAction = ({
 } | {
     kind: "invalid-lang";
     value: string;
+} | {
+    kind: "invalid-assistant";
+    value: string;
+} | {
+    kind: "missing-value";
+    flag: string;
 } | {
     kind: "unknown";
     flag: string;

package/dist/cli.js

@@ -11,7 +11,7 @@ import { loadConfig } from "./core/config.js";
 import { applyProjectExcludes, buildPackageUnits } from "./core/project-units.js";
 import { renderProjectUnitAgents } from "./core/project-unit-output.js";
 import { collectLowConfidenceQuestions, askQuestions, applyAnswers, makeDefaultPromptFn, hasInteractiveTty, } from "./core/prompt-engine.js";
-import { detectAvailableAssistants, polishFilesWithAssistant, defaultExecFn } from "./core/llm-bridge.js";
+import { detectAvailableAssistants, enrichFilesWithAssistant, defaultExecFn, } from "./core/llm-bridge.js";
 import { jsTsPack } from "./packs/js-ts.js";
 import { pythonPack } from "./packs/python.js";
 import { javaPack } from "./packs/java.js";
@@ -44,6 +44,23 @@ const ALL_PACKS = [
     scalaPack,
     rPack,
 ];
+// Final-name docs the tool itself would generate; when they already exist they carry the
+// team's hand-written intent, so enrichment must integrate them instead of ignoring them.
+const EXISTING_DOC_PATHS = ["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md"];
+const MAX_EXISTING_DOC_CHARS = 20_000;
+function readExistingDocs(rootPath) {
+    const docs = [];
+    for (const relativePath of EXISTING_DOC_PATHS) {
+        const absolutePath = path.join(rootPath, relativePath);
+        if (!fs.existsSync(absolutePath))
+            continue;
+        const content = fs.readFileSync(absolutePath, "utf8");
+        if (content.trim() === "")
+            continue;
+        docs.push({ path: relativePath, content: content.slice(0, MAX_EXISTING_DOC_CHARS) });
+    }
+    return docs;
+}
 export async function runCli(rootPath, options = {}) {
     const loadedConfig = options.config ? { config: options.config, warnings: [] } : loadConfig(rootPath);
     const config = loadedConfig.config;
@@ -93,15 +110,49 @@ export async function runCli(rootPath, options = {}) {
         if (scoped)
             files.push(scoped);
     }
-    if (!options.skipLlm && !config.noAi && !options.nonInteractive && hasInteractiveTty()) {
+    const wantsEnrich = options.enrich === true;
+    const canOfferEnrich = !options.nonInteractive && hasInteractiveTty();
+    if (!options.skipLlm && !config.noAi && (wantsEnrich || canOfferEnrich)) {
+        // With --enrich there may be no TTY (scripts, CI); route progress through stderr so
+        // stdout stays parseable in --json mode.
+        const notify = canOfferEnrich ? (message) => clack.log.info(message) : (message) => console.warn(message);
         const assistants = await detectAvailableAssistants(execFn);
-        if (assistants.length > 0) {
-            const chosenAssistant = assistants[0];
-            clack.log.info(ui.polishDetected(chosenAssistant));
-            const usePolish = await clack.confirm({ message: ui.polishConfirm(chosenAssistant) });
-            if (usePolish === true) {
-                const polished = await polishFilesWithAssistant(chosenAssistant, files, execFn, lang);
-                files.splice(0, files.length, ...polished);
+        const requested = options.assistant;
+        if (requested && !assistants.includes(requested)) {
+            console.warn(ui.assistantNotAvailable(requested));
+        }
+        else if (assistants.length === 0) {
+            if (wantsEnrich)
+                console.warn(ui.enrichNoAssistant);
+        }
+        else {
+            const chosenAssistant = requested ?? assistants[0];
+            let proceed = wantsEnrich;
+            if (!proceed) {
+                clack.log.info(ui.enrichDetected(chosenAssistant));
+                proceed = (await clack.confirm({ message: ui.enrichConfirm(chosenAssistant) })) === true;
+            }
+            if (proceed) {
+                const spinner = canOfferEnrich ? clack.spinner() : undefined;
+                if (spinner)
+                    spinner.start(ui.enrichWorking(chosenAssistant));
+                else
+                    notify(ui.enrichWorking(chosenAssistant));
+                const enriched = await enrichFilesWithAssistant(chosenAssistant, files, {
+                    execFn,
+                    lang,
+                    cwd: rootPath,
+                    mustKeep: facts.canonical.map((c) => c.command),
+                    existingDocs: readExistingDocs(rootPath),
+                    model: options.model,
+                });
+                const changed = enriched.some((file, i) => file.content !== files[i].content);
+                const outcome = changed ? ui.enrichDone : ui.enrichKept;
+                if (spinner)
+                    spinner.stop(outcome);
+                else
+                    notify(outcome);
+                files.splice(0, files.length, ...enriched);
             }
         }
     }
@@ -117,6 +168,9 @@ export async function runCli(rootPath, options = {}) {
 function isLang(value) {
     return value === "es" || value === "en";
 }
+function isAssistant(value) {
+    return value === "claude" || value === "codex";
+}
 export function resolveCliAction(argv) {
     const options = {};
     for (let i = 0; i < argv.length; i++) {
@@ -148,6 +202,24 @@ export function resolveCliAction(argv) {
             options.nonInteractive = true;
             continue;
         }
+        if (arg === "--enrich") {
+            options.enrich = true;
+            continue;
+        }
+        if (arg === "--assistant" || arg.startsWith("--assistant=")) {
+            const value = arg.startsWith("--assistant=") ? arg.slice("--assistant=".length) : argv[++i] ?? "";
+            if (!isAssistant(value))
+                return { kind: "invalid-assistant", value };
+            options.assistant = value;
+            continue;
+        }
+        if (arg === "--model" || arg.startsWith("--model=")) {
+            const value = arg.startsWith("--model=") ? arg.slice("--model=".length) : argv[++i] ?? "";
+            if (value === "")
+                return { kind: "missing-value", flag: "--model" };
+            options.model = value;
+            continue;
+        }
         return { kind: "unknown", flag: arg };
     }
     return { kind: "run", ...options };
@@ -183,9 +255,24 @@ export async function main() {
         process.exitCode = 1;
         return;
     }
+    if (action.kind === "invalid-assistant") {
+        console.error(`${ui.invalidAssistant(action.value)}\n\n${usageWithAutomationOptions(ui)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (action.kind === "missing-value") {
+        console.error(`${ui.missingFlagValue(action.flag)}\n\n${usageWithAutomationOptions(ui)}`);
+        process.exitCode = 1;
+        return;
+    }
     const machineOutput = action.json === true;
     const planningOnly = action.dryRun === true || action.check === true;
     const nonInteractive = action.nonInteractive === true || machineOutput || planningOnly;
+    // Enrichment output is non-deterministic, so --check (freshness comparison) must stay
+    // on the deterministic baseline.
+    const enrich = action.enrich === true && action.check !== true;
+    if (action.enrich === true && action.check === true)
+        console.warn("--enrich is ignored with --check.");
     if (!machineOutput)
         clack.intro("agent-rules-init");
     if (!machineOutput && !nonInteractive && !hasInteractiveTty()) {
@@ -206,7 +293,10 @@ export async function main() {
             config: loadedConfig.config,
             dryRun: planningOnly,
             nonInteractive,
-            skipLlm: nonInteractive,
+            skipLlm: nonInteractive && !enrich,
+            enrich,
+            assistant: action.assistant,
+            model: action.model,
             onGeneratedFiles: (files) => {
                 generatedFiles = files;
             },

package/dist/core/i18n.d.ts

@@ -28,13 +28,21 @@ export interface UiTexts {
     automationUsage: string;
     unknownOption: (flag: string) => string;
     invalidLang: (value: string) => string;
+    invalidAssistant: (value: string) => string;
+    missingFlagValue: (flag: string) => string;
+    assistantNotAvailable: (assistant: string) => string;
     noTtyWarning: string;
     skippedQuestion: (message: string) => string;
-    polishDetected: (assistant: string) => string;
-    polishConfirm: (assistant: string) => string;
-    polishFailed: (assistant: string, error: string) => string;
-    polishPrompt: (content: string) => string;
-    polishBatchPrompt: (filesJson: string) => string;
+    enrichDetected: (assistant: string) => string;
+    enrichConfirm: (assistant: string) => string;
+    enrichWorking: (assistant: string) => string;
+    enrichDone: string;
+    enrichKept: string;
+    enrichFailed: (assistant: string, error: string) => string;
+    enrichNoAssistant: string;
+    enrichEvidenceDropped: (paths: readonly string[]) => string;
+    enrichRetrying: (assistant: string) => string;
+    enrichPrompt: (filesJson: string, mustKeep: readonly string[], existingDocsJson?: string) => string;
     fileSkipped: (path: string) => string;
     outroWritten: string;
     outroNothing: string;

package/dist/core/i18n.js

@@ -75,6 +75,7 @@ export const UI = {
 
 Uso:
   npx agent-rules-init            escanea el directorio actual y genera los archivos *.generated.*
+  npx agent-rules-init --enrich   además, usa tu claude/codex instalado para analizar el código y enriquecer el resultado
   npx agent-rules-init --lang es  fuerza el idioma del contenido (es|en); por defecto se detecta del sistema
   npx agent-rules-init --help     muestra esta ayuda
   npx agent-rules-init --version  muestra la versión
@@ -85,17 +86,43 @@ revisa su contenido y quita el sufijo para activarlos.`,
   --dry-run         renderiza y muestra archivos sin escribir
   --check           termina con error si faltan archivos generados; nunca escribe
   --json            emite un único resultado JSON legible por máquinas
-  --non-interactive omite preguntas y el pulido con IA`,
+  --non-interactive omite preguntas y la oferta de enriquecimiento con IA
+  --enrich          fuerza el enriquecimiento con IA sin preguntar (también sin TTY; combinable con --non-interactive)
+  --assistant <id>  elige el asistente para enriquecer: claude o codex (por defecto, el primero instalado)
+  --model <modelo>  modelo a usar, pasado tal cual al asistente (p. ej. haiku, gpt-5.5); por defecto, el del asistente`,
         unknownOption: (flag) => `Opción no reconocida: ${flag}`,
         invalidLang: (value) => `Valor de --lang no válido: "${value}" (usa "es" o "en").`,
+        invalidAssistant: (value) => `Valor de --assistant no válido: "${value}" (usa "claude" o "codex").`,
+        missingFlagValue: (flag) => `La opción ${flag} requiere un valor.`,
+        assistantNotAvailable: (assistant) => `Se pidió ${assistant} con --assistant pero no está instalado; se conserva la versión generada.`,
         noTtyWarning: "No se detectó una terminal interactiva (esto pasa a veces en Git Bash en Windows). " +
-            "Continuando sin preguntas ni oferta de pulido con IA; se usarán los valores detectados.",
+            "Continuando sin preguntas ni oferta de enriquecimiento con IA; se usarán los valores detectados.",
         skippedQuestion: (message) => `No se detectó una terminal interactiva; se omite la pregunta "${message}" y se usa el valor detectado.`,
-        polishDetected: (assistant) => `${assistant} detectado — puede ayudar a pulir la redacción final.`,
-        polishConfirm: (assistant) => `Se detectó ${assistant}. ¿Quieres que pula la redacción final?`,
-        polishFailed: (assistant, error) => `No se pudo pulir el contenido con ${assistant}, se mantiene el original: ${error}`,
-        polishPrompt: (content) => `Pule la redacción del siguiente documento de instrucciones para un agente de IA, sin cambiar su significado ni estructura. Devuelve únicamente el documento pulido, sin comentarios ni explicaciones adicionales:\n\n${content}`,
-        polishBatchPrompt: (filesJson) => "Pule la redacción de estos archivos de instrucciones sin cambiar su significado, estructura, rutas ni formato Markdown. " +
+        enrichDetected: (assistant) => `${assistant} detectado — puede analizar el código de este repo y sustituir las secciones genéricas por reglas específicas verificadas.`,
+        enrichConfirm: (assistant) => `¿Quieres que ${assistant} analice el repositorio y enriquezca los archivos generados? Usará tu instalación de ${assistant} y puede tardar unos minutos.`,
+        enrichWorking: (assistant) => `${assistant} está analizando el repositorio y enriqueciendo los archivos…`,
+        enrichDone: "Archivos enriquecidos con lo observado en el repositorio.",
+        enrichKept: "No se aplicó el enriquecimiento; se conserva la versión generada.",
+        enrichFailed: (assistant, error) => `No se pudo enriquecer el contenido con ${assistant}, se mantiene la versión generada: ${error}`,
+        enrichNoAssistant: "Se pidió --enrich pero no se encontró ningún asistente (claude o codex) instalado; se conserva la versión generada.",
+        enrichEvidenceDropped: (paths) => `Se descartaron afirmaciones del enriquecimiento porque su evidencia citada no existe en el repo: ${paths.join(", ")}`,
+        enrichRetrying: (assistant) => `La respuesta de ${assistant} no pasó la validación; se reintenta una vez…`,
+        enrichPrompt: (filesJson, mustKeep, existingDocsJson) => "Estás ejecutándote en la raíz de un repositorio. Los siguientes archivos de instrucciones para agentes de IA " +
+            "se generaron solo a partir de manifiestos, CI y configuración, por lo que algunas secciones (convenciones, arquitectura, prompts) son genéricas.\n" +
+            "Primero investiga el repositorio real con tus herramientas de lectura: configuración de estilo (linter, formatter, pre-commit), " +
+            "CONTRIBUTING/README, y el código fuente y los tests suficientes para entender sus convenciones y arquitectura reales.\n" +
+            "Después reescribe cada archivo sustituyendo o ampliando los consejos genéricos con reglas específicas y comprobables de este repositorio, " +
+            "citando la evidencia de cada afirmación nueva con el formato (evidencia: `ruta/del/archivo`); las rutas citadas se verificarán contra el repo. " +
+            "No inventes comandos, rutas ni APIs; no afirmes nada que no hayas comprobado. " +
+            "Conserva el idioma, el formato Markdown y las rutas de cada archivo.\n" +
+            (mustKeep.length > 0
+                ? `Conserva literalmente estos comandos, sin modificarlos: ${mustKeep.map((c) => `\`${c}\``).join(", ")}.\n`
+                : "") +
+            (existingDocsJson
+                ? "El repositorio ya contiene estos documentos de instrucciones mantenidos a mano; reflejan la intención del equipo. " +
+                    "Integra sus reglas en los archivos generados correspondientes sin contradecirlas ni perderlas.\n" +
+                    `Documentos existentes (JSON):\n${existingDocsJson}\n`
+                : "") +
             "Devuelve únicamente un array JSON válido con exactamente los mismos objetos path/content y en el mismo orden, sin bloque de código ni comentarios. " +
             `Entrada JSON:\n${filesJson}`,
         fileSkipped: (path) => `${path}: ya existía, se conserva sin cambios.`,
@@ -151,6 +178,7 @@ revisa su contenido y quita el sufijo para activarlos.`,
 
 Usage:
   npx agent-rules-init            scan the current directory and generate the *.generated.* files
+  npx agent-rules-init --enrich   additionally, use your installed claude/codex to analyze the code and enrich the output
   npx agent-rules-init --lang en  force the content language (es|en); defaults to the system locale
   npx agent-rules-init --help     show this help
   npx agent-rules-init --version  show the version
@@ -161,17 +189,43 @@ review their content and drop the suffix to activate them.`,
   --dry-run         render and print files without writing
   --check           exit non-zero if generated files are missing; never write
   --json            emit a single machine-readable JSON result
-  --non-interactive skip questions and AI polishing`,
+  --non-interactive skip questions and the AI-enrichment offer
+  --enrich          force AI enrichment without asking (works without a TTY; composable with --non-interactive)
+  --assistant <id>  pick the enrichment assistant: claude or codex (defaults to the first one installed)
+  --model <model>   model to use, forwarded verbatim to the assistant (e.g. haiku, gpt-5.5); defaults to the assistant's own`,
         unknownOption: (flag) => `Unknown option: ${flag}`,
         invalidLang: (value) => `Invalid --lang value: "${value}" (use "es" or "en").`,
+        invalidAssistant: (value) => `Invalid --assistant value: "${value}" (use "claude" or "codex").`,
+        missingFlagValue: (flag) => `The ${flag} option requires a value.`,
+        assistantNotAvailable: (assistant) => `${assistant} was requested with --assistant but is not installed; keeping the generated version.`,
         noTtyWarning: "No interactive terminal detected (this sometimes happens in Git Bash on Windows). " +
-            "Continuing without questions or the AI-polish offer; detected values will be used.",
+            "Continuing without questions or the AI-enrichment offer; detected values will be used.",
         skippedQuestion: (message) => `No interactive terminal detected; skipping the question "${message}" and using the detected value.`,
-        polishDetected: (assistant) => `${assistant} detected — it can help polish the final wording.`,
-        polishConfirm: (assistant) => `${assistant} was detected. Do you want it to polish the final wording?`,
-        polishFailed: (assistant, error) => `Couldn't polish the content with ${assistant}, keeping the original: ${error}`,
-        polishPrompt: (content) => `Polish the wording of the following instructions document for an AI agent, without changing its meaning or structure. Return only the polished document, with no extra comments or explanations:\n\n${content}`,
-        polishBatchPrompt: (filesJson) => "Polish the wording of these instruction files without changing their meaning, structure, paths, or Markdown format. " +
+        enrichDetected: (assistant) => `${assistant} detected — it can analyze this repo's code and replace the generic sections with verified, repo-specific rules.`,
+        enrichConfirm: (assistant) => `Do you want ${assistant} to analyze the repository and enrich the generated files? It will use your ${assistant} installation and may take a few minutes.`,
+        enrichWorking: (assistant) => `${assistant} is analyzing the repository and enriching the files…`,
+        enrichDone: "Files enriched with what was observed in the repository.",
+        enrichKept: "Enrichment was not applied; keeping the generated version.",
+        enrichFailed: (assistant, error) => `Couldn't enrich the content with ${assistant}, keeping the generated version: ${error}`,
+        enrichNoAssistant: "--enrich was requested but no installed assistant (claude or codex) was found; keeping the generated version.",
+        enrichEvidenceDropped: (paths) => `Dropped enrichment claims because their cited evidence does not exist in the repo: ${paths.join(", ")}`,
+        enrichRetrying: (assistant) => `${assistant}'s response failed validation; retrying once…`,
+        enrichPrompt: (filesJson, mustKeep, existingDocsJson) => "You are running at the root of a repository. The following instruction files for AI agents were generated " +
+            "from manifests, CI and configuration only, so some sections (conventions, architecture, prompts) are generic.\n" +
+            "First investigate the actual repository with your read tools: style configuration (linter, formatter, pre-commit), " +
+            "CONTRIBUTING/README, and enough of the source code and tests to understand its real conventions and architecture.\n" +
+            "Then rewrite each file, replacing or extending the generic advice with specific, verifiable rules from this repository, " +
+            "citing the evidence for every new claim in the form (evidence: `path/to/file`); cited paths will be checked against the repo. " +
+            "Do not invent commands, paths or APIs; do not state anything you have not verified. " +
+            "Keep each file's language, Markdown format and path.\n" +
+            (mustKeep.length > 0
+                ? `Keep these commands verbatim, unmodified: ${mustKeep.map((c) => `\`${c}\``).join(", ")}.\n`
+                : "") +
+            (existingDocsJson
+                ? "The repository already contains these hand-maintained instruction documents; they reflect the team's intent. " +
+                    "Integrate their rules into the corresponding generated files without contradicting or losing them.\n" +
+                    `Existing documents (JSON):\n${existingDocsJson}\n`
+                : "") +
             "Return only a valid JSON array with exactly the same path/content objects in the same order, without a code fence or commentary. " +
             `Input JSON:\n${filesJson}`,
         fileSkipped: (path) => `${path}: already existed, left unchanged.`,

package/dist/core/llm-bridge.d.ts

@@ -5,9 +5,24 @@ export interface ExecResult {
     stdout: string;
     exitCode: number;
 }
-export type ExecFn = (command: string, args: string[], stdin?: string) => Promise<ExecResult>;
+export type ExecFn = (command: string, args: string[], stdin?: string, cwd?: string) => Promise<ExecResult>;
 export declare const defaultExecFn: ExecFn;
 export declare function detectAvailableAssistants(execFn?: ExecFn): Promise<AssistantId[]>;
-export declare function polishWithAssistant(assistant: AssistantId, content: string, execFn?: ExecFn, lang?: Lang): Promise<string>;
-/** Polishes typical runs in one assistant process, splitting only very large outputs. */
-export declare function polishFilesWithAssistant(assistant: AssistantId, files: GeneratedFile[], execFn?: ExecFn, lang?: Lang): Promise<GeneratedFile[]>;
+export interface EnrichOptions {
+    execFn?: ExecFn;
+    lang?: Lang;
+    /** Repo root where the assistant is spawned so its read tools explore the right project. */
+    cwd?: string;
+    /** Commands that must survive verbatim (canonical test/lint/build commands). */
+    mustKeep?: readonly string[];
+    /** Hand-maintained docs already in the repo (CLAUDE.md, AGENTS.md, …) to integrate, not contradict. */
+    existingDocs?: readonly GeneratedFile[];
+    /** Model identifier forwarded verbatim to the assistant CLI; its default when omitted. */
+    model?: string;
+}
+/**
+ * Asks the assistant to investigate the repository it runs in and rewrite the generated
+ * files with repo-specific, evidence-backed guidance. Typical runs use one assistant
+ * process; only very large outputs are split. Falls back to the originals per batch.
+ */
+export declare function enrichFilesWithAssistant(assistant: AssistantId, files: GeneratedFile[], options?: EnrichOptions): Promise<GeneratedFile[]>;

package/dist/core/llm-bridge.js

@@ -1,18 +1,41 @@
 import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 import { UI } from "./i18n.js";
 const VERSION_ARGS = {
     claude: ["--version"],
     codex: ["--version"],
 };
-export const defaultExecFn = (command, args, stdin) => new Promise((resolve, reject) => {
+// Non-interactive invocation per assistant. claude reads the prompt from stdin with -p;
+// codex has no -p: its non-interactive mode is `codex exec`, where "-" reads the
+// instructions from stdin. Without --skip-git-repo-check codex refuses to run in
+// directories that aren't a git repo; enrichment is read-only, so skipping is safe
+// (verified against codex-cli 0.130.0). The model string is passed through untouched —
+// the assistant validates it, so new models need no package update.
+function printArgs(assistant, model) {
+    const modelArgs = model ? ["--model", model] : [];
+    if (assistant === "claude")
+        return ["-p", ...modelArgs];
+    return ["exec", "--skip-git-repo-check", ...modelArgs, "-"];
+}
+// A hung assistant (expired session, dead network) must not hang the CLI forever;
+// 10 minutes comfortably covers real enrichment runs, and on expiry the rejection
+// lands in the normal fallback path that keeps the deterministic files.
+const EXEC_TIMEOUT_MS = 600_000;
+export const defaultExecFn = (command, args, stdin, cwd) => new Promise((resolve, reject) => {
     // shell:true is only needed on Windows, to resolve npm-installed .cmd/.ps1 shims.
-    const child = spawn(command, args, { shell: process.platform === "win32" });
+    // cwd matters for enrichment: the assistant explores the repo it runs in with its
+    // own read tools, so it must be spawned at the target repo root, not wherever the
+    // CLI process happens to live.
+    const child = spawn(command, args, { shell: process.platform === "win32", cwd, timeout: EXEC_TIMEOUT_MS });
     let stdout = "";
     child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
     child.on("error", reject);
     child.on("close", (exitCode) => {
         if (exitCode === 0)
             resolve({ stdout, exitCode });
+        else if (child.killed)
+            reject(new Error(`${command} timed out after ${EXEC_TIMEOUT_MS / 1000}s`));
         else
             reject(new Error(`${command} exited with code ${exitCode}`));
     });
@@ -35,24 +58,14 @@ export async function detectAvailableAssistants(execFn = defaultExecFn) {
     }));
     return results.filter((id) => id !== null);
 }
-export async function polishWithAssistant(assistant, content, execFn = defaultExecFn, lang = "es") {
-    try {
-        const result = await execFn(assistant, ["-p"], UI[lang].polishPrompt(content));
-        return result.stdout.trim() || content;
-    }
-    catch (err) {
-        console.warn(UI[lang].polishFailed(assistant, err.message));
-        return content;
-    }
-}
-const MAX_POLISH_BATCH_CHARS = 60_000;
+const MAX_BATCH_CHARS = 60_000;
 function makeBatches(files) {
     const batches = [];
     let current = [];
     let currentSize = 2;
     for (const file of files) {
         const size = JSON.stringify(file).length + 1;
-        if (current.length > 0 && currentSize + size > MAX_POLISH_BATCH_CHARS) {
+        if (current.length > 0 && currentSize + size > MAX_BATCH_CHARS) {
             batches.push(current);
             current = [];
             currentSize = 2;
@@ -64,10 +77,24 @@ function makeBatches(files) {
         batches.push(current);
     return batches;
 }
-function parsePolishedBatch(stdout, originals) {
+// Despite being told to return only JSON, assistants often prepend prose ("I investigated
+// the repo and...") or wrap the array in a fence. Try the strict forms first and fall back
+// to the outermost [...] slice; path/count validation below rejects any wrong pick.
+function extractJsonArray(stdout) {
     const trimmed = stdout.trim();
-    const withoutFence = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)?.[1] ?? trimmed;
-    const parsed = JSON.parse(withoutFence);
+    if (trimmed.startsWith("["))
+        return trimmed;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i)?.[1];
+    if (fenced?.trim().startsWith("["))
+        return fenced;
+    const start = trimmed.indexOf("[");
+    const end = trimmed.lastIndexOf("]");
+    if (start !== -1 && end > start)
+        return trimmed.slice(start, end + 1);
+    return trimmed;
+}
+function parseAssistantBatch(stdout, originals) {
+    const parsed = JSON.parse(extractJsonArray(stdout));
     if (!Array.isArray(parsed) || parsed.length !== originals.length) {
         throw new Error("assistant returned a different number of files");
     }
@@ -81,19 +108,92 @@ function parsePolishedBatch(stdout, originals) {
         return { path: originals[index].path, content: entry.content };
     });
 }
-/** Polishes typical runs in one assistant process, splitting only very large outputs. */
-export async function polishFilesWithAssistant(assistant, files, execFn = defaultExecFn, lang = "es") {
-    const polished = [];
-    for (const batch of makeBatches(files)) {
-        try {
-            const input = UI[lang].polishBatchPrompt(JSON.stringify(batch));
-            const result = await execFn(assistant, ["-p"], input);
-            polished.push(...parsePolishedBatch(result.stdout, batch));
+// The assistant is free-form: it may drop the one command CI actually runs and invent a
+// plausible replacement. Any lost must-keep command invalidates the whole batch.
+function assertMustKeepSurvive(enriched, originals, mustKeep) {
+    const originalText = originals.map((f) => f.content).join("\n");
+    const enrichedText = enriched.map((f) => f.content).join("\n");
+    for (const command of mustKeep) {
+        if (originalText.includes(command) && !enrichedText.includes(command)) {
+            throw new Error(`assistant dropped a canonical command: ${command}`);
         }
-        catch (err) {
-            console.warn(UI[lang].polishFailed(assistant, err.message));
-            polished.push(...batch);
+    }
+}
+const EVIDENCE_GROUP = /\((?:evidencia|evidence):([^)]*)\)/gi;
+// A checkable citation is a plain relative path; tokens with spaces, URLs or globs are
+// left alone rather than guessed at.
+const PATH_TOKEN = /^[\w.@~-]+(?:[\\/][\w.@~-]+)*[\\/]?$/;
+function checkableCitedPaths(line) {
+    const paths = [];
+    for (const group of line.matchAll(EVIDENCE_GROUP)) {
+        for (const token of group[1].matchAll(/`([^`]+)`/g)) {
+            // Normalize `src/app.py:12` and `pyproject.toml [tool.ruff]` down to the file path.
+            const normalized = token[1].replace(/:\d+(?:-\d+)?$/, "").replace(/\s*\[[^\]]*\]$/, "").trim();
+            if (PATH_TOKEN.test(normalized))
+                paths.push(normalized);
+        }
+    }
+    return paths;
+}
+// Cited evidence is the enrichment's core promise, so it gets checked against the repo:
+// a claim whose cited files all fail to exist is unverifiable. Bullet claims are dropped;
+// prose lines are kept (removing them would mangle paragraphs) but still reported.
+function dropUnverifiableClaims(files, rootPath) {
+    const missing = new Set();
+    const checked = files.map((file) => {
+        const kept = file.content.split("\n").filter((line) => {
+            const cited = checkableCitedPaths(line);
+            if (cited.length === 0)
+                return true;
+            if (cited.some((p) => fs.existsSync(path.join(rootPath, p))))
+                return true;
+            for (const p of cited)
+                missing.add(p);
+            return !/^\s*[-*] /.test(line);
+        });
+        return { path: file.path, content: kept.join("\n") };
+    });
+    return { files: checked, missing: [...missing] };
+}
+/**
+ * Asks the assistant to investigate the repository it runs in and rewrite the generated
+ * files with repo-specific, evidence-backed guidance. Typical runs use one assistant
+ * process; only very large outputs are split. Falls back to the originals per batch.
+ */
+export async function enrichFilesWithAssistant(assistant, files, options = {}) {
+    const { execFn = defaultExecFn, lang = "es", cwd, mustKeep = [], existingDocs = [], model } = options;
+    const existingDocsJson = existingDocs.length > 0 ? JSON.stringify(existingDocs) : undefined;
+    const enriched = [];
+    for (const batch of makeBatches(files)) {
+        const input = UI[lang].enrichPrompt(JSON.stringify(batch), mustKeep, existingDocsJson);
+        // Contract violations (invalid JSON, changed paths, dropped commands) are stochastic,
+        // especially with smaller models; one bounded retry recovers most of them.
+        let attemptsLeft = 2;
+        while (attemptsLeft > 0) {
+            attemptsLeft--;
+            try {
+                const result = await execFn(assistant, printArgs(assistant, model), input, cwd);
+                let parsed = parseAssistantBatch(result.stdout, batch);
+                assertMustKeepSurvive(parsed, batch, mustKeep);
+                if (cwd) {
+                    const verified = dropUnverifiableClaims(parsed, cwd);
+                    if (verified.missing.length > 0)
+                        console.warn(UI[lang].enrichEvidenceDropped(verified.missing));
+                    parsed = verified.files;
+                }
+                enriched.push(...parsed);
+                break;
+            }
+            catch (err) {
+                if (attemptsLeft > 0) {
+                    console.warn(UI[lang].enrichRetrying(assistant));
+                }
+                else {
+                    console.warn(UI[lang].enrichFailed(assistant, err.message));
+                    enriched.push(...batch);
+                }
+            }
         }
     }
-    return polished;
+    return enriched;
 }

package/dist/core/repo-facts.d.ts

@@ -1,8 +1,6 @@
 import { type Lang } from "./i18n.js";
 import type { CiCommand, ArchitectureFact, CommandEntry, CommandSource, ConventionFact, DirEntry, RepoFacts, RepoSignals } from "./types.js";
 export declare function extractJsPackageCommands(signals: RepoSignals): CommandEntry[];
-/** @deprecated Conservado como alias de API; también devuelve comandos pnpm/Yarn/Bun. */
-export declare const extractNpmCommands: typeof extractJsPackageCommands;
 export declare function extractMakeTargets(signals: RepoSignals): CommandEntry[];
 export declare function extractMixAliases(signals: RepoSignals): CommandEntry[];
 export declare function extractToxEnvs(signals: RepoSignals): CommandEntry[];

package/dist/core/repo-facts.js

@@ -28,8 +28,6 @@ export function extractJsPackageCommands(signals) {
     }
     return entries;
 }
-/** @deprecated Conservado como alias de API; también devuelve comandos pnpm/Yarn/Bun. */
-export const extractNpmCommands = extractJsPackageCommands;
 function jsScriptInvocation(manager, packageDir, script) {
     const name = quoteShellArg(script);
     if (manager === "npm") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-rules-init",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Generates CLAUDE.md, AGENTS.md, copilot-instructions.md and prompt files from what your repo actually is.",
   "license": "MIT",
   "type": "module",
@@ -45,6 +45,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@types/node": "^18.19.130",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   }