Project Brain Lite 0.3.1: endurecer contratos, preservación y verificabilidad

[ruzer]

Problem Statement

Project Brain Lite 0.3.0 ya mantiene un contrato pequeño, file-first y no destructivo, pero varias garantías esenciales siguen implícitas o tienen una semántica más amplia que su implementación:

• GeneratedProjection presenta conjuntamente observaciones directas, detecciones heurísticas y comandos candidatos bajo la idea general de “hechos verificados”.
• La huella actual es una huella del inventario basada en ruta y tamaño, pero puede confundirse con un hash de contenido.
• doctor comprueba estructura y seguridad, pero doctor OK no demuestra por sí solo que GeneratedProjection corresponda al estado actual del Repository.
• ContextContract define rutas, marcadores y límites, mientras que los roles, ownership y semántica de los artefactos permanecen repartidos entre plantillas, documentación y pruebas.
• Diagnostic no incluye todavía checkId ni severity; su origen y severidad se infieren por el array que lo contiene.
• La preservación de RepositoryOwnedContent está probada a nivel textual, pero no cubre completamente CRLF, BOM, Unicode, trailing spaces, ausencia de newline final ni condiciones concurrentes posteriores a la segunda lectura.
• La separación con Project Memory Hub está documentada, pero IntegrationReference no tiene una convención mínima que impida duplicar owners, fechas, riesgos, milestones o estado de gestión.

Project Brain Lite 0.3.1 debe endurecer estos contratos sin ampliar el producto: debe conservar Node.js 20+, cero dependencias npm de runtime, comportamiento determinista, operación local-first y file-first, sólo cinco archivos canónicos, sólo tres comandos y ninguna ejecución autónoma.

Solution

Project Brain Lite 0.3.1 formalizará el siguiente modelo de dominio y lo reflejará de forma consistente en documentación, plantillas, proyección generada, diagnósticos y pruebas:

• Repository es la autoridad factual primaria.
• TechnicalContextBundle es el agregado de los cinco ContextArtifact canónicos.
• GeneratedProjection es la única región sobre la cual Project Brain tiene autoridad de escritura después de la inicialización.
• RepositoryOwnedContent es todo contenido que Project Brain debe preservar, aunque originalmente haya sido creado desde una plantilla.
• RepositoryObservation es el resultado determinista y local de observar el repositorio; no se presentará como snapshot transaccional ni como hash completo del contenido.
• TechnicalSource es evidencia técnica localizada dentro del repositorio.
• ObservedFact es una afirmación directamente sustentada por una TechnicalSource.
• Detection es una inferencia determinista producida mediante reglas conocidas.
• TechnicalDecision, TechnicalTask y TechnicalLearning son registros humanos con propósitos diferentes y limitados al dominio técnico.
• ContextContract gobierna topología, roles, marcadores, ownership y presupuestos editoriales.
• DoctorCheckResult resume una comprobación y Diagnostic comunica su check, severidad, código y ubicación.
• IntegrationReference es una referencia Markdown con procedencia hacia otra autoridad; nunca es un conector, sincronizador ni copia de registros.

La proyección generada separará visualmente observaciones verificadas, detecciones heurísticas y comandos candidatos de validación. Doctor añadirá diagnósticos warning-only para roles/frontmatter incorrectos y para una proyección desactualizada. Los arrays públicos errors[] y warnings[], los comandos, las rutas, los nombres de artefactos y los exports existentes permanecerán compatibles.

La escritura de CONTEXT.md preservará exactamente los bytes UTF-8 válidos exteriores a los marcadores y fallará cerrada si el contenido o la identidad esperada del archivo cambia antes del commit.

User Stories

