svelte-kit-vice/docs/process/PLAN-docs-reconciliation.md

# 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`](./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:

1. Los ~14 conflictos de la Fase 1 corregidos (grep del string viejo = 0 hits).
2. THEMING.md es referencia atemporal (≤ ~900 líneas); lo fechado vive en un changelog.
3. `npm run docs:check` existe y pasa (guard de invariantes copiables).
4. `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)

1. [`docs/README.md`](../README.md) — el mapa del corpus y los estratos.
2. [`docs/authoring.md`](../authoring.md) — las reglas de edición (anti-copia, stubs,
   atemporalidad). **Esta fase existe porque esas reglas se violaron antes de existir.**
3. [`CONTINUE-docs-corpus.md`](./CONTINUE-docs-corpus.md) — qué se hizo ya y qué quedó
   diferido (NO rehacer: split THEMING parcial, decisions.md, renames diferidos).
4. Los inventarios de conflictos: [`fable_audit.md`](../old-deprecated/fable_audit.md) §3.5
   (D1–D5) y [`fable-eidos-audit.md`](../old-deprecated/fable-eidos-audit.md) §3.11 + addendum
   (puntos 3–5). Cada ítem de la Fase 1 sale de ahí con evidencia.
5. [`docs/building-a-component.md`](../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`):
- [x] `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`).
- [x] `src/uix/soma/SOMA_ARCHITECTURE.md` §7 "Texto funcional" — mismo cambio.
- [x] `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:
- [x] §4.1: Modal/Dialog = `shift.enter-mode` → el morfo real usa `emerge`
      (open/close); anotar que la tabla es orientativa y el morfo manda.
- [x] §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).
- [x] §2: "8 tokens" sin `tertiary` + naming `--color-{role}-element` → puntero a
      THEMING §4 (9 roles) y slots reales.
- [x] §5.3: shape `defaultSemantic` → el implementado es `allowedFamilies` aditivo
      (LIBRO_VARIACIONES D.11).
- [x] §14 "Plan de migración" → ya ejecutado; marcar como histórico.
- [x] 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):
- [x] §1 "5 layers de CSS" vs §2 "Las 6 capas" → unificar (contar los imports reales
      de `index.css` y que ambos digan lo mismo).
- [x] §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.
- [x] §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).
- [x] `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).
- [x] `eidos/components/README.md`: retirar "Estado de la migración (2026-05-20)".
- [x] `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**:
- [x] `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.
- [x] `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.
- [x] 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).
- [x] `active_architecture.md` §6 + `morfo/README.md`: "24 archetypes" + lista
      copiada → puntero a `ARCHETYPE_VOCABULARY` (types.ts) sin conteo hardcoded.
- [x] 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):

- [x] **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.
- [x] §13 (superseded, event:* scope) y §21 (RFC resuelto) → changelog, stub queda.
- [x] 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):

1. **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".
2. **Campos fantasma**: `translations:` prohibido en bloques de código de docs de
   morfo/soma; `defaultSemantic` prohibido fuera de LIBRO_VARIACIONES.
3. **Deps citadas ⊆ package.json** (dependencies): caza el @floating-ui/clsx stale.
4. **Espejos**: `SHARED_VARIANT_VOCAB` (component-audit.ts) == `EIDOS_VARIANTS`
   (lib/types.ts) — mejor como test unitario en vitest que como doc-check.
5. **Checklist↔script**: todo rule-ID del checklist ∈ {implementados en
   component-audit} ∪ {marcados `manual`/`tool:X`}, y viceversa.
6. **Links relativos resuelven** en `docs/**` + READMEs de capa.
7. 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).