docs(docs): V1-2.6 UX U0, contract amendments, O22 checks, level-1 notes

This commit is contained in:
bchanot committed 2026-11-06 11:06:10 +01:00
1 parent a505b24bfd
commit d9e3e34aff
11 files changed
+604 -141

No files matched your search

+69 -41
View File
@@ -1,9 +1,11 @@
# V1-2.6 UX redesign: technical implementation plan
Status: PROPOSAL for the owner, 2026-11-05, revised the same day with the owner's answers to T2/T3, T4, T5, T9/T10,
T11, T12 and T16 (brief « V1-2.6 UX — Ratification des décisions techniques », recorded in
`V1-2-6_UX_DECISIONS.md`). Nothing in this file authorises code. No application, Rust, SQL or worker change is made
before the owner authorises U0 and then each sub-step explicitly. Branch `feature/v1-2-anatomical-sheets`, worktree
T11, T12 and T16 (brief « V1-2.6 UX — Ratification des décisions techniques », BDR-100), then with the brief
« V1-2.6 UX — Autorisation U0 uniquement » (BDR-101: T4 SQL checks, T5 defaults, T10 option B, T15, T16 count,
« Remplacer par un polygone »), recorded in `V1-2-6_UX_DECISIONS.md` and contract §17.12. Nothing in this file
authorises code. U0 (documents only) was authorised on 2026-11-05; no application, Rust, SQL or worker change is
made before the owner authorises each later sub-step explicitly. Branch `feature/v1-2-anatomical-sheets`, worktree
`/home/bchanot/Documents/faunosteo-v1-2`, audited at `f58cf23`.
Companion files:
@@ -118,7 +120,7 @@ study). Facts that govern it:
- Doctrine conflict, settled by the owner under T2 (route A, ratified with conditions): `.claude/rules/schemas.md:9-11` says additive optional fields keep the
contract; `.claude/rules/sheet-model.md` says a document schema change bumps `SHEET_DOCUMENT_SCHEMA_VERSION`, with
no bump during V1-2 (BLK-008); BDR-068 says `v1` freezes the construction and the validation. Route B (schema v3)
is excluded by the contract during V1-2 (`docs/development/V1-2_ANATOMICAL_SHEETS.md:1779-1781`) and would need a
is excluded by the contract during V1-2 (`docs/development/V1-2_ANATOMICAL_SHEETS.md` §12.3, BLK-008 paragraph) and would need a
data migration (BLK-008) plus a change to `save_sheet_draft`, which never updates `document_schema_version`
(`supabase/migrations/20261028110000_sheet_review_workflow.sql:621-623` against the CHECK of
`20261008110000_anatomical_sheets.sql:120-121`).
@@ -170,8 +172,8 @@ Node `gzipSync(bytes, { level: 9 })` on the `pkg` build, re-measured on 2026-11-
never run). The sandbox reuses `faunosteo_worker:dev` without checking it matches the checkout
(`scripts/db-sandbox.sh:335-347`): every model step rebuilds it explicitly.
- The only SQL the redesign needs is the U6 migration (decision T4): the round withdrawal the contract requires
when the integrity rules change (`V1-2_ANATOMICAL_SHEETS.md:945-949`), the core gate, the rules epoch, the
declared publication check and, if confirmed, the save non-regression check. The curves lot will need its own
when the integrity rules change (contract §6.4, worded at U0: rounds of draft versions), the core gate, the
rules epoch, the declared publication check and the declared save check (both approved, contract §12.2). The curves lot will need its own
withdrawal (path reader). References are in the document; own drawings use the existing upload path, capped at
4 drawings per sheet, 2 MiB each, 6 MiB in all (`core/domain/archive/snapshot.rs:21-28`).
@@ -203,7 +205,7 @@ Node `gzipSync(bytes, { level: 9 })` on the `pkg` build, re-measured on 2026-11-
### A. Non-destructive migration for fixed categories and opacity
- Route A, ratified in principle with conditions (T2, T3): `role` (`bone` | `joint` | `vertebra`) and
- Route A, ratified in principle with conditions (T2, T3): `role` (`bone` | `joint` | `vertebra` | `navigation`, the last under T10 option B) and
`fill_opacity` (integer percent 10 to 100) on `AnnotationCategory`, both `Option` + `#[serde(default)]` +
`js::present` (an explicit `null` refused, one canonical form) + `skip_serializing_if = "Option::is_none"` +
`ts(optional)`, the `LocalizedOptionalText` pattern; never serialised as `null`; an absent key never defaulted in
@@ -214,21 +216,23 @@ Node `gzipSync(bytes, { level: 9 })` on the `pkg` build, re-measured on 2026-11-
review digest, R4 app-path digests, `V1-2-6_UX_TESTS.md` U6); a document carrying a key cannot be read by any
earlier application, worker or core, so the first such write is a point of no return (COMPATIBILITY §0, §7).
- New sheets: `sheet.empty` creates the three fixed categories with roles, core-chosen ids (precedent `view-main`,
`core/domain/sheet/create.rs:9`, `28`), fixed names and default colours (T5; ids, EN names and colours still to
ratify).
`core/domain/sheet/create.rs:9`, `28`), fixed names and default colours (T5, ratified: `cat-bone`, `cat-joint`,
`cat-vertebra`, values and sources in DECISIONS T5).
- Fixed-category checks, no residual gap (T4), never as a `validate.rs` error (that would strip fingerprints and
reject old snapshots):
- core, verdict tier: `sheet_report` on the draft gives error issues for a missing role, a duplicate role or a
wrong name on a role-bearing category, with no base needed, so a first version is judged like any other; they
map to the existing `verification.validation.rules` (`verdict.rs:277-296`), no new verdict code;
- core, editor tier: `edit.rs` refuses removing a role-bearing category, changing or clearing its role, a duplicate
role, a rename away from the fixed names and any `navigation` assignment; giving a role writes the fixed names
role, a rename away from the fixed names and any edit giving, changing or clearing `navigation` (`cat-access`
enters only in the core-built access batch, T10); giving a role writes the fixed names
in the same update; repair commands insert a missing fixed category, restore the fixed names and clear a
duplicate role (DECISIONS T4);
- server: the U6 migration withdraws the rounds of draft versions in flight, adds a core gate at
`complete_sheet_verification` that refuses a passed verdict from a pre-U6 core, and adds a declared SQL check
of the fixed model at approval and publication (O22 amended at U0); recommended, to confirm: a non-regression
check at `save_sheet_draft` (no role removed, duplicated or renamed away; role-less drafts still save).
of the fixed model at approval and publication and a declared check at `save_sheet_draft` (a role carried
twice, renamed away or lost refused; role-less drafts still save); both approved, O22 amended at U0 (contract
§12.2), not built.
- Functional write lock instead of an expand-then-write split: the U6 migration exposes a rules epoch and the
application writes no key and creates no new-model sheet before it reads it; SQL first is mandatory, the only
order that fails closed (COMPATIBILITY §7). U6 runs on the sandbox only until the owner decides otherwise.
@@ -270,12 +274,13 @@ Validated guarantee already held: a curve is never converted or simplified. Path
editor never reshapes them (level-1 C45) and offers « Remplacer par un polygone ». No document of the project holds
a path (the seed has 22 circles, 6 polygons, 0 paths), and no product path can create one: creation makes points
and polygons only (`creation.ts:93-97`), package import and zones from the drawing's shapes stay deferred
(`V1-2_ANATOMICAL_SHEETS.md:1330-1338`). Board 05 labels its curve card « exemple d'une autre fiche ».
(`V1-2_ANATOMICAL_SHEETS.md` §8.3). Board 05 labels its curve card « exemple d'une autre fiche ».
Handle editing of curves (anchors, controls, translation) is deferred out of V1-2.6 to the curves lot (ex-U9,
decision T16). The owner made the deferral conditional on an audit: it confirms that no tracked document holds a
path and no product journey needs one changed; the database contents of DEV and the sandbox were not queried, so a
read-only count runs before U6 or U8 reaches any environment beyond the throwaway sandbox (DECISIONS T16). Until the curves lot, a stored path keeps its
read-only count runs before the new model is activated on an environment and before U6 or U8 reaches any
environment beyond the throwaway sandbox (DECISIONS T16). Until the curves lot, a stored path keeps its
`d` text byte for byte, no operation converts it, and every operation that would change it is refused with the
document unchanged; « Remplacer par un polygone » (contract §8.3) stays the one, explicit, undoable way a path
leaves a document. The curves lot precedes any feature that lets a path enter a document. Its specification is kept
@@ -339,11 +344,11 @@ so it can start without a new study:
- Name proposal (page, display formatting from the core's list): FR and EN names of the `inside` annotations, in
document order, joined by the locale's list format, the first three then « … »; none inside → « Vue détaillée n »
/ « Detail view n », n = number of detail views + 1. Both fields stay editable.
- Access category (T10, principle ratified): a navigation access is never put in Os, Articulations or Vertèbres by
- Access category (T10, option B ratified): a navigation access is never put in Os, Articulations or Vertèbres by
the system. The navigation type exists (`detail_trigger`, `schema.rs:439-462`) but requires an existing category
(`schema.rs:449`, `validate.rs:287-292`), and snapshots carry triggers to N-1 (`snapshot_rules.rs:141-165`).
Recommended, pending the owner's confirmation: one internal category `cat-access`, role `navigation`, created by
the core, absent from every visible panel and picker (DECISIONS T10 option B).
Ratified (option B, brief U0, BDR-101): one internal category `cat-access`, role `navigation`, created by the
core inside the automatic-access batch, absent from every visible panel and picker (DECISIONS T10).
- Access: automatic creation needs that role, so it lands in U6, not U5. Then the view, its access (the drawn
rectangle as its polygon in the parent view) and, if missing, the navigation category are inserted in one batch,
only when the overlap list is empty. Otherwise the box is unchecked with the reason stated, and the access is
@@ -357,8 +362,8 @@ so it can start without a new study:
- Page operations, each one `sheet.edit update` of the whole annotation: vertex drag (preview on move, commit on
pointer-up), « + » inserts the segment midpoint after the segment's start vertex, « − » removes the chosen vertex,
zone drag translates every point, redraw replaces the points after the new trace is accepted.
- Protections before the core: « − » not offered at 3 vertices; no non-finite value committed; a vertex released on
its neighbour is a no-op; above a handle cap (implementation constant, recorded at U0) the shape shows its outline
- Protections before the core: « − » disabled at 3 vertices with « Une zone garde au moins 3 sommets » (board 12 B); no non-finite value committed; a vertex released on
its neighbour is a no-op; above a handle cap (T18: rule recorded at U0, contract §17.12; value fixed at U2 from the equine maximum, 17 vertices, with a margin) the shape shows its outline
and a message instead of one handle per vertex. The core judges the end state on commit (`invalid_shape` below 3
points; `out_of_frame`, `too_small`, `interior_too_small` through `issues.ts:123-175`). A refusal restores the
previous shape.
@@ -390,10 +395,9 @@ seed untouched, axe, keyboard and touch journeys, sandbox and worker runs.
### I. Decisions that block before any code
Each sub-step lists the decisions it consumes; the single table is in `V1-2-6_UX_DECISIONS.md` and the blocking
criteria in `V1-2-6_UX_RISKS.md`. Answered 2026-11-05: T2/T3 (with conditions), T4, T5 (history), T9, T10
(principle), T11, T12 (principle), T16. Still open: before U1, T15; before U5, T1 only if a measure exceeds the
budget; before U6, the two T4 SQL checks, the T5 new-sheet defaults, T10 option B, T17; before U7, the T12 text;
at V1-2.8, T6.
criteria in `V1-2-6_UX_RISKS.md`. Answered 2026-11-05: T2/T3 (with conditions), T4 (with both SQL checks), T5
(history and new-sheet defaults), T9, T10 (option B), T11, T12 (principle), T15, T16. Still open: before U5 or U6,
T1 only if a measure exceeds the budget; before U6, T17; before U7, the T12 text; at V1-2.8, T6; T14 a follow-up.
---
@@ -425,17 +429,23 @@ Common rules for every sub-step that touches code:
### U0 · Contract, decisions and amendments (docs only)
- State: authorised 2026-11-05 (brief « Autorisation U0 uniquement »), contract
`.claude/tasks/contracts/2026-11-05-v1-2-6-ux-u0.md`.
- Objective: record the owner's answers to `V1-2-6_UX_DECISIONS.md` and amend the ratified texts the validated UX
replaces.
- Files: `docs/development/V1-2_ANATOMICAL_SHEETS.md` §7.4 (common text), §8.2 (no coordinate fields, fixed
- Files: `docs/development/V1-2_ANATOMICAL_SHEETS.md` §6.2 (save check, local copy key), §6.4 (withdrawal of draft
rounds), §6.7 (fixed-category row), §7.4 (new-sheet categories, common text), §8.2 (no coordinate fields, fixed
categories, colour shown when set, access created with the view), §8.3 (vertex drag and the crop rectangle leave
level 2; curves per T16), §8.4 (O14 A kept, tablet rule), §16.7 (new state); the level-1 contract
`.claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md` (C3, C4, C6, C7, C8, C13 wording to match the code key,
C32, C33, C40); `docs/design/README.md` (v1-2-6 boards replace V1-2.4 boards 04 and 05 for the editor, BDR-096);
level 2; curves per T16), §8.4 (O14 A kept, tablet rule), §12.2 and the §17.1 row (O22 amended for the two SQL
checks), §16.7 (new state), §16.12 (deferred lots), §17.12 (the decisions); the level-1 contract
`.claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md` (C3, C4, C5, C6, C7, C8, C11 per T15, C13 wording to match
the code key, C16, C18, C20, C25, C28, C32, C33, C40, and a precedence rule in its header); `docs/design/README.md` (v1-2-6
boards replace V1-2.4 boards 04 and 05 for editing, board 05's read-only mode kept, BDR-096);
`.claude/rules/sheet-model.md` (optional keys under T2; rules may also live in `edit.rs` and `sheet_report`) and
`schemas.md`; the implementer decisions (T7, T8, handle cap, branch policy); `.claude/memory/decisions.md` via
`memory.sh`. §7.4 records T12 without any normative wording; §8.3 records the curves lot (T16).
- Dependencies: owner answers (recorded 2026-11-05, BDR-100) and the owner's authorisation to start U0.
- Dependencies: owner answers (recorded 2026-11-05, BDR-100, BDR-101) and the owner's authorisation to start U0
(given 2026-11-05).
- Rust ops: none. Tests: a fresh verifier checks the amendments against the answers.
- Acceptance: each decision recorded once and cited where it applies; no contradiction left between the contract,
the level-1 criteria and the boards.
@@ -454,7 +464,8 @@ Common rules for every sub-step that touches code:
`ToolColumn.tsx`, i18n; `scripts/db-sandbox.sh` (image check, demo sheet), `crates/worker/Dockerfile` (commit
label).
- Dependencies: U0, T11 (ratified: level-1 trial stopped, level 1 not declared validated, residuals tracked), T15
(header undo accessible name).
(ratified: header undo named « Annuler la dernière modification », C11 relabelled « Abandonner les
modifications »).
- Rust ops: none.
- Tests: `V1-2-6_UX_TESTS.md` U1.
- Acceptance: four tabs at 1 024 px and wider; every existing editor journey green on the new shell; narrow-width
@@ -538,7 +549,7 @@ Common rules for every sub-step that touches code:
- Acceptance: board 08 with explicit placement; the replacement dialog on every replacement, « Conserver les
positions », « Repositionner les annotations » and « Annuler » each proven on fixtures, a different aspect ratio
refused, « Annuler » sending no request; one undo entry per remap; size within budget or T1 applied.
- Owner demo: board 08 on the demo sheet; attach the seed head drawing to a crop (keep offered); attach a re-based
- Owner demo: board 08 on the demo sheet; attach the seed head drawing to a crop whose rectangle equals its `viewBox` `60 100 500 380` (keep offered); attach a re-based
fixture drawing (reposition offered); cancel a replacement.
- Risk: size; bounds over-report. Rollback: revert (documents written are plain v2).
- Checkpoint: owner.
@@ -547,11 +558,12 @@ Common rules for every sub-step that touches code:
- Objective: route A (§2 A) under the owner's conditions (T2, T3); `sheet.empty` creates the three categories; the
T4 checks (absolute verdict rule, edit refusals with the repair path, the U6 migration with round withdrawal,
core gate, publication check, rules epoch and the save check if confirmed) live before any key is written (write
core gate, publication check, rules epoch and the save check) live before any key is written (write
lock); the layer applies `fill_opacity`; snapshot and export
gate strip both keys; the snapshot reader widened only as bounded in §2 C; the panel locks the fixed categories
(no delete, name read-only, role badge, « Couleur d'origine » from T5) and gains the opacity slider and field;
automatic access with the navigation category if T10 option B is confirmed; board 09: regions open from the
automatic access with the navigation category `cat-access` (T10 option B, ratified), built on the U5 overlap
list and created only when it is empty; board 09: regions open from the
vertebra-role category, the region picker of a zone filtered to the vertebra-role category's annotations (page
filter, no rule), staged « Appliquer » with the error count; fallback per T17 when no category has the role (the
equine copy before V1-2.8). `docs/ANNOTATION-RENDERING.md` amended first.
@@ -560,10 +572,11 @@ Common rules for every sub-step that touches code:
`domain/archive/snapshot_rules.rs:141-165`, `pdf/write/input.rs:174-181`, `export.rs:27-37`, types; app
`refusal.ts`, the category panel, the repair action, the regions dialog (`components/editor/vertebrae/*`),
`DetailViewForm.tsx` (automatic access), i18n; SQL `supabase/migrations/<timestamp>_sheet_rounds_withdraw_v1_2_6.sql`
(name provisional: round withdrawal, core gate, rules epoch, publication check, save check if confirmed); docs `ANNOTATION-RENDERING.md`, `ANATOMICAL_SHEET_MODEL.md`
(name provisional: round withdrawal, core gate, rules epoch, publication check, save check); docs `ANNOTATION-RENDERING.md`, `ANATOMICAL_SHEET_MODEL.md`
(spec table), `RUST.md`, `DEPLOY.md` (order, write lock).
- Dependencies: U3, U5; T2 and T3 (ratified with conditions), T4 (ratified; the save and publication SQL checks to confirm), T5 (history
ratified; new-sheet defaults to ratify), T10 option B (to confirm, automatic access only), T17.
- Dependencies: U3, U5 (U5 brings `annotations_in_rect`, the overlap list the automatic access needs, after U4's
rectangle); T2 and T3 (ratified with conditions), T4 (ratified with both SQL checks), T5 (ratified), T10 option B
(ratified), T17 (open: blocks U6).
- Rust ops: schema fields, edit refusal kinds, verdict-tier issues, layer reading, snapshot stripping, verdict
marker.
- Tests: `V1-2-6_UX_TESTS.md` U6; each row of `V1-2-6_UX_COMPATIBILITY.md` is an acceptance line, and §8 lists the
@@ -573,7 +586,7 @@ Common rules for every sub-step that touches code:
passes); the contract §16.7 journey on a non-equine sheet with the new UX reaches `open` after the worker verdict;
a role-stripped draft never reaches a round.
- Owner demo: new species sheet with its three categories, custom opacity, regions from Vertèbres, automatic access,
PDF exported and reopened; a role-stripped direct save refused at save (if confirmed) or at verification.
PDF exported and reopened; a role-stripped direct save refused at save.
- Deploy order, write lock and rollback: `V1-2-6_UX_COMPATIBILITY.md` §7. Returning to the old application is
impossible once a document with the keys exists (point of no return; sandbox only until the owner decides
otherwise).
@@ -590,7 +603,7 @@ Common rules for every sub-step that touches code:
change note records the template id and version.
- Rust ops: none (one `update` of the sheet texts).
- Tests: `V1-2-6_UX_TESTS.md` U7.
- Acceptance: board 10; contract §7.4 as amended at U0.
- Acceptance: board 10; contract §7.4 as amended at U0 (no normative wording until the owner's text exists).
- Owner demo: insert, edit, compare. Rollback: revert.
- Checkpoint: owner and the person responsible for the wording.
@@ -598,7 +611,8 @@ Common rules for every sub-step that touches code:
- Objective: recovery and conflict journeys re-run on the new UX; the contract §16.7 acceptance on the sandbox;
the level-1 residuals tracked under T11 re-checked one by one (level 1 still not declared validated as a whole);
the T16 path count recorded for any environment beyond the sandbox; documents and TODO closed;
the T16 path count recorded before the new model is activated on an environment and before U6 or U8 reaches
any environment beyond the sandbox; documents and TODO closed;
`V1-2-6_OWNER_TRIAL.md` updated.
- Dependencies: U1 to U6 (U7 when its text exists; curves in their own lot, T16).
- Tests: `V1-2-6_UX_TESTS.md` U8.
@@ -633,7 +647,7 @@ Common rules for every sub-step that touches code:
| U2 | yes | one read-only value | no | no | no |
| U3, U4 | yes | no | no | no | no |
| U5 | yes | two queries | no | no | no (the worker calls neither) |
| U6 | yes | yes | optional keys | round withdrawal, core gate, rules epoch, publication check, save check if confirmed (T4) | rebuilt, deployed before the app |
| U6 | yes | yes | optional keys | round withdrawal, core gate, rules epoch, publication check, save check (T4) | rebuilt, deployed before the app |
| U7 | yes | no | no | no | no |
| U8 | no | no | no | no | rebuilt for the final run |
| Curves lot (out of V1-2.6) | yes | path ops | no | round withdrawal | rebuilt, deployed before the app |
@@ -657,7 +671,7 @@ robustness CONCERNS(9), simplicity CONCERNS(6); no BLOCKER. Integrated:
- The U7a/U7b expand-then-write split did not hold (`sheet.empty` writes the keys from the first new sheet) and
protected no environment: one model sub-step (U6) with the rollback limit stated.
- M9 dropped: report issues map to the existing `verification.validation.rules` (`verdict.rs:277-296`); the
round-withdrawal migration of contract `945-949` added to U6 and U9, with a frozen pre-U9 reader oracle.
round-withdrawal migration of contract §6.4 added to U6 and U9, with a frozen pre-U9 reader oracle.
- Sub-branches dropped (the gitflow lib branches only from develop): commit in place, rollback by revert.
- Curves: no document holds a path; U9 proposed for deferral (T16); the size lever becomes a fallback measured op by
op (T1), the PDF split a separate track.
@@ -683,6 +697,9 @@ the owner decides under T4. No second review was run on the corrected version.
## 7. Owner answers recorded (2026-11-05)
Dated record; the items still open here (T4 SQL checks, T5 defaults, T10 option B) and the T16 count wording were
answered or refined by the U0 brief and are superseded by §9 and DECISIONS.
Brief « FAUNOSTEO — V1-2.6 UX — Ratification des décisions techniques ». The UX choices are not reopened. Changes
to this plan and its companions:
@@ -715,4 +732,15 @@ rows; the save non-regression variant offered under O22. A fresh verifier on the
older T4 scope, BDR-100 superseded on T4 and T9), fixed, then a targeted re-check (ECARTS(2): one U6 test and the deploy-order line still assumed a permissive save and an all-rounds withdrawal), fixed. A third, independent check
before the commit (2026-11-05): ECARTS(2) on K10 and K11 (the R-3 mitigation and the U6 objective still on the
older T4 scope, the write-lock test assuming a stripping save succeeds, two forms of the T16 count scope), fixed,
then a fresh targeted re-check (result in TODO.md).
then a fresh targeted re-check: CONFORME 12/12, committed at `bd444d6` and `a505b24`.
## 9. Owner answers of the U0 brief (2026-11-05)
Brief « FAUNOSTEO — V1-2.6 UX — Autorisation U0 uniquement » (BDR-101), then « Finalisation de U0 uniquement »:
U0 authorised alone; the 16 boards and 11 choices approved for good. Recorded in `V1-2-6_UX_DECISIONS.md` and
contract §17.12: both T4 SQL checks approved (save; approval and publication), O22 amended strictly for these
invariants (contract §12.2); T5 new-sheet ids, names and colours from the existing data; T10 option B; T15 wording;
T16 deferral kept with the path count before any activation of the new model and before U6 or U8 reaches any
environment beyond the throwaway sandbox; « Remplacer par un polygone » as an
explicit, validated, undoable replacement; T12 and T17 open (U7 and U6), T1 and T6 unchanged. U0 amended the V1-2
contract, the level-1 contract, `docs/design/README.md` and the rules `sheet-model.md` and `schemas.md`.