1. Como maintainer de Project Brain Lite, quiero que el vocabulario del producto coincida con su comportamiento, para que los contratos no dependan de interpretaciones informales.
2. Como persona que mantiene un repositorio, quiero distinguir GeneratedProjection de RepositoryOwnedContent, para saber qué puede regenerarse y qué nunca debe sobrescribirse.
3. Como agente externo, quiero distinguir un ObservedFact de una Detection, para no tratar una heurística como evidencia primaria.
4. Como agente externo, quiero que los comandos aparezcan como candidatos de validación, para no asumir que fueron ejecutados o que pasaron.
5. Como maintainer, quiero que la huella se describa como fingerprint del inventario, para no confundirla con un hash del contenido del repositorio.
6. Como usuario de doctor, quiero saber si GeneratedProjection está desactualizada, para no confundir conformidad estructural con frescura.
7. Como usuario de doctor, quiero que una proyección desactualizada produzca un warning, para conservar compatibilidad con la semántica warning-only de 0.3.x.
8. Como integrador de CI, quiero que un resultado con sólo warnings mantenga ok: true y exit code 0, para no romper pipelines existentes.
9. Como consumidor de JSON, quiero que cada Diagnostic incluya checkId y severity, para no inferirlos por su posición.
10. Como consumidor de JSON existente, quiero conservar errors[], warnings[] y checks[], para que la ampliación de diagnósticos sea aditiva.
11. Como autor de contexto, quiero recibir un warning si el frontmatter o el role no corresponde al ContextArtifact, para detectar drift sin una migración destructiva.
12. Como autor de contexto, quiero que doctor nunca corrija automáticamente frontmatter o contenido humano, para conservar mi autoridad sobre esos bytes.
13. Como maintainer, quiero que TechnicalDecision distinga propuesta, aceptación y reemplazo, para saber qué decisión es normativa.
14. Como colaborador, quiero que TechnicalTask represente sólo trabajo técnico activo y bloqueos actuales, para no convertir Brain en un task board.
15. Como colaborador, quiero que TechnicalLearning incluya evidencia, aplicación y límite, para reutilizarlo sin convertirlo en una regla implícita.
16. Como agente, quiero que TechnicalSource signifique evidencia dentro del repositorio, para no confundirla con una fuente de gestión de Memory Hub.
17. Como usuario de Memory Hub, quiero que owners, fechas, riesgos, milestones y estado de gestión sigan siendo canónicos allí, para evitar dos fuentes de verdad.
18. Como usuario de ambos productos, quiero enlazar registros mediante IntegrationReference, para relacionarlos sin copiarlos ni sincronizarlos.
19. Como responsable de privacidad, quiero que una referencia no descargue ni replique su destino, para mantener el producto local-first.
20. Como maintainer, quiero que sync preserve CRLF en RepositoryOwnedContent, para no introducir diffs editoriales.
21. Como maintainer, quiero que sync preserve BOM UTF-8, Unicode y trailing spaces exteriores al bloque, para mantener intacto el contenido del repositorio.
22. Como maintainer, quiero que un archivo sin newline final siga sin newline final fuera de la proyección reemplazada, para preservar exactamente su estilo.
23. Como maintainer, quiero que UTF-8 inválido falle sin escritura, para evitar normalizaciones silenciosas.
24. Como colaborador que edita CONTEXT.md mientras corre sync, quiero que una modificación posterior a la segunda lectura sea detectada, para no perder mi edición.
25. Como colaborador, quiero que un cambio de identidad del archivo destino aborte la escritura, aunque los bytes coincidan, para evitar sobrescribir un reemplazo concurrente.
26. Como usuario, quiero que cualquier incertidumbre concurrente falle cerrada y limpie temporales, para no dejar contexto parcial.
27. Como usuario de init, quiero que los archivos existentes sigan preservándose, para que 0.3.1 continúe siendo no destructivo.
28. Como consumidor de la API, quiero mantener los exports y resultados existentes, para actualizar dentro de 0.3.x sin reescribir mi integración.
29. Como usuario de CLI, quiero conservar exactamente init, sync y doctor, para que el producto siga siendo pequeño y predecible.
30. Como usuario local, quiero que ninguna comprobación necesite red, modelos o servicios externos, para conservar el funcionamiento offline.
31. Como maintainer, quiero que dos ejecuciones sobre el mismo estado produzcan el mismo resultado, para conservar idempotencia y determinismo.
32. Como maintainer del paquete, quiero pruebas black-box del binario y pruebas de la API pública, para poder reorganizar internals sin perder garantías.
33. Como mantenedor de seguridad, quiero que las pruebas concurrentes sean deterministas y no dependan de sleeps, para evitar falsos positivos y flakes.
34. Como revisor de una implementación, quiero que el scope gate siga impidiendo runtimes, comandos, archivos o dependencias adicionales, para evitar crecimiento accidental.

