12 KiB

Raw Blame History Unescape Escape

PLAN — Reconciliación del corpus de documentación (fase 6 del workstream docs)

EJECUTADO (2026-07-02) — las Fases 1, 2 y 3 están completas y commiteadas (commits 925508c7 → b08dece4 + cierre). Resultado y desviaciones al final de este doc (sección "Resultado del cierre"). La Fase 4 sigue diferida (decisión de usuario).

Para arrancar una sesión nueva: este documento es el kickoff completo. Continúa el workstream de CONTINUE-docs-corpus.md (fases 1–5 hechas: saneo, CANON, de-dup soma, split THEMING con stubs, entrada E0 + guías). Esta fase ataca lo que las auditorías 2026-07-01/02 midieron: conflictos doc↔doc y doc↔código verificados, referencia mezclada con bitácora, y espejos sin guard. Prompt sugerido para la sesión: "Lee docs/process/PLAN-docs-reconciliation.md y ejecútalo en orden."

Objetivo y criterio de éxito

Que un lector (humano o agente) pueda fiarse de cualquier doc del corpus sin contrastarlo con el código. Éxito medible al cierre:

Los ~14 conflictos de la Fase 1 corregidos (grep del string viejo = 0 hits).
THEMING.md es referencia atemporal (≤ ~900 líneas); lo fechado vive en un changelog.
npm run docs:check existe y pasa (guard de invariantes copiables).
docs/building-a-component.md (la puerta única, ya creada) no tiene entradas en su tabla de "Known traps" — porque las trampas ya no existen.

Reglas de trabajo (heredadas del workstream — no negociables)

PROHIBIDO lanzar agentes/workflows. Trabajo a mano.
Responder en castellano; comentarios de código y docs nuevos en inglés (docs/authoring.md §7).
NUNCA tocar words/, palabras/, chronos/ ni el libro (docs/Disenando_lo_que_ocurre_v2_3.md).
Secciones §N son load-bearing (citadas desde código y CLAUDE.md): mover contenido = dejar stub-puntero con el MISMO número (patrón validado en Fase 4).
Editar SOLO con las tools Edit/Write (nunca PowerShell en bloque — bloqueado).
Verificar enlaces relativos tras cada movimiento.
Cuando doc y código discrepan, el código + docs/CANON.md ganan — la doc se corrige, nunca al revés (salvo bug evidente, que se reporta).
Git: git reset -q → add solo lo propio → git diff --cached --name-only sin foráneos → commit por bloque.

Fase 0 — Contexto mínimo (leer antes de tocar nada, ~30 min)

docs/README.md — el mapa del corpus y los estratos.
docs/authoring.md — las reglas de edición (anti-copia, stubs, atemporalidad). Esta fase existe porque esas reglas se violaron antes de existir.
CONTINUE-docs-corpus.md — qué se hizo ya y qué quedó diferido (NO rehacer: split THEMING parcial, decisions.md, renames diferidos).
Los inventarios de conflictos: fable_audit.md §3.5 (D1–D5) y fable-eidos-audit.md §3.11 + addendum (puntos 3–5). Cada ítem de la Fase 1 sale de ahí con evidencia.
docs/building-a-component.md — la puerta única ya creada; su tabla "Known traps" es el checklist de salida de esta fase.

Fase 1 — Reconciliación de conflictos verificados (~1 sesión, mecánico)

Por ítem: corregir → grep del string viejo = 0 → siguiente. Commit por bloques temáticos (1a morfo/soma · 1b GUIA · 1c THEMING · 1d checklist/tooling).

1a — translations: → texts: (el tipo Morfo solo tiene texts; 97 morfos lo usan, 0 usan translations):

src/uix/morfo/README.md — "What morfo contains", Step 4.5 completo, anatomía, pitfalls: todos los ejemplos con translations: deben compilar con texts: (valores = idlangrefs, no records multilingües — ver morfo/types.ts texts).
src/uix/soma/SOMA_ARCHITECTURE.md §7 "Texto funcional" — mismo cambio.
src/uix/soma/README.md §4 — lista de campos del morfo.

1b — GUIA_IMPLEMENTACION_SEMAUIX.md (declarada "autoritativa" en CLAUDE.md pero contradice al código en ≥5 puntos). Decisión recomendada: degradar, no reconciliar — añadir frontmatter + banner "historical seed; superseded by CANON.md + code; kept for the Spanish narrative" y corregir SOLO los 5 puntos peligrosos:

