@imolko/ultra-agent 0.1.0-beta

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@imolko/ultra-agent",
+  "version": "0.1.0-beta",
+  "description": "Metodología ultra como paquete versionado: skills canónicos, registro ADR A/T/P, extensiones de pi y CLI (install/update/status/ship).",
+  "license": "MIT",
+  "author": {
+    "name": "Roberto Matute",
+    "email": "robertomatute@imolko.com"
+  },
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "adr",
+    "cli",
+    "methodology"
+  ],
+  "homepage": "https://gitlab.com/imolko/ultra-stack/ultra-agent",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/imolko/ultra-stack/ultra-agent"
+  },
+  "bin": {
+    "ultra-agent": "./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist-node/index.d.ts",
+      "default": "./dist-node/index.js"
+    },
+    "./eslint": {
+      "default": "./eslint/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist-node/index.js",
+  "types": "./dist-node/index.d.ts",
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./pi/extensions"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist-node",
+    "build": "npm run clean && tsc -p tsconfig.json && bash scripts/copy-assets.sh",
+    "gate": "python3 scripts/verify-adr-consistency.py"
+  },
+  "files": [
+    "bin",
+    "dist-node",
+    "eslint",
+    "!eslint/__fixtures__/**",
+    "skills",
+    "docs/adr",
+    "pi/extensions",
+    "scripts",
+    "README.md",
+    "!**/*.test.ts",
+    "!**/*.integration.test.ts",
+    "!**/*.spec.ts",
+    "!**/package-lock.json",
+    "!**/vitest.config.ts",
+    "!**/node_modules/**",
+    "!**/.DS_Store"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.71.0",
+    "@typescript-eslint/parser": "^8.71.0",
+    "eslint": "^9.0.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-boundaries": "^7.2.0",
+    "eslint-plugin-import-x": "^4.17.1"
+  },
+  "devDependencies": {
+    "@imolko/ultra-tsconfig": "1.1.0",
+    "@types/node": "^22.10.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.1.1"
+  }
+}

package/pi/extensions/handoff/README.md

