Workfile

El repositorio es la base de datos.

@illodev/workfile es un protocolo nativo del repositorio para coordinar Trabajo, Documentación, Historial y Memoria duradera del proyecto entre humanos y agentes de software.

Los archivos Markdown en el repositorio son canónicos. La CLI, la API HTTP y la interfaz local usan los mismos servicios centrales, registro de colecciones, índice y reglas de validación. No se mantiene estado exclusivo en el navegador ni en una base de datos.

Trabajo, Documentación, Historial y Memoria comparten el índice común de ProjectRecord. El núcleo, la CLI, el servidor HTTP y el runtime MCP están escritos en TypeScript y se distribuyen como ESM compilado con declaraciones públicas. La interfaz local está precompilada e incluida en el paquete, y la búsqueda semántica se ejecuta en el dispositivo mediante el paquete de espacio de trabajo opcional @illodev/workfile-search-local.

Prueba la demo en vivo — reproduce el espacio de trabajo de este mismo repositorio: las tarjetas reales, lanzamientos, incidentes y aprendizajes del desarrollo de Workfile. Las mutaciones funcionan por sesión de navegador y se restablecen al recargar.

https://github.com/user-attachments/assets/c9cd3035-6729-4cda-9172-984829ab5dbc

Usado por

En producción

Workfile — dogfooding: cada lanzamiento se planifica y registra en el propio .project/

Límites

Workfile registra el trabajo. No configura agentes.

Ambos se confunden porque viven junto al mismo repositorio. Los configuradores de ecosistemas — gentle-ai es un buen ejemplo — instalan una persona, habilidades seleccionadas, enrutamiento de modelos, servidores MCP y puertas de revisión en los agentes que ya usas, en muchos agentes a la vez. Su pregunta es cómo funciona tu agente. La pregunta de Workfile es qué se hizo, quién lo tiene y con qué evidencia, y su respuesta son archivos Markdown que sobreviven al agente, a la sesión y a este paquete.

Se complementan. Un agente bien configurado aún necesita un lugar duradero para anotar lo que hizo.

Lo que está aquí, y no es trabajo de un configurador:

• El repositorio es canónico. Una tarjeta es un archivo en la solicitud de extracción: revisada en el diff, reportada por workfile doctor cuando está malformada. Sin estado exclusivo en un navegador, una base de datos o ~/.config. Elimina el paquete y los registros siguen siendo legibles.
• Las afirmaciones se aplican, no se acuerdan. La propiedad se verifica en la mutación, por lo que una tarjeta que otro actor posee rechaza tu transición con CARD_CLAIM_OWNER_MISMATCH en lugar de aceptarla silenciosamente — una garantía que ninguna frase en un prompt puede ofrecer.
• review no es done. done requiere evidencia de algún lugar donde el código realmente se ejecutó. Una fusión no es evidencia.
• Los humanos leen los mismos registros. La interfaz, el changelog renderizado y los lanzamientos se derivan exactamente de lo que el agente escribe; no hay una vista de máquina y una vista humana que mantener sincronizadas.

Lo que está deliberadamente ausente: Workfile no instala ni actualiza agentes, no envía una persona, no enruta modelos ni selecciona un catálogo de habilidades. Sincroniza su propio protocolo en los archivos de instrucciones que un agente ya lee (workfile agents sync) y expone cada operación a través de MCP — neutral respecto al proveedor, pero un servidor, no un ecosistema.

Requisitos

• Node.js 22 o más reciente.
• npm, pnpm, yarn o Bun pueden invocar el paquete.

Instalación

Cada comando workfile … en este README requiere que el paquete esté instalado — pnpm dlx / npx de una sola vez ejecutan un comando y descartan el binario después:

pnpm add -D @illodev/workfile     # per repository (recommended)
pnpm workfile doctor              # dependency bins run through pnpm / npx

pnpm add -g @illodev/workfile     # or globally: `workfile` lands on your PATH
workfile doctor
wf doctor                         # `wf` is the same binary, for typing by hand

wf es un alias, no un cambio de nombre: ambos nombres llegan al mismo punto de entrada, y la ayuda y las pistas de error responden en el que hayas escrito. Mantén la forma larga en cualquier cosa generada o compartida. wf solo se resuelve una vez que el paquete está instalado, y existe un wf no relacionado en el registro — por lo que npx wf buscaría la herramienta de otra persona donde npx workfile falla directamente.