Implementation Decisions

MUST

MUST-1 — Formalizar dominio, autoridad y ownership

• Comportamiento actual: el ownership está expresado en prosa y en el reemplazo delimitado por marcadores, pero no existe un glosario contractual único.
• Comportamiento objetivo: usar exclusivamente el vocabulario canónico de esta spec y documentar la precedencia: Repository es autoridad factual; Project Brain controla sólo GeneratedProjection; el repositorio controla RepositoryOwnedContent; Memory Hub controla owners, fechas, riesgos, milestones y estado de gestión; Git controla el pasado.
• Invariantes afectadas: file-first, local-first, cinco artefactos, no duplicación de autoridades y preservación de contenido.
• Compatibilidad: cambio documental y semántico; no cambia rutas, comandos, exports ni formatos obligatorios de notas existentes.
• Acceptance criteria: el glosario define todos los términos canónicos; cada uno tiene una única definición de autoridad y regeneración; la documentación no usa “manual” como categoría normativa ni atribuye gestión a Brain.
• Tests requeridos: comprobaciones de documentación y plantillas para vocabulario, cinco artefactos, responsabilidades y ausencia de términos que contradigan el modelo.
• Riesgo: bajo; el principal riesgo es crear definiciones duplicadas o divergentes.

MUST-2 — Separar las tres clases de información en GeneratedProjection

• Comportamiento actual: inventario, fingerprint, stack, lenguajes, manifests y comandos aparecen bajo un encabezado general de hechos verificados.
• Comportamiento objetivo: renderizar tres secciones inequívocas: observaciones verificadas, detecciones heurísticas y comandos candidatos de validación. fileCount, fingerprint, raíces y manifests son observaciones/derivaciones directas del inventario; lenguajes y stack son detecciones; los comandos son candidatos detectados y nunca evidencia de ejecución.
• Invariantes afectadas: determinismo, seguridad Markdown, proyección limitada a marcadores y repo como autoridad factual.
• Compatibilidad: sólo cambia contenido regenerable dentro de los marcadores. La forma pública de RepositoryObservation mantiene sus campos actuales.
• Acceptance criteria: las tres secciones aparecen siempre en orden estable; valores vacíos tienen fallback estable; el fingerprint se etiqueta como huella de inventario basada en ruta y tamaño; ningún texto implica que un comando fue ejecutado o aprobado.
• Tests requeridos: render con datos completos y vacíos; escape de contenido dinámico; orden determinista; clasificación correcta de cada campo; idempotencia después de regenerar.
• Riesgo: medio, porque consumidores no contractuales podrían estar parseando headings del Markdown generado.

MUST-3 — Definir frescura sin cambiar la semántica de ok

• Comportamiento actual: doctor puede devolver ok: true aunque el repositorio haya cambiado desde el último sync.
• Comportamiento objetivo: doctor reconstruye de forma read-only la GeneratedProjection esperada y la compara con la región existente. Si difieren, emite STALE_GENERATED_PROJECTION como warning. Frescura significa igualdad de la proyección observable, no igualdad byte a byte de todo el repositorio ni igualdad del fingerprint.
• Invariantes afectadas: doctor read-only, determinismo, no ejecución de comandos y doctor OK != context fresh.
• Compatibilidad: warning-only; DoctorResult.ok, DoctorCheckResult.ok y exit code permanecen exitosos si no existen errores. Los siete check IDs actuales conservan orden e identidad. Se añaden al final artifact-roles y generated-freshness, en ese orden, como ampliación aditiva de checks[].
• Acceptance criteria: repo estable y proyección coincidente no producen warning; un cambio que alteraría la proyección produce STALE_GENERATED_PROJECTION con checkId: generated-freshness; ok y exit code siguen siendo exitosos; doctor no escribe; ejecutar sync elimina el warning; un cambio de contenido que no altera la proyección no se declara stale sólo por el fingerprint.
• Tests requeridos: stale por archivo añadido/eliminado, manifest, stack, script y manipulación manual del bloque; cambio mismo tamaño con y sin efecto sobre la proyección; salida JSON y humana; prueba explícita warning-only ⇒ ok: true y exit 0.
• Riesgo: medio; un inventario Git y un fallback local pueden observar conjuntos diferentes, por lo que el modo de inventario debe permanecer consistente durante una comprobación.