§4.1: Modal/Dialog = shift.enter-mode → el morfo real usa emerge (open/close); anotar que la tabla es orientativa y el morfo manda.
§6.2: tabla de holds ≠ SEMA_MAP/holds.ts → sustituir números por puntero a src/uix/sema/sema-map.ts + holds.ts (regla anti-copia).
§2: "8 tokens" sin tertiary + naming --color-{role}-element → puntero a THEMING §4 (9 roles) y slots reales.
§5.3: shape defaultSemantic → el implementado es allowedFamilies aditivo (LIBRO_VARIACIONES D.11).
§14 "Plan de migración" → ya ejecutado; marcar como histórico.
CLAUDE.md la cita como autoritativa 3+ veces — NO tocar CLAUDE.md en esta fase (archivo sensible, tiene su propio ítem diferido); dejar nota en el banner.

1c — THEMING.md + eidos (internos):

§1 "5 layers de CSS" vs §2 "Las 6 capas" → unificar (contar los imports reales de index.css y que ambos digan lo mismo).
§3 "13 slots" + §6 regla 7 (9 slots) vs generador (14: DEFAULT_COLOR_ROLE_SLOT_STEPS, render-css.ts:93) → UNA tabla con puntero al código como fuente; las otras dos menciones apuntan a ella.
§4 tabla "Mapping a escalas físicas": primary=indigo→purple, risk=amber→orange, añadir fila tertiary=indigo (RESERVED) — o mejor: sustituir la tabla por puntero a THEME_BASE_COLOR_ROLES (themes/base.ts:22) con nota de que CANONICAL_INTENT_SCALES (la convención) ≠ base theme (autoría).
eidos/README.md: retirar "Estado actual (2026-05-17)" (sección fechada, lista de wrappers congelada en ~20 vs 137 reales) → docs/process/; barrer citas a DEMO_AUTHORING_GUIDE "§12.8" (la v2 lo reemplazó por §6/§7).
eidos/components/README.md: retirar "Estado de la migración (2026-05-20)".
eidos-motion.md §15 (título "events.css ES el momento-evento") → revisar contra el events.css actual (las firmas migraron al config; el título es stale).

1d — soma docs + checklist↔tooling:

soma/README.md §3 + SOMA_ARCHITECTURE.md §6/§12: @floating-ui → motor propio (layers/floating + $ethereal; @floating-ui es devDep); clsx no es dep; tabla de layers añade popper/stacking/manipulation/zoom-pan/image/list-selection.
COMPONENT_COMPLETION_CHECKLIST.md ↔ scripts/component-audit.ts (drift bidireccional): las reglas declaradas SIN implementar (R-1.6, R-1.7, R-2.2, R-2.3, R-2.4, R-3.1, R-3.3 + D-1.4, D-3.2/3.3, D-4.1/4.2, D-5.x, D-6.x, D-7.1/7.2/7.3/7.5 + E-1.5/1.6/1.7, E-2.4, E-3.x) ganan una columna Enforcement: audit | manual | tool:X — o se implementan (R-2.3 espacios es la más valiosa). R-2.7 (implementada, no declarada) se añade a C2.
Numeración de la cascada sema: elegir 1 family · 2 intent · 3 morfo · 4 runtime · 5a packs · 5b app y unificar sema/README.md + header de engine.ts (comentario) + nota para CLAUDE.md (diferido).
active_architecture.md §6 + morfo/README.md: "24 archetypes" + lista copiada → puntero a ARCHETYPE_VOCABULARY (types.ts) sin conteo hardcoded.
JSDoc de soma/runtime.svelte.ts (TriggerOptions.semantic): quitar defaultSemantic fantasma; alinear "warns via logger" con el comportamiento real (el warn se implementó en la sesión 2026-07-01/02 — verificar).

Fase 2 — Referencia vs bitácora (~1 sesión)

Mismo patrón stub validado en Fase 4 del CONTINUE (renumber-safe):

THEMING.md §20–§38 → eidos/THEMING_CHANGELOG.md — las 19 secciones fechadas (correcciones de sprint, incidentes, commits) se mueven tal cual; en THEMING quedan stubs numerados de 2 líneas (título + puntero + la decisión vigente en una frase). Las citas §N de CLAUDE.md/RFCs/código sobreviven. Cuidado: §25 (modelo de color), §29–§31 (depth/shape/structure) y §32/§35 (focus/escalas) contienen CANON vivo mezclado con crónica — para esas, extraer la doctrina a las secciones de referencia (§4–§7) o al doc del canal y mover solo la crónica.
§13 (superseded, event:* scope) y §21 (RFC resuelto) → changelog, stub queda.
Resultado: THEMING.md ≤ ~900 líneas de referencia atemporal.