pnpm dlx @illodev/workfile init es adecuado para la inicialización de una sola vez, pero mantén el paquete como devDependency después: eso es lo que hace que los scripts project* que init agrega a package.json se resuelvan. Ese prefijo es un espacio de nombres de scripts npm — pnpm project opens the UI, pnpm project:doctor ejecuta las comprobaciones — y no tiene nada que ver con el nombre antiguo del binario.

API de TypeScript

La superficie publicada expone JavaScript y declaraciones a través de exportaciones condicionales de paquetes. Los consumidores de TypeScript reciben contratos tipados de configuración, espacio de trabajo, registros, búsqueda e integración desde el paquete raíz y cada subruta documentada:

import {
    defineProject,
    type CardStatus,
    type ProjectConfig,
    type ProjectRecord
} from "@illodev/workfile";
import { createSemanticSearchProvider } from "@illodev/workfile/search";

const config: ProjectConfig = defineProject({
    schemaVersion: 2,
    name: "Billing",
    cards: {
        areas: ["api", "web"]
    }
});

const status: CardStatus = "doing";

La CLI y la interfaz no requieren TypeScript en los proyectos consumidores. React, Primer, Vite y los paquetes de tipos de la interfaz son dependencias solo de compilación; el paquete instalado sirve activos de navegador empaquetados desde dist/ui.

Espacio de trabajo

Un proyecto se descubre a través de project.config.mjs y normalmente almacena archivos propiedad del protocolo bajo .project/:

project.config.mjs
.project/
├── VERSION
├── cards/
│   └── archive/
├── assets/
├── docs/
├── changelog/
│   ├── unreleased/
│   └── releases/
├── memory/
│   ├── learnings/
│   ├── decisions/
│   ├── incidents/
│   ├── conventions/
│   └── context/
├── agents/
└── .cache/

Configuración mínima — un objeto simple, no defineProject(...). El cargador aplica defineProject por sí mismo, y una importación aquí es un especificador desnudo que el archivo solo puede resolver con node_modules presente, lo que rompe los dos consumidores que se ejecutan sin uno: un espacio de trabajo inicializado con pnpm dlx antes de que el paquete esté instalado, y la ejecución de npx del trabajo de CI generado en un clon limpio. La anotación JSDoc mantiene el tipado del editor sin una importación en tiempo de ejecución:

/** @type {import("@illodev/workfile").ProjectConfigInput} */
export default {
    schemaVersion: 2,
    name: "My project",
    cards: {
        areas: ["api", "web", "infra", "docs"]
    },
    docs: {
        sources: [
            "README.md",
            "docs/**/*.md",
            "apps/*/README.md",
            ".project/specs/**/*.md"
        ]
    },
    changelog: {
        releaseStrategy: "semver",
        defaultVisibility: "public"
    },
    memory: {
        collections: [
            "learnings",
            "decisions",
            "incidents",
            "conventions",
            "context"
        ]
    },
    agents: {
        targets: ["agents-md", "cursor"]
    },
    ci: {
        targets: ["github"]
    },
    mcp: {
        allowMutations: true
    },
    search: {
        semanticWeight: 0.35,
        maxProviderRecords: 500
    }
};

Las áreas, rutas y vocabularios específicos del proyecto se resuelven en tiempo de ejecución y se exponen a través del esquema efectivo. Los ocho estados de Trabajo y las semánticas de la colección de memoria del esquema v2 siguen siendo contratos del protocolo.

Trabajo

Las tarjetas son registros Markdown gestionados bajo .project/cards/. El módulo de Trabajo proporciona jerarquía, dependencias, reclamaciones, alcance, transiciones de estado, archivos, activos y escrituras conscientes de conflictos.

workfile card list --json
workfile card show T-0042 --json
workfile card create --title "Implement runtime schema" --area infra
workfile card create --json-input card.json   # body, parent, source and tags in one call
workfile card claim T-0042 --scope apps/api,packages/sdk   # actor resolves itself
workfile card transition T-0042 review
workfile card patch T-0042 --json-input changes.json --expected-revision sha256:...
workfile card archive T-0042
workfile card reopen T-0042 --status backlog