@@ -0,0 +1,92 @@
+# Handoff Extension
+
+Generates a context handoff document, renames the current session, and spins up a new versioned session seeded with the handoff and task for a fresh agent to continue the work.
+
+## Usage
+
+```
+/handoff now implement this for teams as well
+/handoff execute phase one of the plan
+/handoff check other places that need this fix
+```
+
+The argument is the **task** the next session should focus on. It becomes the first user message in the new session, preceded by the LLM-generated handoff note.
+
+## What it does
+
+1. **Names the current session** — if unnamed, prompts for a slug (defaults from the task text).  
+2. **Injects a handoff prompt** — sends the bundled `handoff-prompt.txt` + task to the LLM.  
+3. **Captures the LLM response** — polls for an assistant message with `stopReason: "stop"`. Times out after 5 minutes.  
+4. **Creates a new session** — version-bumped name (e.g. `fix-auth-v2` → `fix-auth-v3`), parented to the current session.  
+5. **Seeds the new session** — injects the handoff note followed by the task. The fresh session is ready for a new agent.
+
+## Architecture
+
+### Extension replaces the skill
+
+The handoff **extension** (this directory) replaces the former handoff skill (`.pi/skills/handoff/SKILL.md`, now removed). The extension owns the whole flow:
+
+| Artifact | Purpose |
+|----------|---------|
+| `handoff-prompt.txt` (extension) | Tells the LLM to output the handoff **directly in the response** so the extension can capture it programmatically. |
+
+The extension reads its own bundled prompt; there is no skill file anymore.
+
+### Polling mechanism
+
+After injecting the handoff prompt at index `startIndex`, the extension polls `ctx.sessionManager.getBranch()` every 25ms. It uses **positional matching** — it waits for the first assistant message after `startIndex`, regardless of text content. This eliminates coupling to the prompt text and avoids silent breakage if whitespace or wording changes.
+
+### Session replacement safety
+
+After `ctx.newSession()`, the old session runtime is torn down. The `withSession` callback uses only the **replacement `ctx`** parameter — it never references the original command `ctx`, whose `.ui` object is stale after shutdown and will throw.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Extension entry point. Registers `/handoff` command. |
+| `handoff-prompt.txt` | Prompt template injected into the LLM to generate the handoff note. |
+| `index.test.ts` | Unit tests (83) covering all exported helpers. |
+| `index.integration.test.ts` | Integration tests (15) with mocked `ExtensionAPI`. |
+| `package.json` | Vitest dev dependency + test scripts. |
+| `vitest.config.ts` | Vitest configuration. |
+
+## Exported helpers
+
+The extension exports utility functions so they can be imported and tested:
+
+| Export | Description |
+|--------|-------------|
+| `isRecord(value)` | Type guard for plain objects. |
+| `getRoleMessage(entry, role)` | Extracts a `user` or `assistant` message from a session entry. |
+| `getAssistantMessage(entry)` | Extracts an assistant message (with optional `stopReason`). |
+| `getMessageText(entry)` | Gets text content from string or content-array messages. |
+| `findUserMessageIndex(entries, from, text)` | Finds a user message by exact text match (legacy; positional matching is used at runtime). |
+| `hasAssistantAfterIndex(entries, from)` | Returns `true` if any assistant message exists after a given index. |
+| `getAssistantText(entries, from)` | Gets the text of the first assistant message with `stopReason: "stop"` after `from`. |
+| `stripFrontmatter(text)` | Strips YAML frontmatter (`---` … `---`). |
+| `stripSaveInstruction(text)` | Strips "Save to the temp directory…" instructions from text. |
+| `slugify(text)` | Converts text to a URL-safe slug. |
+| `bumpVersion(name)` | Increments a `-vN` suffix or appends `-v2`. |
+| `loadPrompt(extensionDir)` | Reads `handoff-prompt.txt` from the extension directory. |
+
+## Testing
+
+```bash
+cd .pi/extensions/handoff
+npm test          # Run all tests once
+npm run test:watch  # Watch mode
+```
+
+- **Unit tests** (`index.test.ts`): 83 tests covering every exported helper and internal logic — input validation, edge cases, empty/malformed entries, frontmatter stripping, version bumping, slug generation, positional matching, text extraction with `stopReason` filtering.
+- **Integration tests** (`index.integration.test.ts`): 15 tests with a mocked `ExtensionAPI` — missing model/task errors, session naming (prompt/cancel/fallback), full happy path, cancellation, timeout, truncated/empty responses, stale ctx prevention.
+
+## Development
+
+When adding features, follow the red-green-refactor loop:
+
+```bash
+cd .pi/extensions/handoff && npm run test:watch
+```
+
+The extension uses pi's `ExtensionCommandContext` API — see [extension docs](https://github.com/earendil-works/pi-coding-agent/blob/main/docs/extensions.md) for the full API surface.

package/pi/extensions/handoff/handoff-prompt.txt

@@ -0,0 +1,9 @@
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Output the handoff directly in your response — do not save to a file.
+
+Include a "Suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. For GitLab issues, use the full web URL (e.g., `https://gitlab.com/imolko/cortex/-/work_items/1`).
+
+Redact any sensitive information, such as API keys, passwords, tokens, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the document accordingly.

package/pi/extensions/handoff/index.ts

