ghcopilot-hub 1.0.0

package/README.md

@@ -0,0 +1,176 @@
+# ghcopilot-hub
+
+Hub centralizado para reutilizar agentes y skills de GitHub Copilot entre proyectos y materializarlos en cada
+repositorio con un CLI declarativo.
+
+## Objetivo de v1
+
+La v1 resuelve estos puntos:
+
+- catálogo dinámico de agentes y skills leyendo el filesystem
+- packs declarativos de skills
+- manifiesto por proyecto consumidor en `.github/ghcopilot-hub.json`
+- sincronización de archivos gestionados hacia el repo consumidor
+- detección de drift y diff previo a aplicar cambios
+- preservación de personalizaciones locales en `.github/local-overrides/`
+
+No incluye versionado funcional por proyecto. Cada sincronización apunta al estado actual del hub y registra la
+revisión disponible en las cabeceras managed.
+
+## Layout del hub
+
+```text
+hub/
+  agents/            agentes compartidos
+  skills/            skills compartidas con sus assets y referencias
+  packs/             composiciones declarativas de skills
+  base/              archivos base sincronizados a cada proyecto
+tooling/cli/         CLI de materialización, diff y doctor
+docs/                documentación operativa
+```
+
+## Layout del proyecto consumidor
+
+```text
+.github/
+  ghcopilot-hub.json
+  copilot-instructions.md
+  instructions/
+  prompts/
+  agents/
+  skills/
+  local-overrides/
+.vscode/
+  settings.json
+```
+
+## Manifiesto
+
+```json
+{
+  "packs": ["spa-tanstack"],
+  "skills": ["mermaid-expert"],
+  "excludeSkills": [],
+  "settings": {
+    "onConflict": "fail",
+    "preserveLocalOverrides": true
+  }
+}
+```
+
+Reglas de resolución:
+
+- la skill `ghcopilot-hub-consumer` se instala por defecto en cualquier proyecto gestionado por el CLI
+- todos los agentes del hub se copian siempre
+- las skills finales salen de `packs + skills - excludeSkills`
+- `excludeSkills` gana incluso si una skill llega desde un pack
+- los archivos locales viven fuera de los paths gestionados
+
+## CLI
+
+Uso rápido:
+
+```bash
+npm install
+node tooling/cli/src/bin.js doctor --hub-only
+```
+
+Uso rápido con Bun:
+
+```bash
+bun install
+bun run validate:hub
+```
+
+Instalación como paquete distribuido:
+
+```bash
+npm install -g ghcopilot-hub
+ghcopilot-hub doctor --hub-only
+```
+
+Instalación global con Bun:
+
+```bash
+bun add -g ghcopilot-hub
+ghcopilot-hub doctor --hub-only
+```
+
+Uso efímero sin instalación global:
+
+```bash
+npx ghcopilot-hub@latest doctor --hub-only
+```
+
+Uso efímero con Bun:
+
+```bash
+bunx ghcopilot-hub@latest doctor --hub-only
+```
+
+Ejemplos sobre un proyecto consumidor:
+
+```bash
+ghcopilot-hub init --pack spa-tanstack
+ghcopilot-hub add skill mermaid-expert
+ghcopilot-hub remove skill tanstack-router
+ghcopilot-hub diff
+ghcopilot-hub doctor
+ghcopilot-hub update
+```
+
+## Reglas de sync
+
+Paths gestionados:
+
+- `.github/agents/**`
+- `.github/skills/**`
+- `.github/instructions/**`
+- `.github/prompts/**`
+- `.github/copilot-instructions.md`
+- `.vscode/settings.json`
+
+Paths locales:
+
+- `.github/local-overrides/**`
+
+Cada archivo gestionado lleva una cabecera de trazabilidad con:
+
+- `managed-by`
+- `source`
+- `revision`
+- `content-hash`
+
+`content-hash` permite distinguir entre un archivo desactualizado por cambios del hub y un archivo drifted por
+edición local manual.
+
+## Scaffolding del repo
+
+El catálogo sincronizable del hub vive bajo `hub/`. Así la raíz del repositorio queda reservada para tooling,
+documentación, workflows y metadata del paquete.
+
+## Desarrollo
+
+```bash
+npm run lint
+npm run format:check
+npm test
+npm run validate:hub
+npm run pack:check
+```
+
+Con Bun:
+
+```bash
+bun run validate:hub
+bun run test
+bun pm pack --quiet
+```
+
+Documentación adicional:
+
+- [docs/architecture.md](docs/architecture.md)
+- [docs/cli.md](docs/cli.md)
+- [docs/create-skill.md](docs/create-skill.md)
+- [docs/create-pack.md](docs/create-pack.md)
+- [docs/publish.md](docs/publish.md)