Documentación

Documentación combina dos fuentes sin copiar documentación existente:

• Documentos indexados descubiertos desde globs configurados. Reciben IDs PATH-* deterministas y permanecen de solo lectura a través del protocolo.
• Documentos gestionados almacenados en .project/docs/ con IDs DOC-NNNN estables, frontmatter tipado y mutaciones conscientes de revisiones.

Los documentos gestionados se leen recursivamente, por lo que pueden agruparse en carpetas — incluidas carpetas que crees a mano. Los IDs permanecen globales y secuenciales: una carpeta es organización, no identidad. Los documentos nuevos siguen docs.layout (kind, el predeterminado, los agrupa por tipo de documento; flat los escribe en la raíz gestionada) y --folder lo anula.

workfile doc list --query billing
workfile doc show DOC-0012 --json
workfile doc create --title "Deployment runbook" --kind runbook --status current
workfile doc create --title "Rate limiting" --folder architecture/billing
workfile doc move DOC-0012 --folder architecture
workfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...

El doctor detecta enlaces locales rotos, registros relacionados o reemplazados sin resolver, rutas de alcance faltantes y relaciones de revisión/fuente obsoletas.

Historial

El Historial usa fragmentos de cambio atómicos en lugar de pedir a múltiples ramas o agentes que editen un CHANGELOG.md compartido.

Fragmento no lanzado:

---
id: CHG-0042
title: Add portable history workspace
type: added
area: infra
visibility: public
cards: [T-0042]
created: 2026-07-28
updated: 2026-07-28
---

Un lanzamiento consume fragmentos seleccionados, los mueve bajo el directorio de lanzamiento y crea un registro canónico REL-NNNN. Los changelogs públicos o internos son salida derivada.

workfile changelog list --unreleased
workfile changelog add --title "Add portable history" --type added --area infra
workfile changelog preview
workfile changelog release 0.4.0 --title "History and Memory"
workfile changelog render --visibility public
workfile changelog render --visibility public --write
workfile changelog verify

Las versiones de lanzamiento pueden usar validación semver, calendar o freeform según la configuración. Los fragmentos y lanzamientos participan en la misma búsqueda de archivos de trabajo y grafo de enlaces inversos que las tarjetas, documentos y memoria.

Memoria

La Memoria es un conjunto de registros tipados, atómicos y conscientes del ciclo de vida en lugar de una única transcripción de conversación en crecimiento:

Colección	Prefijo	Propósito
Aprendizajes	LRN	Observaciones reutilizables con señales de confianza y ocurrencia
Decisiones	ADR	Decisiones propuestas, aceptadas, rechazadas o reemplazadas
Incidentes	INC	Eventos operativos, gravedad, tiempos y acciones correctivas
Convenciones	CONV	Reglas duraderas seguidas por humanos y agentes
Contexto	CTX	Estado del proyecto útil pero potencialmente expirable

workfile memory list --collection learnings --status active
workfile memory add learning --title "Atomic fragments avoid merge conflicts" \
  --confidence high
workfile memory add decision --title "Keep Markdown canonical" --status accepted
workfile memory add incident --title "Release pipeline stalled" --severity high
workfile memory graduate LRN-0004 --to CONV-0002,DOC-0012
workfile memory supersede ADR-0003 --by ADR-0009
workfile memory patch CTX-0002 --json-input changes.json --expected-revision sha256:...
workfile memory verify

El doctor verifica estados de ciclo de vida inválidos, objetivos de graduación/reemplazo faltantes, contexto expirado y metadatos de resolución de incidentes incompletos.

Índice unificado

Cada módulo normaliza sus archivos como entradas ProjectRecord a través de un registro de colecciones común. El índice derivado del proceso local proporciona:

• búsqueda de texto ponderada en todo el proyecto;
• búsqueda por ID de registro estable;
• referencias salientes y enlaces inversos entrantes en los cuatro dominios;
• enlaces de tarjetas source: y enlaces Markdown locales;
• señales de salud, ciclo de vida y frescura específicas del módulo;
• recuentos de módulos y colecciones.

El estado canónico siempre permanece en disco. La caché del servidor es de corta duración, invalidable y totalmente reconstruible.

