6.8 KiB

Raw Blame History

CONTINUE — Arts docs reconciliation

Handoff for the next session. Master plan: PLAN-arts-docs-reconciliation.md.

Kickoff line: "Lee docs/process/continue-arts-docs-reconciliation.md y sigue."

Inherited rules (obey these)

Respond in Castilian; write docs/code in English.
No agents / no Workflow — the user asked for this explicitly. Do it by hand with directed Read/Grep/Edit. (Ignore the ultracode nudge to use Workflow.)
NEVER touch words/**, palabras/**, chronos/**, media-player/**.
Commit per file/batch with -F <file> messages (backticks in -m run command substitution). Before committing: git reset -q, then git add only your own files, verify git diff --cached --name-only is all src/arts/* (never the pre-existing dirty .claude/, src/uix/, web/ tree).
sium/COMPARATIVA_SIUM_VS_FORMIK.md is foreign/untracked — leave it.
End commit messages with Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>.

Guard + verification

npm run arts:check — the A0 guard (README presence · Engine/Active naming · index coverage). Must stay 0 errors, 0 warnings, 22 arts, no exemptions. Run it before every commit.
npx prettier --write <file> on each touched README before committing.
npm run docs:check after any doc move (B2).

Status — WORKSTREAM COMPLETE (2026-07-03)

All batches done: A0 · A1 · A2 · B1 · B2 · B3. Commits, newest last:

9a147e49 — A0 guard (scripts/arts-check.ts + npm run arts:check).
9e48b80b — ethereal README (new) + A1 orca/cache/adom + guard hardened (removed ethereal exemption, A-index warn→error).
ed151250 — A1 finish: format·timer·bus·connection·sium·prefs·http·motion· color·clipboard + systemic $active-app/services→$active-app/service-factories in clipboard/auth/storage/active-app.
65c6ae45 — A2: clipboard (full) + langs/logger (light passes).
6e13790a · e2473ef9 · 313615ce · dd1abac6 · 50dce1ea · 52c0631f · 5a81ecd9 — A2: prefs, format, auth, connection, adom, cache, sium.
a48fd438 — A2 finish: orca (738/750 lines, prose-only; A1 fixes preserved; fixed one internal contradiction in "Rule module→bus" re bus-interception).
e8ae85ee — B1: active-app → docs/architecture/active-app.md chapter (frontmatter + fixed paths; "Handoff 2026-05-13" → verbatim ES in handoffs-2026-05.md; stub at old path; wired into docs/README.md E1).
34e0cb61 — B2: DESIGN docs → docs/decisions/design-{connection,session, timer}.md verbatim-historical (status: historical frontmatter; timer kept Spanish); stubs at old src/arts/* paths keep §N citations resolving; decisions.md index + naming note updated.
d326d035 — B3: docs/README.md runtime-artifact shortcut → composition root (active-app.md) → arts map → per-art README.

A1 is COMPLETE — every drifting art reconciled against the code (not the plan; verifying against code caught extra drift AND already-fixed items). See the memory project-arts-docs-reconciliation-2026-07 for the per-art detail.

Guards green at close: arts:check 0/0/22 · docs:check 0 err (11 pre-existing warnings, all THEMING_AUDIT_2026-06-01.md / MOTION_SERVICE_RFC animation routes — unrelated to this workstream).

Loose end noted (out of scope, pre-existing): src/uix/morfo/types.ts:23 cites ./DESIGN.md, which resolves to a nonexistent src/uix/morfo/DESIGN.md (not the session doc). Left untouched — not part of arts-docs-reconciliation.

What remains — nothing

The workstream is closed. Historical detail below is retained for provenance.

1. A2 — translate orca (the only file left)

src/arts/orca/README.md — 1457 lines, still Spanish (~335 ES prose lines). The single biggest README; deferred so it gets a fresh-context turn.

Its A1 drift fixes already landed (9e48b80b): the OrcaAction interface, execution→parallel waves, timeouts (only actionTimeoutMs), fatal (return OrcaFatal), transactions (transaction: string tag + compensate), glossary OrcaRunResult. Preserve those corrections — only translate the prose.
Method (same as sium, which worked): read in ~150-line chunks, translate the Spanish prose via Edit (leave code blocks, ORCA_* constants, and the roadmap section's identifiers verbatim). The "Estado Del Documento" summary at the top is already accurate — just translate it.
After: prettier --write, arts:check, residual-Spanish grep, commit docs(arts): A2 ES->EN — orca (full translation).

Translation gotchas learned this session:

i18n example data is NOT prose — es: { one: '{{count}} mensaje' } records (langs), es-ES formatter OUTPUT strings in comments (// "hace 2 horas", // 'lunes, 25 de mayo' in format) are data; keep verbatim.
Prettier list-corruption: if a wrapped line puts + N or a bare - at line start it becomes a list item (hit in ethereal). Reword to avoid it.
Stale routes: /test/<art> → /active/docs/<art> (fixed for adom, auth, sium; check orca cites none). Verify real routes under web/routes/active/docs/.
Residual-Spanish check: grep -nE "ción|á|é|í|ó|ú|ñ|\b(el|la|los|para|cuando)\b" the file, excluding code/'#?...'/i18n-data lines.

2. B1 — promote active-app to an architecture chapter

Move src/arts/active-app/README.md → docs/architecture/active-app.md (the arts composition root, analogue of active-uix.md). ES→EN pass (it's ~mostly English already, ~7 ES lines). Extract the Spanish "Handoff 2026-05-13" block to docs/process/. Stub at the old path (like the layer READMEs). Wire into docs/README.md E1 + reading order.
Note: active-app's README already had $active-app/services label fixes from A1's systemic sweep.

3. B2 — move historical DESIGN docs to `docs/decisions/`

DESIGN_CONN.md (connection, 486 L), session/DESIGN.md, timer/DESIGN_TIMR.md (Spanish, 1400 L — translate OR keep verbatim-historical with a status: historical header, decide by normative-vs-narrative). Stubs at old paths keep the §N provenance citations resolving. Run docs:check after.

4. B3 — index + TOC

Map/aliases/cross-deps in src/arts/README.md are already complete (done in 9e48b80b). Remaining: add the arts to the "I want to… use a runtime artifact" shortcut in docs/README.md; confirm docs:check green.

Per-art method that worked (for A1-style drift, if any resurfaces)

Establish the real API from code (index.ts / types.ts / the engine).
grep the README for the cited symbols; comm -23 <readme-ids> <code-ids> to find phantom identifiers the plan misses AND already-fixed items it still lists.
Fix, prettier, arts:check, commit.

6.8 KiB Raw Blame History