Fase 3 — Guard `docs:check` (~media sesión)

scripts/docs-check.ts + entrada npm. Invariantes (todas nacieron de un drift real):

Conteos de vocabulario: ningún doc afirma un número distinto de SEMA_FAMILIES.length (8), INTENTS.length (6), ARCHETYPE_VOCABULARY.length — regex sobre "N families/familias", "N archetypes", "N intents".
Campos fantasma: translations: prohibido en bloques de código de docs de morfo/soma; defaultSemantic prohibido fuera de LIBRO_VARIACIONES.
Deps citadas ⊆ package.json (dependencies): caza el @floating-ui/clsx stale.
Espejos: SHARED_VARIANT_VOCAB (component-audit.ts) == EIDOS_VARIANTS (lib/types.ts) — mejor como test unitario en vitest que como doc-check.
Checklist↔script: todo rule-ID del checklist ∈ {implementados en component-audit} ∪ {marcados manual/tool:X}, y viceversa.
Links relativos resuelven en docs/** + READMEs de capa.
Modo WARN primero; a error cuando la Fase 1 lo deje en verde.

Fase 4 — Diferidos heredados (decisión de usuario, NO hacer sin preguntar)

Siguen siendo suyos (ver CONTINUE §Diferido): adelgazar CLAUDE.md (hand-offs → process/), rename físico de RFCs, migración de idioma es→en de docs de capa, poda física de copias de vocabulario, commitear el libro. Esta fase solo los lista para que la sesión no los "descubra" y los haga por iniciativa propia.

Al cerrar

Actualizar CONTINUE-docs-corpus.md (HECHO/PENDIENTE) y este plan (checkboxes).
Vaciar/reducir la tabla "Known traps" de docs/building-a-component.md — es el indicador de éxito visible.
npm run docs:check + npm run check + los greps de verificación por ítem.

Resultado del cierre (2026-07-02)

Fase 1 completa (4 commits: 925508c7 translations→texts · 74b23b58 GUIA degradada · d3c25db6 THEMING/eidos · eeedd0f8 soma/checklist/cascada). Extras sobre el plan: el barrido translations: cubrió también COMPONENT_GUIDE + checklist + active-uix/README + 4 READMEs de componente + 3 JSDoc en código; la columna Enforcement se añadió a TODAS las tablas del checklist (no solo a las no implementadas) y los IDs M-* se renombraron A-* para grep-match con el script; se añadieron las reglas implementadas-no-declaradas (R-2.7, A-3.4b).
Fase 2 completa (d4e18e63): eidos/THEMING_CHANGELOG.md con §13 + §20–§38 verbatim; stubs numerados con la decisión vigente + puntero a la fuente viva (RFCs por canal / config / generador). THEMING 2603→~1500 líneas — por encima del estimado ≤900 porque lo restante es referencia legítima (§1.bis, §16, §19, modelo §1–§7); ninguna sección viva se movió.
Fase 3 completa (b08dece4): scripts/docs-check.ts + npm run docs:check con las 6 invariantes (I6 links en WARN). El espejo I4 se implementó por comparación textual dentro del guard (no vitest) — cero acoplamiento con el grafo de test.
Hallazgos fuera de alcance, reportados: clsx es dependencia fantasma (soma/props/props.ts la importa; solo llega como transitiva de svelte) — chip creado; el warn de TriggerOptions.semantic sobre eventos no-polimórficos NUNCA se implementó (el JSDoc mentía; corregido el JSDoc, el warn queda como candidato); soma/layers/popper/ es un directorio VACÍO huérfano; los warns I6 restantes son enlaces a THEMING_AUDIT_2026-06-01.md (borrado en worktree, cambio foráneo sin commitear), PENDIENTES.md (borrado en d68d2c45, normas N-6/N-7 huérfanas en eidos/README) y rutas de demos borradas citadas por MOTION_SERVICE_RFC.md (doc foráneo) — todos decisión de usuario.
Fase 4 sigue diferida (CLAUDE.md adelgazar · rename RFCs · es→en · poda de copias de vocabulario · commitear el libro).

12 KiB Raw Blame History Unescape Escape