@@ -0,0 +1,296 @@
+/**
+ * Handoff extension — generate context handoff and move it to a new session.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+type RoleMessage = {
+  role: "user" | "assistant";
+  content: unknown;
+};
+
+type AssistantRoleMessage = RoleMessage & {
+  role: "assistant";
+  stopReason?: unknown;
+};
+
+const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
+const HANDOFF_POLL_INTERVAL_MS = 25;
+
+export function getRoleMessage(entry: SessionEntry, role: "user" | "assistant"): RoleMessage | null {
+  if (entry.type !== "message" || !isRecord(entry.message)) return null;
+  const message = entry.message;
+  if (message.role !== role || !("content" in message)) return null;
+  return message as RoleMessage;
+}
+
+export function getAssistantMessage(entry: SessionEntry): AssistantRoleMessage | null {
+  const message = getRoleMessage(entry, "assistant");
+  if (!message || !isRecord(message)) return null;
+  return message as AssistantRoleMessage;
+}
+
+export function getMessageText(entry: SessionEntry): string {
+  if (entry.type !== "message" || !isRecord(entry.message) || !("content" in entry.message)) return "";
+  const content = entry.message.content;
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block): block is { type: "text"; text: string } => isRecord(block) && block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+}
+
+export function findUserMessageIndex(entries: SessionEntry[], fromIndex: number, text: string): number {
+  for (let i = entries.length - 1; i >= fromIndex; i--) {
+    const entry = entries[i];
+    if (!getRoleMessage(entry, "user")) continue;
+    if (getMessageText(entry) === text) return i;
+  }
+  return -1;
+}
+
+export function hasAssistantAfterIndex(entries: SessionEntry[], fromIndex: number): boolean {
+  for (let i = entries.length - 1; i > fromIndex; i--) {
+    if (getRoleMessage(entries[i], "assistant")) return true;
+  }
+  return false;
+}
+
+type HandoffTurn = {
+  branch: SessionEntry[];
+  handoffUserIndex: number;
+};
+
+async function waitForHandoffTurn(
+  ctx: ExtensionCommandContext,
+  startIndex: number,
+  timeoutMs = HANDOFF_TIMEOUT_MS,
+): Promise<HandoffTurn | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const branch = ctx.sessionManager.getBranch();
+    // Positional match: we injected at startIndex; wait for the first
+    // assistant response past that point. No text matching needed.
+    if (hasAssistantAfterIndex(branch, startIndex) && ctx.isIdle()) {
+      return { branch, handoffUserIndex: startIndex };
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, HANDOFF_POLL_INTERVAL_MS));
+  }
+  return null;
+}
+
+export function getAssistantText(entries: SessionEntry[], fromIndex: number): string | null {
+  for (let i = entries.length - 1; i >= fromIndex; i--) {
+    const message = getAssistantMessage(entries[i]);
+    if (!message) continue;
+    if (message.stopReason !== "stop") return null;
+    const text = getMessageText(entries[i]);
+    if (text.length > 0) return text;
+  }
+  return null;
+}
+
+// ── prompt loading ───────────────────────────────────────────────────────────
+
+export function stripFrontmatter(text: string): string {
+  const lines = text.split("\n");
+  if (lines[0]?.trim() === "---") {
+    const end = lines.indexOf("---", 1);
+    if (end !== -1) {
+      return lines.slice(end + 1).join("\n").trim();
+    }
+  }
+  return text.trim();
+}
+
+export function stripSaveInstruction(text: string): string {
+  // Remove file-saving instructions like:
+  // "Save to the temporary directory of the user's OS — not the current workspace."
+  // "Save it to the temp directory of the user's OS."
+  return text
+    .replace(
+      /\bSave\s+(it\s+|the\s+document\s+)?to\s+the\s+(temporary|temp)\s+directory\s+of\s+the\s+user'?s\s+OS\s*(—[^.]+)?\.?\s*/gi,
+      "",
+    )
+    .trim();
+}
+
+export function loadPrompt(extensionDir: string): string {
+  // Use the extension's own prompt, not the skill's SKILL.md.
+  // The skill tells the agent to save to a file — that's correct for
+  // general skill invocation, but wrong for the extension which needs
+  // the LLM to output text directly so it can capture the response.
+  const promptPath = join(extensionDir, "handoff-prompt.txt");
+  if (existsSync(promptPath)) {
+    return readFileSync(promptPath, "utf8").trim();
+  }
+  return "";
+}
+
+// ── naming ───────────────────────────────────────────────────────────────────
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 40);
+}
+
+export function bumpVersion(name: string): string {
+  const match = name.match(/^(.*?)-v(\d+)$/);
+  if (match) {
+    const base = match[1];
+    const num = parseInt(match[2], 10);
+    return `${base}-v${num + 1}`;
+  }
+  return `${name}-v2`;
+}
+
+// ── extension ────────────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  // Resolve the extension's own directory for reading bundled files
+  const extensionDir = dirname(new URL(import.meta.url).pathname);
+
+  pi.registerCommand("handoff", {
+    description: "Transfer context to a new focused session",
+    handler: async (args, ctx) => {
+      const notify = (message: string, level: "info" | "warning" | "error") => {
+        ctx.ui?.notify?.(message, level);
+      };
+
+      const setStatus = (text: string) => {
+        ctx.ui?.setStatus?.("handoff", text);
+      };
+
+      const clearStatus = () => {
+        ctx.ui?.setStatus?.("handoff", "");
+      };
+
+      if (!ctx.model) {
+        notify("No model selected", "error");
+        return;
+      }
+
+      const task = args.trim();
+      if (!task) {
+        notify("Usage: /handoff <goal or task for new thread>", "error");
+        return;
+      }
+
+      // ── 1. Name the current session if unnamed ──────────────────────────
+      const currentName = ctx.sessionManager.getSessionName();
+      let baseName: string;
+
+      if (!currentName) {
+        if (ctx.ui?.input) {
+          const suggestion = slugify(task) || "session";
+          const input = await ctx.ui.input(
+            "Name this session (for handoff)",
+            suggestion,
+          );
+          if (!input) {
+            notify("Handoff cancelled", "warning");
+            return;
+          }
+          baseName = input.trim() || suggestion;
+        } else {
+          baseName = slugify(task) || "session";
+        }
+        // Set the name on the current session
+        ctx.sessionManager.appendSessionInfo(baseName);
+      } else {
+        baseName = currentName;
+      }
+
+      const newSessionName = bumpVersion(baseName);
+      setStatus("Handoff: generating note…");
+
+      // ── 2. Load prompt ─────────────────────────────────────────────────
+      const promptBody = loadPrompt(extensionDir);
+      if (!promptBody) {
+        clearStatus();
+        notify("Handoff prompt not found", "error");
+        return;
+      }
+
+      const handoffRequest = `${promptBody}\n\nTask for the next agent:\n${task}`;
+
+      // ── 3. Inject handoff-generation prompt ────────────────────────────
+      const currentSessionFile = ctx.sessionManager.getSessionFile();
+      const startIndex = ctx.sessionManager.getBranch().length;
+
+      if (ctx.isIdle()) {
+        pi.sendUserMessage(handoffRequest);
+      } else {
+        pi.sendUserMessage(handoffRequest, { deliverAs: "followUp" });
+      }
+
+      notify("Handoff started — generating note…", "info");
+
+      // ── 4. Poll for LLM response ───────────────────────────────────────
+      const handoffTurn = await waitForHandoffTurn(ctx, startIndex);
+
+      if (!handoffTurn) {
+        clearStatus();
+        notify("Handoff timed out after 5 minutes", "error");
+        return;
+      }
+
+      const handoffNote = getAssistantText(handoffTurn.branch, handoffTurn.handoffUserIndex + 1);
+
+      if (!handoffNote) {
+        clearStatus();
+        notify("Handoff failed — empty or truncated response", "error");
+        return;
+      }
+
+      setStatus("Handoff: creating session…");
+      notify("Handoff captured — creating new session…", "info");
+
+      // ── 5. Create new session ──────────────────────────────────────────
+      const promptForNewSession = `${handoffNote}\n\n---\n\n## Task\n${task}`;
+
+      const newSessionResult = await ctx.newSession({
+        parentSession: currentSessionFile ?? undefined,
+        setup: (sm) => {
+          sm.appendSessionInfo(newSessionName);
+        },
+        withSession: async (newSessionCtx) => {
+          // Use newSessionCtx, not the captured old ctx — the old session
+          // has been shut down and its ctx.ui is stale (will throw).
+          newSessionCtx.ui?.setStatus?.("handoff", "");
+
+          if (newSessionCtx.isIdle()) {
+            await newSessionCtx.sendUserMessage(promptForNewSession);
+          } else {
+            await newSessionCtx.sendUserMessage(promptForNewSession, { deliverAs: "followUp" });
+          }
+
+          newSessionCtx.ui?.notify?.(`Handoff complete — session: ${newSessionName}`, "info");
+        },
+      });
+
+      if (newSessionResult.cancelled) {
+        clearStatus();
+        notify("Handoff cancelled", "warning");
+      }
+    },
+  });
+}

