@milpa/comal 0.2.1 → 0.2.3

package/README.md

@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.2.1` or `npm install --global @milpa/comal@0.2.1`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.2.3` or `npm install --global @milpa/comal@0.2.3`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 

package/backend/contracts/remote-commands-v1.json

@@ -91,18 +91,6 @@
       "description": "Model capability support and provenance",
       "argument_pattern": "(?:refresh)?"
     },
-    {
-      "name": "permissions",
-      "arguments": "",
-      "description": "Permission mode, saved rules and recent decisions (read-only)",
-      "argument_pattern": ""
-    },
-    {
-      "name": "autonomy",
-      "arguments": "",
-      "description": "Current autonomy level (read-only)",
-      "argument_pattern": ""
-    },
     {
       "name": "plugins",
       "arguments": "[status|list]",

package/backend/contracts/remote-relay-answers-v1.json

@@ -0,0 +1,209 @@
+{
+  "protocol": "comal.remote.relay.answers.v1",
+  "description": "Typed browser answers to /relay cards (remote.inputs.enqueue kind=relay). Admission in Milpa is a useful pre-check, never authority: the local Comal host claims each control, revalidates it (ledger by request_id, session and epoch, local arm, expiry, card still pending, remote.inputs.validate, live relayd read) and only then mutates with the same functions as its terminal cards. The browser never sends tokens, idempotency keys, paths or ADR text. Owned by the Comal Node repository; the backend keeps a byte-identical copy.",
+  "control_ttl_seconds": 600,
+  "step_up_seconds": 600,
+  "arm_max_seconds": 28800,
+  "actions": {
+    "plan.approve": {
+      "card": "plan",
+      "fields": [
+        "digest",
+        "projection_sha256"
+      ],
+      "text": "none",
+      "text_max": 0,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "recent_login"
+    },
+    "plan.reject": {
+      "card": "plan",
+      "fields": [
+        "digest"
+      ],
+      "text": "required",
+      "text_max": 4096,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "none"
+    },
+    "question.option": {
+      "card": "question",
+      "fields": [
+        "option_index",
+        "option_label_sha256"
+      ],
+      "text": "optional",
+      "text_max": 1024,
+      "caps": [
+        "decide",
+        "converse"
+      ],
+      "step_up": "none"
+    },
+    "question.reply": {
+      "card": "question",
+      "fields": [],
+      "text": "required",
+      "text_max": 4096,
+      "caps": [
+        "converse"
+      ],
+      "step_up": "none"
+    },
+    "question.ack": {
+      "card": "question",
+      "fields": [],
+      "text": "none",
+      "text_max": 0,
+      "caps": [
+        "converse"
+      ],
+      "step_up": "none"
+    },
+    "criteria.accept": {
+      "card": "criteria",
+      "fields": [
+        "digest"
+      ],
+      "text": "none",
+      "text_max": 0,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "recent_login"
+    },
+    "criteria.reject": {
+      "card": "criteria",
+      "fields": [
+        "digest"
+      ],
+      "text": "required",
+      "text_max": 4096,
+      "caps": [
+        "plans"
+      ],
+      "step_up": "none"
+    }
+  },
+  "outcomes": {
+    "applied": [
+      "approved",
+      "rejected",
+      "decided",
+      "answered",
+      "acked"
+    ],
+    "stale": [
+      "already_decided",
+      "stale",
+      "card_gone",
+      "epoch",
+      "digest",
+      "projection",
+      "option",
+      "not_pending",
+      "kind"
+    ],
+    "refused": [
+      "local_arm_off",
+      "local_in_progress",
+      "revoked",
+      "relay_unavailable",
+      "delegation",
+      "cap_missing",
+      "host_legacy",
+      "invalid",
+      "host_error"
+    ],
+    "expired": [
+      "expired"
+    ]
+  },
+  "terminal_only": [
+    "task.resume",
+    "review.override",
+    "review.retry",
+    "relay.trust",
+    "project.create",
+    "project.start",
+    "project.stop",
+    "project.attach",
+    "swarm.start",
+    "budget"
+  ],
+  "control": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "enum": [
+          "plan.approve",
+          "plan.reject",
+          "question.option",
+          "question.reply",
+          "question.ack",
+          "criteria.accept",
+          "criteria.reject"
+        ]
+      },
+      "card_id": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{32}$"
+      },
+      "card_seq": {
+        "type": "string",
+        "pattern": "^[1-9][0-9]{0,8}$"
+      },
+      "host_epoch": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{32}$"
+      },
+      "project": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,59}$"
+      },
+      "swarm": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,119}$"
+      },
+      "subject": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,199}$"
+      },
+      "digest": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "projection_sha256": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "option_index": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 3
+      },
+      "option_label_sha256": {
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "text": {
+        "type": "string",
+        "maxLength": 4096
+      }
+    },
+    "required": [
+      "action",
+      "card_id",
+      "card_seq",
+      "host_epoch",
+      "project",
+      "swarm",
+      "subject"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,
@@ -19,9 +19,11 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "backend/verifier/transport.mjs",
     "backend/contracts/artifact-check-v1.schema.json",
     "backend/contracts/remote-commands-v1.json",
+    "backend/contracts/remote-relay-answers-v1.json",
     "backend/contracts/remote-workspace-v1.schema.json",
     "governance/source-task-v1.json",
     "governance/source-task-v2.json",

package/skills/mv3/SKILL.md

@@ -0,0 +1,44 @@
+# /mv3 — extensión de Chrome MV3 desde un brief
+
+Construyes o corriges una extensión de Chrome Manifest V3 que cumpla los criterios de éxito de un brief. El trabajo termina cuando cada criterio tiene evidencia observable, no cuando el código parece completo.
+
+## 1. Entiende el encargo
+
+- Lee completo el brief que nombra la tarea. Si no nombra uno, busca `brief.md`, `docs/brief.md` o `BRIEF*.md`.
+- Mira las imágenes de referencia que nombra la tarea. Si no nombra ninguna, búscalas en `assets/`, `references/` o `visual/`. Son el aspecto esperado, no decoración.
+- Haz la lista de criterios de éxito tal como los numera el brief (C1, C2, …). Si el brief no los numera, numéralos tú en el orden en que aparecen y no inventes criterios que el brief no pide.
+- Revisa lo que ya existe en el workspace antes de crear archivos nuevos.
+
+## 2. Enruta según el tipo de criterio
+
+- Usa `ChromeTask` sólo cuando el brief contenga un **DOM de popup** cuyo estado pueda comprobarse con selector/texto o con sus pruebas de comportamiento. Si está ofrecido y el criterio encaja, úsalo **ANTES de `WorkPlanSet`** y antes de adquirir packs o crear archivos. Declara el criterio y sus pruebas en una sola llamada; la casa asigna el proyecto y administra el plan.
+- Para APIs de extensión sin popup —por ejemplo `chrome.action`, `chrome.storage`, `chrome.alarms`, `chrome.tabs` o un service worker— no uses `ChromeTask` como sustituto de una prueba de API aunque esté ofrecido. Después de una adopción popup válida, usa las herramientas `Chrome*` sin duplicar la administración con `WorkPlanSet`.
+- En el resto de casos, o si no está ofrecido, usa el plan genérico con `WorkPlanSet`. La primera llamada debe incluir, además del descubrimiento del brief, una tarea de **implementación temprana** que pueda empezar en cuanto termine ese descubrimiento. No gastes una tarea o una ronda en buscar herramientas antes de tener un criterio que las necesite.
+- Declara el plan inicial sólo con **operaciones ya disponibles**. No pongas herramientas MCP, `VisualVerify` o checks de navegador aún no ofrecidos en tareas futuras: añade la tarea de verificación cuando esas operaciones existan. Cada criterio termina con al menos un check observable en Chrome; leer tu propio código no basta para verificarlo.
+
+## 3. Aspecto visual
+
+- Con el flujo coordinado, conserva los fixtures y criterios aceptados por la casa y no abras una segunda administración visual para el mismo trabajo.
+- En el flujo genérico, consulta `/visual status` (pack `visual.accept`) sólo cuando el workspace tenga componentes visuales o el brief pida aceptación visual. Si ya hay un componente aprobado, no cambies su configuración, referencias ni criterios. Si necesitas proponer uno, pide aprobación humana con los comandos exactos de `/visual status`.
+- Nunca apruebes tú referencias ni criterios. Solo la persona aprueba.
+- `VisualVerify` es el check de las tareas con interfaz que tengan componentes registrados.
+
+## 4. Construye
+
+- `manifest.json` con `"manifest_version": 3` y solo los permisos que el brief necesita. Explica en el resumen final por qué pide cada permiso.
+- Service worker para la lógica de fondo; recuerda que Chrome lo suspende: guarda el estado en `chrome.storage`, no en variables globales.
+- Content scripts para tocar páginas: el DOM real tiene iframes, shadow DOM y cambios después de cargar. Pruébalos contra páginas que los tengan cuando el brief los toque.
+- Mensajería explícita entre popup, service worker y content scripts. Maneja la respuesta ausente (pestaña cerrada, worker dormido).
+
+## 5. Verifícate en Chrome
+
+- Con el flujo coordinado, publica y ejecuta las comprobaciones con las herramientas `Chrome*` ofrecidas por la casa. No configures otro navegador ni un servidor propio para sustituirlas.
+- En el flujo genérico, sirve las páginas con `WorkspaceServe` (pack `workspace.serve`) y observa la extensión cargada con `browser.verify`. Si el navegador no ofrece carga de extensiones, configura `chrome-devtools` con `McpConfigure` usando `npx chrome-devtools-mcp@latest --isolated --categoryExtensions`.
+- Para comportamiento fuera del contrato coordinado, escribe una suite de pruebas dentro de la extensión y córrela en Chrome real contra las páginas servidas. Registra qué casos pasan.
+- Después de cada cambio, vuelve a capturar y a verificar. Una evidencia de antes del cambio ya no vale.
+
+## 6. Reporta
+
+- Por cada criterio: la evidencia que lo demuestra (check, prueba, captura) o qué falta.
+- Nunca digas que terminaste mientras un criterio no tenga evidencia.
+- Si se acaba el presupuesto de llamadas, di qué criterios quedan pendientes y que se puede continuar con `--resume`.

package/skills/mv3/skill.json

@@ -0,0 +1,4 @@
+{
+  "description": "Crea o corrige una extensión de Chrome MV3 a partir de un brief con criterios de éxito y referencias visuales",
+  "context": "inline"
+}