MUST-4 — Validar roles y frontmatter como warnings compatibles

• Comportamiento actual: roles y project_brain: 1 se verifican en las plantillas del paquete, pero doctor acepta archivos existentes por ruta aunque su frontmatter falte o no corresponda.
• Comportamiento objetivo: doctor emite warnings diferenciados para frontmatter ausente o ilegible, marcador de contrato incorrecto y role ausente/desconocido/no correspondiente a la ruta. Nunca reescribe ni corrige el artefacto.
• Invariantes afectadas: init no destructivo, repository-owned preservation y rutas canónicas estables.
• Compatibilidad: todas las condiciones nuevas son warnings; repositorios aceptados por 0.3.0 continúan con ok: true si no tienen errores independientes. Los archivos preexistentes siguen preservándose.
• Acceptance criteria: cada uno de los cuatro artefactos bajo AI_CONTEXT reconoce su role esperado; AGENTS.md no requiere frontmatter; los warnings usan checkId: artifact-roles e identifican el artefacto y problema; sync no modifica el frontmatter; init no reemplaza archivos existentes para repararlos.
• Tests requeridos: frontmatter ausente, incompleto, duplicado e ilegible; role incorrecto; marcador de versión incorrecto; sólo warnings; archivos intactos antes/después de doctor, sync e init.
• Riesgo: bajo a medio por falsos positivos sobre repositorios que personalizaron sus encabezados.

MUST-5 — Hacer explícito el contrato de Diagnostic

• Comportamiento actual: errors[] y warnings[] contienen objetos sin checkId ni severity; ambos valores se infieren por ubicación.
• Comportamiento objetivo: añadir a cada Diagnostic los campos checkId y severity, con severidades error o warning. Mantener code, file, message y detalles opcionales existentes. Mantener los arrays actuales y los DoctorCheckResult actuales.
• Invariantes afectadas: salida determinista, automatización estable y warning-only ⇒ ok: true.
• Compatibilidad: ampliación aditiva; no se eliminan ni renombran campos, arrays o aliases. Los códigos existentes conservan significado. Los nuevos check IDs, si son necesarios, se añaden después de los actuales.
• Acceptance criteria: todo diagnóstico tiene checkId coincidente con su check y severity coincidente con su array; counts y deduplicación siguen correctos; warning no cambia ok; error sí lo cambia; orden estable independiente del texto del mensaje.
• Tests requeridos: shapes JSON, counts, deduplicación, orden, warning-only, error, paridad entre salida CLI y API pública, y compatibilidad de campos anteriores.
• Riesgo: bajo; consumidores que hagan igualdad profunda contra objetos completos verán campos adicionales.

MUST-6 — Aclarar TechnicalDecision, TechnicalTask, TechnicalLearning y TechnicalSource

• Comportamiento actual: las notas tienen propósitos editoriales, pero “decisión vigente” convive con estados propuesta/reemplazada y la plantilla de tareas puede duplicar responsables de Memory Hub.
• Comportamiento objetivo: TechnicalDecision aceptada es la única normativa; propuesta es no autoritativa; reemplazada es una referencia breve a su sucesora. TechnicalTask contiene sólo resultado técnico activo, siguiente validación, bloqueo y referencia opcional; no replica owner, fecha, milestone ni estado global cuando exista Memory Hub. TechnicalLearning exige evidencia, aplicación y límite. TechnicalSource es evidencia localizada dentro del repositorio, no una fuente de gestión.
• Invariantes afectadas: una autoridad por dato, Git como historia, contenido humano no reescrito y frontera con Memory Hub.
• Compatibilidad: las reglas son editoriales; no se parsean ni reescriben notas existentes. Las plantillas nuevas pueden aclararse sin migrar consumidores ya inicializados.
• Acceptance criteria: documentación y templates definen las cuatro semánticas; ninguna presenta TASKS como task board; propuestas no aparecen como decisiones vigentes; owners/fechas/riesgos/milestones/estado se enrutan a Memory Hub.
• Tests requeridos: assertions de plantilla y documentación; enlaces internos; ausencia de campos de gestión como estructura recomendada de nuevas tareas técnicas.
• Riesgo: bajo; la principal dificultad es mantener una nota local útil cuando Memory Hub no esté instalado.

