8.2 KiB
PLAN — Arts docs reconciliation (the active-app ecosystem)
Why this exists: the docs reconciliation (Phase 6 drift-fix + Phase 7 corpus-libro) covered the active-uix ecosystem (morfo · soma · sema · eidos → the
docs/architecture/*chapters). The active-app side — thearts/runtime artifacts thatActiveAppcomposes — was left as E5-in-place and never got the same pass. This plan does for arts what F6+F7 did for the UIX layers. Grounded in a 22-agent per-art audit (2026-07-03) — every drift below was verified against the code.
Kickoff for a new session: "Lee docs/process/PLAN-arts-docs-reconciliation.md y ejecuta la tanda que toque." Rules (inherited): respond in Castilian, docs in English; NEVER touch
words/palabras/chronos/media-player; commit per batch (-F filemessages — backticks in-mrun command substitution);git reset -q+ stage only your own files; each systemic fix ships a guard.
The ecosystem (22 arts)
src/arts/ = the runtime building blocks ActiveApp composes (the
active-app/README.md composition root is the analogue of active-uix). Naming
canon: Engine* (stateless, pure factory) / Active* (reactive $state,
.svelte.ts). The shared ActiveEngine<TSnapshot,TError> contract + the index
live in src/arts/README.md.
Audit findings (2026-07-03, evidence-based)
| Art | Lang | Drift | Extra docs | Disposition |
|---|---|---|---|---|
| active-app | mixed | 3 (missing defineEngineMotion in services table; 3/7 presets shown; incomplete FS layout) |
— | → architecture chapter (composition root; has a Spanish "Handoff 2026-05-13" to extract) |
| orca | spanish | 6 (phantom OrcaAction.priority/tokenTimeoutMs/onFatal/execution+ORCA_EXEC_*) |
— | book-chapter candidate (orchestration kernel; highest drift; ES→EN, high effort) |
| adom | spanish | 3 (missing prefersReducedMotion/writeProperty/removeProperty; listen() 4 overloads; 9 undoc rune helpers) |
docs page (ok) | E5-reconciled + ES→EN; stale /test/adom ref |
| bus | english | 4 (layer diagram says arts/bus but files in libs/bus; stale preset names post-refactor; COLLECT error mode undoc) |
— | E5-reconciled (agent said book-chapter) |
| cache | mixed | 4 (wrong createActiveApp({cache}) sig → services:{cache:defineActiveCache()}; undoc clearError/snapshot/onChange; demo URL placeholder) |
— | E5-reconciled (agent said book-chapter) |
| format | spanish | 4 (unts/→units/ typo; undoc currency.convertAs/formatAs, units.convertToDefault) |
currency/README.md (keep) |
E5-reconciled + ES→EN |
| timer | english | 4 (FS diagram 11→20 files; "50 tests"→47; reschedule behavior/errors drift vs DESIGN) |
DESIGN_TIMR.md (1400 L, Spanish, normative) |
E5-reconciled; DESIGN doc → decisions/ (translate) |
| color | english | 3 (JSDoc setCssVariables→applyColorScheme; "Phase 0 not consumed" stale; bare THEMING ref) |
— | E5-reconciled |
| connection | spanish | 2 (createEngineConnections() needs {timers}; 6 missing Active props) |
DESIGN_CONN.md (486 L, historical) |
E5-reconciled + ES→EN; DESIGN → decisions/; stale /active+conn-chat refs |
| sium | spanish | 3 (18 codes listed, 8 omitted; undoc cssLength/CSS_LENGTH_REGEX) |
COMPARATIVA_* (foreign/untracked), _examples/README |
E5-reconciled + ES→EN |
| prefs | spanish | 2 (wrong createPrefsStorageBridge/applyBrowserEnvironment param names) |
— | E5-reconciled + ES→EN |
| clipboard | spanish | 1 ($active-app/services→/service-factories) |
— | E5-reconciled + ES→EN (small) |
| motion | english | 2 (missing resolve/has/list/exit; JsDriver svelte unimplemented) |
— | E5-reconciled |
| http | english | 1 (DEFAULT_*→HTTP_DEFAULT_* names) |
— | E5-reconciled |
| ethereal | english | 0 | PERF.md only |
needs-readme (no README at all) |
| session | english | 0 | DESIGN.md (historical) |
E5 clean; DESIGN → decisions/ |
| perm | english | 0 | — | E5 clean; stale /test/perm ref |
| perf | english | 0 | — | E5 clean |
| auth | spanish | 0 | — | E5 clean + ES→EN only |
| langs | mixed | 0 | — | E5-reconciled (light EN pass) |
| logger | mixed | 0 | — | E5-reconciled (light EN pass) |
| storage | english | 0 | — | E5 clean |
Rollup: ~40 verified drift findings across 15 arts · 12 READMEs need ES→EN (8 spanish: adom, auth, clipboard, connection, format, orca, prefs, sium; 4 mixed: active-app, cache, langs, logger) · 1 missing README (ethereal) · 3 historical DESIGN docs (connection, session, timer) + 1 foreign COMPARATIVA (sium) · several dead route/demo cross-refs.
Batches (mirror F6 drift-fix → F7 structure)
| Batch | Content | Effort |
|---|---|---|
| A0 | Guard first: extend docs-check (or a new arts:check) — every src/arts/{name}/ has a README; the Engine*/Active* naming holds; (optional) an I-invariant that the arts index lists every art. Ship it so A1–A3 land against a net. |
low |
| A1 — drift sweep | Fix the ~40 doc↔code mismatches, art by art (verify each edit against the code symbol the audit cited). Priority by count: orca(6) · bus/cache/format/timer(4) · active-app/adom/color(3) · connection/prefs/sium(2) · clipboard/http/motion(1). Also the dead cross-refs (adom /test/adom, connection /active+conn-chat, perm /test/perm, cache demo URL). |
high |
| A2 — ES→EN | Translate the 8 Spanish + 4 mixed READMEs (faithful, mark stale with <!-- TODO(reconcile) -->, same rule as F6). Biggest: orca, adom, format, connection, prefs, sium. |
high |
| A3 — ethereal README | Author src/arts/ethereal/README.md (it only has PERF.md). Ethereal is the floating/positioning engine ($ethereal = the own floating-UI runtime). Follow the art README shape; link PERF.md as its correctness record. |
low |
| B1 — active-app chapter | Promote active-app to docs/architecture/active-app.md — the arts composition root, the missing analogue of active-uix.md. Extract the "Handoff 2026-05-13" Spanish block to docs/process/; ES→EN; stub at the old path (like the layer READMEs). Wire into docs/README.md E1 + the reading order. This is the "active-app was missing from the book" fix the user pointed at. |
medium |
| B2 — DESIGN docs | Move the historical design docs to docs/decisions/ like the eidos RFCs (they're already indexed in docs/decisions.md): DESIGN_CONN.md, session/DESIGN.md, timer/DESIGN_TIMR.md (Spanish, 1400 L — translate or move verbatim-as-historical per the F7 chronicle rule). Stubs at old paths keep the ~30 DESIGN_TIMR §12.8-style provenance citations resolving. sium/COMPARATIVA is foreign/untracked — leave unless staged. |
medium |
| B3 — index + TOC | Verify src/arts/README.md lists all 22 (add any missing); confirm docs/README.md E5 pointer + add the arts to the "I want to… use a runtime artifact" shortcut. docs:check green. |
low |
Open questions (need the user — like F7's AskUserQuestion)
- Arts structure: keep the 22 arts as E5-in-place-reconciled (recommended
— they're peripheral runtime services, same call F7 made) with only
active-app promoted to an architecture chapter? Or move all arts into a
new
docs/arts/book section? Recommendation: E5-reconciled + active-app chapter. - orca: the orchestration kernel is the second architecturally-heavy art
(highest drift, book-chapter verdict). Promote it to
docs/architecture/orca.mdtoo, or keep E5-reconciled? Recommendation: E5-reconciled for now; revisit if it grows a consumer-facing surface. - DESIGN docs: move to
docs/decisions/translated (F7 pattern), or keep in-place with stubs (they're historical, Spanish, cited by§N)? Recommendation: move to decisions/ asrfc-/design-siblings; translate the timer one or keep it verbatim-historical (chronicle rule).
Verification (per batch)
npm run check (compare to the drifting foreign baseline, not 59) · the art's
own tests where they exist (vitest src/arts/{name}) · npm run docs:check
after any doc move · arts:check (A0) green · browser only if an art has a live
docs page.