package/pi/extensions/handoff/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "handoff-extension",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  }
+}

package/pi/extensions/qa-guardrail/README.md

@@ -0,0 +1,108 @@
+# qa-guardrail Extension
+
+Materializa el bucle de linting de [A-045](../../../docs/adr/foundational/A-045-guardrails-aplicables-no-directrices.md) para el agente pi, según el diseño de [A-049](../../../docs/adr/foundational/A-049-materializacion-bucle-guardrails-extension-nativa-pi.md). Este directorio contiene el **slice tracer bullet** (#317), el **delta-scoping** (#318), el **corte en N** (#319), el **cerco** (#320) y el **barrido completo** (#321): el camino completo `config → adaptador → hook → retroalimentación`, limitado a «solo mis cambios», el bloqueo tras N deltas-fallo consecutivos sobre el mismo archivo, y el cerco que impide editar la configuración o desactivar reglas en línea.
+
+## Qué hace hoy
+
+Tras cada `write`/`edit` exitoso, el hook `tool_result`:
+
+1. Carga y valida `.pi/qa-guardrail.json` (ausente/inválido → warning y gate off, nunca crash).
+2. Selecciona el adaptador whitelisted que cubre el archivo (`include`/`exclude`).
+3. Lintea el archivo con la API Node de ESLint (in-process, instancia única, import perezoso).
+4. Reporta **solo el delta** contra la línea base congelada (ver más abajo).
+
+Además, el hook `tool_call` congela la línea base del archivo *antes* de la primera edición; los archivos nuevos parten de línea base vacía. Y si el agente introduce violaciones en N=3 ediciones consecutivas sobre el mismo archivo (sin una edición limpia entre medias), ese archivo se bloquea para `write`/`edit` hasta que la persona lo desbloquee con `/qa-guardrail reset <archivo>`.
+
+Antes de todo eso, el **cerco** bloquea en `tool_call`: los caminos protegidos hardcodeados (`eslint.config.mjs`, `.pi/qa-guardrail.json`, `.pi/extensions/qa-guardrail/**`) y las directivas nuevas `eslint-disable*` en `write.content` / `edit.newText`. El cerco es independiente de ESLint y de la selección: se aplica aunque el config esté ausente o el archivo no esté cubierto por ningún adaptador.
+Por conservadurismo, `checkCerco` bloquea cualquier directiva presente en `edit.newText` aunque ya estuviera en `oldText` (mover una directiva heredada se bloquea como «nueva»): posible falso positivo, coherente con «el cerco prohíbe desactivar reglas en línea».
+
+**Límite del cerco**: solo cerca las herramientas `write`/`edit`. El agente aún podría tocar `eslint.config.mjs` o inyectar `eslint-disable*` vía `bash` (p. ej. `sed`/`cat`); ese hueco es una limitación estructural de A-045 heredada del alcance del PRD (el cerco opera sobre `tool_call` de write/edit), no una desviación del spec.
+
+Sin violaciones nuevas, no se anexa nada.
+Además, `/qa-guardrail check` hace un **barrido completo** (no delta-scoped) de los archivos que coinciden con la configuración: lista las violaciones y las directivas `eslint-disable*` heredadas, sin bloquear nada. Sirve de inventario de migración.
+
+### Delta-scoping
+
+- `baseline.ts`: línea base congelada por archivo y sesión, capturada en `tool_call` (lint del archivo tal como el agente lo encontró; vacía para archivos nuevos).
+- `delta.ts`: `current − baseline` como diferencia de multiconjuntos; solo se reportan las violaciones introducidas. Las heredadas nunca se atribuyen al agente.
+- La identidad delta es `(rule, line, column)`. Si un edit desplaza líneas por encima de una violación heredada, su `line` cambia y puede reportarse como introducida (falso delta-fallo que suma al corte N). Es el punto ciego inverso al documentado en A-049 (agravar sin reportar).
+- `nstop.ts`: contador consecutivo de deltas-fallo por archivo (N=3). Una edición con delta limpio reinicia el contador; al tercer fallo consecutivo el archivo entra en la blocklist y `tool_call` bloquea `write`/`edit`. Solo `/qa-guardrail reset <archivo>` (desbloqueo humano) lo saca.
+
+## Qué NO hace todavía
+
+- Adaptadores `ruff`/`pylint` concretos (quedan el registro whitelisted y la base CLI preparados), formatter/autofix, y el job de lint en CI/`ship.ts`.
+
+## Configuración
+
+`.pi/qa-guardrail.json` (versionado en la raíz del repo) es de **solo selección**: declara qué adaptador cubre qué archivos, nunca binarios, args ni formatter (cerco autosellante):
+
+```json
+{
+  "tools": [
+    {
+      "id": "eslint",
+      "include": ["**/*.{ts,tsx,js,mjs,cjs}"],
+      "exclude": [],
+      "rootMarkers": ["package.json"],
+      "enabled": true
+    }
+  ]
+}
+```
+
+Esquema: `tools: [{ id, include, exclude, rootMarkers, enabled? }]`. `include` vacío no cubre nada (fail-closed, igual que ESLint flat config). `exclude` gana sobre `include`. `rootMarkers` ubica la raíz del proyecto (donde vive `eslint.config.mjs`).
+
+## Comandos
+
+- `/qa-guardrail reset <archivo>` — desbloqueo humano tras el corte en N.
+- `/qa-guardrail check` — barrido completo: lista violaciones y directivas heredadas (sin bloquear).
+
+## Arquitectura
+
+| Módulo | Responsabilidad |
+|--------|-----------------|
+| `config.ts` | Carga, parsea y valida `.pi/qa-guardrail.json`; ausente/inválido → warning y gate off. También `findProjectRoot`. |
+| `selection.ts` | Mapea un archivo al id del adaptador que lo cubre (globs `include`/`exclude`). |
+| `adapters/registry.ts` | Registro whitelisted `id → adaptador`. Ids desconocidos se rechazan con warning. |
+| `adapters/eslint.ts` | `lint(file, {root,cwd}) → Violation[]` vía API Node de ESLint. Import dinámico perezoso, instancia única; lanza cuando eslint falta o su config está rota (el runner avisa y omite el feedback). |
+| `adapters/cli.ts` | Base para adaptadores CLI futuros: resolución perezosa del binario; lanza cuando el binario falta o el run/parse falla (el runner avisa y omite el feedback). |
+| `feedback.ts` | Construye el resumen compacto (o `null` si no hay violaciones). |
+| `baseline.ts` | Línea base congelada por archivo y sesión (capturada en `tool_call`; vacía para archivos nuevos). |
+| `delta.ts` | `current − baseline` como diferencia de multiconjuntos. |
+| `nstop.ts` | Contador consecutivo de deltas-fallo (N=3), blocklist y desbloqueo humano. |
+| `cerco.ts` | Lista protegida hardcodeada y detección de directivas `eslint-disable*` (bloqueo en `tool_call`). |
+| `check.ts` | Barrido completo `/qa-guardrail check`: enumera archivos coincidentes, lista violaciones y directivas heredadas. |
+| `index.ts` | Cablea `tool_call` (cerco → línea base + bloqueo) y `tool_result` (lint → delta → resumen → corte en N); registra `/qa-guardrail reset` y `/qa-guardrail check`. |
+
+## Archivos
+
+| Archivo | Propósito |
+|---------|-----------|
+| `index.ts` | Entry point. Registra el adaptador eslint y los hooks `tool_call` y `tool_result`. |
+| `config.ts`, `selection.ts`, `feedback.ts`, `baseline.ts`, `delta.ts`, `nstop.ts`, `cerco.ts` | Lógica pura y testeable. |
+| `adapters/` | Registro y adaptador eslint. |
+| `*.test.ts` | Tests unitarios de cada módulo puro. |
+| `adapters/eslint.test.ts`, `adapters/eslint-lazy.test.ts` | Tests de integración del adaptador contra un fixture y simulación de eslint ausente. |
+| `adapters/cli.test.ts` | Tests unitarios de la base CLI (carga perezosa, binario ausente, run/parse). |
+| `check.test.ts` | Tests unitarios del barrido y del formato de reporte. |
+| `check.integration.test.ts` | Tests de integración de `/qa-guardrail check` con `ExtensionAPI` mockeado. |
+| `load.integration.test.ts` | Test de integración: la extensión carga sin ningún linter instalado. |
+| `index.integration.test.ts` | Tests de integración con `ExtensionAPI` mockeado (patrón handoff). |
+| `nstop.integration.test.ts` | Tests de integración del corte en N (bloqueo, STOP, reset) con `ExtensionAPI` mockeado. |
+| `cerco.integration.test.ts` | Tests de integración del cerco (caminos protegidos y directivas) con `ExtensionAPI` mockeado. |
+| `package.json` | Vitest como única devDependency. |
+| `vitest.config.ts` | Configuración de Vitest. |
+
+## Testing
+
+```bash
+cd .pi/extensions/qa-guardrail
+npm test            # todos los tests una vez
+npm run test:watch  # watch mode
+```
+
+`eslint` y `minimatch` son peers implícitos resueltos desde el `node_modules` de la raíz del repo. Ambos se cargan perezosamente: `eslint` se importa dinámicamente en el primer lint y `minimatch` se resuelve en la primera selección. Si `minimatch` no está disponible, la selección no cubre nada (fail-closed); si `eslint` no está (o su config está rota), el adaptador lanza y el runner avisa y omite el feedback — nunca un pase silencioso. Cargar la extensión no exige ninguno de los dos.
+
+## Desarrollo
+
+Sigue el ciclo red-green-refactor ([A-003](../../../docs/adr/foundational/A-003-tdd.md)). La API de extensiones de pi está documentada en `docs/extensions.md` del paquete pi.