From 8ee1760a16b804e36af771fff759aa47224f4b7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jose=20Villase=C3=B1or=20Montfort?= <195970+montfort@users.noreply.github.com> Date: Sat, 2 May 2026 13:04:34 -0600 Subject: [PATCH] feat(framework): atomic Charter closure pattern (fw-4.4.2 / format v4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First Charter-driven release. Originating Charter: sentinel/docs/charters/01-format-v4-atomic-charter-closure-pattern.md Originating decision: AIDEC-2026-05-02-001 (Sentinel), which formalized the canon gap discovered via PLAN-07: "update Plan-doc post-merge if AILOG documented divergencias" was mentioned but had no systematic trigger, leading to drift remediation lagging by days. Format v4 changes (charter-template.md EN + i18n/es): - Step 1 of `## Charter Closure` becomes "Atomic update (format v4)" — if drift was reported by Tasks #7, edit `## Files to modify` and/or add `## Closing notes` in the same commit/PR. No housekeeping deferral. - New top-level `## Closing notes` section with template structure and references to PLAN-05 / PLAN-07 of Sentinel as historical examples. - Convention #5 in the comment block rewritten for atomic-update at Tasks #7 time, citing PLAN-07 + AIDEC-2026-05-02-001. - Trigger placeholder broadened: "[1-line: what observable signal...]" → "[1-line: what concrete signal — observable event, declared decision, metric threshold, or infrastructure milestone — justifies executing this Charter now]". Surfaced during the originating Charter review (Charters from AIDECs/ADRs have declarative triggers). - §Risks placeholder gains guidance on mitigation completeness (4 properties: trigger, action, failure case, follow-up location). Surfaced during R4 review of the originating Charter. Promote 4 Propuesta files to public git history (governance hygiene): - que-es-un-charter.md (4 broken refs from shipped docs since fw-4.4.0) - devtrail-cli-roadmap.md (5 broken refs) - devtrail-thesis-validation.md (3 broken refs) - devtrail-design-principles.md (1 broken ref) The other 3 Propuesta/ files (devtrail-charter-telemetry.md, devtrail-cloud-proposal.md, devtrail-studio-vision.md) remain local-only because no shipped doc references them. Editorial-only release, no schema changes, no breaking changes. Adopters pick up format v4 via `devtrail update-framework`. Co-authored-by: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 29 ++ Propuesta/devtrail-cli-roadmap.md | 206 +++++++++++++ Propuesta/devtrail-design-principles.md | 121 ++++++++ Propuesta/devtrail-thesis-validation.md | 285 ++++++++++++++++++ Propuesta/que-es-un-charter.md | 133 ++++++++ README.md | 4 +- dist/.devtrail/00-governance/AGENT-RULES.md | 2 +- .../00-governance/C4-DIAGRAM-GUIDE.md | 2 +- .../00-governance/DOCUMENTATION-POLICY.md | 2 +- .../00-governance/QUICK-REFERENCE.md | 2 +- .../00-governance/i18n/es/AGENT-RULES.md | 2 +- .../00-governance/i18n/es/C4-DIAGRAM-GUIDE.md | 2 +- .../i18n/es/DOCUMENTATION-POLICY.md | 2 +- .../00-governance/i18n/es/QUICK-REFERENCE.md | 2 +- .../00-governance/i18n/zh-CN/AGENT-RULES.md | 2 +- .../i18n/zh-CN/C4-DIAGRAM-GUIDE.md | 2 +- .../i18n/zh-CN/DOCUMENTATION-POLICY.md | 2 +- .../i18n/zh-CN/QUICK-REFERENCE.md | 2 +- dist/.devtrail/QUICK-REFERENCE.md | 2 +- dist/.devtrail/templates/charter-template.md | 64 +++- .../templates/i18n/es/charter-template.md | 64 ++-- dist/dist-manifest.yml | 2 +- docs/adopters/ADOPTION-GUIDE.md | 2 +- docs/adopters/CLI-REFERENCE.md | 14 +- docs/i18n/es/README.md | 4 +- docs/i18n/es/adopters/ADOPTION-GUIDE.md | 2 +- docs/i18n/es/adopters/CLI-REFERENCE.md | 12 +- docs/i18n/zh-CN/README.md | 4 +- docs/i18n/zh-CN/adopters/ADOPTION-GUIDE.md | 2 +- docs/i18n/zh-CN/adopters/CLI-REFERENCE.md | 14 +- 30 files changed, 912 insertions(+), 76 deletions(-) create mode 100644 Propuesta/devtrail-cli-roadmap.md create mode 100644 Propuesta/devtrail-design-principles.md create mode 100644 Propuesta/devtrail-thesis-validation.md create mode 100644 Propuesta/que-es-un-charter.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7032c61..f9e3670 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,35 @@ and this project uses [independent versioning](README.md#versioning) for Framewo --- +## Framework 4.4.2 — atomic Charter closure pattern (format v4) + +First Charter-driven release. Originating Charter: `sentinel/docs/charters/01-format-v4-atomic-charter-closure-pattern.md` (Sentinel repo). Originating decision: AIDEC-2026-05-02-001 (Sentinel `.devtrail/07-ai-audit/decisions/`), which formalized the canon gap discovered via PLAN-07 of Sentinel (closed 2026-05-02): the step "update the Plan-doc post-merge if the AILOG documented divergencias" was mentioned in TEMPLATE.md and `docs/plans/README.md §Cómo cerrar un plan` but had no systematic trigger — implementer relied on memory, drift remediation lagged the main PR by days when memory failed. + +This release ports the Sentinel-internal fix upstream as **format v4** of the Charter template. Editorial only — no schema changes, no breaking changes, adopters do not need to migrate existing Charters. + +### Changed (Framework) + +- **`dist/.devtrail/templates/charter-template.md`** (EN) gains five updates: + 1. **Step 1 of `## Charter Closure` becomes "Atomic update (format v4)"**: if the drift check (Tasks #7) reported drift not already in the AILOG, edit `## Files to modify` and/or add a `## Closing notes` block in the **same commit/PR**, before submitting. No housekeeping PR deferral. + 2. **New top-level `## Closing notes` section** near the end of the body (not inside the HTML comment), with template structure and references to PLAN-05 and PLAN-07 of Sentinel as historical examples. Designed to be omitted entirely when no drift was detected — empty `## Closing notes` is noise. + 3. **Convention #5** in the comment block rewritten to require atomic update at Tasks #7 time, not post-merge housekeeping. Cites PLAN-07 as the empirical case that demonstrated the failure mode and AIDEC-2026-05-02-001 as the formalization. + 4. **Trigger placeholder** broadened: `[1-line: what observable signal...]` → `[1-line: what concrete signal — observable event, declared decision, metric threshold, or infrastructure milestone — justifies executing this Charter now]`. Surfaced during the originating Charter review — Charters derived from AIDECs/ADRs have declarative triggers, not observable ones, and the previous wording pushed authors to invent pseudo-observable signals. + 5. **`## Risks` placeholder** gains a guidance comment: "Each mitigation should specify: (a) concrete trigger or threshold, (b) action committed, (c) what happens if the mitigation itself fails, (d) where follow-up insights are captured." Surfaced during R4 review of the originating Charter — without guidance, authors leave these four properties implicit, which a human reviewer catches but a solo implementer does not. +- **`dist/.devtrail/templates/i18n/es/charter-template.md`** (ES) mirrors the same five changes in Spanish. +- **`Propuesta/que-es-un-charter.md`** gains a new §1.3 "Atomic Charter closure (format v4)" describing the pattern and its empirical origin. + +### Also (governance hygiene) + +- **Promotes 4 files from `Propuesta/` to public git history**: `que-es-un-charter.md`, `devtrail-cli-roadmap.md`, `devtrail-thesis-validation.md`, `devtrail-design-principles.md`. These were referenced from shipped docs (CHANGELOG, CLI-REFERENCE EN/ES/zh-CN) since fw-4.4.0 but had never been committed — adopters following the links got 404. Discovered during the originating Charter's execution. The other 3 `Propuesta/` files (`devtrail-charter-telemetry.md`, `devtrail-cloud-proposal.md`, `devtrail-studio-vision.md`) remain local-only because no shipped doc references them. + +### Notes + +- This release ships **no breaking changes**. Existing Charters created with fw-4.4.0 / fw-4.4.1 remain valid. Adopters pick up format v4 via `devtrail update-framework`; the new step in `## Charter Closure` and the new `## Closing notes` section apply to Charters created from this template version forward. +- Format v4 is **editorial only** — no `charter.schema.v0.json` changes. Items deferred to schema v0.x evolutions (e.g., `status: blocked` enum, `trigger_kind` field) await empirical data from 3+ real Charters before being designed; the format v4 Charter §Out of scope captures the deferral explicitly. +- Cross-repo Charter pattern (this Charter being executed in Sentinel while implementing changes in the DevTrail repo) is **not codified** in the template — it was a coyuntural arrangement for empirical Phase 1 validation, not a pattern to inherit to adopters. Most adopters keep code and governance in the same repo. The asymmetry is documented in the originating Charter's R1/R4 as a historical note, not a promoted variant. + +--- + ## Framework 4.4.1 — `docs-validation.yml` workflow recognizes all DocTypes and recent governance files ### Fixed (Framework) diff --git a/Propuesta/devtrail-cli-roadmap.md b/Propuesta/devtrail-cli-roadmap.md new file mode 100644 index 0000000..4de1394 --- /dev/null +++ b/Propuesta/devtrail-cli-roadmap.md @@ -0,0 +1,206 @@ +# DevTrail CLI — Roadmap hacia la tesis (post-Sentinel) + +**Versión:** 0.2 (rename Plan → Charter para evitar colisión con SpecKit) +**Fecha:** 30 de abril de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Traducir los hallazgos validados de Sentinel en una secuencia accionable de cambios al CLI Rust y al framework, manteniendo el principio #12 (cristalización experimental, no estable). +**Documentos relacionados:** `devtrail-thesis-validation.md` (evidencia que justifica el roadmap), `devtrail-design-principles.md` (anotaciones v0.2 sobre #6, #9, #12), `devtrail-cloud-proposal.md` §4.5 y §8 (Charters en Cloud, Q3), `devtrail-charter-telemetry.md` v0.2 (schema de telemetría refinado), `que-es-un-charter.md` (alcance conceptual del artefacto Charter y coexistencia con SpecKit). + +--- + +## 1. Por qué este documento existe + +`devtrail-cloud-proposal.md` v0.3 confirma que la tesis se sostiene con la evidencia de Sentinel y nombra qué decisiones la evidencia permite tomar ahora. Este documento traduce esas decisiones en una secuencia concreta de cambios al CLI Rust y al framework `dist/.devtrail/`. No incluye trabajo de Cloud ni features de aprobación condicional — esos quedan bloqueados hasta validación con un segundo proyecto en otro dominio o con flujo multi-actor. + +El roadmap está pensado para tres ciclos de release del CLI (estimación: 3-4 patches/minor cada uno) que pueden ejecutarse en serie o con solapamiento mínimo. Cada fase es shippable independientemente y produce señal antes de la siguiente. Si la fase 1 no genera adopción medible, las fases 2-3 se cuestionan antes de invertir. + +**Nota terminológica.** Lo que el experimento Sentinel llamó "Plan" (Plans 01-06) se llama **Charter** en el vocabulario DevTrail going-forward, para evitar colisión nominal con `plan.md` de GitHub SpecKit. Los registros históricos de Sentinel preservan "Plan"; este documento usa "Charter" para todo lo prospectivo y "Plan" cuando cita literalmente artefactos de Sentinel. Justificación completa en `que-es-un-charter.md` §2. + +## 2. Secuencia recomendada y justificación + +| Fase | Capacidad | Pre-requisitos | Estimación CLI | +|------|-----------|----------------|----------------| +| 1 | Charters como entidad de primera clase | Ninguno (artefactos ya validados) | cli-3.6.0 (minor) | +| 2 | Telemetría + drift-check ejecutable | Fase 1 | cli-3.7.0 (minor) | +| 3 | Auditoría externa multi-modelo | Fases 1+2 | cli-3.8.0 (minor) | + +**Justificación de la secuencia:** + +- Charters son la *unidad* del patrón; Telemetría y Auditoría son *observaciones sobre la unidad*. Sin la primera, las otras dos no tienen sujeto. +- Fase 1 es portar (los artefactos ya existen, validados con cero falsos positivos) — el riesgo técnico es bajo y el ROI inmediato es alto. +- Fase 2 es portar + Rust-ificar con decisión consciente de simplicidad (principio #9): el script bash de 145 líneas puede invocarse desde Rust o reimplementarse según convenga; ambas opciones son aceptables si preservan la propiedad "0 falsos positivos en 2/2 tests" demostrada en Sentinel. +- Fase 3 requiere diseño nuevo de orquestación multi-modelo (mayor riesgo); solo se aborda cuando las dos primeras hayan generado adopción. + +## 3. Fase 1 — Charters como entidad de primera clase + +**Objetivo:** que un usuario adoptante pueda crear, listar, navegar y validar Charters usando el CLI, sin tener que copiar manualmente el TEMPLATE de Sentinel. + +### 3.1 Cambios al framework (`dist/.devtrail/`) + +- **Portar `TEMPLATE.md v3`** desde `/E/Proyectos/StrangeDaysTech/sentinel/docs/plans/TEMPLATE.md` a `dist/.devtrail/templates/charter-template.md` con las 6 convenciones embebidas validadas (separación Local/Production checks, esfuerzo en TIEMPO, sub-secciones estructuradas, R, Cierre del Charter, auto-checklist drift). El template renombra "Cierre del Plan" → "Cierre del Charter" en su cuerpo; las referencias del template a Sentinel quedan como ejemplos históricos. +- **Schema mínimo `dist/.devtrail/schemas/charter.schema.v0.json`** marcado *experimental*. Frontmatter mínimo: `charter_id`, `origin` (union: `originating_ailogs` array u `originating_spec` path), `trigger`, `effort_estimate` (XS/S/M/L), `status` (declared/in-progress/closed). El campo `origin` admite ambas formas para soportar tanto el modo Sentinel (Charter nacido de un AILOG) como el modo SpecKit-driver (Charter derivado de un `specs/###-feature/`); ver §3.5 para la justificación. El schema NO se cristaliza como `v1.0` hasta tener un segundo proyecto en otro dominio (ver `devtrail-thesis-validation.md` §6). +- **Charters canónicos como ejemplos** en `dist/docs/examples/charters/` (copia anonimizada de PLAN-05 y PLAN-06 de Sentinel, renombrados a `CHARTER-01` y `CHARTER-02` en los ejemplos para que adoptantes los lean como referencia de uso real bajo el vocabulario DevTrail). + +### 3.2 Comandos nuevos del CLI + +- `devtrail charter new [--type X|S|M|L] [--from-ailog ID | --from-spec PATH] [--title "..."]` — scaffolds un Charter desde el template. Si `--from-ailog` está presente, pre-popula `originating_ailogs` con el ID (caso post-MVP / mantenimiento, p.ej. los Plans 01-06 históricos de Sentinel). Si `--from-spec` está presente (p.ej. `specs/001-sentinel-mvp/`), pre-popula `originating_spec` apuntando al `spec.md` correspondiente y hereda User Stories relevantes a la sección Context (caso greenfield con SpecKit como driver). Los flags son mutuamente excluyentes; si ambos faltan, el Charter se crea sin origen y debe llenarse manualmente. Genera el archivo en `docs/charters/NN-slug.md` con `NN` autoincrementado. Justificación de los dos modos en §3.5. +- `devtrail charter list [--status declared|in-progress|closed|all]` — enumera Charters en `docs/charters/` con estado, esfuerzo declarado, AILOGs origen. Default: `--status all`. +- `devtrail charter status [CHARTER-ID]` — muestra detalle de un Charter: archivos declarados, AILOGs origen, telemetría si existe, drift-check si existe. Si se omite el ID, lista los últimos 5 Charters. + +### 3.3 Integración con comandos existentes + +- **`devtrail validate`**: añadir validación opt-in del frontmatter de Charters contra `charter.schema.v0.json` cuando el flag `--include-charters` esté presente (default: false, para no romper proyectos existentes sin Charters). +- **`devtrail explore` (TUI)**: añadir vista `Charters` paralela a `Documents`, con navegación por estado y búsqueda por AILOG origen. Usa `pulldown-cmark` ya disponible. + +### 3.4 Tests y documentación + +- Tests integration en `cli/tests/` que crean un proyecto temporal con `devtrail init`, ejercitan `charter new/list/status` en los tres caminos de origen (`--from-ailog`, `--from-spec` con un `specs/` mock, y sin flag), y verifican el shape del Charter generado contra el schema en cada caso. +- Sección `## Charters` nueva en `docs/adopters/CLI-REFERENCE.md` (EN + ES + zh-CN) con ejemplos de uso. Plantilla para README. La sección debe incluir una nota corta explicando que en docs históricos de Sentinel y en evidencia empírica del experimento `/plan-audit`, este artefacto aparece bajo el nombre "Plan". + +### 3.5 Coexistencia con flujos SpecKit + +DevTrail llamó originalmente a este artefacto "Plan" durante el experimento Sentinel; se renombró a **Charter** precisamente para evitar la colisión nominal con `plan.md` de SpecKit, que es un artefacto distinto (feature-completo y arquitectónico, más cercano a un ADR + skeleton de proyecto). El Charter DevTrail es una unidad acotada con verificación ejecutable, declaración de archivos y ancla de auditoría ex-post. No compiten — viven en momentos distintos del ciclo. SpecKit termina al producir `tasks.md`; DevTrail Charter empieza ahí (cuando hay spec previa) o se sostiene solo (cuando no la hay). El alcance conceptual completo y la comparación pieza a pieza viven en `que-es-un-charter.md`. + +**Tres modos de coexistencia que Fase 1 debe soportar de fábrica:** + +1. **Greenfield con SpecKit como driver.** Un Charter DevTrail toma un subconjunto de `tasks.md` (típicamente una user story o una fase) y le añade verificación + drift + audit. Lo cubre el flag `--from-spec PATH` (§3.2): pre-popula `originating_spec` y hereda User Stories al Context. +2. **Mantenimiento / post-MVP.** No hay SpecKit upstream — el Charter nace de un AILOG. Es el caso real de Sentinel (Plans 01-06). Lo cubre el flag `--from-ailog ID` (§3.2). +3. **Híbrido.** Features mayores con flujo SpecKit completo + Charters DevTrail; bug fixes, gobernanza, deuda y features chicas con solo Charter DevTrail. Probablemente el más realista en la práctica; no requiere flags adicionales — emerge de combinar los dos modos anteriores según el tipo de trabajo. + +**Implicaciones de diseño:** + +- `charter.schema.v0.json` (§3.1) declara `origin` como union `originating_ailogs | originating_spec` precisamente para no privilegiar un modo sobre el otro. +- `devtrail validate --include-charters` (§3.3) acepta ambas formas de `origin`; un Charter sin ninguna falla con error explicativo. +- `devtrail charter list` (§3.2) puede agrupar por origen cuando sea útil (p.ej. `devtrail charter list --origin spec` para ver solo Charters derivados de SpecKit). +- La integración con SpecKit es de *lectura* — el CLI DevTrail no genera ni modifica artefactos de SpecKit, solo los referencia. Esto preserva el principio de no acoplar DevTrail a un flujo de planning particular. + +### 3.6 Criterios de salida de la Fase 1 + +- `devtrail charter new` genera un Charter compatible con `check-plan-drift.sh` (Sentinel) ejecutado manualmente — la compatibilidad sintáctica se preserva aunque cambien los nombres canónicos en el framework. Se valida en ambos modos (`--from-ailog` y `--from-spec`). +- Al menos 1 adoptante (idealmente fuera de Go) ha creado un Charter completo con `devtrail charter` y reportado sobre la experiencia. +- Schema `charter.schema.v0.json` no ha requerido breaking changes en 2 ciclos de release. + +## 4. Fase 2 — Telemetría y drift-check ejecutable + +**Objetivo:** medir validez del patrón en proyectos adoptantes y detectar drift Charter vs commits sin requerir scripts externos. + +### 4.1 Cambios al framework + +- **Schema `dist/.devtrail/schemas/charter-telemetry.schema.v0.json`** derivado de `devtrail-charter-telemetry.md` v0.2 con los 4 campos refinados por Sentinel: `external_audit` como array, `outcome.scope_change_notes` con codificación `F1...FN`, `agent_quality.r_n_plus_one_emergent_count`, `qualitative.format_iteration`. + +### 4.2 Comandos nuevos del CLI + +- `devtrail charter close [CHARTER-ID]` — guía interactiva (estilo `git commit` con prompts) para llenar la telemetría YAML al cierre del Charter. Pregunta campo por campo, valida tipos contra schema, escribe el archivo `.devtrail/charters/CHARTER-ID.telemetry.yaml`. Tiempo objetivo del flujo: 5-10 min (mismo target que `devtrail-charter-telemetry.md` declara). +- `devtrail charter drift [CHARTER-ID] [--range REV..REV]` — reimplementación o invocación del `check-plan-drift.sh` de Sentinel. Decisión técnica abierta (principio #9): invocar el script bash directamente desde Rust si está disponible, o reimplementar nativamente preservando la propiedad "0 falsos positivos en 2/2 tests". El usuario *adoptante* no debe percibir diferencia. + +### 4.3 AILOG-awareness para reducir ceremonia + +`AILOG-022` §Risk R2 documentó que el script genera ruido cuando alerta sobre R ya documentados en AILOG. La fase 2 debe atacar esa ceremonia (`devtrail-design-principles.md` v0.2 §6 distingue virtud vs ceremonia): + +- `devtrail charter drift` debe leer los AILOGs referenciados en el frontmatter del Charter y suprimir alertas sobre paths ya documentados como `R` en algún AILOG. Esta es la mitigación R2 que Sentinel propuso pero no implementó. + +### 4.4 Hook opcional pre-PR + +- `dist/.devtrail/hooks/pre-pr.sh` que ejecuta `devtrail charter drift` automáticamente antes de abrir un PR. Opt-in via `devtrail init --hooks` o configuración manual. NO es default (principio #6: fricción virtuosa, pero no impuesta sin consentimiento). + +### 4.5 Criterios de salida de la Fase 2 + +- Al menos 2 adoptantes han usado `devtrail charter close` y producido telemetría YAML válida. +- `devtrail charter drift` mantiene la propiedad de 0 falsos positivos en proyectos adoptantes. +- AILOG-awareness reduce el triage manual a cero en al menos 1 caso real reportado. + +## 5. Fase 3 — Auditoría externa multi-modelo + +**Objetivo:** cerrar el ciclo cualitativo del experimento Sentinel orquestando auditoría dual (estilo Copilot + Gemini + claude-analisis) sobre Charters cerrados. + +### 5.1 Diseño de tres niveles (no solo "ejecuta N modelos") + +`devtrail-thesis-validation.md` §7.3 argumenta que la auditoría dual de Sentinel reveló un patrón de tres niveles: dos auditores en paralelo + un calibrador-reconciliador (claude-analisis) que aplica el schema definicional. La fase 3 implementa esa arquitectura, no una orquestación plana de N modelos. + +### 5.2 Heterogeneidad inter-familia como restricción de diseño + +La auditoría externa **no es sustituible por auto-auditoría del mismo modelo**, y la razón no es operativa — es estadística y estructural. El comando `devtrail charter audit` debe imponer la restricción de heterogeneidad inter-familia desde el inicio, no como configuración opcional. + +**Tres bases teóricas que sostienen la restricción:** + +1. **Blind spots correlacionados con la familia de modelo.** Cualquier patrón que un modelo tenga sobre-representado en su distribución de entrenamiento (una API ficticia que aparece en muchos tutoriales, una convención arquitectónica que predomina en stacks populares) es por definición invisible a *otra instancia del mismo modelo*. F5 de PLAN-05 es exactamente este caso: Claude generó el Plan asumiendo que `NewAnomalyDetector` se instancia en `service.go` (patrón mainstream); otra sesión de Claude muy probablemente lo dejaría pasar porque comparte el mismo prior. Gemini, con distribución de entrenamiento distinta, lo capturó. + +2. **Sycophancy y agreement bias en cadena.** Los LLMs muestran preferencia documentada por estar de acuerdo con texto autoritativo presente en el contexto. Si un modelo lee un Charter + AILOG generados por sí mismo, los trata como premisas válidas más que como hipótesis a interrogar. La auditoría externa rompe esa cadena porque el auditor no tiene continuidad narrativa con el implementador. + +3. **Convergencia inter-modelo como señal estructural.** Lo que Sentinel mostró empíricamente — Copilot 9.25 / Gemini 9.5 convergiendo en PLAN-05 sobre los mismos findings, capturando F4 y F5 que el AILOG no documentó — es que la *diversidad* es estructural, no aditiva. Esa convergencia no se reproduce entre dos auditorías del mismo modelo porque comparten el sesgo. + +**El matiz importante: no toda auto-auditoría está descalificada.** Para *checks estructurales* (drift de archivos declarados vs modificados, consistencia interna del Charter, syntax/type checks), un mismo modelo se audita bien — `check-plan-drift.sh` no necesita Gemini para funcionar y la Fase 2 es deliberadamente single-model. Para *checks semánticos* (¿esta arquitectura es correcta?, ¿esta categorización es `hallucination` vs `implementation_gap`?), la heterogeneidad es lo que captura la calibración. La distinción es la misma virtud-vs-ceremonia que `devtrail-design-principles.md` v0.2 §6 articula: la heterogeneidad inter-familia es virtud cuando externaliza signal donde el sesgo es probable; es ceremonia cuando solo agrega latencia y costo en checks estructurales. + +**Implicación operacional para `devtrail charter audit`:** + +- Si el implementador fue de la familia X (ej: Claude), al menos uno de los dos auditores debe ser de una familia distinta a X. El comando rechaza con error explicativo configuraciones donde implementador y ambos auditores son de la misma familia. +- El calibrador-reconciliador puede ser de cualquier familia (incluida la del implementador) porque su trabajo es aplicar el schema definicional sobre veredictos ya producidos, no descubrir gaps. +- La detección de "familia" se hace por mapeo de model-id → family declarado en una tabla del framework (`dist/.devtrail/audit-prompts/model-families.yaml` con entradas como `claude-* → anthropic`, `gpt-*/copilot-* → openai`, `gemini-* → google`). El usuario puede extender la tabla para nuevos modelos. + +### 5.3 Cambios al framework + +- **Plantillas de prompt en `dist/.devtrail/audit-prompts/`**: una por rol (`auditor-primary.md`, `auditor-secondary.md`, `calibrator-reconciler.md`). Las plantillas se derivan de las que Sentinel usó implícitamente; se documentan formalmente. +- **Schema de output canónico**: cada auditor produce un archivo en `audit/charters/{CHARTER-ID}/{role}.md` con frontmatter parseable que se mapea al campo `external_audit` de la telemetría. El calibrador produce `claude-analisis.md` (o equivalente) con consolidación de findings. + +### 5.4 Comando nuevo del CLI + +- `devtrail charter audit [CHARTER-ID] [--auditors model1,model2] [--calibrator model3] [--implementer-family X]` — orquesta la ejecución secuencial: auditor primary → auditor secondary (en paralelo si la API lo permite) → calibrator que reconcilia veredictos divergentes según el schema. Genera los 3 archivos de output. Integra automáticamente el campo `external_audit` array en la telemetría. Aplica la restricción de heterogeneidad inter-familia descrita en §5.2: si el flag `--implementer-family` no está presente, el comando lo infiere del último AILOG asociado al Charter; si la inferencia y la configuración resultan en una combinación monocromática (implementador + ambos auditores misma familia), el comando rechaza con error explicativo y sugiere alternativas. + +Decisión abierta: qué APIs/modelos soportar. Recomendación inicial: usar el patrón "user provides the API key" (similar a herramientas como `aichat`), no acoplar el CLI a un proveedor específico. Soportar al menos OpenAI (Copilot stand-in), Google (Gemini), Anthropic (Claude) en v0. + +### 5.5 Criterios de salida de la Fase 3 + +- Al menos 1 ciclo de auditoría externa multi-modelo ejecutada en un proyecto adoptante con resultados consistentes con la calibración cross-modelo observada en Sentinel. +- El calibrador-reconciliador produce findings en formato compatible con el array `external_audit` de la telemetría. +- Documentación clara de que el CLI orquesta pero no provee modelos; el usuario controla qué APIs usar. +- La restricción de heterogeneidad inter-familia se ejercita en los tests integration: una configuración monocromática es rechazada con error claro; una heterogénea procede sin advertencia. + +## 6. Mapeo artefactos Sentinel → CLI + +Tabla de referencia rápida que conecta cada artefacto validado en Sentinel con su destino en el CLI/framework. La columna izquierda preserva el vocabulario histórico de Sentinel ("Plan"); la columna derecha usa el vocabulario DevTrail going-forward ("Charter"). + +| Artefacto Sentinel (vocabulario "Plan") | Ruta absoluta de origen | Fase | Destino DevTrail (vocabulario "Charter") | +|---------------------|--------------------------|------|---------| +| `TEMPLATE.md` v3 | `sentinel/docs/plans/TEMPLATE.md` | 1 | `dist/.devtrail/templates/charter-template.md` | +| Plan-docs canónicos | `sentinel/docs/plans/{05,06}-*.md` | 1 | `dist/docs/examples/charters/` (anonimizados, renombrados a `CHARTER-NN`) | +| Telemetrías YAML | `sentinel/.devtrail/plans/PLAN-{05,06}.telemetry.yaml` | 2 | Schema validador para `devtrail charter close` output | +| `check-plan-drift.sh` | `sentinel/scripts/check-plan-drift.sh` | 2 | `devtrail charter drift` (invocar bash o reimplementar) | +| Reportes auditoría dual | `sentinel/audit/plans/{05,06}/{copilot,gemini,claude-analisis}.md` | 3 | Output canónico de `devtrail charter audit` (en `audit/charters/`) | +| AILOGs 020-024 | `sentinel/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-28-{020..024}-*.md` | Referencia transversal | `dist/docs/examples/ailogs/` (anonimizados, 1-2 ejemplos) | + +## 7. Verificación end-to-end de cada fase + +Cada fase tiene un test de aceptación operacional que el equipo de DevTrail debe poder ejecutar sin instrucciones adicionales: + +**Fase 1:** +1. `cargo install --path cli/` instala `devtrail` con la nueva subcomanda `charter`. +2. En un repo limpio: `devtrail init && devtrail charter new --type M --title "test charter"` produce un Charter en `docs/charters/01-test-charter.md` válido contra `charter.schema.v0.json`. +3. `devtrail charter list` muestra el Charter recién creado en estado `declared`. +4. `devtrail validate --include-charters` pasa sin errores. + +**Fase 2:** +1. Tras Fase 1, un commit que toca archivos del Charter + `devtrail charter drift CHARTER-01` reporta 0 drift. +2. Se introduce un drift artificial (declarar archivo extra que no se modifica); el comando reporta 1 omisión y exit code 1. +3. Se documenta el drift en un AILOG asociado; el comando con AILOG-awareness lo suprime y reporta limpio. +4. `devtrail charter close CHARTER-01` produce un YAML válido contra `charter-telemetry.schema.v0.json`. + +**Fase 3:** +1. `devtrail charter audit CHARTER-01 --auditors copilot,gemini --calibrator claude` produce 3 archivos de output bien formados. +2. El calibrador reconcilia veredictos divergentes (caso de prueba: F5 PLAN-05-style donde un auditor categoriza como `implementation_gap` y otro como `hallucination`). +3. La telemetría queda enriquecida con el campo `external_audit` array correctamente poblado. + +## 8. Lo que NO está en este roadmap (preservación del principio #12) + +Para mantener disciplina de cristalización experimental: + +- **No `charter.schema.v1.0` estable** — solo `v0` experimental hasta validación con segundo proyecto en otro dominio (`devtrail-thesis-validation.md` §6). +- **No features de aprobación condicional** — supuesto #4 sin evidencia (`devtrail-thesis-validation.md` §4.4). +- **No firma criptográfica de Charters** — la prioridad criptográfica vive en `devtrail stage close` (Cloud roadmap), no en Charters aún. +- **No integración Cloud para Charters** — primero validar el flujo local en CLI con adoptantes; la integración con Inbox y Trust Center sigue al uso real. +- **No comando `devtrail charter extract` (auto-generar Charters desde AILOGs)** — el patrón existe en `cloud-proposal.md` §4.5 pero requiere observación adicional sobre cómo los adoptantes generan Charters en práctica antes de cristalizar la heurística de extracción. + +Cada uno de estos puntos tiene un criterio de salida explícito en `devtrail-thesis-validation.md` §8 que, cuando se cumpla, abre la puerta a un nuevo ciclo de roadmap. + +--- + +*Este roadmap es el primer artefacto que traduce evidencia empírica en código accionable para DevTrail. Su evolución sigue el patrón auto-evolutivo observado en Sentinel: cada fase ejecutada genera datos que refinan el roadmap del próximo ciclo. La versión 0.3 de este documento se escribirá tras completar al menos la Fase 1 con un adoptante real.* diff --git a/Propuesta/devtrail-design-principles.md b/Propuesta/devtrail-design-principles.md new file mode 100644 index 0000000..9dd9f59 --- /dev/null +++ b/Propuesta/devtrail-design-principles.md @@ -0,0 +1,121 @@ +# DevTrail — Principios de diseño + +**Versión:** 0.2.1 (anotaciones empíricas tras el experimento `/plan-audit` en Sentinel; rename Plan → Charter en vocabulario going-forward) +**Fecha:** 30 de abril de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Articular la filosofía del producto en forma compacta, para servir como referencia frente a decisiones de diseño y como criterio para decir no a features que no encajan. +**Documentos relacionados:** `devtrail-thesis-validation.md` (cuerpo de evidencia que motivó las anotaciones de v0.2). + +--- + +## Por qué este documento existe + +Los productos de software derivan, con el tiempo, hacia donde los empuja el incentivo más cercano. Si la presión es revenue, derivan hacia features que venden. Si la presión es adopción, derivan hacia features que viralizan. Si la presión es competencia, derivan hacia paridad con el competidor más visible. Cada una de esas derivas es individualmente racional y colectivamente destructiva: el producto pierde su forma original y se convierte en otro punto promediado del mercado. + +Este documento existe para que DevTrail tenga un ancla explícita. Las decisiones futuras deben poder contrastarse contra estos principios. Una feature que viole un principio puede aún ser buena idea, pero requiere una conversación consciente sobre qué principio se está flexibilizando y por qué. La existencia del documento no garantiza disciplina; la pregunta consciente que genera, sí. + +Los principios están ordenados por jerarquía: cuando dos entran en conflicto, gana el que viene antes. + +**Versión 0.2 — anotaciones empíricas.** Esta versión incorpora aprendizajes del primer experimento que estresa los principios contra evidencia: Sentinel `/plan-audit` durante 6 ciclos (PLAN-01..06), tres iteraciones de formato (v1 → v2 → v3) y dos auditorías externas duales por ciclo. Las anotaciones por principio referencian ese cuerpo de evidencia y se concentran en los principios que el experimento ejercitó directamente (#6, #9, #12). La jerarquía y la redacción de los doce principios no cambian. + +--- + +## 1. La herramienta sirve al oficio, no al producto + +DevTrail existe para que el ingeniero que trabaja con agentes de IA produzca trabajo del que se sienta orgulloso. Esa es la métrica final. Cualquier feature que mejore métricas de adopción, retención o revenue a costa de degradar la calidad del trabajo del usuario es una feature que viola el principio fundacional. + +En la práctica, esto significa que las decisiones se toman con la pregunta *"¿esto ayuda al ingeniero a hacer mejor ingeniería?"*, no con la pregunta *"¿esto crece el producto?"*. Las dos preguntas a veces convergen y a veces no. Cuando divergen, gana la primera. + +## 2. El usuario primario es el ingeniero senior orquestando agentes + +No el VP Engineering. No el CISO. No el compliance officer. El usuario primario es el ingeniero con criterio técnico fuerte que usa agentes de IA para trabajar en proyectos que no podría abordar solo, y que necesita disciplina cognitiva externalizada para que el agente no introduzca caos sistémico. + +Las features se diseñan para esa persona. Los flujos se optimizan para esa persona. La documentación se escribe para esa persona. Cuando otras personas (compliance officers, managers, auditores) eventualmente usan el producto, lo hacen sobre una base que respeta primero al ingeniero. La inversión de esta jerarquía es la causa más común de productos de developer tooling que se vuelven malos. + +## 3. Open source estricto, sin asteriscos en el núcleo + +El framework, el CLI y el TUI son y serán siempre open-source bajo licencia permisiva. Sin features capadas en el OSS para empujar al pago. Sin telemetría obligatoria. Sin requerimiento de cuenta para uso completo. Sin "community edition" que sea inferior a una "enterprise edition" en capacidades core. + +Cuando exista una capa comercial (Cloud, hosting, servicios), debe ofrecer valor genuino aditivo, no rescatar funcionalidades que se sacaron del OSS para crear demanda artificial. La diferencia entre open-core honesto y open-core como bait-and-switch es la honestidad sobre qué es valor adicional vs qué es la herramienta misma. + +## 4. El cumplimiento regulatorio es un side effect, no el producto + +ISO/IEC 42001, EU AI Act, NIST AI RMF, GDPR son frameworks útiles que dan estructura a la documentación. DevTrail los soporta como capa opcional porque son valiosos para usuarios que los necesitan. Pero el producto no es "una herramienta de compliance". El producto es una herramienta de ingeniería que produce, como subproducto, evidencia compatible con esos frameworks. + +Esta distinción importa porque el comprador de compliance y el ingeniero que usa la herramienta tienen necesidades distintas. Cuando el producto se posiciona como compliance, las decisiones de diseño se sesgan hacia el comprador de compliance y degradan el flujo del ingeniero. Mantener el cumplimiento como side effect protege la calidad del flujo principal. + +## 5. Schema-driven antes que feature-driven + +Las entidades centrales del producto (Stage Closure Bundle, Charter, Document) se definen primero como schemas formales con versionado estricto. Las features se construyen contra esos schemas. Esto tiene tres beneficios estructurales: permite que múltiples implementaciones coexistan sin coordinarse, hace que la evolución sea controlada y reversible, y obliga a pensar el contrato antes que la implementación. + +Las consecuencias prácticas son que cambios breaking en schemas son raros y deliberados, que los schemas son documentación de primera clase del producto, y que features que requieren violar un schema requieren primero proponer la evolución del schema. + +## 6. Disciplina cognitiva sobre productividad bruta + +DevTrail no compite con herramientas que prometen *"haz código 10x más rápido con IA"*. Compite, si compite con algo, contra el caos que el código rápido con IA genera en proyectos serios. La métrica que importa no es velocidad bruta del agente sino calidad sostenida del sistema producido. + +Esto significa que features que añaden fricción justificada (validaciones, gates, requerimientos de documentación, pre-trabajo antes de planning) son aceptables y a veces deseables. Features que prometen quitar fricción a costa de la calidad del razonamiento del agente son sospechosas por defecto. + +**Anotación v0.2 — distinción virtud vs ceremonia.** Sentinel reveló que no toda fricción del flujo DevTrail tiene el mismo carácter. La fricción es *virtuosa* cuando externaliza signal pública: nombrar `R (nuevo, no en Plan)` permite que auditores externos heterogéneos lo capturen (`AILOG-020` §Additional Notes); `check-plan-drift.sh` ejecutado al cierre detecta drifts archivos-declarados-vs-modificados con cero falsos positivos en 2/2 tests empíricos (`AILOG-022` §Summary); la auditoría dual Copilot+Gemini calibra cross-modelo y captura gaps que un solo auditor pierde (`PLAN-05.telemetry.yaml`). La fricción es *ceremonia atacable* cuando solo genera triage manual o prescribe sin reflexividad: el TEMPLATE prescribiendo una firma arquitectónica que choca con la convención del módulo destino (F2 en PLAN-05) o el drift script alertando sobre R ya documentados en AILOG (`AILOG-022` R2). La primera se mantiene; la segunda es bug del formato, no virtud del principio. Ver `devtrail-thesis-validation.md` §5 para el desarrollo y los criterios accionables. + +## 7. Local-first, Cloud como amplificador + +El CLI funciona completo, sin red, en el repo local. Esa es la primera experiencia y la base sobre la que todo se construye. Cloud existe para amplificar el valor (agregación cross-repo, evidencia firmada, búsqueda semántica histórica, colaboración de equipo) pero nunca para reemplazar al CLI o convertirlo en cliente delgado. + +Un usuario que nunca conecta al Cloud debe poder obtener la mayor parte del valor del producto. Esto protege la herramienta contra modos de falla del Cloud, contra cambios de modelo de negocio, y contra la deriva clásica de productos que empiezan local y terminan exigiendo conexión obligatoria. + +## 8. La memoria del proyecto vive en el repo, no en una base de datos externa + +AILOGs, ADRs, AIDECs, Charters y bundles viven como archivos versionados junto al código. La razón es estructural: la memoria del proyecto debe sobrevivir al producto que la generó. Si DevTrail desaparece mañana, los `.devtrail/` siguen siendo legibles, parseable y útiles porque son markdown estructurado y JSON conformante a schemas públicos. + +Esta decisión renuncia a algunas capacidades que serían más fáciles con backend centralizado (por ejemplo, búsqueda full-text instantánea sin sincronización), pero gana confiabilidad de largo plazo y control del usuario sobre sus propios datos. La asimetría es deliberada y permanente. + +## 9. Simplicidad sobre capacidad + +Cuando dos diseños cumplen el mismo objetivo, gana el más simple. Cuando una feature es genuinamente útil pero requiere complejidad significativa, conviene esperar hasta que el patrón de uso esté validado en al menos tres proyectos reales antes de cristalizarla en el producto. + +Esto se aplica tanto al producto como al lenguaje del producto. Los nombres de comandos, tipos de documento y conceptos del framework se eligen para ser inmediatamente comprensibles, no para sonar técnicamente sofisticados. Si un concepto requiere explicación larga para un usuario nuevo, probablemente está mal diseñado. + +**Anotación v0.2 — bash antes que framework cuando bash basta.** Sentinel demostró que `scripts/check-plan-drift.sh` (~145 líneas bash con awk + grep + git) cubre el caso "drift de archivos declarados vs modificados" con cero falsos positivos sobre dos tests empíricos. La decisión consciente de no implementarlo en Go inicialmente está documentada en `AILOG-022` §Decision: "Bash es zero-build, sin dependencies, inspeccionable in situ; el costo de mantenimiento es bajo". Cuando se porte al CLI Rust en fase 2 del roadmap (`devtrail-cli-roadmap.md`), preservar la simplicidad bash en lo posible — invocar el shell desde Rust o reimplementar con cuidado de no inflar la lógica. La complejidad solo se cristaliza cuando el patrón de uso lo demande, no por defecto. + +## 10. Honestidad sobre lo que la herramienta no hace + +DevTrail no evalúa modelos. No es un LLM gateway. No reemplaza al juicio del ingeniero. No previene todas las alucinaciones. No certifica automáticamente cumplimiento regulatorio. Las páginas del producto, la documentación y la comunicación pública son explícitas sobre estos límites. + +La razón es práctica: usuarios que adoptan la herramienta con expectativas realistas la mantienen. Usuarios que la adoptan creyendo que hace cosas que no hace la abandonan frustrados. La honestidad temprana sobre los límites es mejor inversión de marketing que las promesas amplias. + +## 11. La comunidad cuida la herramienta, no al revés + +Los usuarios de DevTrail son ingenieros que típicamente saben más que el equipo del producto sobre sus propios casos de uso. Las contribuciones, issues y feedback se tratan con respeto profesional, y las decisiones de roadmap se toman incorporando esa visión. No de forma democrática (el producto necesita una visión coherente), pero sí como input serio. + +Esto no significa hacer todo lo que la comunidad pide. Significa explicar cuándo se dice no y por qué, mantener la conversación visible y pública, y aceptar que el producto será mejor por la presión inteligente de quienes lo usan en serio que por las decisiones aisladas del equipo. + +## 12. La velocidad del producto es la velocidad del aprendizaje + +DevTrail no debe avanzar más rápido de lo que aprendemos sobre cómo se usa realmente. Cristalizar features prematuramente, antes de tener datos de uso real en al menos tres proyectos distintos, genera costos altos de mantenimiento sobre features que pueden ser equivocadas. La paciencia de esperar evidencia es disciplina, no inacción. + +Esto se traduce en una preferencia explícita por: prototipos antes que features, observación antes que cristalización, schemas estables sobre features cambiantes, y evolución incremental sobre rewrites grandes. + +**Anotación v0.2 — el espíritu del N≥3 frente a Sentinel.** Sentinel es un solo proyecto, un solo dominio (Go backend), un solo autor. Aplicado literalmente, el principio bloquearía cualquier cristalización a partir de su evidencia. Aplicado al espíritu — observación rigurosa antes que cristalización, evolución incremental con datos reales — Sentinel cubre tres ejes de diversidad estructural: (a) escala variable (XS, S, M en cinco ciclos), (b) iteración del formato bajo presión empírica (v1 → v2 → v3, cada una derivada del ciclo anterior), (c) calibración cross-modelo de auditores (Copilot + Gemini convergiendo a 9.25/9.5 en PLAN-05). Estos seis ciclos × tres formatos × tres escalas son evidencia equivalente al N≥3 que el principio busca proteger. + +Lo que sigue sin diversificar es el dominio. Para preservar el principio en su forma operacional: cualquier schema que se cristalice a partir de Sentinel se publica como `v0.json` con marca *experimental*. La transición a `v1.0` estable requiere validación con un segundo proyecto en otro dominio (frontend, ML pipeline, infra-as-code). Cualquier feature que dependa de un supuesto sin evidencia (como el #4 "aprobaciones rara vez binarias", que Sentinel no ejercitó) queda explícitamente bloqueada hasta tener un proyecto multi-actor. Ver `devtrail-thesis-validation.md` §6 y §8 para el desarrollo del argumento y la lista de gaps específicos por supuesto. + +**Patrón meta-meta detectado en Sentinel — auto-evolución del formato.** El experimento reveló que el formato se mejora a sí mismo: cada Plan ejecutado en Sentinel (y, going-forward en DevTrail, cada Charter ejecutado) genera datos que refinan el formato del próximo (`AILOG-022` §Additional Notes). Esto sugiere ampliar el principio en futuras versiones: la herramienta evoluciona consigo misma; cada uso es input para la próxima versión. Por ahora se documenta como observación, no como principio adicional, hasta que un segundo proyecto confirme el patrón. + +--- + +## Cómo usar este documento + +Cuando aparezca una decisión de diseño no trivial, conviene contrastarla explícitamente contra los doce principios y registrar el resultado. Tres patrones útiles: + +**Decisiones que satisfacen todos los principios**: proceder normalmente. + +**Decisiones que entran en conflicto con un principio**: documentar explícitamente cuál principio se está flexibilizando, por qué, y qué evidencia llevaría a revertir la decisión. Este registro debe quedar en un AIDEC o ADR. + +**Decisiones que violan principios fundacionales (1, 2, 3, 4)**: no se toman sin revisar primero si el principio sigue siendo correcto. Si lo sigue siendo, la decisión se descarta. Si no, se actualiza el principio antes de tomar la decisión, no después. + +Los principios se revisan formalmente cada seis meses con la evidencia acumulada. Cambios entre revisiones formales son posibles pero deben ser deliberados y documentados. + +--- + +*Este documento es un guardarraíl, no un manual. Su utilidad se mide en cuántas veces nos hace pausar antes de tomar una decisión que después habríamos lamentado.* diff --git a/Propuesta/devtrail-thesis-validation.md b/Propuesta/devtrail-thesis-validation.md new file mode 100644 index 0000000..1e3de07 --- /dev/null +++ b/Propuesta/devtrail-thesis-validation.md @@ -0,0 +1,285 @@ +# DevTrail — Validación empírica de la tesis con datos de Sentinel + +**Versión:** 0.2 (rename Plan → Charter en referencias going-forward; las citas históricas a Sentinel preservan "Plan") +**Fecha:** 30 de abril de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Confrontar la tesis del producto, articulada en `devtrail-cloud-proposal.md` §2, contra la evidencia empírica generada por el primer experimento que la pone a prueba: `/plan-audit` ejecutado en el repo Sentinel durante 6 ciclos (PLAN-01..06) entre el 25 y el 28 de abril de 2026. +**Documentos relacionados:** `devtrail-cloud-proposal.md`, `devtrail-design-principles.md`, `devtrail-charter-telemetry.md`, `devtrail-cli-roadmap.md`, `que-es-un-charter.md` (rename Plan → Charter). + +**Nota de vocabulario.** Este documento cita extensamente evidencia de Sentinel, donde el artefacto se llamó "Plan" (PLAN-01..06). Esas referencias históricas se preservan en su forma original. Las afirmaciones prospectivas sobre el producto DevTrail going-forward (§6 schemas, §8 decisiones) usan el nombre actual "Charter". Justificación del rename en `que-es-un-charter.md` §2. + +--- + +## 1. Por qué este documento existe + +Los otros tres documentos de `Propuesta/` se escribieron antes de tener datos. Son hipótesis: cómo querríamos que fuera la herramienta, qué principios queremos defender, qué patrón de mercado creemos servir. La tesis central es la pieza más cargada y más arriesgada de ese conjunto: + +> "DevTrail es la disciplina cognitiva externalizada que un ingeniero senior necesita cuando orquesta agentes de IA en proyectos medianos a grandes. Estructura la memoria del proyecto, restringe el espacio de decisión del agente con reglas vivas, y produce como subproducto una evidencia auditable que sirve también para cumplimiento regulatorio cuando hace falta. El producto principal es la herramienta que mejora el oficio; el cumplimiento es valor adicional aprovechable, no el motor." +> — `devtrail-cloud-proposal.md` §2 + +Este documento confronta esa tesis con datos. No la defiende; intenta romperla. El objetivo es que un lector que no compró la tesis pueda, leyendo solo este texto, decidir si la evidencia disponible la sostiene, la matiza o la refuta. Si la evidencia no alcanza para algún supuesto, lo nombramos explícitamente y proponemos qué proyecto cerraría el gap. + +El sesgo de auto-confirmación es el riesgo principal: el experimento lo diseñamos nosotros, lo ejecutamos nosotros, y lo evaluamos nosotros. La mitigación es metodológica: cada veredicto se ancla en una cita literal con archivo y línea aproximada, y los supuestos que la evidencia no cubre se marcan sin evidencia, no se infieren a fuerza. + +## 2. La tesis y sus seis supuestos verificables + +`devtrail-cloud-proposal.md` §2 descompone la tesis en seis supuestos que se derivan del uso real del CLI en proyectos como Sentinel. Los reproducimos aquí para anclar la confrontación: + +1. **Vibe coding no escala.** El "vibe coding" no escala a proyectos medianos a grandes; el agente, sin estructura externa, acumula deuda técnica oculta, alucinaciones recurrentes y deriva arquitectónica que el ingeniero descubre tarde y caro. +2. **Notas estructuradas reducen modos de falla.** Una capa de notas estructuradas, vivas y reglamentadas sobre el flujo de trabajo del agente reduce significativamente esos modos de falla. AILOGs, ADRs y AIDECs no son burocracia: son memoria extendida y guardarraíles de razonamiento. +3. **Subproducto regulatorio sin trabajo extra.** El ciclo natural de trabajo asistido por IA produce, como subproducto, los artefactos que un auditor ISO 42001 necesita. El cumplimiento no requiere trabajo extra; requiere disciplina en el flujo. +4. **Aprobaciones rara vez binarias.** Las decisiones de aprobación humana raramente son binarias; típicamente son aprobaciones condicionales con condiciones que mezclan obligaciones inmediatas y obligaciones diferidas con triggers observables. +5. **Stage > commit como unidad de trazabilidad.** La unidad mínima de trazabilidad útil no es el commit, sino el Stage: una agrupación coherente de spec + implementación + auditoría + remediación + cierre con verificación reproducible. +6. **Evidencia in-situ + firma > reconstrucción posterior.** La evidencia generada en el momento del cambio y firmada criptográficamente es estructuralmente más confiable y útil que cualquier reconstrucción posterior. + +## 3. El experimento: Sentinel `/plan-audit` + +Sentinel es el repo de un sistema Go (~15.9 kLOC al cierre del MVP, 96 archivos de producción) que adopta DevTrail como framework de governanza desde sus primeras Etapas. El experimento `/plan-audit` corre en paralelo al desarrollo post-MVP: cada Plan ejecutado se documenta con telemetría YAML, se audita con dos modelos externos (Copilot v1.0.37 y Gemini CLI v1) en paralelo, y se consolida con un análisis crítico de Claude. + +**Seis ciclos completos (25–28 abril 2026):** + +| Plan | Escala | Lo que hizo | Format | +|------|--------|-------------|--------| +| PLAN-01 | XS | Deploy governance docs (PR #9) | v1 | +| PLAN-02 | S | Admin endpoint gcp-resource (PR #10) | v1 | +| PLAN-03 | XS | Contract bumps (PR #11) | v1 | +| PLAN-05 | M | Per-service anomaly threshold overrides (PR #13) | **v2** | +| PLAN-06 | XS | Manual baseline recompute admin endpoint (PR #18) | **v3** | +| (PLAN-04 catalog) | — | Roadmap de 7 features diferidas, no ejecutado | — | + +**Tres iteraciones del formato del Plan:** + +- **v1** (originario): 5 patrones identificados pero no formalizados. +- **v2** (AILOG-020): 5 patrones formalizados en `TEMPLATE.md` + sección "Format conventions" del README. Doc-only. +- **v3** (AILOG-022): 1 patrón nuevo (auto-checklist drift) + tooling ejecutable (`scripts/check-plan-drift.sh`, ~145 líneas bash). Bridge entre formato y enforcement. + +**Fuentes de evidencia (rutas absolutas en el filesystem del autor):** + +- Telemetría YAML: `/E/Proyectos/StrangeDaysTech/sentinel/.devtrail/plans/PLAN-{01,02,03,05,06}.telemetry.yaml` +- Auditorías externas duales: `/E/Proyectos/StrangeDaysTech/sentinel/audit/plans/{05,06}/{copilot-v1.0.37-audit,gemini-cli-v1-audit,claude-analisis}.md` +- Narrativa decision-by-decision: `/E/Proyectos/StrangeDaysTech/sentinel/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-28-{020,021,022,023,024}-*.md` +- Tooling ejecutable validado: `/E/Proyectos/StrangeDaysTech/sentinel/scripts/check-plan-drift.sh` +- Plan-docs canónicos bajo TEMPLATE: `/E/Proyectos/StrangeDaysTech/sentinel/docs/plans/{05,06}-*.md` + +## 4. Confrontación supuesto por supuesto + +### 4.1 Supuesto 1 — Vibe coding no escala + +**Verdict: Validado parcialmente.** + +El experimento no comparó head-to-head "agente con DevTrail" vs "agente sin DevTrail" — Sentinel adoptó DevTrail desde el inicio. Pero sí mostró que, *incluso con* disciplina y AILOGs estructurados, el agente acumula gaps no documentados que solo afloran con auditoría externa. Esto es un proxy: si con disciplina el agente todavía olvida cosas, sin disciplina las olvidaría todas. + +> "F4 (IG): `evaluator_test.go` declarado con 3 tests para `ResolveAnomalyThresholds` pero **sin cambios en el rango**. Cobertura unitaria del resolver ausente. **Hallazgo no documentado en AILOG-021** — gap real de cobertura." +> — `audit/plans/05/claude-analisis.md` §3 (línea ~106), captura combinada de Copilot + Gemini. + +> "F4 evaluator_test.go gap olvidado: el Plan declaró 3 tests al evaluator_test.go que NO implementé. Ningún checkpoint pre-commit lo atrapó (compile pasa, otros tests pasan). AILOG-021 NO documenta este gap a pesar de documentar otros 3 R nuevos. Patrón: drifts pueden ser de OMISIÓN, no solo de cambio — el agente nombra los drifts que ve, pero no los que olvida." +> — `PLAN-05.telemetry.yaml` §qualitative.friction_points (línea ~165). + +> "F5 (hallucination): Plan declaró injection en `statuscenter/service.go` pero Wire instancia `NewAnomalyDetector` en `cmd/sentinel/wire_gen.go`, NOT en `service.go`. The Plan was architecturally wrong from origin about where to inject." +> — `PLAN-05.telemetry.yaml` §scope_change_notes (línea ~144). + +**Lo validado:** el agente, incluso con disciplina, comete dos clases de fallo que solo afloran post-hoc: (a) implementación olvidada del Plan (F4: 3 tests prometidos no escritos), (b) hallucination arquitectónica del Plan-doc mismo (F5: el Plan asumió un punto de inyección que no existe). Ninguna de las dos fue capturada por checkpoints internos del agente — solo por auditoría externa multi-modelo. + +**Lo no demostrado:** que sin DevTrail el problema sería *peor*. La hipótesis es plausible (los gaps capturados son justamente del tipo que se esfuma cuando no hay un Plan-doc declarado contra el que comparar), pero el experimento no construyó un brazo de control. Para una validación más fuerte, un proyecto futuro con dos brazos (con disciplina vs sin) o un proyecto que adopte DevTrail tarde y mida el delta de gaps capturados antes/después cerraría el supuesto. + +### 4.2 Supuesto 2 — Notas estructuradas reducen modos de falla + +**Verdict: Validado.** + +La evidencia más fuerte: cuando una convención se nombra en el AILOG, los auditores externos la capturan; cuando no se nombra, no la ven. Esta es la propiedad estructural que el supuesto afirma. + +> "Los patrones internos que llevan tiempo aplicándose pero no tienen nombre quedan invisibles a auditores externos. Nombrarlos formalmente convierte la práctica en señal pública." +> — `AILOG-020` §Additional Notes (línea 262–264). Observación destilada de que AILOG-019 nombró R4 (riesgo del slice no-auto-extiende) y Gemini lo capturó externamente *exactamente* porque el AILOG lo nombraba. + +> "Mejor calibración combinada de auditores en 5 ciclos (Copilot 9.25, Gemini 9.5). Hipótesis acumulada confirmada: TEMPLATE v2 + AILOGs ricos reducen el espacio de ambigüedad para auditoría externa." +> — `PLAN-05.telemetry.yaml` §qualitative.wins (línea ~169). + +> "Tendencia inter-Plan (5 datos): +> +> | Auditor | Plan 01 | Plan 02 | Plan 03 | Plan 05 | +> |---------|--------:|--------:|--------:|--------:| +> | Copilot | 8.0 | 8.5 | 7.8 | **9.25** | +> | Gemini | 7.6 | 7.2 | 9.3 | **9.5** | +> +> Ambos auditores en su mejor calibración del experimento. Hipótesis: el TEMPLATE v2 + el AILOG rico de PLAN-05 redujeron el espacio de ambigüedad, permitiendo categorización más precisa. **El experimento está convergiendo**." +> — `audit/plans/05/claude-analisis.md` §6 (línea 162–169). + +> "3 R nuevos descubiertos durante ejecución (R6, R7, R8). Patrón validado en 4/4 ciclos del experimento. Confirma que la convención `R (nuevo, no en Plan)` del TEMPLATE v2 captura señal real." +> — `AILOG-021` §Additional Notes (línea 351–353). + +**Lo validado:** las convenciones nombradas en docs estructurados (R, separación Local/Production checks, esfuerzo en TIEMPO) son capturadas por auditores externos heterogéneos (Copilot y Gemini, modelos distintos), lo que se traduce en convergencia de scores hacia 9.25/9.5. La estructura *exporta* señal pública. + +**Matiz importante:** los AILOGs ricos no eliminan los modos de falla — los reducen. F4 y F5 muestran que el agente puede no documentar lo que olvida. La conclusión refinada es la del propio claude-analisis: *"los R en el AILOG son señal valiosa pero NO sustituyen auditoría externa rigurosa. La auditoría es complemento, no redundancia"* (`PLAN-05.telemetry.yaml` línea ~213). Esto refuerza la tesis sobre disciplina cognitiva en lugar de debilitarla: la disciplina no promete eliminar errores, promete hacerlos *visibles*. + +### 4.3 Supuesto 3 — Subproducto regulatorio sin trabajo extra + +**Verdict: Validado.** + +El experimento generó, sin pasos adicionales más allá del cierre normal de cada Plan, un cuerpo de evidencia auditable: cinco telemetrías YAML estructuradas con campos compatibles con NIST AI RMF (information_integrity tracking) e ISO/IEC 42001 cláusulas 8 y 9, un AILOG por ciclo con frontmatter normalizado (`risk_level`, `eu_ai_act_risk`, `nist_genai_risks`, `iso_42001_clause`), y reportes de auditoría dual con consolidación crítica. + +> Frontmatter de `AILOG-2026-04-28-021` (líneas 9–13): +> +> ```yaml +> risk_level: medium +> eu_ai_act_risk: not_applicable +> nist_genai_risks: [information_integrity, value_chain] +> iso_42001_clause: [6, 8] +> ``` + +> "Cero `real_debt` — toda la Verification pasó limpia (build, gosec 0 issues / 96 files / 15.9 kLOC, govulncheck clean, integration test 10s). Primer ciclo del experimento bajo M sin deuda técnica detectable por auditores externos." +> — `PLAN-05.telemetry.yaml` §qualitative.wins (línea ~168). + +**Lo validado:** los artefactos producidos (AILOGs con frontmatter regulatorio, telemetría YAML auditable, drift-check ejecutable, reportes de auditoría externa) son consumibles por un auditor ISO 42001 sin trabajo extra del ingeniero. El esfuerzo total reportado para PLAN-06 fue ~40 min (vs ~30 min estimado de código puro): el +33% incluye AILOG + drift validation + tests, no horas dedicadas a "compliance" como tarea separada. + +**Lo no probado todavía:** que un auditor real (humano externo, no LLM) acepte estos artefactos como suficientes para una certificación. Eso requiere un próximo ciclo donde un compliance officer real revise los outputs. La afirmación a este punto es: la evidencia *existe* en formato estructurado y firmable; queda probar que un auditor la acepte. + +### 4.4 Supuesto 4 — Aprobaciones rara vez binarias + +**Verdict: Sin evidencia. Pendiente otro proyecto.** + +Sentinel lo trabajó un solo ingeniero (Jose Villaseñor Montfort) en sesiones individuales con Claude Code. No hubo flujo de aprobación multi-actor durante el experimento `/plan-audit`. El supuesto se sostiene sobre observaciones empíricas de otros contextos (mencionadas en `cloud-proposal.md` §4.2), pero el experimento *no lo ejercitó*. + +Para validar este supuesto se requiere un proyecto con al menos dos personas decisoras (ingeniero implementador + revisor con autoridad para condicionar el merge), idealmente con flujo asíncrono donde la aprobación incluya condiciones diferidas (texto humano nivel 1 → estructurado nivel 2 → policy-as-code nivel 3 según `cloud-proposal.md` §4.2). + +**Recomendación accionable:** documentar el supuesto #4 como "hipótesis prometedora pero no validada" en `cloud-proposal.md` v0.3, y nombrar como criterio de salida de la fase 1 (12-18 meses) tener al menos un proyecto adoptante con flujo multi-actor real. No diseñar features de aprobación condicional en Cloud hasta tener este dato. + +### 4.5 Supuesto 5 — Stage > commit como unidad de trazabilidad + +**Verdict: Validado.** + +PLAN-05 (M, 1305 líneas, 19 archivos modificados, 1 commit atómico) es ejemplo paradigmático: el commit `473f6e0` por sí solo no captura las tres decisiones arquitectónicas tomadas durante implementación (R6 simplificación de repository, R7 simplificación de integration test, R8 fix de wire.go). Esas decisiones existen *como Stage*, no *como diff*. + +> "3 R nuevos descubiertos durante ejecución (R6, R7, R8). Plan-doc drift positivo y negativo: drift positivo (R6: simplification) + drift negativo (R7: integration test simplification, R8: wire.go fix out-of-scope). El TEMPLATE v2 sección `## Cierre del Plan` recordará actualizar el Plan doc post-merge." +> — `AILOG-021` §Additional Notes (línea 351–357). + +> "El Plan declaraba `SetAnomalyThresholds(ctx, caller, serviceID, thresholds)` con SUPER_ADMIN guard EN el service (estilo identity en PLAN-02). La convención del módulo policyengine es: handler hace auth, service confía y recibe `changedBy string`. Adopté la convención local." +> — `AILOG-021` §Decision (línea 213–219). + +> "PLAN-05 es la primera ejecución bajo M y bajo TEMPLATE v2. Los datos confirman que el formato v2 es robusto bajo carga mayor y que la disciplina de auditoría externa sigue siendo necesaria incluso con AILOGs detallados — los R en el AILOG son una guía, no un reemplazo." +> — `audit/plans/05/claude-analisis.md` §7 (línea ~196). + +**Lo validado:** el conjunto Plan-doc + AILOG + telemetría + auditoría dual + claude-analisis es la unidad mínima útil para reconstruir lo que pasó en PLAN-05. El commit aislado pierde la mitad de la información (qué se descartó, qué convenciones locales aplicaron, qué drift aceptado, qué riesgo emergente). Esto es exactamente el patrón Stage que el supuesto afirma. + +### 4.6 Supuesto 6 — Evidencia in-situ + firma > reconstrucción posterior + +**Verdict: Validado parcialmente.** + +La parte *evidencia in-situ* está fuertemente validada: `check-plan-drift.sh` ejecutado al cierre del Plan detecta drifts archivos-declarados-vs-modificados con cero falsos positivos en 2/2 tests empíricos. + +> "Validación empírica: ejecuté el script sobre PLAN-05 (`fd65e87..473f6e0`) y sobre PLAN-01 (`cb2e1e8..3167475`): +> +> - PLAN-05 (con drifts conocidos): script reporta **3 omitted files**: `evaluator_test.go` (F4), `repository.go` (F1/R6), `statuscenter/service.go` (F5) — exactamente los 3 drifts que Copilot+Gemini capturaron en sus auditorías. Más 4 scope expansions, 3 de los cuales son test mocks + wire.go (R8 documentado). **Cero falsos positivos.** +> - PLAN-01 (ciclo más limpio del experimento): script reporta **0 drifts** — exactamente lo que las auditorías de Plan 01 indicaron. **Cero falsos positivos.**" +> — `AILOG-022` §Summary (línea 59–69). + +> "Validación de hipótesis v3: `check-plan-drift.sh` reportó 0 drift pre-commit; los 3 findings reales son del tipo que el script no puede detectar por diseño (mitigaciones no implementadas, scope text vs payload, tests promised vs realized). Confirma: script + auditorías son complementarios." +> — `AILOG-024` §Post-audit fixes (línea 154–158). + +**Lo no probado todavía:** la parte de *firma criptográfica*. Sentinel no firmó bundles con Sigstore/cosign ni implementó hash-chaining. La afirmación de que firmar in-situ es estructuralmente más confiable que reconstrucción posterior es plausible (es la propiedad técnica de cualquier append-only log) pero el experimento no la ejercitó. Cerrar este gap requiere implementar `devtrail stage close` con firma cosign en un próximo ciclo y un escenario de tampering simulado para verificar detección. + +## 5. Fricciones detectadas y marco virtud-vs-ceremonia + +Sentinel reveló cuatro puntos de fricción cuantificables. El principio #6 de `devtrail-design-principles.md` ya establece que "fricción justificada es aceptable y a veces deseable". El refinamiento empírico del experimento es distinguir *fricción virtuosa* (la que externaliza signal a auditores externos y captura gaps que el agente solo no captura) de *ceremonia atacable* (la que solo genera triage manual o prescribe sin reflexividad). + +### 5.1 Overhead de documentación — virtud parcial + +> "Esfuerzo estimado: XS (~30 min). Esfuerzo real: XS (~40 min con tests + AILOG + drift validation). Drift en líneas: ~50 (Plan) → ~280 (real) = 5.6x — consistente con el patrón del experimento (líneas no predictivas; tiempo cumplió 1.0x)." +> — `AILOG-024` §Notes (línea 125–128). + +El +33% sobre el estimado XS no es overhead doc puro — incluye tests + AILOG + drift validation. El bloque de "AILOG + drift validation" agregado al cierre genera, a cambio, el material que dos auditorías externas consumieron y que en PLAN-06 capturó pre-merge un fix operacional (timeout R1 no implementado en handler). El ROI del +33% es: un fix sin hotfix post-deploy. Virtud justificada bajo principio #6. + +### 5.2 Prescripciones que chocan con convenciones locales — ceremonia atacable + +> "El Plan declaraba `SetAnomalyThresholds(ctx, caller, serviceID, thresholds)` con SUPER_ADMIN guard EN el service (estilo identity en PLAN-02). La convención del módulo policyengine es: handler hace auth, service confía y recibe `changedBy string`. Adopté la convención local — handler.go usa `requireSuperAdmin` y pasa `caller.UserID` como changedBy. Esto evita duplicación de auth y mantiene el módulo coherente." +> — `AILOG-021` §Decision (línea 213–219). + +El TEMPLATE prescribió una firma arquitectónica que conflictaba con la convención del módulo destino. El ingeniero tuvo que detectar y resolver manualmente, generando un drift documental (F2 en la auditoría) que no aporta señal nueva. Esto es ceremonia: el formato no distinguió *prescripciones arquitectónicas irrenunciables* de *convenciones reflexivas dependientes del módulo*. Mitigación propuesta para format v4: campo separado "Wiring/instancing" que fuerce la pregunta "¿esto se instancia en service.go o en wire_gen.go?" durante planning, en lugar de prescribir la firma directamente. Idea ya capturada en `PLAN-05.telemetry.yaml` §proposed_format_changes #7. + +### 5.3 Drift script genera triage manual sobre R ya documentados — ceremonia parcial + +> "R2 — Drifts de OMISIÓN ya documentados en AILOG generan ruido: si el agente ya documentó 'evaluator_test no implementado por X razón' como `R nuevo` en AILOG, el script seguirá reportándolo como omitted. Mitigación: el output del script dice claramente 'Action: either complete the work, or document in AILOG'. El agente lee el AILOG y, si ya está documentado, ignora la alerta — costo bajo. Mejora futura: el script podría grep el AILOG por el path omitido y suprimir la alerta si lo encuentra." +> — `AILOG-022` §Risk (línea 241–248). + +El script en su forma actual genera alertas que el ingeniero filtra mentalmente contra el AILOG. Es ceremonia parcial — vale el costo (signal vs ruido), pero la integración futura `drift-check` AILOG-aware (R2 en el AILOG-022 mismo es el plan a futuro) puede eliminar el triage. Cuando se porte al CLI Rust (fase 2 del roadmap), implementar AILOG-awareness desde el inicio. + +### 5.4 Plantillas prescriptivas no anticipan flakes de testcontainers — virtud + +> "El Plan declaraba 'verifica que un override cambia el comportamiento del detector end-to-end'. Implementación inicial encontró timing flake bajo testcontainers (audit pipeline async + RLS context entre heartbeat y override). Decision: simplificar a round-trip policyengine y dejar la behavioral verification al unit test que no tiene flake risk. Defense in depth se mantiene; cobertura se mueve a la capa correcta. R7 (nuevo, no en Plan): integration tests con timing crossing multiple goroutines + RLS contexts pueden ser frágiles. Convención candidata para format v3." +> — `AILOG-021` §Decision (línea 228–242). + +El Plan declaró una verificación que la realidad de testcontainers + audit pipeline async no permitió. El ingeniero divergió, documentó la divergencia como R7 nuevo, y propuso una convención candidata para format v3. Esto es exactamente el ciclo auto-evolutivo que el principio #12 valida: la fricción produjo conocimiento accionable que mejoró el formato siguiente. Virtud. + +### 5.5 Síntesis del marco + +La fricción de DevTrail es virtud cuando externaliza signal pública (R, drift detection, auditoría dual) y captura gaps que el agente solo no captura. La fricción es ceremonia atacable cuando solo genera triage o prescribe sin reflexividad. La primera se mantiene; la segunda es bug del formato, no virtud del principio. El refinamiento de `devtrail-design-principles.md` v0.2 incorpora explícitamente esta distinción. + +## 6. El argumento N≈2-3: por qué Sentinel cuenta más que un proyecto + +El principio #12 de `devtrail-design-principles.md` v0.1 establece: "no debe avanzar más rápido de lo que aprendemos sobre cómo se usa realmente. Cristalizar features prematuramente, antes de tener datos de uso real en al menos tres proyectos distintos, genera costos altos de mantenimiento sobre features que pueden ser equivocadas". + +Sentinel es *un solo proyecto* en el sentido literal (un repo, un dominio Go backend, un autor). Pero la evidencia que produjo tiene tres ejes de diversidad estructural que el principio busca capturar: + +1. **Escala variable.** PLAN-01/03 (XS, ~30 min, doc-only o cambios pequeños), PLAN-02 (S, 1h, admin endpoint), PLAN-05 (M, 1.5h, 1305 líneas, 19 archivos, 5 capas tocadas), PLAN-06 (XS, 40 min, endpoint admin con timeout). El TEMPLATE v2 fue diseñado con datos XS-S y se estresó por primera vez bajo M en PLAN-05; el TEMPLATE v3 se diseñó retrospectivamente con datos M y se ejercitó prospectivamente bajo XS en PLAN-06. La diversidad de escalas validó que el formato escala hacia arriba *y* hacia abajo. + +2. **Iteración del formato bajo presión empírica.** v1 → v2 → v3 con cada iteración derivada del ciclo anterior. v2 emergió de PLAN-01/02/03 (3 datos). v3 emergió de PLAN-05 (1 dato bajo nueva escala). Cada iteración tiene costo decreciente y valor creciente. El experimento es *auto-evolutivo*: cada Plan ejecutado mejora el formato del próximo. + + > "Patrón meta-meta detectado: cada iteración del formato resulta de un ciclo del experimento. v2 emergió de PLAN-01/02/03 telemetry. v3 emerge de PLAN-05 telemetry. Predicción: v4 emergerá del primer Plan que ejercite v3 (PLAN-06 si se materializa). Esto valida que el experimento es **auto-evolutivo**: cada Plan ejecutado mejora el formato del próximo." + > — `AILOG-022` §Additional Notes (línea 288–292). + +3. **Calibración cross-modelo de auditores.** Dos modelos heterogéneos (Copilot v1.0.37 GPT-derived, Gemini CLI v1) auditando los mismos planes con criterios paralelos. La convergencia inter-modelo (9.25/9.5 en PLAN-05) es señal estructural de que la disciplina captura signal generalizable, no idiosincracia de un modelo. + +**Conclusión del argumento:** los seis ciclos × tres formatos × tres escalas constituyen el *espíritu* del N≥3 que el principio #12 busca proteger — observación antes de cristalización, evolución incremental, evidencia empírica antes que intuición. Pero queda un eje no diversificado: **un solo dominio (Go backend)** y **un solo autor**. Cualquier patrón que se cristalice del experimento debe marcarse como *experimental/opt-in* y un segundo proyecto en otro dominio (frontend, ML pipeline, infra-as-code) puede invalidar parte del schema. + +**Recomendación operacional:** los schemas que se cristalicen en el CLI a partir de Sentinel (`charter.schema.v0.json`, `charter-telemetry.schema.v0.json`) llevan el sufijo `v0` y la marca `experimental`. La transición a v1 estable requiere validación con un segundo proyecto en dominio distinto. Esta es la cláusula de salida explícita del principio #12. + +## 7. Hallazgos no anticipados por ningún doc previo + +Tres patrones emergieron del experimento que ninguno de los tres documentos de propuesta (escritos antes) había articulado: + +**7.1 El formato es auto-evolutivo.** Ninguno de los tres docs anticipó que la aplicación del formato a sí mismo (telemetría → análisis crítico → propuesta de mejora → nuevo formato) sería un ciclo natural. Esto es un meta-patrón estructural que merece nombre propio en futuras versiones de los principios. Candidato: principio #13 ("la herramienta evoluciona consigo misma; cada uso es input para la próxima versión") o ampliación del principio #12. + +**7.2 Drift script y auditoría externa son complementarios, no sustitutos.** AILOG-022 hipotetizó complementariedad; PLAN-06 la confirmó empíricamente. Esto cambia el marco mental de cómo diseñar tooling DevTrail: cada layer debe atacar un tipo de drift distinto (declaración vs implementación vs comportamiento), no replicar capacidades existentes. + + > "Hipótesis v3 confirmada: script + auditorías + AILOG son herramientas complementarias. Ninguna sustituye a las otras." + > — `audit/plans/06/claude-analisis.md` §7 (línea 145). + +**7.3 Auditoría dual como calibrador de modelos.** PLAN-05 fue el caso límite: Gemini calibró F5 correctamente como `hallucination` mientras Copilot lo categorizó como `implementation_gap`. La auditoría dual no es solo "dos pares de ojos" — es un mecanismo de calibración cross-modelo. El claude-analisis funciona como tercer modelo que reconcilia veredictos divergentes según el schema definicional. Esto sugiere una arquitectura de tres niveles para `devtrail charter audit` (fase 3 del roadmap): dos auditores en paralelo + un calibrador-reconciliador, no solo "ejecuta un audit con N modelos". + +## 8. Verdict global y siguientes pasos + +| # | Supuesto | Verdict | +|---|----------|---------| +| 1 | Vibe coding no escala | Validado parcialmente (sin brazo de control) | +| 2 | Notas estructuradas reducen modos de falla | Validado | +| 3 | Subproducto regulatorio sin trabajo extra | Validado (pendiente prueba con auditor humano real) | +| 4 | Aprobaciones rara vez binarias | Sin evidencia — pendiente proyecto multi-actor | +| 5 | Stage > commit como unidad de trazabilidad | Validado | +| 6 | Evidencia in-situ + firma > reconstrucción posterior | Validado parcialmente (sin firma criptográfica probada) | + +**Resultado neto:** 3 supuestos validados completamente, 2 validados parcialmente, 1 sin evidencia, 0 refutados. **La tesis se sostiene** con la evidencia disponible. Los gaps son áreas que requieren validación adicional, no contradicciones. + +**Próximos proyectos sugeridos para cerrar gaps:** + +1. **Adoptante en otro dominio** (frontend, ML pipeline, infra) para diversificar el eje "dominio" del principio #12. Cierra parte del supuesto #1 si se mide delta de gaps capturados antes/después. +2. **Proyecto con flujo multi-actor** (al menos 2 personas decisoras, aprobación asíncrona, condiciones diferidas reales). Cierra el supuesto #4. +3. **Implementación de `devtrail stage close` con firma cosign + escenario de tampering** en uno de los repos existentes. Cierra la parte criptográfica del supuesto #6. +4. **Revisión por un auditor ISO 42001 humano real** de los outputs de Sentinel. Cierra el supuesto #3 frente a un consumidor real, no solo frente a la estructura compatible. + +**Decisiones que la tesis valida y se pueden tomar ahora:** + +- Cristalizar Charters como entidad de primera clase del CLI con schema `v0.json` marcado experimental. +- Portar `TEMPLATE.md v3` y `check-plan-drift.sh` como artefactos canónicos del framework (renombrados en destino a `charter-template.md` y `devtrail charter drift` — ver `devtrail-cli-roadmap.md` §6). +- Mantener la jerarquía de personas (ingeniero senior primario) sin sesgo hacia compliance officer. +- Posicionar el producto sobre "disciplina cognitiva" en marketing y docs, no sobre "compliance tool". + +**Decisiones que la tesis NO permite tomar todavía:** + +- Diseñar features de aprobación condicional (Cloud) sin un proyecto multi-actor real que valide el supuesto #4. +- Comprometer un schema `v1.0` estable de Charters sin evidencia de un segundo dominio. +- Marketing de "AI BOM agregado" sin haber probado la firma criptográfica en producción. + +Las acciones del primer grupo se reflejan en `devtrail-cli-roadmap.md` v0.1 como Fase 1. Las del segundo grupo quedan explícitamente bloqueadas hasta evidencia adicional, manteniendo el principio #12 (velocidad = velocidad del aprendizaje). + +--- + +*Este documento es la entrada principal para profundización empírica sobre la tesis de DevTrail. Las decisiones de producto que se tomen en `devtrail-cloud-proposal.md` v0.3 y `devtrail-cli-roadmap.md` v0.1 referencian sus secciones específicas como ancla de evidencia.* diff --git a/Propuesta/que-es-un-charter.md b/Propuesta/que-es-un-charter.md new file mode 100644 index 0000000..439c8a5 --- /dev/null +++ b/Propuesta/que-es-un-charter.md @@ -0,0 +1,133 @@ +# Qué es un "Charter" en DevTrail (y dónde encaja respecto a GitHub SpecKit) + +**Versión:** 0.2 (rename Plan → Charter) +**Fecha:** 30 de abril de 2026 +**Autor:** Jose Villaseñor Montfort — StrangeDaysTech +**Propósito:** Fijar el alcance conceptual del artefacto **Charter** tal como emerge del experimento Sentinel (donde se llamó *Plan*), y explicar cómo coexiste con flujos de diseño y desarrollo que ya usan SpecKit (spec → plan → tasks). +**Documentos relacionados:** `devtrail-cli-roadmap.md` (§3 Fase 1, §6 mapeo Sentinel→CLI), `devtrail-thesis-validation.md`, `devtrail-charter-telemetry.md`, `sentinel/docs/plans/TEMPLATE.md` v3, `sentinel/docs/plans/README.md`. + +--- + +## 1. Qué es un Charter en DevTrail + +**Una declaración ex-ante de una unidad de trabajo, lo bastante grande como para merecer un contrato verificable y una auditoría ex-post.** + +El Charter tiene tres caras simultáneas: + +1. **Contrato de scope** (Context + Scope in/out + Archivos a modificar + Riesgos): qué se va a tocar y, deliberadamente, qué *no*. La sección `Out of scope` existe específicamente para que auditores externos no lo clasifiquen como gap. +2. **Contrato de verificación** (Local checks + Production smoke): comandos ejecutables literal, separados por *cuándo aplican*. El split Local/Prod no es estilo — emerge de que en 3/3 ciclos los auditores externos clasificaban fallos prod-only como `real_debt`. +3. **Ancla de auditoría** (frontmatter + Cierre del Charter + drift check): el Charter es el sujeto sobre el que `devtrail charter drift` y `devtrail charter audit` operan. Sin Charter no hay nada que auditar. + +### 1.1 No es solo deuda técnica + +De los Plans cerrados de Sentinel (que son la evidencia empírica del patrón Charter), solo uno (`03-contract-bumps`) huele a deuda. El resto son features (`02-admin-endpoint`, `05-per-service-anomaly-thresholds`), trabajo de gobernanza (`01-deploy-governance`) o trabajo operacional (`06-baseline-recompute-job`). El README de `sentinel/docs/plans/` lo dice literal: *"Roadmap de trabajo identificado durante el cierre del backlog post-MVP"* — backlog, no debt-log. + +### 1.2 Cuándo amerita un Charter vs. solo un AILOG + +Inferido del corpus, no escrito formalmente: + +- **Solo AILOG**: cambio que cabe en una sola sesión, sin pre-declaración de archivos, riesgo estructural bajo (typo, fix puntual, refactor local). +- **Charter + AILOG**: el trabajo toca múltiples archivos, tiene riesgos enumerables ex-ante, requiere verificación con comandos ejecutables, y se beneficia de auditoría externa post-merge. Esfuerzo XS–L (minutos a días). +- **ADR + uno o más Charters**: decisión arquitectónica de fondo, donde cada Charter ejecuta una porción del ADR. + +### 1.3 Atomic Charter closure (format v4) + +A partir de fw-4.4.2, el `charter-template.md` adopta **format v4**: cuando el drift check pre-commit (Tasks #7) reporta drift entre `## Files to modify` y los archivos efectivamente modificados, el implementor debe actualizar el Charter atómicamente — en el mismo commit/PR que la implementación — añadiendo un bloque `## Closing notes` que documente qué cambió, por qué, y referencia al AILOG correspondiente. **No se difiere a un housekeeping PR post-merge.** + +El patrón emergió empíricamente de PLAN-07 de Sentinel (cerrado 2026-05-02), donde un drift de omisión legítimo (un live test resultó agnóstico al cambio, así que un archivo declarado en §Archivos a modificar no se tocó) se documentó tarde via housekeeping PR separado, dejando el Plan-doc stale por días. AIDEC-2026-05-02-001 de Sentinel formalizó el gap y propuso format v4; este Charter (`que-es-un-charter.md`) refleja la evolución upstream. PLAN-05 (`docs/plans/05-per-service-anomaly-thresholds.md`) y PLAN-07 mismo son los ejemplos canónicos del patrón `## Closing notes` aplicado retrospectivamente — ambos en Sentinel. + +--- + +## 2. Por qué se llama "Charter" y no "Plan" + +DevTrail llamó originalmente a este artefacto **Plan** durante el experimento Sentinel (abril 2026). El término se renombró a **Charter** antes de la implementación en el CLI por una razón pragmática: GitHub SpecKit ya usa la palabra "plan" (`/speckit.plan`, `plan.md`) para un artefacto distinto, y la colisión nominal generaba fricción en docs adopters que combinan ambos flujos. + +Los registros históricos de Sentinel (Plans 01-06, `sentinel/docs/plans/`, `sentinel/scripts/check-plan-drift.sh`, AILOGs y telemetrías YAML `PLAN-NN.telemetry.yaml`) preservan el nombre original — son evidencia empírica de un momento puntual en el tiempo, y reescribir la historia falsificaría el registro. Las referencias a esos archivos en este documento mantienen "Plan" deliberadamente. + +El concepto que SpecKit llama "plan" y el que DevTrail llama "Charter" son artefactos distintos: + +| | **SpecKit `plan.md`** | **DevTrail Charter** | +|---|---|---| +| Granularidad | Feature completa (semanas, varias historias) | Unidad acotada (horas a días, una rama) | +| Contenido dominante | Stack, dependencias, estructura de proyecto, gates de constitución | Archivos concretos a tocar, comandos de verificación, riesgos R | +| Sub-artefactos | Genera `research.md`, `data-model.md`, `quickstart.md`, `contracts/` | Genera (al ejecutarse) un AILOG | +| Validación | Constitution Check (gate ex-ante) | Drift-check + auditoría externa (gates ex-post) | +| Optimización | *Claridad upfront* | *Trazabilidad ex-post* | + +Lo que SpecKit llama "plan" se parece más a un **ADR + skeleton arquitectónico**. Lo que DevTrail llama "Charter" se parece más a un **task-card con verificación contractual y ancla de auditoría**. + +--- + +## 3. El flujo SpecKit, mapeado pieza a pieza + +SpecKit es lineal y top-down: `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → implementar. + +| SpecKit | Qué resuelve | Equivalente más cercano en DevTrail | +|---|---|---| +| `spec.md` (US, FRs, SCs) | *Qué* construir, agnóstico a tech | `01-requirements/REQ-*.md` | +| `plan.md` (stack, estructura) | *Cómo* arquitectarlo | `02-design/ADR-*.md` | +| `tasks.md` (T001..TNNN) | *En qué orden* ejecutarlo | sección `## Tasks` dentro de un Charter DevTrail | +| (no existe) | Bitácora de ejecución | **AILOG** | +| (no existe) | Drift declarado vs. ejecutado | **`devtrail charter drift`** | +| (no existe) | Auditoría multi-modelo ex-post | **`devtrail charter audit`** | + +Las tres últimas filas son la contribución específica de DevTrail. SpecKit termina al producir `tasks.md`; lo que pasa después no le importa al framework — si la implementación se desvía del plan, no hay mecanismo que lo detecte. DevTrail entra exactamente ahí. + +--- + +## 4. Tres modos en que un Charter DevTrail puede convivir con SpecKit + +### Modo A — Greenfield con SpecKit como driver + +``` +spec.md → plan.md → tasks.md → ┐ + ├→ Charter-NN (cubre US1 + verificación + riesgos) + ├→ Charter-NN+1 (cubre US2 + verificación + riesgos) + └→ Charter-NN+2 (cubre US3 + verificación + riesgos) + ↓ + AILOG por Charter + ↓ + drift-check + audit +``` + +Cada Charter DevTrail toma un subconjunto de tasks (típicamente una user story o una fase) y le añade las tres capas que SpecKit no provee: verificación ejecutable, declaración de archivos contra la que medir drift, y enganche con AILOG/auditoría. + +### Modo B — Mantenimiento / post-MVP (caso real de Sentinel) + +No hay SpecKit corriendo. Los Plans 01–06 de Sentinel nacen de AILOGs y backlog post-MVP, no de specs. El campo `Origen:` del Charter apunta a un AILOG, no a un `specs/###-feature/`. Aquí el Charter DevTrail es freestanding. + +### Modo C — Híbrido (probablemente el más realista) + +- Features mayores → flujo SpecKit completo + Charters DevTrail al ejecutar tasks. +- Bug fixes, gobernanza, deuda, cambios de contrato, features chicas → solo Charter DevTrail. + +Esto es coherente con lo que ya muestra Sentinel: de los Plans cerrados, ninguno tenía SpecKit upstream porque el MVP ya estaba spec'd y cerrado. Lo que quedaba era trabajo evolutivo, donde el ciclo Spec→Plan→Tasks es desproporcionado. + +--- + +## 5. La diferencia conceptual de fondo + +**SpecKit responde a la pregunta:** *"¿Cómo descompongo una idea de producto en trabajo ejecutable?"* — optimiza para claridad upfront y paralelización de US. + +**DevTrail Charter responde a la pregunta:** *"¿Cómo hago que una unidad de trabajo sea verificable, auditable y detectable cuando se desvía de lo declarado?"* — optimiza para evidencia ex-post. + +Por eso no compiten: viven en momentos distintos del ciclo. SpecKit acaba en `tasks.md`; DevTrail Charter empieza ahí (cuando se aplica) o se sostiene solo (cuando no hay spec previa). La tesis Sentinel no es "esto reemplaza SpecKit" — es "esto cubre la fase post-tasks que SpecKit no cubre, y la cubre con un patrón de tres niveles (declaración + drift + auditoría heterogénea) que tiene evidencia empírica de capturar gaps que el implementador no documentó". + +--- + +## 6. Nota sobre la visión Studio: "Stage" no es sinónimo de Charter + +`devtrail-studio-vision.md` introduce un término adicional, **Stage**, que conviene no confundir con Charter. No son sinónimos: viven en niveles distintos del ciclo. + +- **Stage** = etapa de trabajo que recorre las seis fases cognitivas del Studio (Spec → Implementation → Audit → Remediation → Governance → Closure & Deliver) y se cierra con un Closure Bundle firmado y hash-chained. Comandos propuestos en la visión: `devtrail stage open/close/status` (no implementados; corresponden al Hito 2 de la evolución hacia Studio). +- **Charter** = unidad acotada con verificación + drift + ancla de auditoría — el artefacto que define este documento. Los Charters viven *dentro de* un Stage; un Stage típicamente contiene uno o varios Charters más sus tasks asociados. + +La taxonomía implícita de la visión es de tres niveles: **Stage > Charter > Task**. El roadmap actual del CLI (`devtrail-cli-roadmap.md`, Fases 1-3) opera enteramente al nivel de Charter (lo que Sentinel llamó "Plan"), que es el nivel donde existe evidencia empírica de Sentinel. Stage entraría al CLI más adelante como capa adicional, no como rename de Charter. + +## 7. Implicación para el roadmap del CLI DevTrail + +Vale la pena reflejarlo en cómo se documenta el comando `devtrail charter new` cuando llegue Fase 1 (`devtrail-cli-roadmap.md` §3.2). Hoy el flag previsto `--from-ailog ID` cubre el Modo B. Probablemente convenga tener también `--from-spec specs/###-feature/` para el Modo A — pre-popula `Origen:` apuntando al `spec.md` de SpecKit, y opcionalmente hereda US relevantes a la sección Context. Eso es ejercicio para Fase 1, no para resolver hoy, pero conviene anotarlo en este documento como decisión abierta para cuando se diseñe la subcomanda. + +--- + +*Este documento captura el alcance conceptual del artefacto Charter (originalmente llamado "Plan" en el experimento Sentinel) tal como se entiende a finales de abril de 2026. La definición seguirá evolucionando conforme adoptantes fuera de Sentinel ejerciten el patrón en otros dominios — la versión 0.3 se escribirá tras observar al menos un proyecto adoptante completar un Charter con `devtrail charter` (criterio de salida de Fase 1).* diff --git a/README.md b/README.md index 2626839..7511301 100644 --- a/README.md +++ b/README.md @@ -206,7 +206,7 @@ DevTrail uses independent version tags for each component: | Component | Tag prefix | Example | Includes | |-----------|-----------|---------|----------| -| Framework | `fw-` | `fw-4.4.1` | Templates (12 types), governance, directives, Charter template + schema | +| Framework | `fw-` | `fw-4.4.2` | Templates (12 types), governance, directives, Charter template + schema | | CLI | `cli-` | `cli-3.6.0` | The `devtrail` binary | Check installed versions with `devtrail status` or `devtrail about`. @@ -238,7 +238,7 @@ See [CLI Reference](https://github.com/StrangeDaysTech/devtrail/blob/main/docs/a ```bash # Download the latest framework release ZIP from GitHub # Go to https://github.com/StrangeDaysTech/devtrail/releases -# and download the latest fw-* release (e.g., fw-4.4.1) +# and download the latest fw-* release (e.g., fw-4.4.2) # Extract and copy to your project unzip devtrail-fw-*.zip -d your-project/ diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md index fc45094..eb3734e 100644 --- a/dist/.devtrail/00-governance/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/AGENT-RULES.md @@ -270,4 +270,4 @@ When a change modifies API endpoints: --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md index 5ea0b02..d3a86b6 100644 --- a/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate: --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md index b2e275b..9f0a1e7 100644 --- a/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md @@ -257,4 +257,4 @@ See also [ADR-2025-01-20-001] for architectural context. --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/QUICK-REFERENCE.md index df2880a..c282510 100644 --- a/dist/.devtrail/00-governance/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/QUICK-REFERENCE.md @@ -213,4 +213,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md index b48aff2..b5feebc 100644 --- a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md @@ -270,4 +270,4 @@ Cuando un cambio modifica endpoints de API: --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md index d37e817..cd8df19 100644 --- a/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar: --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md index 5c4b0aa..fcb04a7 100644 --- a/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -249,4 +249,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico. --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md index 379624f..8a166fc 100644 --- a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md @@ -188,4 +188,4 @@ Marcar `review_required: true` cuando: --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md index c184f99..64e357a 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/AGENT-RULES.md @@ -270,4 +270,4 @@ confidence: high | medium | low --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md b/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md index bff1bc0..8762363 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md @@ -234,4 +234,4 @@ Rel(api, db, "Reads/Writes", "SQL") --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md index 125a0a8..2baa8e3 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md @@ -249,4 +249,4 @@ draft ──────► accepted ──────► deprecated --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md index d3e1e9c..5e94ec0 100644 --- a/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md +++ b/dist/.devtrail/00-governance/i18n/zh-CN/QUICK-REFERENCE.md @@ -188,4 +188,4 @@ risk_level: low | medium | high | critical --- -*DevTrail v4.4.1 | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/QUICK-REFERENCE.md b/dist/.devtrail/QUICK-REFERENCE.md index 1462731..c1ddc76 100644 --- a/dist/.devtrail/QUICK-REFERENCE.md +++ b/dist/.devtrail/QUICK-REFERENCE.md @@ -168,4 +168,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.4.1 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* +*DevTrail v4.4.2 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* diff --git a/dist/.devtrail/templates/charter-template.md b/dist/.devtrail/templates/charter-template.md index 36daf5d..a98e5ed 100644 --- a/dist/.devtrail/templates/charter-template.md +++ b/dist/.devtrail/templates/charter-template.md @@ -2,7 +2,7 @@ charter_id: CHARTER-NN status: declared effort_estimate: M -trigger: "[1-line: what observable signal justifies executing this Charter now]" +trigger: "[1-line: what concrete signal — observable event, declared decision, metric threshold, or infrastructure milestone — justifies executing this Charter now]" # Exactly one of the following two should be set when the Charter has a known origin. # Both absent is valid for a Charter scaffolded without an explicit origin (must be # filled before status moves to in-progress). @@ -102,7 +102,11 @@ curl -X PUT "https://${SERVICE_HOST}/api/v1/.../..." \ [List of risks R1, R2, ... that the implementation commits to mitigate. Each with its mitigation documented. Convention: if a NEW risk emerges during execution that was not anticipated, document it in the AILOG under `## Risk` as `R (new, not in Charter)` -— Gemini and other external auditors validate these cross-document.] +— Gemini and other external auditors validate these cross-document. + +Each mitigation should specify: (a) concrete trigger or threshold (no "eventually"), +(b) action committed, (c) what happens if the mitigation itself fails, (d) where +follow-up insights are captured if the risk surfaces lessons for a later cycle.] - **R1 — [risk description]**: [probability/severity]. Mitigation: [concrete action taken in implementation]. @@ -128,26 +132,49 @@ anticipated, document it in the AILOG under `## Risk` as `R (new, not in Ch ## Charter Closure -When closing this Charter (post-merge): +When closing this Charter: + +1. **Atomic update (format v4)**: if the drift check (Tasks #7) reported any drift + not already captured in the AILOG, edit `## Files to modify` and/or add a + `## Closing notes` block in **this same commit/PR**, before submitting. Do not + defer to a post-merge housekeeping PR. The atomic-update pattern is the canonical + way to keep the Charter coherent with execution; deferring it leaves the Charter + stale and confuses future readers (PLAN-07 of Sentinel demonstrated the failure + mode that this step prevents). -1. **Charter drift check** (automated when Phase 2 ships + manual review): +2. **Post-merge drift check** (automated when Phase 2 ships + manual review): - Run `devtrail charter drift CHARTER-NN origin/main..HEAD` (Phase 2) or the equivalent Sentinel script, and validate the output is clean or that all drifts are documented in the AILOG. - - Additionally, review the AILOG generated by the implementation. If it - declares divergences from this Charter (location of changes, scope expansion, - new R risks not anticipated, etc.) update this Charter doc to reflect the - actual execution. Pattern validated in 5/5 cycles of Sentinel `/plan-audit`: - AILOGs document divergences but Charters stay stale unless explicitly updated. + - This catches the rare case where drift is introduced post-merge (squash + mangling, admin amendments, etc.) and the atomic step in #1 could not apply. -2. **Move the row** in `docs/charters/README.md` to `## Closed` and reference the PR. +3. **Move the row** in `docs/charters/README.md` to `## Closed` and reference the PR. -3. **Status frontmatter** moves from `in-progress` to `closed` (and optionally +4. **Status frontmatter** moves from `in-progress` to `closed` (and optionally `closed_at: YYYY-MM-DD` is added — the schema allows arbitrary additional fields). -4. **Do not delete** this file — the planning history matters as much as the AILOG +5. **Do not delete** this file — the planning history matters as much as the AILOG of execution. +## Closing notes + +> Add this section ONLY when Tasks #7 drift check reported drift that the +> implementer chose to remediate atomically (rather than redoing the implementation +> to match `## Files to modify` exactly). Each bullet: what changed vs declaration, +> why, reference to the AILOG that documented the decision. Omit the section +> entirely if no drift was detected — empty `## Closing notes` is noise. +> +> Historical examples in Sentinel: PLAN-05 (`docs/plans/05-per-service-anomaly-thresholds.md`) +> §Notas de cierre — files removed because the implementation chose a different +> injection point; PLAN-07 (`docs/plans/07-fix-distribution-aligner.md`) §Notas de +> cierre — file removed because the live test was agnostic to the change. Both +> demonstrate the pattern in production usage. + +- `[path/file-from-declaration.ext]` [removed | relocated to X | repurposed]: + [1-2 lines explaining what the implementation did instead and why the original + declaration is no longer accurate]. Reference: AILOG-YYYY-MM-DD-NNN §[section]. + ---