|
|
|
|
# CONTINUE — Arts docs reconciliation
|
|
|
|
|
|
|
|
|
|
Handoff for the next session. Master plan:
|
|
|
|
|
[`PLAN-arts-docs-reconciliation.md`](./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)
|
|
|
|
|
|
|
|
|
|
1. Establish the **real API** from code (`index.ts` / `types.ts` / the engine).
|
|
|
|
|
2. `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.
|
|
|
|
|
3. Fix, `prettier`, `arts:check`, commit.
|