MUST-7 — Formalizar IntegrationReference sin integración runtime

• Comportamiento actual: los productos se enlazan por referencias con procedencia, pero no hay una convención mínima.
• Comportamiento objetivo: una IntegrationReference es Markdown repository-owned y declara cuatro campos conceptuales: system, destination, provenance y authority. destination es una ruta relativa, URL o identificador portable. La referencia no importa contenido, no se sincroniza, no se resuelve por red y no transfiere autoridad.
• Invariantes afectadas: local-first, file-first, cero red, separación de memorias y preservación humana.
• Compatibilidad: convención editorial opcional dentro de artefactos existentes; no crea un sexto archivo, schema de integración obligatorio, comando o dependencia.
• Acceptance criteria: existe una definición y ejemplo para referencia Brain→Hub y Hub→Brain; cada ejemplo nombra el sistema de autoridad; no duplica owner, fecha, riesgo, milestone o estado; referencias relativas continúan siendo auditadas por doctor y referencias remotas no generan llamadas de red.
• Tests requeridos: documentación/templates; validación de enlaces relativos existente; prueba de que doctor no intenta acceder a destinos remotos; ninguna escritura o sincronización externa.
• Riesgo: bajo; un formato excesivamente rígido convertiría una convención Markdown en un registro nuevo.

MUST-8 — Preservar RepositoryOwnedContent a nivel de bytes UTF-8 válidos

• Comportamiento actual: sync conserva prefijo y sufijo como strings y preserva modo POSIX, pero la cobertura no prueba todas las representaciones textuales requeridas.
• Comportamiento objetivo: sólo los bytes desde el marcador inicial hasta el final pueden cambiar. Todo byte válido UTF-8 anterior y posterior permanece idéntico. No hay normalización de line endings, Unicode, espacios o newline final. UTF-8 inválido falla cerrado sin escritura.
• Invariantes afectadas: init/sync no destructivos, marcadores exactos, escritura atómica e idempotencia.
• Compatibilidad: Markdown UTF-8 válido mantiene comportamiento; propietario, ACL, xattrs, inode y timestamps no se convierten en garantías de 0.3.1; el modo POSIX continúa preservándose.
• Acceptance criteria: prefijo y sufijo son byte-idénticos para LF, CRLF, BOM, Unicode NFC/NFD, emoji, trailing spaces, tabs y ausencia de newline final; una segunda sincronización deja el archivo completo idéntico; UTF-8 inválido rechaza y conserva el buffer original.
• Tests requeridos: comparación con Buffer para cada caso y combinaciones representativas; idempotencia; modo POSIX condicionado por plataforma; CLI JSON ante UTF-8 inválido.
• Riesgo: alto, porque una implementación basada únicamente en strings puede aparentar preservación sin demostrarla binariamente.

MUST-9 — Fallar cerrado ante cambios concurrentes del destino