package/hub/agents/README.md

@@ -0,0 +1,243 @@
+# Sistema de agentes
+
+Este sistema separa el trabajo en dos fases para reducir improvisación y hacer cada cambio auditable:
+
+- **Planificación**: define el trabajo, las restricciones, los archivos exactos y la estrategia de pruebas antes de tocar código.
+- **Implementación**: ejecuta el plan aprobado con TDD, valida el resultado y pasa auditorías finales.
+
+La idea de fondo es que el sistema no dependa de que un agente "improvise bien". La planificación reduce ambigüedad, la implementación reduce desviaciones y las auditorías finales reducen regresiones y atajos.
+
+## Principios clave
+
+Este sistema no busca solo producir cambios, sino producir cambios **explicables, auditables y repetibles**. Para eso aplica unas pocas reglas de ingeniería muy concretas:
+
+- **Contract-first execution**: primero se aprueba un plan ejecutable y luego se implementa.
+- **Decision-complete handoff**: una fase no le pasa ambigüedad a la siguiente; si faltan nombres, capas, referencias o comandos, el handoff está mal.
+- **Separation of concerns**: cada agente responde a una pregunta distinta: diseñar, ejecutar, auditar producción, auditar tests o archivar.
+- **TDD y shift-left quality**: la calidad empieza antes de tocar producción, no después.
+- **Evidence-based validation**: no vale "parece correcto"; hacen falta plan, diff, tests y comandos reales.
+- **Traceability end to end**: el cambio debe poder seguirse desde la petición hasta `changelog.md`.
+
+En términos metodológicos, el flujo combina specification by contract, stage gates, architecture governance y audit trail engineering en un mismo pipeline.
+
+También aparecen conceptos clásicos de ingeniería de software y delivery como **progressive elaboration**, **quality gates**, **go/no-go decisions**, **independent verification**, **risk-based specialization** y **traceable execution**.
+
+## Fase 1: planificación
+
+La fase de planificación está orquestada por **Planificador**. Su trabajo no es programar, sino convertir una petición en un plan ejecutable y verificable.
+
+- **Explore** localiza rutas, archivos, patrones y puntos de entrada.
+- **Librarian** aporta documentación, firmas y ejemplos cuando hace falta contexto técnico.
+- **Oracle** fija decisiones de arquitectura, límites de capa y estrategia de pruebas.
+- **Momus** revisa el plan final y decide si el traspaso a implementación está libre de ambigüedades.
+
+### Qué hace realmente Planificador
+
+Planificador actúa como un diseñador de ejecución. Antes de producir un plan, clasifica la petición para decidir la profundidad necesaria:
+
+- **Trivial**: cambio pequeño y obvio.
+- **Standard**: feature, bugfix o refactor normal con varias piezas.
+- **Architecture**: cambio transversal o con impacto estructural; aquí Oracle es obligatorio.
+
+Después recorre un flujo fijo:
+
+1. **Discovery**: explora el repositorio y busca referencias reales antes de preguntar nada al usuario.
+2. **Alignment**: solo pregunta cuando faltan preferencias, tradeoffs o decisiones de producto.
+3. **Design**: construye un plan detallado con tareas atómicas, archivos exactos, pruebas, restricciones y comandos.
+4. **Persistence**: mantiene el plan vivo en memoria de sesión para que el sistema pueda retomar contexto sin rehacer el análisis.
+5. **Review**: envía el plan a Momus y no lo considera listo hasta recibir OKAY.
+
+### Valor de los agentes auxiliares en planificación
+
+- **Explore** evita preguntas innecesarias porque localiza patrones, rutas, archivos y puntos de entrada ya existentes.
+- **Librarian** reduce errores por conocimiento obsoleto cuando una decisión depende de librerías, firmas, configuración o breaking changes.
+- **Oracle** protege la arquitectura: define qué capa debe hacer cada cosa, qué no se puede mezclar y cómo debe probarse.
+- **Momus** no mejora el diseño por gusto; comprueba si Implementador podrá ejecutar el plan sin inventar nombres, pasos o validaciones.
+
+```mermaid
+%%{init: {'theme': 'forest', 'look': 'classic', 'flowchart': {'curve': 'stepBefore'}} }%%
+flowchart TD
+    user[Solicitud del usuario] --> planificador[Planificador]
+
+    subgraph fase_plan[FASE 1 · PLANIFICACION · Progressive Elaboration]
+        planificador --> explore[Explore]
+        planificador --> librarian[Librarian]
+        planificador --> oracle[Oracle]
+
+        explore --> findings[Discovery / Contexto y referencias]
+        librarian --> findings
+        oracle --> findings
+
+        findings --> questions{Alignment / Hay dudas de alcance o preferencia}
+        questions -- Si --> user_feedback[Preguntas al usuario]
+        user_feedback --> draft[Design / Plan ejecutable]
+        questions -- No --> draft[Design / Plan ejecutable]
+
+        draft --> session_memory[Persistence / Memoria de sesion]
+        session_memory --> momus[Momus]
+        momus --> approved{Quality Gate / Plan OKAY}
+
+        approved -- No --> planificador
+        approved -- Si --> approved_plan[Handoff / Contrato ejecutable]
+    end
+```
+
+En esta fase la salida importante no es código: es un plan con archivos exactos, tareas por orden, skills requeridas, pruebas [RED], implementación [GREEN], referencias y comandos de validación.
+
+### Conceptos de ingeniería presentes
+
+- **Discovery-driven planning** y **progressive elaboration**: primero se investiga y luego se concreta.
+- **Specification by contract**: el plan fija archivos, restricciones, dependencias y validaciones antes de ejecutar.
+- **Architecture governance**: Oracle y los guardrails convierten la arquitectura en una restricción activa.
+- **Verification planning**: los criterios de aceptación y comandos se definen antes de escribir producción.
+
+### Qué contiene un plan aprobado
+
+Un plan válido no es una lista genérica de ideas. Debe dejar cerrados estos puntos:
+
+- **Objetivo y alcance**: qué entra y qué no entra.
+- **Ownership por capas**: dominio, infraestructura, aplicación, interfaz y presentación.
+- **Orden de ejecución**: qué tarea bloquea a cuál.
+- **Estrategia de pruebas**: qué test nace primero y qué comando lo valida.
+- **Referencias concretas**: archivos existentes que marcan el patrón a seguir.
+- **Guardrails**: cosas que el implementador no puede hacer aunque parezcan convenientes.
+
+En otras palabras: la salida de planificación es un **contrato de ejecución**, no una propuesta abierta.
+
+## Fase 2: implementación
+
+La fase de implementación empieza solo cuando existe un plan aprobado. **Implementador** consume ese plan como contrato y no debería inventar nombres, capas ni validaciones.
+
+- Lee el plan en un orden fijo.
+- Revisa referencias antes de editar.
+- Aplica las skills exigidas por cada tarea.
+- Trabaja con TDD: primero tests, luego código.
+- Ejecuta validaciones atómicas por tarea.
+- Cierra con dos revisiones obligatorias y un archivado final: **plan-guardian**, **test-sentinel** y **archiver**.
+
+### Qué hace realmente Implementador
+
+Implementador está optimizado para ejecutar, no para rediseñar. Su primer filtro es comprobar que el plan cumple el contrato exigido por el sistema:
+
+- rutas y archivos exactos;
+- skills invocadas por tarea;
+- pasos [RED] y [GREEN];
+- restricciones `Must NOT do`;
+- referencias suficientes;
+- criterios de aceptación con comandos concretos;
+- metadatos de dependencia entre tareas.
+
+Si eso no existe, debe detenerse y pedir un nuevo paso de planificación. Esa regla es importante porque evita que la fase de implementación reabra decisiones que deberían haberse cerrado antes.
+
+### Orden interno de trabajo
+
+Implementador lee el plan en un orden deliberado:
+
+1. requisitos de producto y reglas de negocio;
+2. decisiones de contexto y arquitectura;
+3. notas de handoff para implementación;
+4. guardrails globales;
+5. estrategia de ejecución;
+6. tarea concreta a ejecutar.
+
+Ese orden evita un error común: empezar por la tarea aislada y perder restricciones globales que luego se rompen sin querer.
+
+### Flujo de ejecución por tarea
+
+Cada tarea debería recorrer este ciclo:
+
+1. leer contexto, edge cases y restricciones;
+2. comprobar dependencias y bloqueos;
+3. abrir referencias del repositorio antes de editar;
+4. aplicar las skills obligatorias de la tarea;
+5. escribir los tests [RED];
+6. ejecutar los tests y observar el fallo esperado cuando sea viable;
+7. implementar solo lo necesario para pasar a [GREEN];
+8. ejecutar la validación atómica definida en el plan;
+9. cerrar la tarea solo si pasa su criterio de aceptación.
+
+Con esto, Implementador no trabaja por intuición sino por una secuencia repetible.
+
+```mermaid
+%%{init: {'theme': 'default', 'look': 'neo', 'flowchart': {'curve': 'stepBefore'}} }%%
+flowchart TD
+    plan[Plan aprobado] --> imp[Implementador]
+
+    subgraph fase_impl[FASE 2 · IMPLEMENTACION · TDD y Quality Gates]
+        imp --> tasks[Small Batches / Tasks del plan]
+        tasks --> task_ctx[Contexto + referencias + skills]
+        task_ctx --> task_red[RED / Failing tests]
+        task_red --> task_green[GREEN / Implementacion minima]
+        task_green --> task_atomic[Atomic Validation / Go-No Go]
+        task_atomic --> more_tasks{Quedan tasks pendientes}
+        more_tasks -- Si --> task_ctx
+        more_tasks -- No --> pg[plan-guardian / Quality Gate]
+
+        pg --> pg_ok{Go-No Go / Implementacion conforme al plan}
+        pg_ok -- No --> fix_code[Feedback Loop / Corrige implementacion]
+        fix_code --> pg
+
+        pg_ok -- Si --> ts[test-sentinel / Quality Gate]
+        ts --> ts_ok{Go-No Go / Calidad validada}
+        ts_ok -- No --> fix_tests[Feedback Loop / Completa pruebas y revalida]
+        fix_tests --> ts
+
+        ts_ok -- Si --> arch[archiver / Audit Trail]
+        arch --> log[changelog.md / Trazabilidad]
+        arch --> readme[README.md / Documentacion viva]
+    end
+```
+
+En esta fase el resultado esperado es código alineado con el plan, con validaciones ejecutadas, y con documentación durable: `changelog.md` siempre actualizado y `README.md` ajustado cuando el cambio vuelva obsoleta la documentación principal del proyecto.
+
+### Auditorías y archivado obligatorios al final
+
+La implementación no termina cuando "todo compila". El sistema exige dos revisiones separadas y una etapa final de archivado:
+
+- **plan-guardian** audita el código de producción contra el plan aprobado. Busca desvíos como archivos inventados, capas mal conectadas, reglas violadas o trabajo incompleto respecto al handoff.
+- **test-sentinel** audita la parte de calidad. Comprueba que los tests pedidos existen, que se respetó la matriz de testing por capas y que hay evidencia de ejecución.
+- **archiver** corre al final, lanzado por **Implementador** solo cuando ambos revisores ya devolvieron OK para la revisión actual. Convierte el contexto final y unos Delta Specs en formato fijo en una entrada de `changelog.md` y, si al leer el `README.md` detecta que el cambio lo dejó obsoleto, también lo ajusta. Si el cambio altera un flujo o un handoff, puede cargar la skill de Mermaid del repositorio para generar y validar un diagrama antes de archivarlo.
+
+Esta separación es útil porque evita mezclar preguntas distintas:
+
+- "¿el código implementado coincide con el plan?"
+- "¿las pruebas exigidas existen y están bien ejecutadas?"
+- "¿queda una huella verificable y útil del cambio ya validado?"
+
+El sistema responde cada una con un agente diferente. Esa separación reduce sesgo de confirmación y convierte el cierre del cambio en una decisión basada en controles independientes.
+
+### Conceptos de ingeniería presentes
+
+- **Strict TDD** y **small-batch execution**: cada tarea avanza en ciclos cortos de RED -> GREEN -> validación.
+- **Atomic validation** y **go/no-go criteria**: una tarea no se cierra si no supera su validación concreta.
+- **Quality gates** e **independent verification**: plan-guardian y test-sentinel auditan desde ángulos distintos.
+- **Audit trail** y **evidence-based closure**: archiver documenta el cambio real con soporte en diff, archivos y comandos.
+
+## Traspaso entre fases
+
+La frontera entre ambas fases es deliberada:
+
+1. **Planificador** reduce incertidumbre.
+2. **Momus** bloquea planes ambiguos o incompletos.
+3. **Implementador** ejecuta sin reinterpretar el alcance.
+4. **plan-guardian** confirma que el código coincide con el plan.
+5. **test-sentinel** confirma que las pruebas pedidas existen y se han ejecutado.
+6. **archiver** deja el cambio archivado en `changelog.md` y mantiene `README.md` al día cuando el cambio afecta la documentación principal del proyecto.
+
+En resumen, el sistema usa la planificación para fijar decisiones antes de editar y la implementación para ejecutarlas con controles de calidad al final. Funciona bien solo si el plan es realmente ejecutable, los revisores bloquean de verdad y la documentación refleja el cambio real en vez de la intención.
+
+## Resumen de responsabilidades
+
+Visto como sistema, cada agente cubre un riesgo distinto:
+
+- **Planificador**: riesgo de ambigüedad.
+- **Explore**: riesgo de desconocer el repositorio.
+- **Librarian**: riesgo de aplicar documentación incorrecta o desactualizada.
+- **Oracle**: riesgo de romper arquitectura o testing strategy.
+- **Momus**: riesgo de entregar un plan imposible de ejecutar sin improvisación.
+- **Implementador**: riesgo de ejecución inconsistente.
+- **plan-guardian**: riesgo de desviación entre plan y código real.
+- **test-sentinel**: riesgo de calidad insuficiente o TDD incompleto.
+- **archiver**: riesgo de perder trazabilidad verificable del cambio una vez validado.
+
+Por eso el sistema es más rico que un simple "planner + coder": en realidad es una cadena de especialización donde cada agente estrecha el margen de error antes de pasar al siguiente.

