# Witness > Firma, verifica y rastrea regresiones de fixes marcados a lo largo del tiempo mediante un manifiesto witness Ed25519 determinista. Funciona en cualquier proyecto: clona el toolkit, inicialízalo, registra fixes y regenera en cada release. Fuente: https://skillsagentes.com/skills/ruvnet/ruflo/witness Markdown: https://skillsagentes.com/skills/ruvnet/ruflo/witness.md Repositorio: https://github.com/ruvnet/ruflo Autor: ruvnet Licencia: MIT Actualizado: hace 27 días Coste de contexto: 49 tok instalada, 1.1k tok al activarse, 1.1k tok con todos los archivos del bundle Bundle: 1 archivo, 4 KB Permisos que pide: bash(node *), read, write, edit ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add ruvnet/ruflo --skill witness --agent claude-code # Cursor npx -y skills add ruvnet/ruflo --skill witness --agent cursor # Codex npx -y skills add ruvnet/ruflo --skill witness --agent codex # Gemini CLI npx -y skills add ruvnet/ruflo --skill witness --agent gemini # Windsurf npx -y skills add ruvnet/ruflo --skill witness --agent windsurf # Cline npx -y skills add ruvnet/ruflo --skill witness --agent cline ``` ## Qué hace - Firma un manifiesto Ed25519 que lista cada fix documentado del código junto a su sha256 y una marca de texto distintiva. - Verifica que las marcas de los fixes sigan presentes en el árbol de trabajo, detectando regresiones. - Mantiene un historial temporal en JSONL para identificar en qué commit se introdujo una regresión. ## Cuándo usarla - Para que el CI de un proyecto (propio o de ruflo) bloquee publicaciones si un fix documentado se revirtió. - Al inicializar el toolkit en un proyecto nuevo y registrar sus fixes en `witness-fixes.json`. - Para consultar el historial temporal y saber cuándo se introdujo una regresión. ## Qué la activa - "Genera el manifiesto witness para este release" - "Verifica que los fixes documentados sigan presentes" - "¿En qué commit se introdujo esta regresión?" ## Antes de instalar - Requiere Node.js y el paquete `@noble/ed25519` para firmar el manifiesto. - Necesita en el PATH: node, npm - writes to your files ## Archivos - SKILL.md — 4 KB ## SKILL.md Reproducido tal cual desde ruvnet/ruflo bajo MIT. Esta sección es el documento original y está en inglés. # Witness — cryptographic fix-regression tracking The witness toolkit lets you ship every release with a *signed* manifest that lists every documented fix in your codebase along with a sha256 + marker substring. Anyone with the same git commit can re-derive the public key and verify the signature without a committed private key. A temporal history (JSONL) tracks how the fix population evolves across releases — so when a regression appears, you can pinpoint *the commit that introduced it*, not just "it's broken now." This skill works two ways: 1. **Inside ruflo** — used by ruflo's own CI to gate publishes (see `.github/workflows/v3-ci.yml` job `witness-verify`). 2. **In your own project** — copy `plugins/ruflo-core/scripts/witness/` into your repo, run `init.mjs`, register your fixes in `witness-fixes.json`, and call `regen.mjs` from your release pipeline. ## Quick start (any project) ```bash # One-time bootstrap — creates verification.md.json, # verification-history.jsonl, and witness-fixes.json template node plugins/ruflo-core/scripts/witness/init.mjs --root . # Edit witness-fixes.json: add { id, desc, file, marker } per fix. # A "marker" is a distinctive substring that MUST appear in `file` # while the fix is present. If someone reverts the fix, the marker # disappears and `verify` reports it as `regressed`. # Regenerate the manifest (signing requires @noble/ed25519) npm i @noble/ed25519 node plugins/ruflo-core/scripts/witness/regen.mjs \ --manifest verification.md.json \ --history verification-history.jsonl \ --fixes witness-fixes.json # Verify markers are present in the live tree node plugins/ruflo-core/scripts/witness/verify.mjs \ --manifest verification.md.json # Or authenticate the manifest and check source markers in a clean clone. # Generated dist/ entries are explicitly reported as skipped. node plugins/ruflo-core/scripts/witness/verify.mjs \ --manifest verification.md.json --source-only ``` ## Temporal queries (ADR-103) ```bash # Latest snapshot vs. previous node plugins/ruflo-core/scripts/witness/history.mjs \ --history verification-history.jsonl summary # For each currently-regressed fix, find the commit that introduced it node plugins/ruflo-core/scripts/witness/history.mjs \ --history verification-history.jsonl regressions # Status timeline for a specific fix node plugins/ruflo-core/scripts/witness/history.mjs \ --history verification-history.jsonl timeline --id F1 # Machine-readable for CI node plugins/ruflo-core/scripts/witness/history.mjs \ --history verification-history.jsonl summary --json ``` `summary` exits non-zero if any fix newly regressed since the last snapshot — drop it in CI as a soft pre-merge gate. ## Anti-patterns - **Hand-editing `verification.md.json`** — always regenerate via `regen.mjs`, otherwise the signature breaks. - **Markers that are too generic** (`'function'`, `'import'`) — pick something unique enough that `grep` doesn't false-positive against unrelated code. - **Skipping the history append** — without `--history`, you lose the ability to bisect when a regression was introduced. - **Committing one without the other** — `verification.md.json` and `verification-history.jsonl` belong in the same commit; the JSONL is what lets future you verify the signed manifest is the latest in the line. ## Files - `scripts/witness/lib.mjs` — shared regenerate / history logic. - `scripts/witness/regen.mjs` — CLI: sign + append history. - `scripts/witness/history.mjs` — CLI: query the temporal log. - `scripts/witness/init.mjs` — CLI: bootstrap into a fresh project. - `scripts/witness/verify.mjs` — CLI: validate signature + markers. ## In ruflo's CI `v3-ci.yml` job `witness-verify` runs after the behavioral smoke tests and before `publish`. Failure modes: | Failure | Cause | |---|---| | `signatureValid: no` | manifest hand-edited; re-run regen | | `regressed: > 0` | a documented fix lost its marker since issuance | | `missing: > 0` | a cited dist file no longer exists; rebuild or remove the entry | | `scope: source-only` | signature + source markers checked; generated entries intentionally skipped | ## Dónde encaja - Categoría: [DevOps e infraestructura](https://skillsagentes.com/categorias/devops-infraestructura.md) — Despliegues, contenedores, IaC y flujos de gestión de incidentes. - Creador: [ruvnet](https://skillsagentes.com/creators/ruvnet.md) — 275 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Harness Gepa](https://skillsagentes.com/skills/ruvnet/ruflo/harness-gepa.md): Inspecciona y audita genomas GEPA: carga y valida un genoma, renderiza el system prompt que compila, o clasifica los modos de fallo de una transcripción de ejecución. - [Deepseek Reason](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-reason.md): Completion en modo razonamiento contra deepseek-reasoner (R1) de DeepSeek. Devuelve el chain-of-thought por separado de la respuesta final. Lee DEEPSEEK_API_KEY y degrada si falta o la API no responde. - [Deepseek Chat](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-chat.md): Completion de un solo turno contra el modelo deepseek-chat de DeepSeek vía /v1/chat/completions. Lee DEEPSEEK_API_KEY y degrada con status:degraded si falta o la API no responde. Para tareas sin razonamiento. - [Adr Index](https://skillsagentes.com/skills/ruvnet/ruflo/adr-index.md): Construye o reconstruye el índice de ADRs y su grafo de dependencias ejecutando scripts/import.mjs, en vez de cientos de llamadas MCP. - [Agntcy Status](https://skillsagentes.com/skills/ruvnet/ruflo/agntcy-status.md): Muestra el estado de la integración AGNTCY/SLIM/CASA: si los paquetes están instalados, qué transporte está activo y si el enforcement de CASA está habilitado. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)