Closing pass of PLAN-docs-reconciliation:
- docs/building-a-component.md 'Known traps' table emptied — every trap
was fixed by phases 1a-1d/2 and docs:check guards the recurrence
classes (this was the phase's visible success indicator).
- PLAN checkboxes ticked + 'Resultado del cierre' appended (commits,
deviations from the plan, out-of-scope findings pending user decision).
- CONTINUE-docs-corpus.md Fase 6 marked HECHA.
- testing-and-tooling.md row reworded so the guard doesn't flag its own
description (the phantom-field literal).
Final state: npm run docs:check = 0 errors, 13 warns (all known foreign/
user-decision targets: THEMING_AUDIT deleted in worktree, PENDIENTES.md
deleted in d68d2c45, MOTION_SERVICE_RFC demo routes).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Phase 3 of PLAN-docs-reconciliation (fable_audit D5: the 'link, don't
copy' law had no mechanical guard). New scripts/docs-check.ts + npm run
docs:check with six invariants, each born from a verified drift:
- I1 vocabulary counts vs SEMA_FAMILIES/INTENTS/ARCHETYPE_VOCABULARY
(context-gated: font/shape families, variant archetypes and evaluative
subsets don't false-positive; section numbers and quoted historical
mentions skipped).
- I2 phantom fields: translations: in morfo/soma docs, defaultSemantic
outside LIBRO_VARIACIONES (rename/rejection mentions allowed).
- I3 dependency claims: soma dep lists must cite real package.json
dependencies; corpus-wide @floating-ui mentions need their devDep-only
context.
- I4 SHARED_VARIANT_VOCAB (component-audit) == EIDOS_VARIANTS (textual
mirror comparison).
- I5 checklist<->audit: every Enforcement:audit rule exists in the
script, every script rule ID is declared.
- I6 relative links resolve (WARN until the known dangling targets get
their user decision: THEMING_AUDIT deleted in worktree, PENDIENTES.md
deleted 2026-06-07, MOTION_SERVICE_RFC demo routes).
Chronicle docs (process/, changelogs, audits, CONTINUEs, status:
historical frontmatter, the book) are exempt from truth-tracking.
Also: THEMING s2 per-layer table realigned to the real entrypoint (the
fragile rule-count column dropped); stale adom link in SOMA_ARCHITECTURE
fixed; validator documented in docs/testing-and-tooling.md.
Current output: 1 error (building-a-component known-traps row — cleared
in the closing pass) + 13 warns.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The ~12 overlay recipes hardcoded an ad-hoc parallel z-index scale (raw integers
60–99/1200) that duplicated nothing reusable and had drifted out of order
(tooltip 76 < dropdown 80 — a tooltip painted BEHIND a dropdown). They are now a
named scale.
- `STATIC_Z_INDEX_OVERLAY` (static.ts) → emitted as `--z-index-overlay-{inline,
backdrop,content,floating,tooltip,detached,toast}`. A SEPARATE scale from the
global `--z-index-*` ladder (which orders the depth planes) — overlays portal
to <body> as siblings of modals, so they share one flat low band where each
rung sits just above the modal scrim. Mapping them to the 300–900 ladder would
hide a dropdown/select/popover opened INSIDE a dialog (dropdown 300 < modal
700); the combobox recipe already warned about this. `tooltip` now sits above
`floating` (fixes the inversion); `toast` stays above the soma FloatPanel band.
- Every overlay recipe token (`content-z`/`overlay-z`/`inline-z`/`toaster-z`/
`preview-z`) now references `var(--z-index-overlay-*)` — zero raw integers.
dialog/drawer gain an explicit `content-z` rung (drops the `calc(... + 1)`).
- Guard (contracts.test.ts, "overlay z-index against raw integers"): a recipe
`*-z` token must reference the scale, never a bare integer. Proven to catch
drift (a raw `'76'` makes it fail). Local `z-index: 0..5` (avatar/tabs/sticky)
is intra-component relative stacking — out of scope, stays.
- Docs: THEMING.md §35 rewritten to describe the consolidated scale + the
flat-band rationale + the guard; token table gains `--z-index-overlay-*`;
testing-and-tooling.md documents the catalogue guards (VG-8/SYS-1/A31/A30/
THEME-SYS-1).
Stacking order verified from the resolved CSS (deterministic z compare: content
70 < floating 80 < tooltip 90 < toast 1200; dropdown-in-dialog preserved). A
live browser check was blocked by a port conflict with another session's server.
check: 0 new type errors; the 5 guards green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per explicit instruction to remove deprecated/erroneous files (noise/confusion):
- DATA_ATTRS.md (repo root, 2158 lines) — a stale "Terra Data Attributes
Contracts" catalog, already self-headed DEPRECATED. The data-* contract is the
morfo, validated by morfo:check; this file only lied about it.
- scripts/generate-contracts-docs.ts — its generator, which imports the removed
src/uix/terra/utils/contracts.ts, so it can no longer run.
No doc links to either; nothing imports the script. The package.json
`generate:contracts-docs` entry now dangles at the deleted script — left
untouched because package.json carries unrelated concurrent edits I won't sweep;
flagged in the CONTINUE hand-off to remove later.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
testing-and-tooling.md listed `generate:contracts-docs` as live codegen "from
the morfos" — it is not. The script imports `src/uix/terra/utils/contracts.ts`
(the removed terra layer), so it no longer runs, and its output DATA_ATTRS.md is
a terra-era fossil. Corrected: the data-* contract is the morfo itself, validated
by morfo:check; the legacy script + DATA_ATTRS.md survive but are dead.
Also recorded the pending-.md census in the CONTINUE hand-off: DATA_ATTRS.md
(root, retire to process), the two dated audits (audit-opus / THEMING_AUDIT —
the latter cited in ~7 places), and what to leave (fix-stext.md is cited
provenance; MOTION_SERVICE_RFC / chronos are concurrent; words/palabras excluded).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Consolidates the cross-cutting verification story that was scattered across
package.json, COMPONENT_GUIDE and SOMA_ARCHITECTURE into one reference:
- The two-project vitest suite (browser client / node server) and how to run one.
- Each validator and the class of bug it catches: morfo:check (DOM vs contract),
morfo:vocabulary (verb drift), component:audit (acceptance), perm:check
(state transitions), smoke (hydration), translations:check, eidos-lint.
- Codegen vs authored: generate:eidos-css, generate:contracts-docs, and the
compileMorfo primitive.
- The SSR posture: dom:false -> disabledDom, ActiveDom owner-document resolution,
ornamental sema, and why smoke (not HTTP 200) is what catches hydration bugs.
All grounded in the real package.json scripts. Wired into docs/README.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dev