agent-rules-init 0.3.0 → 0.5.0

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,13 +58,142 @@ 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;
+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_BATCH_CHARS) {
+            batches.push(current);
+            current = [];
+            currentSize = 2;
+        }
+        current.push(file);
+        currentSize += size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+// 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();
+    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");
     }
-    catch (err) {
-        console.warn(UI[lang].polishFailed(assistant, err.message));
-        return content;
+    return parsed.map((value, index) => {
+        if (!value || typeof value !== "object")
+            throw new Error("assistant returned an invalid file entry");
+        const entry = value;
+        if (entry.path !== originals[index].path || typeof entry.content !== "string") {
+            throw new Error("assistant changed a path or returned invalid content");
+        }
+        return { path: originals[index].path, content: entry.content };
+    });
+}
+// 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}`);
+        }
+    }
+}
+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 enriched;
 }

package/dist/core/project-unit-output.d.ts

@@ -0,0 +1,13 @@
+import type { Lang } from "./i18n.js";
+import type { ProjectUnit } from "./project-units.js";
+export interface ProjectOverrides {
+    framework?: string;
+    testRunner?: string;
+    linter?: string;
+    packageManager?: string;
+}
+/** Generates the path-scoped AGENTS file for one JS/TS package. */
+export declare function renderProjectUnitAgents(unit: ProjectUnit, lang: Lang, overrides?: ProjectOverrides): {
+    path: string;
+    content: string;
+} | null;

package/dist/core/project-unit-output.js

@@ -0,0 +1,25 @@
+import { buildRepoFacts } from "./repo-facts.js";
+import { renderAgentsMd } from "./templates.js";
+import { jsTsPack } from "../packs/js-ts.js";
+function applyOverrides(detection, overrides) {
+    const updated = { ...detection };
+    for (const field of ["framework", "testRunner", "linter", "packageManager"]) {
+        const value = overrides[field];
+        if (value)
+            updated[field] = { value, confidence: "high" };
+    }
+    return updated;
+}
+/** Generates the path-scoped AGENTS file for one JS/TS package. */
+export function renderProjectUnitAgents(unit, lang, overrides = {}) {
+    const rawDetection = jsTsPack.detect(unit.signals);
+    if (!rawDetection)
+        return null;
+    const detection = applyOverrides(rawDetection, overrides);
+    const facts = buildRepoFacts(unit.signals, lang);
+    const ruleSet = jsTsPack.rules(detection, lang, { facts, signals: unit.signals });
+    return {
+        path: `${unit.path}/AGENTS.generated.md`,
+        content: renderAgentsMd([{ detection, ruleSet }], facts, lang),
+    };
+}

package/dist/core/project-units.d.ts

@@ -0,0 +1,16 @@
+import type { RepoSignals } from "./types.js";
+export interface ProjectUnit {
+    /** POSIX path relative to the repository root. */
+    path: string;
+    signals: RepoSignals;
+}
+export declare function isProjectExcluded(projectPath: string, patterns: readonly string[]): boolean;
+/** Removes excluded JS packages before repo-wide aggregation and scoped rendering. */
+export declare function applyProjectExcludes(signals: RepoSignals, patterns: readonly string[]): RepoSignals;
+/**
+ * Creates an isolated RepoSignals view for every nested JS/TS package.
+ *
+ * Files and presence checks become relative to the package, so packs can run without
+ * learning workspace-specific rules and cannot accidentally use a sibling's stack.
+ */
+export declare function buildPackageUnits(signals: RepoSignals): ProjectUnit[];

package/dist/core/project-units.js