workfile search "billing architecture"
workfile search release --kind change,release,memory --limit 25 --json

Inicialización

El inicializador puede ejecutarse interactivamente o de forma determinista en automatización. Detecta el gestor de paquetes, carpetas de monorepo, áreas de tarjetas probables, fuentes de documentación, entornos de agentes existentes y proveedores de CI. Una ejecución en seco expone el plan exacto del sistema de archivos.

pnpm dlx @illodev/workfile init
pnpm dlx @illodev/workfile init --yes \
  --agents agents-md,claude,cursor,copilot --ci github
workfile init --dry-run --json

El project.config.mjs generado exporta un objeto simple, por lo que un espacio de trabajo inicializado mediante pnpm dlx sigue siendo cargable antes de que el paquete esté instalado localmente. Los archivos existentes no se sobrescriben a menos que --force sea explícito. .project/.cache/ se agrega a .gitignore; todos los archivos canónicos del protocolo permanecen rastreados.

Demo alojada

La interfaz incluye un modo de demostración para alojamiento estático (Vercel, GitHub Pages, cualquier servidor de archivos). npm run build:demo compila la interfaz con una API en memoria que reproduce una instantánea de un espacio de trabajo sembrado: cada vista funciona y las mutaciones se comportan normalmente durante la sesión, luego se restablecen al recargar. El repositorio incluye un vercel.json, por lo que importarlo en Vercel despliega la demo con cero configuración.

pnpm run demo:data   # reseed and resnapshot packages/workfile/ui/src/demo-data.json
pnpm run build:demo  # static demo build into packages/workfile/dist/demo

Las compilaciones regulares eliminan la capa de demo y la instantánea del paquete.

Lanzamiento

Los lanzamientos se publican desde CI mediante npm publicación de confianza (OIDC) — no se almacena ningún token npm en el repositorio. Antes de cortar, si algún cambio de interfaz se envió desde la última etiqueta, ejecuta pnpm run screenshots: recaptura cada vista y publica las imágenes fijas del README y la página de destino por sí mismo, y pertenecen al commit que movió el shell, no al aumento de versión. El circuito:

