@imolko/ultra-agent 0.1.0-beta

package/dist-node/ship/ship.tracker.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXEC_AFK = exports.STATE_COMPLETED = exports.STATE_IN_DEV = exports.STATE_READY = void 0;
+exports.glab = glab;
+exports.glabJson = glabJson;
+exports.glabExec = glabExec;
+exports.verifyAuth = verifyAuth;
+exports.projectPathFromRemote = projectPathFromRemote;
+exports.getProjectPath = getProjectPath;
+exports.encodeProjectPath = encodeProjectPath;
+exports.getIssue = getIssue;
+exports.getIssueComments = getIssueComments;
+exports.getLinkedChildren = getLinkedChildren;
+exports.extractBlockers = extractBlockers;
+exports.isBlocked = isBlocked;
+exports.isReady = isReady;
+exports.selectNextIssue = selectNextIssue;
+exports.claim = claim;
+exports.markDone = markDone;
+exports.resetOrphan = resetOrphan;
+const node_child_process_1 = require("node:child_process");
+const ship_output_1 = require("./ship.output");
+// ── Labels (A-037) ────────────────────────────────────────────────────────────
+exports.STATE_READY = "state::ready";
+exports.STATE_IN_DEV = "state::in-development";
+exports.STATE_COMPLETED = "state::completed";
+exports.EXEC_AFK = "exec::AFK";
+const GLAB_TIMEOUT_MS = 30000;
+const JSON_PREVIEW_LENGTH = 200;
+const COMMENT_HISTORY_LIMIT = 20;
+function glab(args) {
+    return (0, node_child_process_1.execSync)(`glab ${args.join(" ")} 2>&1`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: GLAB_TIMEOUT_MS,
+        shell: "/bin/bash",
+    });
+}
+function glabJson(args) {
+    const output = glab(args);
+    const trimmed = output.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\}|\[[\s\S]*\])/);
+        if (match)
+            return JSON.parse(match[0]);
+        throw new Error(`Failed to parse JSON from glab output: ${trimmed.slice(0, JSON_PREVIEW_LENGTH)}`);
+    }
+}
+// glab via execFileSync (no shell) — safe for titles/descriptions with spaces.
+function glabExec(args) {
+    return (0, node_child_process_1.execFileSync)("glab", args, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: GLAB_TIMEOUT_MS,
+    });
+}
+function verifyAuth() {
+    const output = glab(["auth", "status"]);
+    if (!output.includes("Token found")) {
+        throw new Error("glab is not authenticated. Run 'glab auth login' first.");
+    }
+}
+/**
+ * Extrae el path completo del proyecto (`namespace/proyecto`) de un remote de git.
+ * Conserva todos los segmentos del namespace —los grupos anidados no se truncan—
+ * y soporta HTTPS, `ssh://` y la forma SCP (`git@host:path`).
+ */
+function projectPathFromRemote(remote) {
+    return remote
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "") // esquema (https://, ssh://)
+        .replace(/^[^/@]+@/, "") // usuario@
+        .replace(/^[^/:]+(?::\d+)?[:/]/, "") // host[:puerto] + separador
+        .replace(/\.git$/, "")
+        .replace(/\/+$/, "");
+}
+function getProjectPath() {
+    const remote = (0, node_child_process_1.execSync)("git remote get-url origin 2>/dev/null", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (!remote)
+        throw new Error("Not in a git repository with a remote");
+    const project = projectPathFromRemote(remote);
+    if (!project.includes("/"))
+        throw new Error(`Could not parse project path from remote: ${remote}`);
+    return project;
+}
+function encodeProjectPath(project) {
+    return encodeURIComponent(project);
+}
+function getIssue(iid) {
+    const json = glabJson(["issue", "view", String(iid), "--output", "json"]);
+    return {
+        iid: json.iid ?? 0,
+        title: json.title || "Unknown",
+        description: json.description || "",
+        state: json.state || "unknown",
+        labels: json.labels || [],
+    };
+}
+function getIssueComments(iid) {
+    const json = glabJson(["issue", "view", String(iid), "--comments", "--output", "json"]);
+    const notes = [];
+    const discussions = json.discussions || [];
+    for (const discussion of discussions) {
+        for (const note of discussion.notes || []) {
+            if (!note.system) {
+                const author = note.author?.username || "unknown";
+                notes.push(`${author}: ${note.body}`);
+            }
+        }
+    }
+    return notes.slice(-COMMENT_HISTORY_LIMIT).join("\n");
+}
+function getLinkedChildren(projectEncoded, parentIid) {
+    const apiPath = `projects/${projectEncoded}/issues/${parentIid}/links`;
+    const json = glabJson(["api", apiPath]);
+    if (!Array.isArray(json))
+        return [];
+    return json.map((issue) => {
+        const item = issue;
+        return {
+            iid: item.iid ?? 0,
+            title: item.title || "Unknown",
+            description: item.description || "",
+            state: item.state || "unknown",
+            labels: item.labels || [],
+        };
+    });
+}
+// ── Frontier (deterministic; the orchestrator owns it) ────────────────────────
+function extractBlockers(description) {
+    const lines = description.split("\n");
+    let inBlockerSection = false;
+    const refs = [];
+    for (const line of lines) {
+        if (line.startsWith("# Bloqueado por")) {
+            inBlockerSection = true;
+            continue;
+        }
+        if (inBlockerSection) {
+            if (line.startsWith("#"))
+                break;
+            const match = line.match(/#(\d+)/);
+            if (match)
+                refs.push(parseInt(match[1], 10));
+        }
+    }
+    return [...new Set(refs)];
+}
+function isBlocked(issue, fetchIssue = getIssue) {
+    const blockers = extractBlockers(issue.description);
+    if (issue.description.toLowerCase().includes("ninguno - puede iniciarse")) {
+        return false;
+    }
+    if (blockers.length === 0)
+        return false;
+    for (const ref of blockers) {
+        try {
+            const blocker = fetchIssue(ref);
+            if (!blocker.labels.includes(exports.STATE_COMPLETED)) {
+                return true;
+            }
+        }
+        catch {
+            return true; // can't fetch the blocker → treat as blocked
+        }
+    }
+    return false;
+}
+function isReady(child) {
+    return (child.state === "opened" &&
+        child.labels.includes(exports.STATE_READY) &&
+        child.labels.includes(exports.EXEC_AFK));
+}
+function selectNextIssue(children, fetchIssue = getIssue) {
+    for (const child of children) {
+        if (!isReady(child))
+            continue;
+        if (isBlocked(child, fetchIssue)) {
+            (0, ship_output_1.writeError)(`  ⏳ Issue #${child.iid} is blocked — skipping`);
+            continue;
+        }
+        return child;
+    }
+    return null;
+}
+// ── State transitions (the orchestrator owns every label change) ──────────────
+function claim(iid) {
+    // Atomic: the label transition is what prevents a second ship from re-picking it.
+    glab(["issue", "update", String(iid), "--label", exports.STATE_IN_DEV, "--unlabel", exports.STATE_READY]);
+    try {
+        glab(["issue", "update", String(iid), "--assignee", "@me"]);
+    }
+    catch {
+        // assignee is visibility, not correctness — non-fatal
+    }
+}
+function markDone(iid, context) {
+    glab(["issue", "update", String(iid), "--label", exports.STATE_COMPLETED, "--unlabel", exports.STATE_IN_DEV]);
+    glabExec([
+        "issue", "note", String(context.parentIid),
+        "--message", `ship: completado #${iid}. ${context.summary}`,
+    ]);
+}
+function resetOrphan(iid) {
+    // A leftover in-development child from an interrupted run → back to ready.
+    glab(["issue", "update", String(iid), "--label", exports.STATE_READY, "--unlabel", exports.STATE_IN_DEV]);
+    try {
+        glab(["issue", "update", String(iid), "--unassign", "@me"]);
+    }
+    catch {
+        // non-fatal
+    }
+}
+//# sourceMappingURL=ship.tracker.js.map

package/dist-node/ship/ship.tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.tracker.js","sourceRoot":"","sources":["../../src/ship/ship.tracker.ts"],"names":[],"mappings":"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"}

package/dist-node/version.cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CLI de derivación de versión para los scripts de release (A-033 §7).
+ *
+ * Uso: `node dist-node/version.cli.js <base>` — lee los subjects de commit por
+ * stdin (uno por línea) y escribe por stdout la próxima versión `major.minor.patch`.
+ * Sale con código 0 si hubo bump; con código 1 si ningún commit mueve versión.
+ */
+export {};
+//# sourceMappingURL=version.cli.d.ts.map

package/dist-node/version.cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.cli.d.ts","sourceRoot":"","sources":["../src/version.cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist-node/version.cli.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * CLI de derivación de versión para los scripts de release (A-033 §7).
+ *
+ * Uso: `node dist-node/version.cli.js <base>` — lee los subjects de commit por
+ * stdin (uno por línea) y escribe por stdout la próxima versión `major.minor.patch`.
+ * Sale con código 0 si hubo bump; con código 1 si ningún commit mueve versión.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const version_1 = require("./version");
+function main() {
+    const argv = process.argv.slice(2);
+    const base = argv[0] ?? "0.0.0";
+    let subjects = argv.slice(1);
+    if (subjects.length === 0) {
+        subjects = (0, node_fs_1.readFileSync)(0, "utf-8")
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    const level = (0, version_1.classifyCommits)(subjects);
+    if (level === "none") {
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(`${(0, version_1.bumpVersion)(base, level)}\n`);
+}
+main();
+//# sourceMappingURL=version.cli.js.map

package/dist-node/version.cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.cli.js","sourceRoot":"","sources":["../src/version.cli.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAEH,qCAAuC;AACvC,uCAAyD;AAEzD,SAAS,IAAI;IACX,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC;IAEhC,IAAI,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,QAAQ,GAAG,IAAA,sBAAY,EAAC,CAAC,EAAE,OAAO,CAAC;aAChC,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,KAAK,GAAG,IAAA,yBAAe,EAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAA,qBAAW,EAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist-node/version.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Derivación de versión SemVer a partir de los tipos de Conventional Commits
+ * (A-033 §7): `feat`→minor, `fix`→patch, breaking (`!` o `BREAKING CHANGE:`)→major.
+ *
+ * Funciones puras: ninguna toca el sistema de archivos ni el shell. El script de
+ * release las invoca para calcular la próxima versión; los tests las ejercen
+ * directamente sobre listas de mensajes de commit.
+ */
+export type BumpLevel = "major" | "minor" | "patch" | "none";
+/**
+ * Clasifica un único mensaje de commit (subject + body) según Conventional Commits.
+ * El breaking change se detecta por el `!` del header o por el footer `BREAKING CHANGE:`.
+ */
+export declare function classifyCommit(message: string): BumpLevel;
+/**
+ * Clasifica una lista de commits devolviendo el nivel más alto (major > minor > patch > none).
+ */
+export declare function classifyCommits(messages: string[]): BumpLevel;
+/**
+ * Aplica el bump a una versión `major.minor.patch` (ignora sufijos como `-beta`).
+ * Devuelve la versión de entrada sin cambios si no puede parsearse.
+ */
+export declare function bumpVersion(version: string, level: BumpLevel): string;
+//# sourceMappingURL=version.d.ts.map

package/dist-node/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAI7D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAazD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAS7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAoBrE"}

package/dist-node/version.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Derivación de versión SemVer a partir de los tipos de Conventional Commits
+ * (A-033 §7): `feat`→minor, `fix`→patch, breaking (`!` o `BREAKING CHANGE:`)→major.
+ *
+ * Funciones puras: ninguna toca el sistema de archivos ni el shell. El script de
+ * release las invoca para calcular la próxima versión; los tests las ejercen
+ * directamente sobre listas de mensajes de commit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyCommit = classifyCommit;
+exports.classifyCommits = classifyCommits;
+exports.bumpVersion = bumpVersion;
+const HEADER_RE = /^(\w+)(\([^)]*\))?(!)?:/;
+/**
+ * Clasifica un único mensaje de commit (subject + body) según Conventional Commits.
+ * El breaking change se detecta por el `!` del header o por el footer `BREAKING CHANGE:`.
+ */
+function classifyCommit(message) {
+    const header = message.split("\n")[0]?.trim() ?? "";
+    const match = header.match(HEADER_RE);
+    if (!match)
+        return "none";
+    const type = match[1];
+    const bang = match[3] === "!";
+    const breaking = /BREAKING CHANGE:/i.test(message);
+    if (breaking || bang)
+        return "major";
+    if (type === "feat")
+        return "minor";
+    if (type === "fix")
+        return "patch";
+    return "none";
+}
+/**
+ * Clasifica una lista de commits devolviendo el nivel más alto (major > minor > patch > none).
+ */
+function classifyCommits(messages) {
+    let level = "none";
+    for (const message of messages) {
+        const current = classifyCommit(message);
+        if (current === "major")
+            return "major";
+        if (current === "minor")
+            level = "minor";
+        else if (current === "patch" && level === "none")
+            level = "patch";
+    }
+    return level;
+}
+/**
+ * Aplica el bump a una versión `major.minor.patch` (ignora sufijos como `-beta`).
+ * Devuelve la versión de entrada sin cambios si no puede parsearse.
+ */
+function bumpVersion(version, level) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return version;
+    let major = Number(match[1]);
+    let minor = Number(match[2]);
+    let patch = Number(match[3]);
+    if (level === "major") {
+        major += 1;
+        minor = 0;
+        patch = 0;
+    }
+    else if (level === "minor") {
+        minor += 1;
+        patch = 0;
+    }
+    else if (level === "patch") {
+        patch += 1;
+    }
+    return `${major}.${minor}.${patch}`;
+}
+//# sourceMappingURL=version.js.map

package/dist-node/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAUH,wCAaC;AAKD,0CASC;AAMD,kCAoBC;AA3DD,MAAM,SAAS,GAAG,yBAAyB,CAAC;AAE5C;;;GAGG;AACH,SAAgB,cAAc,CAAC,OAAe;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;IAC9B,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEnD,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC;IACpC,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,QAAkB;IAChD,IAAI,KAAK,GAAc,MAAM,CAAC;IAC9B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,OAAO;YAAE,OAAO,OAAO,CAAC;QACxC,IAAI,OAAO,KAAK,OAAO;YAAE,KAAK,GAAG,OAAO,CAAC;aACpC,IAAI,OAAO,KAAK,OAAO,IAAI,KAAK,KAAK,MAAM;YAAE,KAAK,GAAG,OAAO,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,OAAe,EAAE,KAAgB;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAE3B,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7B,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QACtB,KAAK,IAAI,CAAC,CAAC;QACX,KAAK,GAAG,CAAC,CAAC;QACV,KAAK,GAAG,CAAC,CAAC;IACZ,CAAC;SAAM,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QAC7B,KAAK,IAAI,CAAC,CAAC;QACX,KAAK,GAAG,CAAC,CAAC;IACZ,CAAC;SAAM,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QAC7B,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IAED,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;AACtC,CAAC"}

package/docs/adr/ADR-0000-proceso-y-formato-de-adrs.md

@@ -0,0 +1,115 @@
+# ADR-0000: Proceso y formato de los ADRs
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: imolko
+
+**tags**: arquitectura, tooling
+
+## Contexto
+
+El repositorio Guarura mantiene un registro de decisiones de arquitectura (ADR) distribuido en varios tiers y decenas de archivos. Hasta ahora la información sobre *cómo* se escriben y gobiernan esos ADRs vivía dispersa en las secciones "Formato" y "Tiers" de `docs/adr/index.md`, sin respaldo de decisión: no estaba escrito por qué se usa el formato de Michael Nygard, por qué existen cuatro tiers, ni qué reglas se aplican para mantener la consistencia.
+
+Sin un ADR que canonice el proceso, cada decisión nueva corre el riesgo de:
+
+- usar un formato distinto (por ejemplo, un frontmatter YAML en lugar de las líneas `**Campo**: valor` del proyecto);
+- romper la jerarquía de referencias entre tiers;
+- omitir campos obligatorios como `originally` o las etiquetas;
+- introducir enlaces rotos o listas duplicadas que el gate detecta.
+
+Este documento es el **meta-ADR**: define el proceso y el formato que el resto de ADRs debe seguir. Vive en la raíz de `docs/adr/` y usa el ID `0000` precisamente porque está **fuera** de la jerarquía A→T/P→G: define esa jerarquía y, por lo tanto, no pertenece a ninguno de sus tiers. Por su nombre no es detectado por el gate de consistencia, lo cual es correcto.
+
+## Decisión
+
+### Formato: Michael Nygard con frontmatter del proyecto
+
+Cada ADR sigue el formato de **Michael Nygard**, con tres secciones de contenido:
+
+- **Contexto**: situación que motiva la decisión (fuerzas, restricciones, problema).
+- **Decisión**: qué se decidió y por qué.
+- **Consecuencias**: implicaciones positivas y negativas de la decisión.
+
+Cada ADR cubre **una única decisión ortogonal**. Ampliar el alcance sobre el mismo eje — por ejemplo, extender una regla de value-objects a entidades y agregados — se hace en el mismo ADR; una decisión de un eje distinto — por ejemplo, la validación de artefactos de dominio frente al contrato de configuración de la aplicación — vive en su propio ADR. Un ADR que acumula dos ejes se divide.
+
+Además del título H1 (`# <ID>: <Título descriptivo>`), cada ADR lleva un **frontmatter del proyecto** como líneas `**Campo**: valor` inmediatamente después del título:
+
+| Campo | Obligatorio | Descripción |
+|-------|-------------|-------------|
+| `**Estado**` | Sí | Uno de: `Aceptado`, `Propuesto`, `Deprecado`, `Reemplazado`. |
+| `**Fecha**` | Sí | Fecha de la decisión (formato `YYYY-MM-DD` o `YYYY-MM`). |
+| `**originally**` | Sí | Procedencia original de la decisión (ID fuente, en minúsculas). |
+| `**Enriquecido desde**` | No | Fuente de enriquecimiento posterior (cuando aplica). |
+| `**tags**` | Sí (tier A hoy) | De una a tres etiquetas del vocabulario en [A-043](./foundational/A-043-vocabulario-etiquetas-adrs.md). |
+
+El gate valida el formato H1 y la ortografía exacta de `originally` (minúsculas) y `Enriquecido desde` (capitalización exacta) para los ADRs de los tiers A/T/P/G.
+
+### Jerarquía de tiers: A → T/P → tier de proyecto
+
+Los ADRs se organizan en tres tiers de metodología más el tier de proyecto de cada consumidor, según su alcance:
+
+| Tier | Ubicación | Alcance |
+|------|-----------|---------|
+| **Fundacional (A)** | [`foundational/`](./foundational/index.md) | Decisiones metodológicas agnósticas al lenguaje (Clean Architecture, TDD, comandos y consultas, DDD). Aplican a todos los proyectos de Imolko. |
+| **TypeScript (T)** | [`typescript/`](./typescript/index.md) | Decisiones específicas del ecosistema TypeScript/Zod/Node.js. |
+| **Python (P)** | [`python/`](./python/index.md) | Decisiones específicas del ecosistema Python (FastAPI, SQLAlchemy, Pydantic). |
+| **Tier de proyecto** | `docs/adr/` (raíz) u otro directorio del consumidor | Decisiones específicas del dominio del proyecto consumidor. El prefijo es propio de cada proyecto (por ejemplo `G` para Guarura) y no forma parte de la metodología distribuida ([A-052](./foundational/A-052-distribucion-metodologia-paquete-versionado.md)). |
+
+**Reglas de referencia** (jerarquía estricta):
+
+- Los ADRs **A** no referencian ADRs T, P ni del tier de proyecto.
+- Los ADRs **T** y **P** pueden referenciar A, pero no se referencian entre sí ni al tier de proyecto.
+- El **tier de proyecto** puede referenciar A, T y P.
+
+La numeración es **estable**: los IDs existentes no se renumeran. Los IDs omitidos intencionalmente (por ejemplo A-021) no se reutilizan.
+
+### Fases narrativas del tier fundacional
+
+Los ADRs fundacionales (A-XXX) se agrupan en fases narrativas; el orden y el agrupamiento exactos viven en [`foundational/index.md`](./foundational/index.md), que es quien porta la narrativa. Las fases son una organización de lectura; no cambian la numeración ni los tiers.
+
+### Gate de consistencia
+
+La consistencia del registro se verifica con [`scripts/verify-adr-consistency.py`](../../scripts/verify-adr-consistency.py), un script de solo lectura que se ejecuta desde la raíz del repositorio:
+
+```bash
+python3 scripts/verify-adr-consistency.py
+```
+
+El gate valida **cinco reglas** y debe salir con código `0` y cero violaciones:
+
+| Regla | Qué valida |
+|-------|------------|
+| `jerarquia` | Los ADRs no referencian tiers prohibidos según la jerarquía A→T/P→tier de proyecto. |
+| `enlaces` | Todos los enlaces markdown internos (relativos, `*.md`) resuelven a un archivo existente. |
+| `frontmatter` | El título sigue `# <TIER>-<NNN>: Título` y los campos `originally` / `Enriquecido desde` usan la ortografía correcta. |
+| `indices` | Cada ADR aparece en el índice de su tier y el índice no lista ADRs inexistentes. |
+| `hardcoded` | Los ADRs no duplican listas cuya fuente canónica vive en otro archivo (workspaces/dependencias → `package.json`, skills → paquete `@imolko/ultra-agent` y su materializador, release → `domain/scripts/release*.sh`). |
+
+El gate y su salida `0` son la condición de aprobación no negociable para cualquier cambio en `docs/adr/`.
+
+### Ciclo de vida
+
+Cada ADR transita por un ciclo de vida simple:
+
+1. **Propuesto**: la decisión se propone y se discute.
+2. **Aceptado**: la decisión queda en vigor y su `**Estado**` es `Aceptado`.
+3. **Reemplazado** o **Deprecado**: cuando una decisión posterior la sustituye o queda obsoleta, se actualiza su `**Estado**` y se enlaza al ADR que la reemplaza (en prosa markdown, sin campos prev/next).
+
+Reglas de numeración:
+
+- El siguiente ADR de un tier toma el siguiente número correlativo (`A-NNN`, `T-NNN`, `P-NNN`, o el prefijo propio del tier de proyecto).
+- Los IDs omitidos intencionalmente (por ejemplo A-021) **no se reutilizan**: permanecen omitidos para preservar la estabilidad de los IDs existentes.
+
+## Consecuencias
+
+### Positivas
+
+- **Proceso canonizado**: el formato, la jerarquía y el gate dejan de vivir dispersos y pasan a tener respaldo de decisión.
+- **Onboarding más corto**: un colaborador nuevo lee un único ADR para entender cómo contribuir decisiones.
+- **Consistencia ejecutable**: el gate automatiza la verificación de las cinco reglas, con salida 0 como criterio de aceptación.
+- **Jerarquía clara**: las reglas de referencia entre tiers evitan acoplamientos incorrectos (por ejemplo, un ADR fundacional citando uno de Guarura).
+
+### Negativas
+
+- **Un archivo más que mantener**: el meta-ADR debe actualizarse si cambia el proceso (por ejemplo, si se añade una regla al gate).

package/docs/adr/foundational/A-001-clean-architecture-4-capas.md

@@ -0,0 +1,88 @@
+# A-001: Clean Architecture con 4 capas
+
+**Estado**: Aceptado
+
+**Fecha**: 2025-02-25
+**originally**: imolko
+**Enriquecido desde**: Cortex ADR 004 — Clean Architecture feature structure with ports & drivers
+
+**tags**: arquitectura
+
+## Contexto
+
+Los proyectos de Imolko necesitan una estructura que:
+
+- Separe claramente las reglas de negocio de los detalles de infraestructura
+- Permita probar el dominio de forma aislada (sin base de datos, sin HTTP, sin frameworks)
+- Facilite el reemplazo de tecnologías (base de datos, transporte, UI) sin afectar la lógica de negocio
+- Soporte múltiples formas de despliegue (nodo local, servidor central, workers)
+- Escale a 15+ features sin degenerar en caos estructural
+
+## Decisión
+
+Adoptar **Clean Architecture** con 4 capas concéntricas, inspirada en la arquitectura hexagonal (puertos y adaptadores) y los principios de DDD. Las reglas de negocio puras viven en el dominio; los casos de uso las orquestan a través de puertos, y la infraestructura es un detalle de implementación.
+
+### Estructura global
+
+```
+domain/              # Capa más interna — reglas de negocio puras
+features/            # Casos de uso — slices verticales independientes
+shared-infra/        # Drivers y esquemas de persistencia por tecnología
+representations/     # Formas de wire por protocolo
+apps/                # Unidades desplegables independientes
+```
+
+### Capa 1: domain
+
+Contiene las reglas de negocio puras. Artefactos DDD:
+
+- Value objects, entidades, agregados (aggregate roots)
+- Servicios de dominio
+- Especificaciones
+- Eventos de dominio
+
+**Dependencias mínimas**: solo librerías de validación y result-type. Sin dependencias de infraestructura, frameworks HTTP, ni bases de datos.
+
+### Capa 2: features
+
+Cada feature es un slice vertical autocontenido que vive bajo `features/` a nivel de workspace. Su anatomía (puertos de dominio, adaptadores y driver ports) y la mecánica Puerto→Adaptador→Driver port están en [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md). Su portabilidad entre apps y su composición en wiring están en [A-024](./A-024-features-slices-verticales-portables.md).
+
+### Capa 3: shared-infra
+
+La infraestructura compartida entre features vive en `shared-infra/`, un directorio que agrupa un paquete por tecnología (`shared-infra/mongo/`, `shared-infra/postgres/`, …). Cada paquete contiene los drivers que implementan los driver ports que las features declaran, junto con sus esquemas de persistencia. Las formas de wire (`representations/`) viven en su propio paquete por protocolo (`representations/graphql/`, `representations/protobuf/`, …), junto a `shared-infra/`. Las features nunca importan estos paquetes. El catálogo completo está en [A-026](./A-026-infraestructura-compartida.md).
+
+### Capa 4: apps
+
+Unidades desplegables independientes. Cada app selecciona un conjunto de features y las empaqueta para despliegue componiéndolas en su capa de wiring. Ejemplos: un nodo local para el almacén, un servidor central de reporting, un worker que procesa eventos de sistemas externos.
+
+El patrón de wiring entry-point está en [A-027](./A-027-patron-wiring-entry-point.md).
+
+### Dirección de dependencias
+
+Las dependencias siempre apuntan hacia adentro: el dominio no depende de ninguna
+capa exterior; `representations/<protocol>/` importa solo el dominio; `shared-infra/<tech>/`
+importa el dominio y los driver ports que
+las features declaran, nunca al revés. El driver de `shared-infra/<tech>/` implementa el driver
+port que la feature define; la feature nunca importa
+`shared-infra/` ni `representations/`.
+
+La regla de que las features nunca importan
+del interior de otras features — el acoplamiento ocurre
+solo en tiempo de wiring — vive en
+[A-024](./A-024-features-slices-verticales-portables.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Dominio aislado**: las reglas de negocio se pueden probar sin infraestructura.
+- **Flexibilidad tecnológica**: cambiar de base de datos o protocolo no afecta el dominio — reemplazar un driver toca solo `drivers/<tech>/` de la feature y, cuando lo comparte, el paquete `shared-infra/<tech>/`.
+- **Despliegues independientes**: cada app se despliega por separado.
+- **Desarrollo paralelo**: múltiples features pueden desarrollarse simultáneamente sin conflictos.
+- **Testabilidad**: cada capa se prueba de forma aislada con dobles de prueba.
+
+### Negativas
+
+- **Mapeo entre capas**: requiere DTOs y mapeo de datos entre capas (dominio ↔ aplicación ↔ infraestructura).
+- **Curva de aprendizaje**: el equipo debe entender la arquitectura y respetar la dirección de las dependencias (siempre hacia adentro).
+- **Disciplina requerida**: mantener los ports puros y los drivers aislados requiere revisión constante.

package/docs/adr/foundational/A-002-cqrs-semantico.md

@@ -0,0 +1,58 @@
+# A-002: Separación de comandos y consultas
+
+**Estado**: Aceptado
+
+**Fecha**: 2025-02-25
+
+**originally**: imolko
+
+**tags**: arquitectura
+
+## Contexto
+
+Un sistema expone casos de uso de dos naturalezas: los que **cambian el estado** del dominio y los que **responden preguntas**. Sin un criterio explícito para distinguirlos, ambas naturalezas se mezclan en el código — operaciones que escriben y devuelven datos a la vez, consultas con efectos secundarios — y los nombres derivan hacia verbos técnicos (CRUD) en lugar del lenguaje del negocio.
+
+Las consultas no son un caso menor: muchas involucran reglas de negocio (p. ej. una fórmula de disponibilidad) y deben modelarse con el mismo rigor semántico que los comandos.
+
+## Decisión
+
+Separar **comandos** (operaciones que cambian el estado) de **consultas** (operaciones que retornan datos) en la estructura de features, usando **lenguaje ubicuo** en los nombres de los casos de uso.
+
+### Clasificación command vs query
+
+La clasificación se infiere del nombre del caso de uso por convención de nomenclatura:
+
+| Tipo | Definición | Criterio |
+|---|---|---|
+| `command` | Modifica el estado del sistema | El nombre comienza con un verbo de acción: `registrar-*`, `agregar-*`, `eliminar-*`, `modificar-*`, `asignar-*`, `recibir-*`, `transferir-*` |
+| `query` | Consulta o valida sin modificar estado | El nombre comienza con un verbo de consulta: `consultar-*`, `validar-*`, `verificar-*`, `filtrar-*`, `listar-*`, `calcular-*` |
+
+Esta taxonomía permite que cualquier desarrollador clasifique nuevos casos de uso de forma consistente con solo inspeccionar el nombre. Un caso de uso `command` **nunca** debe retornar datos de lectura como propósito principal; un caso de uso `query` **nunca** debe tener efectos secundarios observables.
+
+El campo `type` en el frontmatter del feature documenta esta clasificación. El esquema de ese frontmatter se define en [A-032](./A-032-domain-artifact-documentation-format.md).
+
+### Principios
+
+1. **Separación estructural**: cada operación (comando o consulta) es un feature independiente en `features/<caso-de-uso>/` (anatomía en [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)). No hay features "mixtas" que lean y escriban en el mismo caso de uso.
+2. **Semántica de negocio**: los casos de uso se nombran con verbos del dominio, no con verbos CRUD ([A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)):
+   - ✅ `registrar-pedido`, `consultar-disponibilidad`
+   - ❌ `createStockMovement`, `getInventory`
+
+### Alcance
+
+La separación es **estructural y de nombrado**: clasifica cada caso de uso y lo aísla en su feature, sin prescribir la infraestructura de lectura. La persistencia de lectura y escritura no se segrega. La optimización de las consultas (vistas materializadas, cachés, índices) y su proyección desde eventos son responsabilidad del driver, no de esta decisión ([A-010](./A-010-propiedad-emision-eventos-dominio.md)).
+
+Cuando las lecturas se sirven de proyecciones reconstruidas desde eventos, la consistencia depende de la naturaleza de la lectura: la que respalda un **invariante de un comando** (una verificación que el comando debe respetar) es **síncrona** — un índice actualizado en la misma transacción de la escritura —; la que respalda una **consulta o reporte** es **eventual** — una proyección mantenida por un suscriptor del stream. La primera no puede quedar eventual sin arriesgar el invariante; la segunda no necesita ser síncrona.
+
+## Consecuencias
+
+### Positivas
+
+- **Lenguaje ubicuo en el código**: los nombres de features reflejan directamente las operaciones del negocio
+- **Features enfocadas**: cada caso de uso tiene una sola responsabilidad (comandar o consultar)
+- **Estructura predecible**: cualquier desarrollador sabe que `features/consultar-*` son consultas y `features/<verbo>-*` son comandos
+
+### Negativas
+
+- **Optimización de lecturas delegada al driver**: la eficiencia de las consultas depende del driver que se use; la optimización es responsabilidad de cada driver
+- **Features numerosas**: cada consulta es un feature separado, y la navegación requiere disciplina de nombres