package/hub/agents/archiver.agent.md

@@ -0,0 +1,231 @@
+---
+name: archiver
+description: "Creates or updates changelog.md and, when needed, the project README.md from orchestrator-provided context plus Delta Specs."
+tools: [execute, read/readFile, search, edit/createFile, edit/editFiles, vscode/memory]
+model: GPT-5.4 (copilot)
+user-invocable: false
+---
+
+You are **archiver**. Your mission is to answer ONE question:
+**"Can this change be archived into the project documentation accurately, using only the context provided by Implementador and the repository state?"**
+
+## Rule 0 - Input
+
+You are a **documentation-only** subagent. Implementador is the orchestrator and decides when to call you.
+
+You accept this package:
+
+1. Context from Implementador to identify the change title and intent. This may include the approved plan, a change title, or a short archival brief.
+2. ONE `Delta Specs` block derived from the real implementation. It must summarize the actual change, not the intended change.
+3. Optional verification context to include in the changelog entry, such as commands that already ran successfully.
+
+If the package does not contain enough context to write a factual changelog entry, fail fast and ask for a retry with better archival context.
+
+## Philosophy (STRICT)
+
+- The changelog is an **audit trail**, not release marketing.
+- The project `README.md` is a product-facing reference and should only change when the implementation materially changes what the project is, how it runs, or what it documents.
+- Never document behavior that was planned but not actually implemented.
+- Prefer short, traceable entries over long narratives.
+- If a diagram does not improve comprehension, do not add one.
+- Do not re-audit plan quality, code quality, or test quality. That belongs to Implementador and the review agents it orchestrates.
+
+## What You Check Before Writing
+
+1. **Archival context sufficiency**
+   - Confirm the input package gives you enough information to name the change and summarize its intent.
+   - If the title or intent cannot be derived safely, return a retry result instead of guessing.
+
+2. **Delta Specs grounded in evidence**
+   - Cross-check the `Delta Specs` with the repository using a real diff for every file listed in `CHANGED FILES`, and use `read` and `search` when needed to clarify the diff.
+   - Use `execute` to inspect the actual repository diff for each listed file before trusting Implementador's summary.
+   - Corroborate that the claimed `ADDED`, `UPDATED`, `FIXED`, or `REMOVED` items are visible in the diff or directly supported by the resulting file contents.
+   - If the Delta Specs mention files, behaviors, or commands that do not match the actual diff or workspace state, return a retry result.
+
+3. **Real diff verification (MANDATORY)**
+   - For every path under `CHANGED FILES`, inspect a real diff against repository state before writing documentation.
+   - Prefer a VCS diff such as `git diff -- <path>` and also inspect staged changes when relevant.
+   - If a listed file has no corroborating diff and is not clearly a new file in repository state, treat the Delta Specs as unsupported and return a retry result.
+   - If the diff shows materially different changes than the archival brief claims, trust the diff, not the brief.
+   - If needed, read the changed file to understand the diff precisely, but do not skip the diff step.
+
+4. **Documentation targets**
+   - `changelog.md` is the mandatory audit trail target.
+   - The project `README.md` is a conditional target and must be updated only when, after reading it, the change clearly makes some top-level documentation stale.
+   - If `changelog.md` does not exist, create it.
+   - Prepend new changelog entries after the file header so the newest archived change appears first.
+
+5. **README impact check**
+   - Read the root `README.md` and compare it against the archival context, the approved plan, and the real Delta Specs.
+   - Update `README.md` when the final implemented change affects at least one of these areas:
+     - setup or environment configuration
+     - scripts or developer workflow
+     - architecture or project structure explained in the README
+     - user-visible capabilities summarized in the README
+     - important technical constraints or persistence behavior already documented there
+   - If none of those areas became stale, do not edit `README.md`.
+
+6. **Mermaid necessity and validation**
+   - Use Mermaid only when the change modifies workflow, handoff, architecture boundaries, or multi-step interactions that are easier to understand visually.
+   - When Mermaid is needed, you MUST load the repository Mermaid skill that governs how Mermaid diagrams are created, styled, and validated in this workspace.
+
+## Delta Specs Input Contract (FIXED)
+
+Implementador must pass Delta Specs using this exact structure:
+
+```md
+<!-- OMP:DELTA-SPECS:BEGIN -->
+
+## Delta Specs
+
+### Change Title
+
+- {short archival title}
+
+### Change Intent
+
+- {1-2 bullets about the real implemented outcome}
+
+### ADDED
+
+- {new behavior, file, or workflow}
+
+### UPDATED
+
+- {changed behavior, file, or workflow}
+
+### FIXED
+
+- {bug fix or correction}
+
+### REMOVED
+
+- {removed behavior, file, or workflow}
+
+### CHANGED FILES
+
+- path/to/file.ext
+
+### VERIFICATION
+
+- Command: {real command}
+- Note: {optional note}
+<!-- OMP:DELTA-SPECS:END -->
+```
+
+Parsing rules:
+
+- `Change Title` is mandatory.
+- `Change Intent` is mandatory.
+- `CHANGED FILES` is mandatory and must list only real files.
+- `CHANGED FILES` is also the mandatory scope for real diff verification. Do not archive claims outside that verified scope.
+- Keep all headings in the input block, even if some sections contain `- None`.
+- Treat `ADDED`, `UPDATED`, `FIXED`, and `REMOVED` as archival categories. Convert `- None` into omission in the final `changelog.md` entry.
+- Treat `VERIFICATION` as optional archival context. If it contains only `- None`, keep the final changelog verification section minimal.
+
+## README Update Contract
+
+When repository evidence shows the change made `README.md` stale, edit the root `README.md` conservatively:
+
+- Update only the sections made stale by the implemented change.
+- Preserve the existing tone, language, and section structure whenever possible.
+- Do not turn the README into a changelog.
+- Do not document internal agent mechanics in the project README unless the implementation truly makes them part of the product or contributor workflow already described there.
+
+## Changelog Entry Contract
+
+Every archived entry in `changelog.md` must follow this shape:
+
+````md
+## YYYY-MM-DD | {change title}
+
+### Summary
+
+- ...
+
+### Delta Specs
+
+- ADDED: ...
+- UPDATED: ...
+- FIXED: ...
+- REMOVED: ...
+
+### Changed Files
+
+- path/to/file.ext
+
+### Verification
+
+- Commands: ...
+- Notes: ...
+
+### Diagram in mermaid format
+
+```mermaid
+...
+```
+````
+
+```
+
+Rules:
+
+- Omit any Delta Specs category that has no content.
+- Omit the `Diagram` section when a diagram is unnecessary.
+- List only real changed files.
+- Preserve existing older entries below the new one.
+- If no verification context was provided, keep the `Verification` section concise and factual.
+
+## What You Do
+
+1. Parse the archival context from Implementador and extract the change title plus business intent.
+2. Parse the provided `Delta Specs` and extract the exact `CHANGED FILES` scope.
+3. Run a real diff for each listed file and use that diff to corroborate the claimed change categories before drafting any documentation.
+4. Reduce the verified Delta Specs to factual changelog bullets only after the diff check passes.
+5. Inspect `changelog.md` if it exists; otherwise create it with a short header that explains newest-first ordering.
+6. Read `README.md` and decide whether it needs an update based on repository evidence plus the archival context and verified Delta Specs.
+7. Write or prepend the changelog entry.
+8. If needed, update the minimal stale sections of `README.md`.
+9. If a Mermaid diagram is justified, create the smallest useful diagram and validate it.
+10. Return a concise archival summary.
+
+## What You Must NOT Do
+
+- Do NOT invent acceptance results, commands, or files.
+- Do NOT trust `Delta Specs` blindly when the real diff says otherwise.
+- Do NOT summarize open failures as completed work.
+- Do NOT rewrite older changelog entries unless needed to keep the file structurally valid.
+- Do NOT add Mermaid just for decoration.
+- Do NOT archive multiple changes in one run.
+- Do NOT act as a quality gate for plan-guardian or test-sentinel.
+- Do NOT request production-code changes. If archival fails, the retry must be about documentation context or changelog structure only.
+- Do NOT edit `README.md` for minor internal-only changes that do not affect top-level project documentation.
+
+## Output Format (MANDATORY)
+
+[ARCHIVER_OK] or [ARCHIVER_RETRY]
+
+Summary: 1-2 sentences.
+
+If OK:
+- `changelog.md` updated: yes/no
+- `README.md` updated: yes/no
+- Diagram: added / omitted (with short reason)
+- Archived change title: `{title}`
+- Skills invoked: `none` or `Mermaid skill`
+
+If RETRY:
+- `changelog.md` updated: no
+- `README.md` updated: no
+- Reason: [missing archival context, diff mismatch / unsupported claim in Delta Specs, or Mermaid validation failure]
+- Retry with: [what Implementador must pass or fix before calling again]
+- Skills invoked: `none` or `Mermaid skill`
+
+If OK, include:
+
+<!-- OMP:ARCHIVER:OK -->
+
+If RETRY, include:
+
+<!-- OMP:ARCHIVER:RETRY -->
+```