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

+220 -12
View File
@@ -769,9 +769,10 @@ round (on a draft):
before M5, working copy, empty document) gives no base, and every group is
to cover (§6.3).
- Unsaved changes stay in the page. The leave guard of V1-1 protects them;
a local recovery copy, keyed by version and revision, is kept in the
browser with the report editor's persistence pattern and offered back after
a crash or an expired session, never sent automatically.
a local recovery copy, keyed by account and version with the revision
recorded in the copy (wording matched to the code at V1-2.6 U0, §17.12), is
kept in the browser with the report editor's persistence pattern and offered
back after a crash or an expired session, never sent automatically.
- Validation while editing: the page runs the core's checks and shows the
validation panel (§8.1). It is advisory; the server verdict decides (§6.4).
- Saving is explicit (« Enregistrer »): `save_sheet_draft(version_id,
@@ -785,6 +786,11 @@ round (on a draft):
the author set, and the audit records `anatomical_sheet_version.saved` with
the revision. A draft may hold integrity errors while it is being written;
the verdict refuses them at submission.
- From V1-2.6 U6 (owner 2026-11-05, §17.12; not built yet), the save also
applies the declared fixed-category check of §12.2: no role carried by two
categories, a category carrying a role keeps that role's fixed names, no
role of the stored draft lost. A draft that carries no role (every draft
saved before U6, the equine working copy) still saves.
- A trigger bumps `revision` on any content write, so no write slips under a
round unseen.
- The direct UPDATE grants on `content`, `change_note`, `name`, `slug` and
@@ -943,9 +949,11 @@ caps; completeness counts (statuses, vet referrals, uncited elements); the
groups and their digests; the change list; `verified_with` (core version).
Core changes. A release that changes the SVG reader, the integrity rules, the
caps or the fingerprint ships a migration that withdraws every round in
`verifying`, `open` or `approved`, with the reason recorded; editors submit
again and the new worker verifies. The release replay (§15) runs before such a
caps or the fingerprint ships a migration that withdraws every round of a
draft version in `verifying`, `open` or `approved`, with the reason recorded
(the round of a published version stays `approved`, §6.1, and
`withdraw_sheet_review` refuses it with `draft.not_a_draft`; worded at V1-2.6
U0); editors submit again and the new worker verifies. The release replay (§15) runs before such a
release.
Availability. Reviews and publications need a running, health-checked
@@ -1100,6 +1108,7 @@ Four stages, each a superset of the previous:
| Every annotation in frame shows at least 4 CSS px on the smallest preview, the editor at 320 × 568 (main view box 286 × 310, detail view box 254 × 191, `xMidYMid meet`): a point's visible disc (`2 × max(2, r − 12)`), a trigger circle's diameter, a polygon's or a path's smaller side (curves and arcs on their shape). Same views, same frame; the document is never rewritten (owner brief 2026-11-01, RUST.md §12.13) | yes | | | `verification.validation.marker_too_small` (issue `annotation.geometry.too_small`) |
| Every polygon or path annotation in frame fills a disc of 4 CSS px on the same preview: under the `nonzero` rule the layer fills with, its stroke left out, a centre inside the fill at least the radius from every edge (closing edges included), curves and arcs cut into chords whose deviation is taken off; arcs modelled as browsers store them (`f32` endpoints, a radius other than zero at least `2⁻²⁰`, the spread of one `f32` ulp added); measured within `interior::MAX_OUTLINE_VERTICES` 4 096 vertices and one budget of `2²⁵` edge distances per sheet, refused past them; refused in doubt (owner brief « fermeture du dernier MEDIUM » 2026-11-01, RUST.md §12.14) | yes | | | `verification.validation.marker_interior_too_small` (issue `annotation.geometry.interior_too_small`) |
| Fingerprint computed | yes | | | `verification.integrity.fingerprint` |
| Fixed categories (from V1-2.6 U6, §17.12; not built yet): each of `bone`, `joint`, `vertebra` carried by exactly one category with its fixed FR and EN names, `navigation` by at most one with its fixed names; judged on drafts, never on a published version (the §15 replay filters it) | yes | yes | yes | submission: issues `category.fixed.*` under `verification.validation.rules`; approval and publication: the declared check of §12.2 (closed code fixed at U6) |
| Verdict passed, on the current revision | | yes | yes | `verdict.missing`, `verdict.failed`, `verdict.stale` |
| No `to_confirm` element (D2) | | yes | yes | `publish.to_confirm.open` |
| No `inherited` element, an omitted status counting as `inherited` (O3 B) | | yes | yes | `publish.inherited.present` |
@@ -1114,7 +1123,8 @@ Four stages, each a superset of the previous:
- The rules of the first six lines come from the stored verdict. SQL checks
relations, states, rights, separation, the verdict's structure (§6.4), and
the declared defensive check of statuses on the stored document (§12.2).
the declared defensive checks on the stored document (§12.2): statuses and,
from V1-2.6 U6, the fixed categories.
- Shown, never blocking: uncited elements, the two warning codes, the number
of vet referral nodes.
- Approval never changes the document.
@@ -1232,6 +1242,19 @@ uses, and whether a species gets a default sheet, is decided with V1-3.
- No template of scientific content is shipped. Vertebral formulas, zones and
findings of a new species are entered by the editor from sources cited in
the references registry.
- From V1-2.6 U6 (owner 2026-11-05, §17.12) the empty document carries the
three fixed categories `cat-bone` (« Os » / « Bones »), `cat-joint`
(« Articulations » / « Joints ») and `cat-vertebra` (« Vertèbres » /
« Vertebrae »), with their roles and default colours; nothing else is
pre-filled.
- Scope and limits (choice 7, decision T12): the editor may insert a
versioned common text once into the FR and EN scope fields while both are
empty; the fields stay free text afterwards, and no later version of the
common text changes a draft or a published version. No common text exists
yet: its FR and EN wording, its source and its validation record are
supplied by the owner before U7, and nothing is written in their place
meanwhile. It is never presented as veterinary or legal advice approved by
the platform.
### 7.5 Species-specific checks
@@ -1325,6 +1348,35 @@ An editor can, from the application only:
report, submit, follow the round and its verification, read comments,
withdraw.
Amended for the V1-2.6 redesign (owner 2026-11-05, §17.12; built in sub-steps
U1 to U6, each on its own authorisation). The functions above stay; the way
they are reached changes:
- four tabs, Général, Annotations, Constats and Vérification; views,
drawings, annotation categories and vertebral regions in Annotations; the
references registry in a side panel opened from the header or from a
finding; undo and redo in the header on every tab;
- geometry by direct manipulation on the drawing: a point moved, and sized
with a slider snapped to the sizes of its view, the core's minimum shown; a
polygon's vertices dragged, added with « + » on a segment, removed with
« − »; a zone moved (with the mouse once selected, in an explicit mode by
touch) or redrawn, the old shape kept until the new one is accepted; the
keyboard alternative goes through the handles. No coordinate field remains
in the normal journey;
- a detail view drawn as a rectangle over its parent's drawing, its name
proposed from the annotations inside and editable (U5); its access placed
from the view's menu (U4), or created with the view from U6 when no
annotation overlaps the rectangle, in the internal navigation category
`cat-access`;
- annotation categories: the three fixed categories keep their names and
roles, their colour and fill opacity adjustable (from U6); other categories
stay free; an annotation's own colour is shown only when set, with
« Revenir à la couleur de la catégorie »; a new annotation inherits its
category's colour;
- replacing the drawing of a crop view asks first: keep the positions,
reposition the annotations or cancel, each offered only under the
conditions of decision T9, never an approximate transformation.
### 8.3 Level 2, deferred
Curves (`path` drawn or edited by handles; existing paths are displayed and
@@ -1337,6 +1389,17 @@ drawing or on elements, drag and drop in the finding tree, bulk import of
findings, species templates, collaborative live editing, package export and
import.
Amended 2026-11-05 (§17.12): dragging vertices and drawing a crop rectangle
on the canvas move into V1-2.6 (§8.2 as amended); the size slider snaps to
the sizes already used in the view, other snapping stays deferred. Curves
form the curves lot (decision T16), which precedes package import, zones from
the drawing's own shapes and any curve drawing tool. Until then a stored path
keeps its data byte for byte and is never converted; an operation that would
change it is refused with the document unchanged. « Remplacer par un
polygone » stays its one exit, as an explicit replacement only: the editor
traces the polygon, the core validates it, the old path stays until the
polygon is accepted, and the change is undone and redone as one entry.
### 8.4 What level 1 does not do, and narrow screens (O14 A)
Level 1 never edits the drawing itself, accepts no raster image, draws no
@@ -1350,6 +1413,12 @@ per sheet, revision conflicts).
| Draft editor, every tab, graphic and structured | full | read-only with a notice naming the 1 024 px minimum |
| Admin lists, overview, rights, species, review screen (read, comment, acknowledge, decide), publication confirmation, deprecation, archive | full | usable, tested at 375 px |
Amended 2026-11-05 (§17.12): O14 A is kept. Editing on a phone (boards 14 to
16 of `docs/design/v1-2-6`) is a future lot after V1-2. From 1 024 px the
editor works with the mouse, the keyboard and touch (a tablet in landscape,
handles of at least 44 px); below 1 280 px the application's sidebar is
hidden in the editor, its menu one tap away.
---
## 9. Drawings (SVG assets)
@@ -1701,14 +1770,32 @@ Inventory of the current SQL checks and their fate:
| `reference.url.scheme` | `sheet_document_reference_issues` | duplicate of the core's strict parse | removed in M5 |
| verdict structure: group keys and drawings match the document (§6.4) | completion RPC (new) | relational | added in M5 and M6 |
| statuses: no `to_confirm`, no `inherited`, an absent `review_status` counting as `inherited` (new) | publication and approval | declared defensive check | added in M5 |
| fixed categories at save: no role carried by two categories, a category carrying a role keeps that role's fixed FR and EN names, no role of the stored draft lost; a document without roles saves when the stored draft has none (owner 2026-11-05, §17.12) | `save_sheet_draft` | declared defensive check | planned at V1-2.6 U6, not built |
| fixed model at approval and publication: each of `bone`, `joint`, `vertebra` carried by exactly one category with its fixed FR and EN names, `navigation` by at most one with its fixed names (owner 2026-11-05, §17.12) | `private.sheet_fixed_categories_ok(content)` (name provisional), called by `decide_sheet_review` and `publish_sheet_version` | declared defensive check | planned at V1-2.6 U6, not built |
- The status check is the one remaining mirror, declared as such: a
- The status check is the first declared mirror (the fixed-category checks
below are the others, from V1-2.6 U6): a
structural walk over `annotations[*]`, `finding_zones[*].categories[*]` and
every `children[*]` below them, refusing an element whose `review_status`
is absent, `to_confirm` or `inherited`. It is kept in SQL so that a worker
defect can never make unread content official, and it follows the schema's
default (`inherited`), which is why the absent case is explicit. A pgTAP
case uses an omitted status. No other rule is mirrored.
case uses an omitted status. Besides it, only the two fixed-category checks
below are mirrored (O22 amended 2026-11-05).
- The fixed-category checks (owner 2026-11-05, §17.12; planned at U6, not
built) are declared mirrors of the category model's invariants only: the
fixed roles, their uniqueness, their presence and their fixed names, read
from `categories[*].role` and `categories[*].name`. At save they stop a
direct save, an older tab or « Garder ma version » from stripping,
duplicating or renaming the fixed categories of a draft; at approval and
publication they keep a worker defect from making a draft outside the model
official. The core keeps the authority and the same rule with its messages
(the verdict issues `category.fixed.*`, the editor's refusals and repairs);
no other part of the core's validation is mirrored (no annotation, view,
finding or reference rule). A draft that carries no role still saves when
the stored draft carries none, so no draft saved before U6 is locked, and every state a save can reach stays
repairable in the editor. Closed codes and pgTAP allowed and denied cases
come with U6.
- Transition without an unprotected window: M5 replaces the publication gate
by the verdict-based one and drops the mirror functions in the same
migration. From M5 until M6 provides the worker RPCs, no verdict can be
@@ -2323,7 +2410,9 @@ V1-2.7 on.
- Application changes: the draft editor. SQL changes: M8 `sheet_draft_last_save`, a read
migration for the conflict dialog (§12.3, owner decision 2026-11-03; was « none »).
- Tests: `e2e:shell` A2, A3, A4 with a conflict and a local recovery;
keyboard path through numeric fields; axe; read-only below 1 024 px.
keyboard path through numeric fields (amended 2026-11-05, U0: from V1-2.6
U2 through the handles, from U4 through the crop rectangle, §8.2 as
amended); axe; read-only below 1 024 px.
- Acceptance: a sheet for a species other than the horse, with a drawing
exported from a vector tool and cleaned, a detail view, points, zones,
links and a finding catalogue, is built from scratch in the UI on the
@@ -2350,6 +2439,17 @@ V1-2.7 on.
under 61 ms (budget 500 ms). Only measured views are editable (owner
2026-11-04); the AAL2 residual of §13 stays open. DEV untouched; the owner
has not tried the editor yet.
- State 2026-11-05: the owner stopped the level-1 trials (decision T11):
level 1 is not declared validated as a whole, its residuals stay tracked in
`.claude/tasks/TODO.md`. The editor is redesigned on the validated boards of
`docs/design/v1-2-6` (§8.2 to §8.4 as amended, §17.12) in sub-steps U0 to
U8 of `docs/development/V1-2-6_UX_PLAN.md`, each started on its own owner
authorisation; U0 (contract and decisions, documents only) was authorised
on 2026-11-05. SQL changes planned for the redesign: one U6 migration (the
round withdrawal of §6.4, a core gate, a rules epoch, the fixed-category
checks of §12.2). The acceptance above is re-run on the redesigned editor at
U6 and U8, with the verification worker on the sandbox, up to a round
`open`.
### 16.8 V1-2.7 Preview, review and publication UI
@@ -2454,7 +2554,9 @@ sharing, follows, forks, students; rights scoped by species or sheet; review
quorum (O5); e-mail notifications; species deactivation and deletion; Storage
object deletion beyond the `object_conflict` runbook; offline cache;
professional verification (Step 9); entitlements (Step 11, switch of §5.3); a
synchronous verification service. RR-2 (fingerprint rollback limit, `RUST.md`
synchronous verification service; the curves lot (§8.3 as amended, decision
T16); editing on a phone (§8.4 as amended); a multi-tab notice (decision T14,
a follow-up candidate). RR-2 (fingerprint rollback limit, `RUST.md`
§11.22) stays open on the release track: before any release to users, a gate
requires it settled, by shipping the switch with the release or the alias
registry in any build that can be rolled back to; V1-2 does not resolve it.
@@ -2491,7 +2593,7 @@ which would have accepted a browser verdict or deferred MFA, are rejected.
| O19 | A: cleaning before upload with preview and confirmation, refusal of active and external content, server check kept, no silent change of a stored drawing | §9.2 |
| O20 | Deferred to the release track; RR-2 open; gate before any release to users | §16.12 |
| O21 | Catalogue access as an explicit, provisional, fail-closed right until the entitlements of Step 11; layers distinguished; reader row predicate; tests per actor | §5.1, §5.3 |
| O22 | Rust core the only authority on document rules; SQL keeps access, relations, states, revisions, locks, atomicity and the verdict's identity; the business mirror is removed in M5 without an unprotected window; one declared status check kept | §12.2 |
| O22 | Rust core the only authority on document rules; SQL keeps access, relations, states, revisions, locks, atomicity and the verdict's identity; the business mirror is removed in M5 without an unprotected window; one declared status check kept; amended 2026-11-05: two declared fixed-category checks, at save and at approval and publication (§17.12) | §12.2 |
| O23 | Fail-closed verification: explicit states and outcomes, closed codes per category, idempotent retries under a limit, withdrawal always possible, audit, no partial publication | §6.5 |
### 17.2 Arbitration AR-1: MFA on platform role changes (ratified, option B)
@@ -2674,6 +2776,112 @@ wordings ratified in V1-2.4 are kept.
reviewed in `IDENTITY.md` §4.2; no safe, rehearsed recovery exists yet, which is a production prerequisite
(§13). No MFA bypass, no `aal2` weakening, no new path that resets a factor.
### 17.12 V1-2.6 UX redesign decisions (owner, 2026-11-05)
Three owner briefs of 2026-11-05: « V1-2.6 — Validation UX définitive et
préparation technique » (the sixteen boards of `docs/design/v1-2-6` and the
eleven choices of its `ARBITRAGES.md`), « V1-2.6 UX — Ratification des
décisions techniques » (BDR-100) and « V1-2.6 UX — Autorisation U0
uniquement » (BDR-101). The technical detail, the single decision table and
the sub-steps U0 to U8 (plus the curves lot, ex-U9) live in
`docs/development/V1-2-6_UX_{DECISIONS,PLAN,COMPATIBILITY,TESTS,RISKS}.md`.
Nothing below is built yet; each sub-step starts on its own authorisation.
**Level 1 (T11).** Built (lots A to O, level-1 criteria C1 to C48), never
tried by the owner, not declared validated as a whole; its trials stop and its
residuals stay tracked in `.claude/tasks/TODO.md`, re-checked at U8.
**Validated UX (choices 1 to 11).** Four tabs, references in a side panel,
undo and redo in the header on every tab; direct manipulation of points and
polygons, a zone moved with the mouse once selected and in an explicit mode
by touch, a size slider snapped to the sizes of the view; no coordinate field
in the normal journey; a detail view drawn as a rectangle, its name proposed,
its access never laid over an existing annotation; fixed categories Os,
Articulations, Vertèbres (names and roles fixed, colour and fill opacity
adjustable); a one-time copy of a versioned common text; explicit save with
the local copy; O14 A kept, touch drawing on a tablet in landscape, the
sidebar hidden in the editor below 1 280 px, phone editing a future lot; an
annotation's own colour shown only when set. Amended accordingly: §6.2, §7.4,
§8.2 to §8.4, §16.7, §16.12, and the level-1 contract
(`.claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md`: C3, C4, C5, C6,
C7, C8, C11, C13, C16, C18, C20, C25, C28, C32, C33, C40, the undo question of
its CLARIFICATIONS, and a precedence rule in its header; the board differences
left to the owner are listed in `V1-2-6_UX_DECISIONS.md`).
**Category model (T2, T3, T4, T5, T10).**
- Two optional keys on a category, `role` (`bone`, `joint`, `vertebra`,
`navigation`) and `fill_opacity` (an integer percent from 10 to 100),
omitted when absent, never `null`, no schema version bump. Written only once
the proofs of `V1-2-6_UX_COMPATIBILITY.md` §8 are green and reviewed and the
checks below are live (write lock). Compatibility runs one way: once a
document carries a key, no earlier application, worker or core reads it,
and returning to the old application is impossible.
- Fixed model: each of `bone`, `joint`, `vertebra` carried by exactly one
category, with its fixed names; `navigation` by at most one.
- New-sheet defaults (T5): `cat-bone` « Os » / « Bones » `#a41e65`,
`cat-joint` « Articulations » / « Joints » `#ff9500`, `cat-vertebra`
« Vertèbres » / « Vertebrae » `#e100ff`, colours shown as « Couleur
d'origine ». The names Bones and Joints and the three colours come from the
equine categories `os`, `articulations` and `zone-colonne`; no existing
category is named Vertebrae, which follows the editor's tab pair
« Vertèbres » / « Vertebrae ».
- Navigation category (T10 option B): `cat-access`, role `navigation`,
« Accès aux vues détaillées » / « Detail view access », no colour; never
shown as an anatomical category (no panel, no picker); holds detail
triggers only; created by the core with the first automatic access (U6).
- Checks (T4, no residual gap): the core's verdict issues `category.fixed.*`
(§6.7) and editor refusals with repairs; a core gate at verification
completion that refuses a passed verdict of a core older than U6; the
round withdrawal of §6.4; the two declared SQL checks of §12.2 (O22
amended), at save and at approval and publication, holding the
fixed-category invariants only.
- History (T5): the historical equine versions keep their ids, names,
colours, own colours, annotations and fingerprints; roles go on the working
copy only (V1-2.8, decision T6); the seed and the published historical
version never change.
**Detail views (T9, T10).** Replacing a crop view's drawing opens a dialog
before any upload with three actions: keep the positions (only when the
candidate's `viewBox` equals the crop), reposition the annotations (only for
the same aspect ratio, with no path and no descendant crop), cancel; never an
approximate automatic transformation. The automatic access needs the
navigation role, so it comes at U6, not U5, and only when no annotation
overlaps the rectangle; until then the access is placed explicitly from the
view's menu (U4).
**Curves (T16).** Curve handle editing is deferred to the curves lot, which
precedes any feature letting a path into a document. Stored paths keep their
data byte for byte and are never converted; an operation that would change
one is refused with the document unchanged. « Remplacer par un polygone » is
kept as an explicit replacement only (§8.3 as amended). Before the new model
is activated on an environment, and before U6 or U8 reaches any environment
beyond the throwaway sandbox, a read-only count of path geometries in its
drafts and published versions is recorded (DEV and shared environments by the
owner or under an explicit authorisation, never during U0); a non-zero count
reopens T16.
**Common text (T12).** One versioned copy inserted once into empty fields
(§7.4); U7 blocked until the owner supplies the FR and EN text, its source and
its validation record; no normative wording before that.
**Wording (T15).** « Annuler la dernière modification » names the history
command (header button, tooltip and accessible name, the toast after a
gesture); « Abandonner » or « Abandonner les modifications » names leaving a
form or discarding unsaved changes (level-1 C11).
**Open.** T1 (only if a measure exceeds the 600 000 B wasm budget), T6
(V1-2.8), T14 (multi-tab notice, follow-up), T17 (the vertebral regions entry
when no category carries the vertebra role; blocks U6), the T12 text (blocks
U7), and the category of an access placed by hand after U6 when annotations
overlap the rectangle (a U6 design point, DECISIONS T10).
**Implementer decisions** (no owner question): T7 both keys stripped from
every envelope snapshot; T8 path operations on the written digits (curves
lot); T13 commits in place on `feature/v1-2-anatomical-sheets`, rollback by
revert; T18 a handle cap per shape, fixed at U2 from the equine maxima (17
vertices today) with a margin; T19 sliders and arrow moves commit on release,
Enter or blur.
---
## 18. Documents touched by V1-2.0