@@ -0,0 +1,95 @@
+import path from "node:path";
+function normalize(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+function matchesPattern(projectPath, rawPattern) {
+    const value = normalize(projectPath);
+    const pattern = normalize(rawPattern);
+    if (!pattern)
+        return false;
+    if (pattern.endsWith("/**") && value === pattern.slice(0, -3))
+        return true;
+    const marker = "\u0000";
+    const regex = pattern
+        .replace(/\*\*/g, marker)
+        .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*")
+        .replace(new RegExp(marker, "g"), ".*");
+    return new RegExp(`^${regex}$`).test(value);
+}
+export function isProjectExcluded(projectPath, patterns) {
+    return patterns.some((pattern) => matchesPattern(projectPath, pattern));
+}
+/** Removes excluded JS packages before repo-wide aggregation and scoped rendering. */
+export function applyProjectExcludes(signals, patterns) {
+    if (patterns.length === 0 || !signals.packageJsons?.length)
+        return signals;
+    const packageJsons = signals.packageJsons.filter((manifest) => {
+        const packageDir = path.posix.dirname(manifest.path);
+        return packageDir === "." || !isProjectExcluded(packageDir, patterns);
+    });
+    const excludedDirs = (signals.packageJsons ?? [])
+        .map((manifest) => path.posix.dirname(manifest.path))
+        .filter((dir) => dir !== "." && isProjectExcluded(dir, patterns));
+    const isExcludedPath = (relativePath) => {
+        const normalized = normalize(relativePath);
+        return excludedDirs.some((dir) => normalized === dir || normalized.startsWith(`${dir}/`));
+    };
+    const primary = packageJsons[0];
+    const packageJson = primary
+        ? {
+            name: primary.name,
+            main: primary.main,
+            dependencies: Object.assign({}, ...packageJsons.map((manifest) => manifest.dependencies)),
+            devDependencies: Object.assign({}, ...packageJsons.map((manifest) => manifest.devDependencies)),
+            scripts: primary.scripts,
+            moduleType: primary.moduleType,
+            packageManager: primary.packageManager,
+        }
+        : undefined;
+    return {
+        ...signals,
+        files: signals.files.filter((file) => !isExcludedPath(file)),
+        hasFile: (relativePath) => !isExcludedPath(relativePath) && signals.hasFile(relativePath),
+        hasDir: (relativeDir) => !isExcludedPath(relativeDir) && signals.hasDir(relativeDir),
+        packageJson,
+        packageJsons,
+    };
+}
+function withoutLocation(manifest) {
+    const { path: _path, ...packageJson } = manifest;
+    return packageJson;
+}
+/**
+ * Creates an isolated RepoSignals view for every nested JS/TS package.
+ *
+ * Files and presence checks become relative to the package, so packs can run without
+ * learning workspace-specific rules and cannot accidentally use a sibling's stack.
+ */
+export function buildPackageUnits(signals) {
+    return (signals.packageJsons ?? [])
+        .filter((manifest) => manifest.path !== "package.json")
+        .map((manifest) => {
+        const unitPath = path.posix.dirname(manifest.path);
+        const prefix = `${unitPath}/`;
+        const unitFiles = signals.files
+            .map((file) => file.split(path.sep).join("/"))
+            .filter((file) => file.startsWith(prefix))
+            .map((file) => file.slice(prefix.length));
+        const packageJson = withoutLocation(manifest);
+        return {
+            path: unitPath,
+            signals: {
+                rootPath: path.join(signals.rootPath, ...unitPath.split("/")),
+                files: unitFiles,
+                hasFile: (relativePath) => signals.hasFile(`${prefix}${relativePath}`),
+                hasDir: (relativeDir) => signals.hasDir(`${prefix}${relativeDir}`),
+                packageJson,
+                packageJsons: [{ ...packageJson, path: "package.json" }],
+                guidanceFiles: (signals.guidanceFiles ?? [])
+                    .filter((file) => file.path.startsWith(prefix))
+                    .map((file) => ({ ...file, path: file.path.slice(prefix.length) })),
+            },
+        };
+    });
+}

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

@@ -1,6 +1,6 @@
 import { type Lang } from "./i18n.js";
-import type { CiCommand, CommandEntry, CommandSource, DirEntry, RepoFacts, RepoSignals } from "./types.js";
-export declare function extractNpmCommands(signals: RepoSignals): CommandEntry[];
+import type { CiCommand, ArchitectureFact, CommandEntry, CommandSource, ConventionFact, DirEntry, RepoFacts, RepoSignals } from "./types.js";
+export declare function extractJsPackageCommands(signals: RepoSignals): CommandEntry[];
 export declare function extractMakeTargets(signals: RepoSignals): CommandEntry[];
 export declare function extractMixAliases(signals: RepoSignals): CommandEntry[];
 export declare function extractToxEnvs(signals: RepoSignals): CommandEntry[];
@@ -17,4 +17,12 @@ export declare function extractCiCommands(signals: RepoSignals): {
     omittedCount: number;
 };
 export declare function extractStructure(signals: RepoSignals, lang: Lang): DirEntry[];
+export declare function detectTestDirs(files: string[]): string[];
+export declare function detectEntrypoints(signals: RepoSignals): RepoFacts["entrypoints"];
+export declare function extractArchitectureFacts(signals: RepoSignals, lang: Lang, testDirs?: string[], entrypoints?: {
+    label: string;
+    target: string;
+    source: string;
+}[]): ArchitectureFact[];
+export declare function extractConventionFacts(signals: RepoSignals, lang: Lang): ConventionFact[];
 export declare function buildRepoFacts(signals: RepoSignals, lang: Lang): RepoFacts;

package/dist/core/repo-facts.js

@@ -1,21 +1,53 @@
 import path from "node:path";
 import { parse } from "yaml";
 import { UI } from "./i18n.js";
+import { selectCanonicalCommands } from "./canonical-commands.js";
 const NPM_DIRECT_LIFECYCLE = new Set(["test", "start", "stop", "restart"]);
-export function extractNpmCommands(signals) {
-    const scripts = signals.packageJson?.scripts ?? {};
+export function extractJsPackageCommands(signals) {
     const entries = [];
-    for (const [name, body] of Object.entries(scripts)) {
-        if (typeof body !== "string" || body.trim() === "")
-            continue;
-        entries.push({
-            source: "npm",
-            invocation: NPM_DIRECT_LIFECYCLE.has(name) ? `npm ${name}` : `npm run ${name}`,
-            detail: body.trim(),
-        });
+    const locatedManifests = signals.packageJsons ?? [];
+    const hasLocatedManifests = locatedManifests.length > 0;
+    const manifests = hasLocatedManifests
+        ? locatedManifests
+        : signals.packageJson
+            ? [{ ...signals.packageJson, path: "package.json" }]
+            : [];
+    for (const manifest of manifests) {
+        const packageDir = path.posix.dirname(manifest.path);
+        const manager = manifest.packageManager ?? signals.packageJson?.packageManager ?? "npm";
+        for (const [name, body] of Object.entries(manifest.scripts)) {
+            if (typeof body !== "string" || body.trim() === "")
+                continue;
+            entries.push({
+                source: manager,
+                invocation: jsScriptInvocation(manager, packageDir, name),
+                detail: body.trim(),
+                ...(hasLocatedManifests ? { manifestPath: manifest.path } : {}),
+            });
+        }
     }
     return entries;
 }
+function jsScriptInvocation(manager, packageDir, script) {
+    const name = quoteShellArg(script);
+    if (manager === "npm") {
+        const prefix = packageDir === "." ? "npm" : `npm --prefix ${quoteShellArg(packageDir)}`;
+        return NPM_DIRECT_LIFECYCLE.has(script) ? `${prefix} ${name}` : `${prefix} run ${name}`;
+    }
+    if (manager === "pnpm") {
+        const prefix = packageDir === "." ? "pnpm" : `pnpm --dir ${quoteShellArg(packageDir)}`;
+        return NPM_DIRECT_LIFECYCLE.has(script) ? `${prefix} ${name}` : `${prefix} run ${name}`;
+    }
+    if (manager === "yarn") {
+        const prefix = packageDir === "." ? "yarn" : `yarn --cwd ${quoteShellArg(packageDir)}`;
+        return `${prefix} run ${name}`;
+    }
+    const prefix = packageDir === "." ? "bun" : `bun --cwd ${quoteShellArg(packageDir)}`;
+    return `${prefix} run ${name}`;
+}
+function quoteShellArg(value) {
+    return /\s/.test(value) ? JSON.stringify(value) : value;
+}
 export function extractMakeTargets(signals) {
     const makefile = signals.makefile;
     if (!makefile)
@@ -178,9 +210,190 @@ export function extractStructure(signals, lang) {
         return note ? { dir: `${dir}/`, note } : { dir: `${dir}/` };
     });
 }
+const TEST_DIR_NAMES = new Set(["test", "tests", "spec", "specs", "__tests__"]);
+const MEANINGFUL_TEST_CHILDREN = new Set(["acceptance", "integration", "unit", "e2e"]);
+const AUXILIARY_FACT_DIRS = new Set([
+    "docs", "doc", "tools", "tool", "scripts", "script", "examples", "example",
+    "benchmark", "benchmarks", "fixture", "fixtures",
+]);
+function isAuxiliaryFactPath(file) {
+    return file.split(/[\\/]/).some((segment) => AUXILIARY_FACT_DIRS.has(segment.toLowerCase()));
+}
+export function detectTestDirs(files) {
+    const dirs = new Set();
+    for (const file of files) {
+        const segments = file.split(/[\\/]/).slice(0, -1);
+        for (let i = 0; i < segments.length; i++) {
+            if (TEST_DIR_NAMES.has(segments[i].toLowerCase())) {
+                dirs.add(segments.slice(0, i + 1).join("/") + "/");
+                // Solo conserva sublayouts inequívocos. Directorios como tests/static o
+                // tests/templates suelen ser fixtures, no ubicaciones independientes de tests.
+                const child = segments[i + 1]?.toLowerCase();
+                const languageLayout = segments[0]?.toLowerCase() === "src" && segments[1]?.toLowerCase() === "test";
+                if (child && (languageLayout || MEANINGFUL_TEST_CHILDREN.has(child))) {
+                    dirs.add(segments.slice(0, i + 2).join("/") + "/");
+                }
+                break;
+            }
+        }
+    }
+    return [...dirs].sort();
+}
+export function detectEntrypoints(signals) {
+    const out = [];
+    if (signals.packageJson?.main) {
+        out.push({ label: "main", target: signals.packageJson.main, source: "package.json" });
+    }
+    const scriptsSection = signals.pyprojectToml?.match(/\[project\.scripts\]([\s\S]*?)(?:\n\[|$)/)?.[1];
+    if (scriptsSection) {
+        for (const match of scriptsSection.matchAll(/^\s*([\w.-]+)\s*=\s*["']([^"']+)["']/gm)) {
+            out.push({ label: match[1], target: match[2], source: "pyproject.toml" });
+        }
+    }
+    return out;
+}
+function evidencePath(file) {
+    return file.split(path.sep).join("/");
+}
+export function extractArchitectureFacts(signals, lang, testDirs = detectTestDirs(signals.files.filter((file) => !isAuxiliaryFactPath(file))), entrypoints = detectEntrypoints(signals)) {
+    const facts = [];
+    const normalized = signals.files.filter((file) => !isAuxiliaryFactPath(file)).map(evidencePath);
+    const add = (fact) => facts.push({ ...fact, scope: ".", confidence: "high" });
+    if (entrypoints.length > 0) {
+        const rendered = entrypoints.map((entry) => `${entry.label} -> ${entry.target}`).join(", ");
+        add({
+            kind: "entrypoint",
+            statement: lang === "es" ? `Puntos de entrada declarados: ${rendered}.` : `Declared entry points: ${rendered}.`,
+            evidence: [...new Set(entrypoints.map((entry) => entry.source))],
+        });
+    }
+    if (testDirs.length > 0) {
+        const testEvidence = [...new Set(testDirs.map((dir) => {
+                const directory = dir.replace(/\/$/, "");
+                return signals.hasDir(directory) ? dir : normalized.find((file) => file.startsWith(dir));
+            }).filter((f) => Boolean(f)))];
+        add({
+            kind: "tests",
+            statement: lang === "es"
+                ? `Los tests se colocan en ${testDirs.join(", ")}.`
+                : `Tests are placed under ${testDirs.join(", ")}.`,
+            evidence: testEvidence,
+        });
+    }
+    const sourceRoots = ["src", "lib"].filter((dir) => signals.hasDir(dir) || normalized.some((file) => file.startsWith(`${dir}/`)));
+    const sourceLocations = sourceRoots.flatMap((dir) => dir === "src" && signals.hasDir("src/main") ? ["src/main/"] : [`${dir}/`]);
+    if (sourceLocations.length > 0) {
+        add({
+            kind: "source-layout",
+            statement: lang === "es"
+                ? `El código principal vive en ${sourceLocations.join(", ")}.`
+                : `Primary source code lives under ${sourceLocations.join(", ")}.`,
+            evidence: sourceLocations.map((location) => {
+                const directory = location.replace(/\/$/, "");
+                return signals.hasDir(directory) ? location : normalized.find((file) => file.startsWith(location));
+            }).filter(Boolean),
+        });
+    }
+    const layerPatterns = [
+        ["controller", /(?:^|\/)(?:controllers?)(?:\/|$)/i],
+        ["service", /(?:^|\/)(?:services?)(?:\/|$)/i],
+        ["repository", /(?:^|\/)(?:repositories|repository)(?:\/|$)/i],
+    ];
+    const layers = layerPatterns.map(([name, pattern]) => ({ name, file: normalized.find((file) => pattern.test(file)) }));
+    if (layers.every((layer) => layer.file)) {
+        add({
+            kind: "layers",
+            statement: lang === "es"
+                ? "El repositorio separa controller, service y repository en capas distintas."
+                : "The repository separates controller, service and repository into distinct layers.",
+            evidence: layers.map((layer) => layer.file),
+        });
+    }
+    const workspaceManifests = (signals.packageJsons ?? []).filter((manifest) => manifest.path !== "package.json");
+    if (workspaceManifests.length > 0) {
+        add({
+            kind: "workspace",
+            statement: lang === "es"
+                ? `El workspace contiene ${workspaceManifests.length} paquete(s) JavaScript/TypeScript anidado(s).`
+                : `The workspace contains ${workspaceManifests.length} nested JavaScript/TypeScript package(s).`,
+            evidence: workspaceManifests.map((manifest) => manifest.path),
+        });
+    }
+    return facts;
+}
+function uniqueConfigValue(content, key) {
+    const values = [...content.matchAll(new RegExp(`^\\s*${key}\\s*=\\s*([^#;\\r\\n]+)`, "gmi"))]
+        .map((match) => match[1].trim().toLowerCase());
+    const unique = [...new Set(values)];
+    return unique.length === 1 ? unique[0] : undefined;
+}
+export function extractConventionFacts(signals, lang) {
+    const facts = [];
+    const rootFiles = (signals.guidanceFiles ?? []).filter((file) => !evidencePath(file.path).includes("/"));
+    const get = (name) => rootFiles.find((file) => file.path.toLowerCase() === name.toLowerCase())?.content;
+    const add = (fact) => facts.push({ ...fact, scope: ".", confidence: "high" });
+    const editorConfig = get(".editorconfig");
+    if (editorConfig) {
+        const style = uniqueConfigValue(editorConfig, "indent_style");
+        const rawSize = uniqueConfigValue(editorConfig, "indent_size");
+        const size = rawSize && /^\d+$/.test(rawSize) ? rawSize : undefined;
+        if (style)
+            add({
+                kind: "formatting",
+                statement: lang === "es"
+                    ? `La indentación usa ${style === "space" ? "espacios" : style === "tab" ? "tabuladores" : style}${size ? ` con tamaño ${size}` : ""}.`
+                    : `Indentation uses ${style === "space" ? "spaces" : style === "tab" ? "tabs" : style}${size ? ` with size ${size}` : ""}.`,
+                evidence: [".editorconfig"],
+            });
+        const finalNewline = uniqueConfigValue(editorConfig, "insert_final_newline");
+        if (finalNewline === "true")
+            add({
+                kind: "formatting",
+                statement: lang === "es" ? "Los archivos deben terminar con una línea nueva." : "Files must end with a final newline.",
+                evidence: [".editorconfig"],
+            });
+    }
+    const tsconfig = get("tsconfig.json");
+    if (tsconfig && /["']strict["']\s*:\s*true\b/i.test(tsconfig))
+        add({
+            kind: "typescript",
+            statement: lang === "es" ? "TypeScript tiene activado el modo strict." : "TypeScript strict mode is enabled.",
+            evidence: ["tsconfig.json"],
+        });
+    const pyproject = get("pyproject.toml");
+    if (pyproject) {
+        for (const tool of ["ruff", "black"]) {
+            const section = pyproject.match(new RegExp(`(?:^|\\n)\\[tool\\.${tool}\\]([\\s\\S]*?)(?:\\n\\[|$)`, "i"))?.[1];
+            const lineLength = section?.match(/(?:^|\n)\s*line-length\s*=\s*(\d+)/i)?.[1];
+            if (lineLength)
+                add({
+                    kind: "python-style",
+                    statement: lang === "es"
+                        ? `${tool} configura una longitud máxima de línea de ${lineLength}.`
+                        : `${tool} configures a maximum line length of ${lineLength}.`,
+                    evidence: ["pyproject.toml"],
+                });
+        }
+    }
+    const contributing = get("CONTRIBUTING.md");
+    if (contributing) {
+        const directives = contributing.split(/\r?\n/)
+            .map((line) => line.match(/^\s*[-*]\s+(.{1,180})$/)?.[1]?.trim())
+            .filter((line) => Boolean(line))
+            .filter((line) => /\b(?:must|should|required|do not|don't|run|use|follow|debe|debes|ejecuta|usa|sigue|no añadas)\b/i.test(line))
+            .slice(0, 5);
+        for (const directive of directives)
+            add({
+                kind: "contributing",
+                statement: directive,
+                evidence: ["CONTRIBUTING.md"],
+            });
+    }
+    return facts;
+}
 export function buildRepoFacts(signals, lang) {
     const allCommands = [
-        ...extractNpmCommands(signals),
+        ...extractJsPackageCommands(signals),
         ...extractComposerCommands(signals),
         ...extractMakeTargets(signals),
         ...extractMixAliases(signals),
@@ -188,11 +401,18 @@ export function buildRepoFacts(signals, lang) {
     ];
     const { kept, omitted } = filterCommands(allCommands);
     const { commands: ciCommands, omittedCount: omittedCiCount } = extractCiCommands(signals);
+    const testDirs = detectTestDirs(signals.files.filter((file) => !isAuxiliaryFactPath(file)));
+    const entrypoints = detectEntrypoints(signals);
     return {
         commands: kept,
         omittedCommands: omitted,
         structure: extractStructure(signals, lang),
         ciCommands,
         omittedCiCount,
+        canonical: selectCanonicalCommands(signals, kept, ciCommands),
+        testDirs,
+        entrypoints,
+        architectureFacts: extractArchitectureFacts(signals, lang, testDirs, entrypoints),
+        conventionFacts: extractConventionFacts(signals, lang),
     };
 }