Version. 0.1
Date. 2026-05-01
Author. Marvin Percival (DUNIN7), prepared via Claude.
Target. /Users/dunin7/loomworks-ui (frontend). /Users/dunin7/loomworks (substrate — CR archival and implementation notes only, plus optional version-chain endpoint). DUNIN7-M4 (MacMini).
Priority. Standard.
Confidential. Internal.
Companion to. Phase 29 scoping note v0.1, Phase 3 CR v0.2 (revise/retract functions), Phase 16 CR v0.1 (Memory room contribution UI), Loom Protocol §4 (transitions), methodology v0.19.
Status. First draft. Seven scoping decisions (S1–S7). No open design questions.
Phase 29 completes the assertion lifecycle UI in the Memory room. The Operator can now revise assertions (pre-populated editing surface, new version in held state, commit to make authoritative), retract assertions (inline confirmation with required rationale), and view the version chain of any revised assertion. The substrate already supports all three operations — revise_assertion, retract_assertion, and the wasRevisionOf relationship chain are fully built and tested. Phase 29 surfaces them in the frontend.
This completes the Loom Protocol §4 transition set in the UI: Add (Phase 16), Commit (Phase 16), Revise (Phase 29), Retract (Phase 29), Relate (script-only, not user-facing).
Layer 1 — Loom Protocol §4. Five transitions: Add, Commit, Revise, Retract, Relate. Phase 16 surfaced Add and Commit. Phase 29 surfaces Revise and Retract. Relate remains script-only (appropriate — relationships are structural, not contributed through a general-purpose UI).
Layer 2 — Phase 3 CR v0.2. The substrate implementation. revise_assertion produces a new version in held state with was_revision_of pointing at the prior version, records assertion_revised event and wasRevisionOf relationship. retract_assertion produces a retracted version with required rationale, records assertion_retracted event. Both reject operations on retracted assertions.
Layer 3 — Phase 16 CR v0.1. The current Memory room UI. Contribution surface with four input modes. Assertion list with held and committed states. Commit action on held assertions. Room explanation toggle.
Layer 4 — Rendering room retire confirmation. The inline confirmation pattern (not a modal) reused for the Retract action.
phase-28-expandable-explanations. 1181 tests, 2 skips.phase-28-expandable-explanations. 132 component tests, 6 E2E (1 skipped). Lint + tsc + build + test clean. Fourteen surfaces.The following endpoints exist and are tested. Phase 29 wires the frontend to them:
POST /engagements/{eid}/assertions/{aid}/revise — body: { content: string }. Returns the new assertion version in held state.POST /engagements/{eid}/assertions/{aid}/retract — body: { rationale: string }. Returns the assertion in retracted state.CC verifies the exact request/response shapes before wiring proxy routes. If the endpoint signatures differ slightly from the above (e.g., additional fields, different path structure), CC adapts the proxy and frontend calls accordingly.
The was_revision_of field on each assertion version provides the chain. CC determines the most efficient approach:
Option A — Client-side resolution. The assertion list already contains all assertions. The frontend walks was_revision_of references to build the chain. No new endpoint.
Option B — Dedicated endpoint. GET /engagements/{eid}/assertions/{aid}/history returns the full version chain for one assertion. Cleaner if the assertion list does not include superseded versions or if the chain resolution is complex.
CC picks the option that produces the simplest, most reliable result. If Option B is chosen, the endpoint is a minimal substrate addition (a read-only convenience join).
Archive this CR to docs/phase-crs/phase-29-cr-memory-room-assertion-lifecycle-v0_1.md.
Commit (substrate repo): Phase 29 step 0: CR archival.
"Revise" appears as a {components.button-ghost} on every held and committed assertion in the Memory room assertion list. Hidden on retracted assertions.
Clicking "Revise" opens an inline editing area below the assertion. The editing area:
{components.button-secondary}) and "Cancel" (text link).Only one editing surface may be open at a time in the assertion list. Opening a new one closes any other open editing surface (same pattern as one-card-expanded in the Shaping and Rendering rooms).
"Submit revision" calls the revise endpoint with the edited content. On success:
On error: an inline error message appears below the textarea. The editing surface remains open.
If the content is empty or unchanged from the original, "Submit revision" is disabled. The Operator must change the content to submit.
The new version is held. The Operator commits it through the existing commit action. This is the standard two-step: revise (propose), then commit (make authoritative). No special flow — the existing commit button on held assertions handles it.
"Retract" appears as a {components.button-ghost} alongside "Revise" on every held and committed assertion. Hidden on retracted assertions.
Clicking "Retract" expands an inline confirmation below the assertion (not a modal). The confirmation contains:
{typography.body} with {colors.ink-faint}:> Retract this assertion? It will be marked as invalidated. The assertion content is preserved for reference.
{typography.caption}. Required — "Confirm retraction" is disabled until the rationale is non-empty (trimmed).{components.button-ghost}.This matches the Rendering room's retire confirmation pattern (Phase 22/27).
"Confirm retraction" calls the retract endpoint with the rationale. On success:
On error: an inline error message appears in the confirmation area.
If the revise editing surface is open on an assertion, the "Retract" button is hidden (and vice versa — if the retract confirmation is open, "Revise" is hidden). Only one action surface at a time per assertion.
"Prior versions · N" appears on any assertion that has at least one prior version in its was_revision_of chain. N is the count of prior versions. Assertions with no revision history do not show the toggle.
The toggle appears below the assertion content and above the action buttons.
"Prior versions · N" as a text link in {typography.caption} with {colors.brass}. Chevron indicator.
Each prior version as a compact row with {colors.cartridge} (#F2EDE0) background and {spacing.s-2} padding:
{typography.label} (IBM Plex Mono).{typography.body} with {colors.ink-faint}.{typography.caption}.{typography.caption} with {colors.ink-faint}.Versions ordered oldest first (v1 at top). The current version is not repeated — it is the assertion displayed above the toggle.
Clicking the toggle again collapses the history. No localStorage persistence — always collapsed on page load.
The Memory room assertion list shows four distinct visual treatments:
{colors.rule}.{typography.label} (IBM Plex Mono, uppercase).{colors.state-attest}.{typography.label}.{colors.state-amend}.{typography.label}.{typography.caption} with {colors.ink-faint}, prefixed with "Reason: ".When a committed assertion has been revised but the revision is not yet committed:
{colors.state-attest}.{typography.label}. The "REVISED" portion in {colors.brass} to distinguish it.This indicator tells the Operator: "a newer version of this assertion exists in held state." Once the revision is committed, the prior version loses the "REVISED" indicator and is superseded (visible only through the revision history toggle on the new version).
To determine whether a committed assertion has a pending revision: check whether any held assertion in the list has was_revision_of pointing at this assertion's MemoryRef. CC determines the most efficient way to perform this check — either client-side from the assertion list data or via a field on the API response.
CC picks the display approach that best fits the existing assertion list layout:
Option A — Inline with dimming. Retracted assertions stay in their natural position in the list with reduced opacity (e.g., 0.6) and the "RETRACTED" label. Rationale visible as caption.
Option B — Collapsible section. Retracted assertions move to a "Show retracted · N" collapsible section at the bottom of the assertion list. Matches the Rendering room's retired/invalidated pattern.
The requirement: retracted assertions are visible, clearly distinguished from active assertions, and show their retraction rationale. CC picks the option.
Wire proxy routes for the revise and retract endpoints if not already present:
POST /api/engagements/[eid]/assertions/[aid]/revise → substrate revise endpoint.POST /api/engagements/[eid]/assertions/[aid]/retract → substrate retract endpoint.If a version-chain endpoint is added (§3.3 Option B):
GET /api/engagements/[eid]/assertions/[aid]/history → substrate history endpoint.No new visual patterns. Reuses existing patterns:
{colors.cartridge} background (same as Render rows, Shaping rows).{colors.rule}, {colors.state-attest}, {colors.state-amend}).{components.button-ghost} in {colors.type-metal}.env-memory (#E4E6E8).Write or update tests to cover:
Existing Memory room tests (contribution, commit) should pass unchanged.
Auto-mode posture: Step 0 auto. Steps 1–3 auto, Checkpoint A. Steps 4–5 auto, Checkpoint B (final).
Step 0 — CR archival.
Archive this CR to docs/phase-crs/phase-29-cr-memory-room-assertion-lifecycle-v0_1.md.
Commit (substrate repo): Phase 29 step 0: CR archival.
Step 1 — Revise action.
Verification: lint + tsc + build clean. Operator can revise a committed assertion, see the held revision, commit it.
Commit (frontend repo): Phase 29 step 1: revise action.
Step 2 — Retract action.
Verification: lint + tsc + build clean. Operator can retract an assertion with rationale, see retracted state.
Commit (frontend repo): Phase 29 step 2: retract action.
Step 3 — Revision history toggle.
Verification: lint + tsc + build clean. Operator can view revision history on revised assertions.
Commit (frontend repo): Phase 29 step 3: revision history toggle.
If substrate endpoint added, commit (substrate repo): Phase 29 step 3: assertion history endpoint.
Checkpoint A — All three capabilities functional. Revise, Retract, and revision history work. Operator confirms before tests and tagging.
Step 4 — Component tests.
Write component tests (§12).
Verification: lint + tsc + build + test clean.
Commit (frontend repo): Phase 29 step 4: component tests.
Step 5 — Implementation notes and tagging.
Create docs/phase-impl-notes/phase-29-implementation-notes-v0_1.md.
Commit (substrate repo): Phase 29 step 5: implementation notes.
Checkpoint B — Final. Both repos green. Tag both repos as phase-29-assertion-lifecycle-ui.
Phase 29 is accepted when:
On acceptance: tag both repos as phase-29-assertion-lifecycle-ui. Write implementation notes.
revise_assertion supports changing normative force. The UI does not expose this — all assertions currently use the default. Future phase if needed.
Read the Change Request document at the path I supply below. This is
CR-2026-042 v0.1, the Phase 29 Change Request. You are the executing
agent named in the CR.
CR path: ~/Downloads/phase-29-cr-memory-room-assertion-lifecycle-v0_1.md
Phase 29 adds Revise, Retract, and revision history to the Memory
room. The substrate already supports all three operations — this
phase surfaces them in the frontend.
Key requirements:
- "Revise" on held and committed assertions. Hidden on retracted.
Opens pre-populated inline editing surface. New version arrives
held. Only one editing surface open at a time.
- "Submit revision" disabled when content empty or unchanged.
- "COMMITTED · REVISED" label on committed assertions that have
a pending held revision.
- "Retract" on held and committed assertions. Hidden on retracted.
Inline confirmation with required rationale (same pattern as
Rendering room retire confirmation). Retracted assertions show
rationale.
- Revise and retract surfaces mutually exclusive per assertion.
- "Prior versions · N" toggle on assertions with revision history.
Expanded: version rows on cartridge ground, oldest first, with
version label, state, content (truncatable), contributor,
timestamp.
- Pick retracted-assertions display: inline with dimming (Option A)
or collapsible section (Option B). See CR §9.
- Pick version-chain data approach: client-side resolution
(Option A) or dedicated endpoint (Option B). See CR §3.3.
Substrate baseline: 1181 tests, 2 skips.
Frontend baseline: 132 component tests, 6 E2E (1 skip).
Run Step 0: archive CR in substrate repo.
Steps 1–3 auto, Checkpoint A halts for smoke test.
Steps 4–5 auto, Checkpoint B halts for tagging.
Brand enforcement: env-memory (#E4E6E8) outer frame. Bleached
(#FFFCF5) assertion backgrounds. Cartridge (#F2EDE0) revision
history rows. Ghost buttons in type-metal. State dots per §8.
No pure white. IBM Plex Serif for assertion content. Inter for
body. IBM Plex Mono for labels, version numbers, status badges.
Implementation notes at Step 5:
docs/phase-impl-notes/phase-29-implementation-notes-v0_1.md
DUNIN7 — Done In Seven LLC — Miami, Florida Phase 29: Memory Room Assertion Lifecycle UI — CR v0.1 — 2026-05-01