1. Corta el changelog: workfile changelog release <version> y workfile changelog render --write.
2. Aumenta la versión y etiqueta: npm version <version> luego git push && git push --tags. El hook de versión lleva cada paquete packages/* dentro del mismo aumento — los paquetes del espacio de trabajo siempre envían la versión del núcleo.
3. El flujo de trabajo Release verifica que la etiqueta coincida con package.json (y que ninguna versión del espacio de trabajo se haya desviado), ejecuta check:release (compilación, verificaciones de tipos, pruebas, auditoría y una prueba de humo del tarball empaquetado) con pnpm, y publica el núcleo y cada paquete del espacio de trabajo con la CLI de npm bajo latest.

No hay canal de prelanzamiento: cada versión publicada está a un npm install de distancia, y una etiqueta v*-rc.* falla el lanzamiento en lugar de publicar. Eso es una consecuencia de la publicación de confianza más que una preferencia — OIDC autoriza npm publish y ninguna otra escritura de registro, por lo que CI no puede mover una etiqueta de distribución fuera de un candidato de lanzamiento una vez que se ha establecido.

Protocolo de agente

Las instrucciones canónicas y los flujos de trabajo viven bajo .project/agents/. Bloques gestionados compactos se sincronizan en entornos compatibles sin reemplazar contenido de usuario no relacionado:

AGENTS.md
CLAUDE.md
.cursor/rules/workfile.mdc
.github/copilot-instructions.md

workfile agents sync
workfile agents sync --targets agents-md,claude,cursor,copilot
workfile agents check
workfile agents context --card T-0042

Los bloques gestionados llevan la versión del paquete y un digesto SHA-256. agents check y workfile doctor informan sobre instrucciones generadas faltantes, no gestionadas o desactualizadas. El contexto del agente está acotado y prioriza la tarjeta seleccionada, las relaciones directas, las convenciones activas, los incidentes no resueltos y el contexto no caducado en lugar de cargar toda la memoria del workfile.

Protocolo de Contexto de Modelo

Workfile incluye un servidor MCP local, sin dependencias, que utiliza JSON-RPC delimitado por nuevas líneas en UTF-8 sobre stdio. Delega cada operación a los mismos servicios centrales que usa la CLI y la API HTTP, habla tanto la revisión moderna (2026-07-28) como la heredada (2025-11-25) del protocolo, y expone 32 herramientas, cuatro recursos y tres indicaciones. Las herramientas de mutación desaparecen por completo en el modo --read-only.

Apunta un cliente a él sin instalar nada. Esta es la invocación que el registro oficial publica para io.github.illodev/workfile, y lo que la mayoría de los clientes construirán para ti a partir de esa lista:

{
  "mcpServers": {
    "workfile": {
      "command": "npx",
      "args": ["-y", "@illodev/workfile", "mcp"]
    }
  }
}

mcp hay un subcomando, no un binario: npx resuelve el bin cuyo nombre coincide con el paquete y le pasa todo lo que sigue. Añade --root PATH cuando el cliente se inicie en un lugar distinto al espacio de trabajo; de lo contrario, busca hacia arriba .project/, y --read-only para servir solo las herramientas de lectura, con toda mutación rechazada.

Con el paquete instalado, el mismo servidor está a un subcomando de distancia:

workfile mcp
workfile mcp inspect --json
workfile mcp config --read-only --json

Para Claude Code, la misma superficie se distribuye como un plugin: el servidor MCP más los comandos /claim, /card-context, /next y /done, una habilidad y hooks que convierten las afirmaciones de las tarjetas en una salvaguarda ejecutable, sin archivos generados comprometidos en el repositorio:

/plugin marketplace add illodev/workfile
/plugin install workfile@illodev

El contrato completo (inventario de herramientas, recursos, indicaciones, higiene de procesos y la superficie del plugin) está documentado en docs/mcp.md.

El servidor está listado en Glama, que lo construye en un contenedor e inspecciona las capacidades que reporta:

Integraciones de búsqueda

La búsqueda léxica sigue siendo determinista y local. Los hosts pueden inyectar un proveedor semántico opcional mediante programación; Workfile nunca selecciona un proveedor ni envía contenido del repositorio por la red por sí mismo.

De primera parte: incrustaciones locales

@illodev/workfile-search-local ejecuta incrustaciones en el dispositivo (onnxruntime-web, ONNX en CPU, Xenova/multilingual-e5-small cuantizado); el contenido del repositorio nunca sale de la máquina. Decláralo en project.config.mjs con una importación protegida, porque la configuración también debe cargarse donde el paquete no puede resolverse (el trabajo de CI generado ejecuta npx en un clon limpio):

export const integrations = await (async () => {
    try {
        const { localSearchIntegration } = await import(
            "@illodev/workfile-search-local"
        );
        return [localSearchIntegration()];
    } catch {
        return []; // package absent: search stays lexical
    }
})();

export default {
    // …
    search: { provider: "local-embeddings" }
};

Conoce el modelo de costos antes de conectarlo: la primera búsqueda híbrida incrusta cada registro candidato no almacenado en caché: minutos de CPU sostenida en un espacio de trabajo de unos pocos miles de registros, activados por la superficie que busque primero (CLI, interfaz del tablero o el servidor MCP que carga un agente). El proveedor limita ONNX a la mitad de los núcleos por defecto, persiste por lote para que un pase interrumpido se reanude en lugar de reiniciarse, e informa el progreso en stderr; ajustar search.maxProviderRecords a tu corpus hace que cada registro sea elegible. Detalles y opciones en packages/search-local/README.md.

Trae el tuyo

import {
    createSemanticSearchProvider,
    searchProjectRecordsHybrid
} from "@illodev/workfile/search";

const provider = createSemanticSearchProvider({
    id: "company-embeddings",
    async search({ query, records }) {
        // Return [{ id, score }] with scores between 0 and 1.
        return rankWithYourApprovedProvider(query, records);
    }
});

const result = await searchProjectRecordsHybrid(index.records, query, {
    provider,
    semanticWeight: 0.35
});

El límite del adaptador hace que la divulgación de datos externos sea una decisión explícita del host y mantiene la implementación canónica de Markdown/índice independiente del proveedor.

Registro de integración experimental

Los hosts programáticos pueden agrupar adaptadores de búsqueda semántica y salud aprobados en un registro pequeño y neutral para el proveedor:

import {
    createIntegrationRegistry,
    defineProjectIntegration
} from "@illodev/workfile/integrations";

const integrations = createIntegrationRegistry([
    defineProjectIntegration({
        id: "company.platform",
        semanticSearchProvider: provider,
        async healthCheck({ workspace, index }) {
            return [];
        }
    })
]);

El registro es aceptado por el servidor MCP y las API de doctor. Está intencionalmente limitado en el RC actual: los rastreadores de problemas específicos del proveedor, los sistemas de implementación y las credenciales no forman parte del paquete canónico. El límite puede madurar a partir de integraciones reales sin comprometer el esquema con GitHub, GitLab, Jira o un proveedor de implementación.

Plantillas de CI

Los archivos de CI usan el mismo contrato de archivos gestionados y se pueden generar para GitHub Actions, GitLab CI o un ejecutor de shell genérico:

workfile ci sync --targets github,gitlab,generic
workfile ci check

Las plantillas ejecutan tanto el doctor de workfile como la verificación de sincronización del agente contra la versión fijada de Workfile.

Migración heredada

El sistema v1 .planning se puede planificar y aplicar con comprobaciones deterministas de colisiones:

workfile migrate plan --source .planning
workfile migrate apply --source .planning --mode copy
workfile migrate apply --source .planning --mode move

Las tarjetas y activos heredados válidos se convierten en registros de trabajo v2 canónicos. Las propuestas antiguas, los changelogs, los aprendizajes y los registros malformados se conservan bajo .project/sources/legacy-planning/ en lugar de reinterpretarse silenciosamente con un esquema incompatible. Cada migración aplicada escribe .project/migrations/legacy-planning.json con metadatos de origen, destino, digesto y resultado.

CLI general

workfile init
workfile schema --json
workfile doctor --json
workfile ui
workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com

Los comandos devuelven errores estables legibles por máquina con --json. Una revisión desactualizada sale con el código 3; los errores de configuración salen con el código 2; los errores de validación y no encontrado salen con el código 1. La superficie completa de comandos está documentada en docs/cli.md.

API HTTP

workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com sirve el mismo tablero como algo que la gente lee: cada ruta de mutación responde 409 WORKSPACE_READ_ONLY y la interfaz elimina sus herramientas de edición. Sigue sin tener autenticación propia, así que coloca un proxy inverso que autentique delante de cualquier cosa publicada de esta manera; consulta docs/security.md.

workfile ui inicia el servidor local, normalmente en http://127.0.0.1:4747. La superficie versionada /api/v2/* cubre el espacio de trabajo, la búsqueda unificada y cada colección: tarjetas, documentos, changelog (incluyendo vista previa/ensamblaje/renderizado de versiones), ciclo de vida de memoria, agentes y sincronización de CI. Las lecturas de registros gestionados exponen un ETag, las escrituras aceptan If-Match y los errores usan códigos estables. La referencia de endpoints vive en docs/http-api.md.

Interfaz local

La navegación es una barra lateral plegable agrupada por dominio:

• Trabajo: Explorador, Triaje, Flujo, Épicas y una Línea de tiempo Gantt (barras de colores por estado, escala mensual, marcador de hoy).
• Conocimiento: Documentos (búsqueda, Markdown, metadatos, frescura, alcance, enlaces de retroceso) y Memoria (colecciones tipadas, advertencias de ciclo de vida, graduación y sustitución).
• Proyecto: Flujo de trabajo (el grafo de procedencia: cada registro un nodo, relaciones tipadas como aristas), Historial (fragmentos, versiones, preparación de versiones, vista previa del changelog renderizado) y Salud.

Los problemas de salud pueden navegar a registros en cualquier dominio. La configuración en tiempo de ejecución impulsa las áreas de tarjetas, los vocabularios de cambios y los estados de colecciones de memoria; estos valores no están compilados en las vistas. Los enlaces de archivos abren el editor local, o la interfaz web del repositorio cuando el servidor proporciona un repoUrl (como hace la demo alojada).

La Vista general responde "cómo vamos" en una frase elegida de peor a mejor: errores de doctor, afirmaciones colgantes, alcances en colisión, tarjetas bloqueadas, trabajo en curso, por encima del rastro de cada movimiento que los agentes escribieron mientras estabas ausente.

Explorador con el inspector abierto	Línea de tiempo Gantt

Historial con versiones	Memoria (tema oscuro)

El Flujo de trabajo lee las colecciones en un solo grafo en lugar de cuatro listas: la primera fila de alternancias las selecciona, la segunda selecciona los tipos de relación. Una relación declarada en frontmatter dibuja una arista sólida y un ID escrito en una frase una discontinua, porque un enlace en prosa es una afirmación más débil que un campo y no debería verse igual de sólido. El escaneo de prosa está desactivado por defecto: son 294 de las 742 aristas de este espacio de trabajo. La imagen de arriba es el corpus curado con sus relaciones declaradas: un documento related a la tarjeta que rastrea, un aprendizaje al incidente que lo enseñó, una decisión a la tarjeta que resolvió, de modo que una tarjeta, la decisión detrás de ella y el documento que la describe se lean como un solo objeto.

Desarrollo

El repositorio es un espacio de trabajo pnpm: la raíz es un shell privado que contiene la versión y los scripts delegadores, mientras que todo lo publicado vive bajo packages/: el núcleo en packages/workfile, proveedores como packages/search-local a su lado, todos enviados en bloqueo de versiones. pnpm está fijado mediante el campo packageManager (corepack enable lo recoge automáticamente):

pnpm install
pnpm run check
pnpm run smoke:package
node ./packages/workfile/dist/bin/workfile.js mcp inspect --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js schema --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js doctor --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js ui --root ./packages/workfile/test/fixtures/workspace

pnpm run check compila el runtime de TypeScript y las declaraciones, verifica el contrato estricto del consumidor público, verifica tipos y empaqueta la interfaz de React, y ejecuta la suite de pruebas completa. pnpm run smoke:package empaqueta e instala el tarball real en un proyecto temporal antes de ejercitar la inicialización, los cuatro dominios, MCP y la interfaz empaquetada: las instalaciones de humo usan npm a propósito, ejercitando la ruta del consumidor de npm.

prepack reconstruye las declaraciones del runtime y la interfaz para que un paquete publicado futuro contenga solo artefactos de runtime compilados bajo dist/, nunca TypeScript de desarrollo o un árbol de fuentes de interfaz copiado.

Garantías actuales

• códec de frontmatter restringido con idas y vueltas de escalares/listas estables en bytes;
• preservación de campos de frontmatter desconocidos y bytes del cuerpo;
• reemplazo atómico de archivos, bloqueos por registro y reservas de ID a prueba de colisiones;
• tokens de revisión SHA-256 y rechazo de escrituras desactualizadas;
• operaciones atómicas de afirmaciones, transiciones, archivo y reapertura de Trabajo;
• mutaciones gestionadas de Documentos, fragmentos de Historial y Memoria tipada;
• ensamblaje de versiones con consumo canónico de fragmentos y renderizado derivado;
• rutas seguras para el repositorio y vocabularios de runtime configurables;
• normalización común, búsqueda, referencias y enlaces de retroceso en todos los dominios;
• diagnósticos de salud para Trabajo, Documentos, Historial y Memoria;
• ESM compilado y declaraciones .d.ts para el paquete público y exportaciones de subrutas;
• binarios CLI/MCP empaquetados ejecutables verificados desde una instalación de tarball limpia;
• API versionada más un adaptador de compatibilidad para el tablero original.

Documentos

• docs/getting-started.md — instala, inicializa y el ciclo diario.
• docs/cli.md — referencia completa de CLI para cada módulo.
• docs/http-api.md — referencia de endpoints, convenciones y errores.
• docs/mcp.md — contrato del servidor MCP: herramientas, recursos, indicaciones.
• docs/security.md — modelo de amenazas del servidor local, guardia de solicitudes, manejo de activos y lo que está deliberadamente fuera de alcance.
• docs/ui.md — la interfaz: su construcción, la garantía de cero dependencias y cómo la migración de shadcn coexiste con el sistema de diseño.
• docs/SPEC.md — la especificación normativa del protocolo: modelo de datos, contratos de registros, semántica de revisiones y el contrato de integración MCP.