• Comportamiento actual: sync compara una segunda lectura con la primera y la escritura valida la identidad del directorio padre, pero no demuestra que el contenido y la identidad del archivo destino sigan siendo los esperados inmediatamente antes del commit.
• Comportamiento objetivo: la escritura recibe el contenido y la identidad esperados del ContextArtifact; antes del commit vuelve a validar ambos. Cualquier cambio de bytes, inode/tipo, symlink o identidad del padre aborta sin reemplazar la edición competidora. Los temporales se limpian de forma segura.
• Invariantes afectadas: repository-owned ownership, atomicidad, confinamiento al root y fail closed.
• Compatibilidad: no cambia la firma pública de init/sync ni los resultados exitosos. Los fallos concurrentes siguen siendo errores de comando.
• Acceptance criteria: una modificación posterior a la segunda lectura se conserva y hace fallar sync; un destino reemplazado por otro inode con bytes iguales hace fallar sync; un destino convertido en symlink hace fallar; ningún caso escribe fuera del root ni deja temporales; contexto original/competidor permanece completo.
• Tests requeridos: interleaving determinista mediante checkpoint interno privado entre verificación y commit; mutación de contenido, reemplazo de identidad, symlink y cambio del directorio padre; sin sleeps ni polling; verificación de bytes, identidad y árbol antes/después.
• Riesgo: alto por condiciones TOCTOU y diferencias entre plataformas. El seam de prueba no debe convertirse en API pública.

MUST-10 — Congelar el scope y la compatibilidad 0.3.x

• Comportamiento actual: el paquete tiene Node.js 20+, cero dependencias, un binario, tres comandos, cinco artefactos y exports públicos acotados.
• Comportamiento objetivo: 0.3.1 conserva exactamente ese alcance y añade sólo endurecimiento contractual, documentación, diagnósticos, preservación y pruebas.
• Invariantes afectadas: todas las restricciones fundamentales del producto.
• Compatibilidad: no se cambian rutas, nombres canónicos, marcadores, tres comandos, API pública, arrays de doctor ni semántica warning-only. Ningún warning existente se vuelve error salvo que se demuestre que no es posible leer, auditar o preservar de forma segura.
• Acceptance criteria: el paquete sigue sin dependencias npm; sólo publica brain; help sólo muestra init/sync/doctor; el contrato contiene cinco rutas; los exports existentes permanecen; ninguna operación usa red ni ejecuta comandos detectados; el producto permanece debajo del límite de tamaño existente.
• Tests requeridos: scope gate, exports exactos, versión de CLI consistente con paquete, consumidor limpio del paquete local, binario black-box, doctor sobre el propio repositorio y worktree limpio.
• Riesgo: bajo si el scope gate permanece obligatorio; alto si las mejoras se usan para introducir abstracciones o artefactos nuevos.

SHOULD

SHOULD-1 — Publicar contratos estructurados de resultados públicos

• Comportamiento actual: las formas de scanner, init, sync y doctor son contratos implícitos en código y tests.
• Comportamiento objetivo: documentar sus shapes, campos obligatorios/aditivos y semántica de compatibilidad sin añadir una dependencia de validación runtime.
• Invariantes afectadas: API pública estable y cero dependencias.
• Compatibilidad: sólo documentación o schemas distribuidos como artefactos del paquete; no cambia ejecución.
• Acceptance criteria: consumidores pueden conocer la forma de RepositoryObservation, DoctorCheckResult y Diagnostic; se documenta que campos nuevos dentro de 0.3.x son aditivos.
• Tests requeridos: comprobación de que ejemplos/schemas corresponden a resultados reales.
• Riesgo: bajo; un schema incorrecto sería peor que no tenerlo.

SHOULD-2 — Hacer explícito el modo de observación

• Comportamiento actual: Git es preferido y el recorrido local es fallback, pero RepositoryObservation no comunica cuál se usó.
• Comportamiento objetivo: exponer de forma aditiva el modo de inventario y documentar sus límites, sin convertirlo en una nueva fuente de estado.
• Invariantes afectadas: determinismo y trazabilidad.
• Compatibilidad: campo opcional/aditivo; no cambia la huella actual ni los campos existentes.
• Acceptance criteria: el resultado identifica Git o filesystem; la misma ejecución usa un solo modo; GeneratedProjection puede omitir el dato si aumenta ruido.
• Tests requeridos: repositorio Git, fallback local y falla de Git; orden y no escritura.
• Riesgo: medio, porque el fallback no replica toda la semántica de .gitignore.

SHOULD-3 — Diagnosticar IntegrationReference incompleta

