6.6 KiB

Raw Blame History

PLAN — Corpus-libro en `docs/` (fase 7 del workstream docs)

Kickoff para sesión nueva: "Lee docs/process/PLAN-docs-book.md y continúa la tanda que toque." Decisión de usuario (2026-07-02): el corpus deja de ser un mapa sobre docs dispersos — la referencia de capa SE MUEVE a docs/ con orden de libro, en inglés. Los 189 READMEs de componente quedan FUERA (E5 in-place, enlazados). Sustituye la decisión "estructura híbrida" del kickoff original (CONTINUE-docs-corpus §Decisiones acordadas).

Objetivo

Un corpus único, estructurado y sin ambigüedad bajo docs/: base directa del libro y de la futura web de docs. Junto al código quedan stubs finos (puntero + mini-resumen) para que ninguna cita por ruta se rompa y el que navega el código encuentre la puerta.

Reglas de trabajo (heredadas + nuevas)

PROHIBIDO lanzar agentes/workflows. Responder en castellano; docs nuevos en inglés.
NUNCA tocar words/, palabras/, chronos/, el libro (docs/Disenando_lo_que_ocurre_v2_3.md), ni eidos/MOTION_SERVICE_RFC.md + chronos/SPEC-* (foráneos/concurrentes — NO se mueven).
Editar con Edit/Write (PowerShell solo WriteAllLines para reescrituras).
Git: git reset -q → add solo lo propio → commit por tanda.
npm run docs:check verde (0 errores) al cierre de CADA tanda.
Patrón de migración por doc (validado por el piloto F7.1):
1. Traducir a inglés adaptando (reglas de docs/authoring.md: frontmatter, timeless, link-don't-copy) — misma sustancia, no reescritura creativa.
2. Write en la ruta nueva del árbol objetivo.
3. La ruta vieja queda como stub (status: moved, puntero + 2-4 líneas de orientación; si el doc era citado por §N desde código, el stub lleva el mapa §N→sección nueva).
4. Barrer los links del corpus que apuntaban a la ruta vieja → ruta nueva (el stub garantiza que los no barridos sigan resolviendo).
5. docs:check + commit.

Árbol objetivo

docs/
  README.md                    ← entrada: pasa de mapa a TOC del libro (se
                                 actualiza en cada tanda)
  getting-started.md · glossary.md · authoring.md · comparison.md
  testing-and-tooling.md · building-a-component.md · CANON.md · decisions.md
                               ← ya viven aquí; se quedan
  architecture/
    overview.md                ← src/uix/README.md (la tesis)
    active-architecture.md     ← src/uix/active_architecture.md
    morfo.md                   ← src/uix/morfo/README.md
    soma.md                    ← src/uix/soma/README.md
    soma-architecture.md       ← src/uix/soma/SOMA_ARCHITECTURE.md
    sema.md                    ← src/uix/sema/README.md
    eidos.md                   ← src/uix/eidos/README.md
    active-uix.md              ← src/uix/active-uix/README.md   (piloto F7.1)
  canon/
    tsc.md                     ← src/uix/eidos/TSC.md
    recipe-contract.md         ← src/uix/eidos/RECIPE_CONTRACT.md
  theming/
    reference.md               ← src/uix/eidos/THEMING.md
    guide.md                   ← THEMING_GUIDE.md · notes.md ← THEMING_NOTES.md
    changelog.md               ← THEMING_CHANGELOG.md
    motion.md                  ← eidos-motion.md · motion-guide.md ← MOTION_GUIDE.md
    channels.md                ← CHANNELS_SYNTHESIS.md
  rfcs/
    rfc-color-model.md         ← COLOR_MODEL_RFC.md      (el rename legacy→
    rfc-color-engine.md        ← COLOR_ENGINE_RFC.md      rfc-* por fin es
    rfc-depth.md · rfc-shape.md · rfc-structure.md        seguro: el stub en
    rfc-scaling.md · rfc-typography.md                    la ruta vieja conserva
                                                          las ~30 citas provenance)
  guides/
    component-guide.md         ← src/uix/soma/COMPONENT_GUIDE.md
    completion-checklist.md    ← src/uix/COMPONENT_COMPLETION_CHECKLIST.md
                                 (actualizar la ruta en scripts/docs-check.ts I5)
    demo-authoring.md          ← web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md
    component-audit.md         ← web/routes/uix/lib/COMPONENT_AUDIT_GUIDE.md
  decisions/
    book-deviations.md         ← src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md
    guia-semantica-historica.md← src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md
                                 (histórica; se mueve tal cual, en castellano —
                                 es semilla, no referencia)
  process/                     ← queda (efímero)

Fuera del libro (E5 in-place, enlazados desde el TOC): READMEs de componente (189), src/arts/*/README.md (29), docs de libs/svrs, eidos/components/README.md (patrón — candidato a guides/ en F7.5, decidir), audits/fósiles ya gestionados.

Tandas

Tanda	Contenido	Volumen	Estado
F7.1	Plan + esqueleto + piloto `active-uix.md` (valida el patrón)	~100 L	HECHA 2026-07-02
F7.2	`architecture/` completo — overview · active-architecture · morfo · soma · soma-architecture · sema · eidos (7 capítulos, ~5.4k L movidas/traducidas; stubs con mapa §N en las rutas viejas)	—	HECHA 2026-07-02
F7.3	`theming/` + `canon/` — THEMING familia, TSC, RECIPE_CONTRACT, motion	~3.1k L	pendiente
F7.4	`rfcs/` — 7 RFCs (rename incluido; MOTION_SERVICE_RFC NO — foráneo)	~3-4k L	pendiente
F7.5	`guides/` — COMPONENT_GUIDE, checklist (tocar docs-check I5), demo guides	~2.2k L	pendiente
F7.6	`decisions/` — LIBRO_VARIACIONES, GUIA histórica; barrido final de links + TOC completo en README	~1.5k L	pendiente
F7.7	CLAUDE.md fino — hand-offs → process/, referencias → rutas del libro (archivo sensible: presentar diff antes de commitear)	—	pendiente

Notas por tanda:

La traducción es→en va incluida en cada movimiento (F7.2 es la cara: THEMING ya quedó saneada en la fase 6; SOMA_ARCHITECTURE/sema/eidos READMEs son el grueso).
Tras cada tanda, actualizar docs/README.md (el TOC) — es el índice del libro.
docs:check ya vigila links y campos fantasma; considerar añadir invariante "stub no crece" si aparece drift stub↔destino.

Riesgos conocidos

Citas §N desde código (THEMING §5/§25/§35, TSC, DESIGN_*): el stub lleva mapa §N cuando el doc migre. Las citas por ruta sobreviven por el stub.
scripts/docs-check.ts (I5) y cualquier tooling que lea rutas de docs se actualizan EN LA MISMA tanda que mueve su doc.
Traducir ≠ reescribir: sustancia idéntica; lo que huela a stale se marca con  y se anota en el CONTINUE, no se "arregla" silenciosamente en la traducción.

6.6 KiB Raw Blame History

PLAN — Corpus-libro en docs/ (fase 7 del workstream docs)