|
|
# 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/` completos — canon/tsc + canon/recipe-contract; theming/reference (§1–§38, stub con mapa completo) + guide + notes + channels + motion (§1–§19, stub con mapa) + motion-guide + changelog (verbatim) — 9 docs, ~5.2k L | — | **HECHA 2026-07-02** |
|
|
|
| **F7.4** | `rfcs/` completo — 7 RFCs traducidos + rename `rfc-*` (stubs conservan las citas provenance; decisions.md realineado; MOTION_SERVICE_RFC NO — foráneo) — 1.5k L | — | **HECHA 2026-07-02** |
|
|
|
| **F7.5** | `guides/` completo — component-guide (banner es→en, resto verbatim) · completion-checklist (docs-check I5 + component-audit.ts movidos en la misma tanda) · demo-authoring · component-audit (§5 reconciliado a link-don't-copy) | — | **HECHA 2026-07-02** |
|
|
|
| **F7.6** | `decisions/` completo — book-deviations + guia-semantica-historica (verbatim castellano: bitácora del autor; exención I2 de docs-check movida con el doc); barrido final global + TOC-libro completo en README | — | **HECHA 2026-07-02** |
|
|
|
| **F7.7** | CLAUDE.md fino — 981→350 L: hand-offs → process/handoffs-claude-md.md, referencias → libro, CANON.md como autoridad, doctrina compactada a reglas+puntero (diff aprobado por el usuario) | — | **HECHA 2026-07-02** |
|
|
|
|
|
|
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
|
|
|
`<!-- TODO(reconcile): ... -->` y se anota en el CONTINUE, no se "arregla"
|
|
|
silenciosamente en la traducción.
|