• Comportamiento actual: doctor valida enlaces, pero no la completitud conceptual de una referencia.
• Comportamiento objetivo: cuando una nota declare explícitamente una IntegrationReference, advertir si falta system, destination, provenance o authority. No intentar inferir referencias desde cualquier enlace Markdown.
• Invariantes afectadas: warning-only y contenido repository-owned.
• Compatibilidad: warning opt-in por convención reconocible; nunca error ni auto-fix.
• Acceptance criteria: referencias completas no generan warning; incompletas generan uno; enlaces Markdown normales permanecen sin nueva interpretación.
• Tests requeridos: referencia completa, campos ausentes, enlace ordinario y destino remoto sin red.
• Riesgo: medio por sobreinterpretación de Markdown humano.

SHOULD-4 — Aumentar pruebas black-box sin crear nuevos seams públicos

• Comportamiento actual: gran parte de la CLI se prueba mediante I/O inyectado y las APIs por función pública.
• Comportamiento objetivo: cubrir el binario real y un consumidor del paquete local, manteniendo las APIs públicas como seam principal. Sólo las carreras usan un checkpoint privado de pruebas.
• Invariantes afectadas: contratos de CLI, empaquetado y capacidad de reorganizar internals.
• Compatibilidad: no requiere publicación ni red.
• Acceptance criteria: init/sync/doctor, JSON, stderr/stdout y exit codes funcionan desde rutas temporales con espacios y Unicode.
• Tests requeridos: proceso real, paquete local y comparación de resultados con API.
• Riesgo: bajo; evitar snapshots frágiles del texto humano completo.

DEFER

DEFER-1 — Sustituir fingerprint por content hash

• Comportamiento actual: fingerprint es SHA-256 de ruta y tamaño.
• Comportamiento objetivo diferido: evaluar por separado una huella de contenido o de inputs semánticos si aparece un caso de uso que justifique costo, privacidad y compatibilidad.
• Invariantes afectadas: determinismo y rendimiento.
• Compatibilidad: cambiar el significado del campo actual sería breaking; no pertenece a 0.3.1.
• Acceptance criteria para reconsiderarlo: caso de uso documentado que no pueda resolverse comparando GeneratedProjection.
• Tests requeridos futuros: escala, archivos grandes, cambios mismo tamaño y confidencialidad.
• Riesgo: alto si se introduce sin límites.

DEFER-2 — Enforcement obligatorio del contenido humano

• Comportamiento actual: notas humanas son Markdown flexible.
• Comportamiento objetivo diferido: considerar validaciones bloqueantes sólo en una versión incompatible y con migración explícita.
• Invariantes afectadas: repository-owned authority e init no destructivo.
• Compatibilidad: convertir roles, estados o campos editoriales en errores rompería 0.3.x.
• Acceptance criteria para reconsiderarlo: contrato nuevo versionado y estrategia de migración autorizada.
• Tests requeridos futuros: compatibilidad de notas existentes y migración no destructiva.
• Riesgo: alto.

DEFER-3 — Metadatos de filesystem más allá del modo

• Comportamiento actual: la escritura preserva modo POSIX, no inode, timestamps, owner, ACL o xattrs.
• Comportamiento objetivo diferido: ampliar garantías sólo con necesidad multiplataforma demostrada.
• Invariantes afectadas: portabilidad y atomicidad.
• Compatibilidad: no prometerlos en 0.3.1.
• Acceptance criteria para reconsiderarlo: matriz de plataformas y semántica portable definida.
• Tests requeridos futuros: macOS, Linux y Windows con metadata soportada.
• Riesgo: alto y específico de plataforma.

DEFER-4 — Registro o conector de integraciones

• Comportamiento actual: referencias Markdown preservan independencia.
• Comportamiento objetivo diferido: ninguno para 0.3.x; cualquier registro machine-readable, sincronización, fetching o autenticación requiere una decisión de producto separada.
• Invariantes afectadas: local-first, cero red y cinco artefactos.
• Compatibilidad: fuera de alcance.
• Acceptance criteria para reconsiderarlo: caso de uso autorizado que no pueda resolverse con referencias.
• Tests requeridos futuros: privacidad, provenance, offline y autoridad.
• Riesgo: alto por acoplamiento y duplicación de fuentes de verdad.

Testing Decisions

• El seam principal será la API pública y el binario brain ejecutados contra repositorios temporales reales. Las pruebas comprobarán resultados, exit codes y bytes de artefactos, no funciones auxiliares internas.
• Scanner se probará mediante scanRepository; sync mediante syncRepository y brain sync; doctor mediante doctor y brain doctor; init mediante initRepository y brain init.
• Se reutilizarán las suites actuales de scanner, sync, doctor, init, templates, CLI y scope como prior art. No se crearán dependencias nuevas de testing.
• La proyección se probará end-to-end: mutación del Repository → doctor warning stale → sync → doctor sin warning → segundo sync idempotente.
• Los casos de preservación compararán buffers antes y después, delimitando el rango generado y verificando prefijo/sufijo byte-idénticos.
• Los fixtures mínimos obligatorios son LF, CRLF, BOM UTF-8, Unicode NFC/NFD, emoji, trailing spaces, tabs y archivo sin newline final, además de una combinación de varios casos.
• UTF-8 inválido debe producir fallo sin escritura; no debe normalizarse silenciosamente.
• Las carreras utilizarán un único seam interno privado para detener la operación entre la segunda validación y el commit. No se usarán sleeps, polling ni condiciones probabilísticas.
• La prueba concurrente debe mutar contenido, sustituir el inode con los mismos bytes, introducir symlink y cambiar identidad del padre, comprobando fail closed y limpieza.
• Doctor tendrá pruebas contractuales de checkId, severity, counts, deduplicación, orden, warning-only y error.
• Los nuevos warnings de roles y frescura se probarán como ok: true, check ok: true, exit 0 y sin escrituras.
• CLI se probará como proceso real para JSON único en stdout, warnings/errores en los canales esperados y códigos de salida estables.
• El scope gate seguirá probando Node.js 20+, cero dependencias, un binario, tres comandos, cinco artefactos, exports exactos, ausencia de runtimes adicionales y tamaño acotado.
• Una buena prueba afirma conducta visible y autoridad de escritura. Sólo la prueba de carrera puede usar un seam interno, porque la intercalación debe ser determinista.

Out of Scope

• Agents, swarm, LLM routing o cualquier runtime de IA.
• Runtime memory, bases de datos o almacenamiento remoto.
• Plugins, conectores, sincronización o fetching de IntegrationReference.
• Dependencias de red o npm runtime dependencies.
• Ejecución autónoma o ejecución de comandos candidatos.
• Nuevos comandos, nuevos archivos canónicos o nuevas rutas obligatorias.
• Cambiar los marcadores de GeneratedProjection.
• Migrar, parsear estructuralmente o reescribir contenido humano existente.
• Importar owners, fechas, riesgos, milestones, roadmap o estado desde Memory Hub.
• Fusionar los TechnicalContextBundle de Brain y la memoria de gestión del Hub.
• Cambiar el fingerprint existente a content hash.
• Convertir warnings semánticos o de frescura en errores.
• Garantizar owner, ACL, xattrs, inode o timestamps del archivo reescrito.
• Publicar el paquete, crear el tag o promover ramas como parte de este issue.

Further Notes

• Release objetivo: Project Brain Lite 0.3.1.
• Baseline: codex/document-memory-hub-boundary en 9ea16cd.
• La implementación debe ser un endurecimiento de contrato, no un rediseño de plataforma.
• fingerprint != content hash.
• doctor OK != context fresh; la frescura debe consultarse en warnings/checks.
• detected command != executed command.
• El repositorio tiene autoridad factual; Brain sólo tiene autoridad de escritura sobre GeneratedProjection.
• Todo lo exterior a los marcadores es RepositoryOwnedContent.
• Memory Hub conserva autoridad sobre owners, fechas, riesgos, milestones y estado de gestión.
• Los repositorios adoptados por 0.3.0 no requieren migración destructiva. init continúa preservando archivos existentes y los cambios de proyección se aplican sólo mediante sync.
• La definición de terminado exige que todas las pruebas existentes y nuevas pasen, doctor permanezca read-only, el worktree quede limpio y no aparezca ninguna dependencia, comando, artefacto canónico o capacidad fuera de scope.