Version. 0.2
Date. 2026-04-27
Author. Marvin Percival (DUNIN7), prepared via Claude.
Target. /Users/dunin7/loomworks (substrate, Step 0 amendments) and /Users/dunin7/loomworks-ui (frontend, Steps 1–5). DUNIN7-M4 (MacMini).
Priority. Standard.
Confidential. Internal.
Supersedes. CR-2026-035 v0.1 (Phase 21, first draft). v0.1 was archived by CC at Step 0 but execution halted at pre-flight when CC identified display-readiness gaps requiring substrate amendments and a CR revision. v0.1 remains in docs/phase-crs/ as historical; v0.2 is the executing document.
Companion to. Phase 21 scoping note v0.1, Phase 11 CR v0.1 (Shaping substrate), Phase 9 CR v0.3 (shape production substrate), Phase 16 CR v0.1 (room model), methodology v0.19.
Status. Second draft. Incorporates four pre-flight findings from CC's Step 0 execution against v0.1. Three resolved at Step 0 as substrate amendments; one deferred with a relaxed display spec.
CC executed v0.1's Step 0 (pre-flight) and identified four display-readiness gaps between what the CR's display spec requires and what the substrate responses provide. This revision resolves three and defers one:
| Gap | Description | Resolution | |-----|-------------|------------| | 1+4 | AgentExecutorSchema.agent_ref lacks display_name | Resolved at Step 0. Schema change + router population. No migration. | | 2 | ShapeEventResponse missing manifestation_ref, shaping_ref, produced_at | Resolved at Step 0. Schema additions, migration (view columns), projector update. Null accepted for pre-amendment rows. | | 3 | No substrate endpoint for listing available executors | Deferred. Create/Change Executor modals use typed reference inputs. Executor registry endpoint is future work. |
Phase 21 builds the Shaping room — the third methodology room in the UI. The room is organized by DeclaredShapeType (the seed's commitments about what the engagement produces). Each declared type is a section; Shapings that serve it appear within. The Operator creates Shapings, amends their rules, changes their executor, retires them, and triggers shape production against the current Manifestation. Produced Shapes appear under their parent Shaping with Manifestation version, Shaping version, and timestamp.
Step 0 executes three substrate amendments required for display readiness: agent executor display name (Gaps 1+4), and Shape-event lineage fields (Gap 2). Frontend steps follow. Executor selection in the Create and Change Executor modals uses typed references (Gap 3 deferred — no substrate endpoint for listing available executors at this scale).
Layer 1 — Methodology document v0.19. Shaping takes a confirmed Manifestation and forms it for a specific consumer. A Shaping is a versioned first-class process with a name, rules, and an executor. The five operation types (subtractive, recasting, selective, navigational, origin-filtered) describe what Shapings do. The methodology requires each operation to have its own visible space (v0.19's four-operations principle).
Layer 2 — Reference Design v0.1.2. S-2 (selective shaping): the Shaping room is where the Operator manages the selection and recasting of material for specific consumers.
Layer 3 — Playground Specification v0.10. Sec-C.3 (Shaping operations), Sec-C.4 (Shape production and confirmation).
docs/phase-crs/phase-21-cr-shaping-room-ui-v0_1.md.CC confirms before Step 1 (after Step 0 substrate amendments):
npm run test passes (36 component tests).RoomSwitcher component and EngagementRoomLayout are identified.Endpoint path note. The exact substrate endpoint paths may differ from Phase 11 CR specifications. CC confirms at pre-flight and wires proxy routes accordingly. If any endpoint is missing or returns unexpected shapes, stop and reconcile before Step 1.
Archive this CR (v0.2) to docs/phase-crs/phase-21-cr-shaping-room-ui-v0_2.md in the substrate repo at Step 0. v0.1 is already archived; v0.2 sits alongside it. v0.2 is the executing document.
Three amendments to bring substrate responses to display readiness. All executed in the substrate repo at Step 0 before frontend work begins.
Problem. AgentExecutorSchema.agent_ref uses ActorRefSchema (kind/id/instruction_version) which has no display_name. The Shaping card (§6) needs "Agent: [name]" and the CR creates responses that carry the executor in both create-response and read-response paths.
Fix.
schemas.py: Change AgentExecutorSchema.agent_ref from ActorRefSchema to ActorRefResponse (which carries display_name).routers/shapings.py: Populate display_name when constructing agent_ref. The underlying AgentExecutor.agent_ref already carries display_name via Phase 16's field on ActorRef.Scope. ~3 lines. No migration. Same pattern as Phase 18's derived_by amendment.
Problem. ShapeEventResponse carries engagement_version_at_production and shaping_agent_instruction_version, but the CR's §12 (Shape list) requires per-Shape entries showing "Against Manifestation v[N]," "Shaping v[N]," and a production timestamp. The underlying ShapeEvent domain object has manifestation_ref and shaping_ref (both MemoryRef | None), and the shape_produced event payload carries this data, but the response schema and the shape_events_view projection do not surface them.
Fix.
ShapeEventResponse schema: Add manifestation_object_id (str | None), manifestation_version (int | None), shaping_object_id (str | None), shaping_version (int | None), produced_at (datetime | None).Scope. One migration, schema additions, projector update. ~150 LOC across schemas/routers/projector. 5–8 new tests.
Not built in Phase 21. At current scale the Operator knows what executors are registered because they registered them via API. The Create Shaping and Change Executor modals (§7, §9) accept typed references instead of a picker list. A proper executor registry listing endpoint is future work — see §19.
Page at /engagement/[id]/shaping. Wrapped in EngagementRoomLayout. Environment tint: env-shaping (#E6D4C5, warm ochre).
Room header: "Shaping" in {typography.h2}. Subtitle in {typography.body} with {colors.ink-faint}:
> Shapings form material from the Manifestation for specific consumers. Each Shaping has rules, an executor, and a name.
The page fetches the engagement's DeclaredShapeTypes and Shapings on load. Three states:
Each DeclaredShapeType from the seed is a section in the room. Section heading: the declared type's name in {typography.h3}. Below the heading, the declared type's description (from the seed) in {typography.body} with {colors.ink-faint}.
Active Shapings serving this declared type appear as cards within the section (§6). If no active Shaping serves this declared type, a prompt card appears:
> No Shaping has been created for this declared type yet.
With a "Create Shaping" primary button.
Sections are ordered as they appear in the seed.
Each active Shaping is a card ({components.card}) within its DeclaredShapeType section.
Card content:
{typography.body-em}.{typography.mono}.{typography.caption}. Display name is populated via Amendment A (Step 0).{colors.state-attest} dot. "Retired" with {colors.ink-faint} dot (for retired section).{typography.caption}.Action buttons (active Shapings only):
{components.button-primary}. Triggers shape production (§11).{components.button-secondary}. Opens amend modal (§8).{components.button-secondary}. Opens executor modal (§9).{components.button-ghost}. Confirmation flow (§10).Buttons appear only when the Shaping is active. Per "only show what is available."
Modal content:
{typography.caption}.{typography.h3}.{components.button-ghost}.{components.button-primary}.On success: the modal closes, the new Shaping card appears under its DeclaredShapeType section.
Note (Gap 3 deferral). A future phase may add a substrate endpoint for listing registered agents/skills, replacing the typed reference with a picker. At current scale, the Operator registered these executors via API and knows their identifiers.
Modal content:
{typography.caption}.{typography.h3}.{components.button-ghost}.{components.button-primary}.On success: the Shaping's version advances. The card updates to show the new version.
Modal content:
{typography.caption}.{typography.h3}.{components.button-ghost}.{components.button-primary}.On success: the Shaping's version advances. The card updates.
Note (Gap 3 deferral). Same as §7 — typed reference replaces picker until a future executor registry endpoint exists.
Clicking "Retire" on an active Shaping shows an inline confirmation (same pattern as the Discard action on held assertions in the Memory room — not a modal, an inline expansion):
> Retire this Shaping? It will no longer be available for shape production. Existing Shapes are preserved.
Reason — text input. Required.
"Confirm retirement" — {components.button-ghost}. "Cancel" — text link.
On success: the Shaping moves to the retired section (§13).
The "Produce Shape" button on an active Shaping card. When clicked:
Shape production is asynchronous. While in progress, the button shows a loading indicator ("Producing..."). The Shaping card shows a subtle loading state.
On completion, the new Shape appears in the Shaping's expanded Shape list (§12). The Shape count on the card updates.
On failure, an error message appears inline on the card.
Each Shaping card is expandable. The expanded view shows Shapes produced by this Shaping, ordered newest-first.
Each Shape entry shows:
{typography.caption}. Populated from manifestation_version (Amendment B, Step 0). If null (pre-amendment Shape), show "Against Manifestation v—".{typography.caption}. Populated from shaping_version (Amendment B, Step 0). If null, show "Shaping v—".{colors.state-attest} dot) or "Pending" (with {colors.ink-faint} dot).Shape entries are compact — one line per Shape. The full shaped content is not displayed inline. A future phase can add a Shape detail view.
Within each DeclaredShapeType section, retired Shapings appear in a collapsible block below active Shapings. Same pattern as Manifestation history:
"Show retired · [N]" toggle. Collapsed by default.
Retired Shaping cards show: name, last version, executor at retirement, retirement reason, historical Shape count. No action buttons. "Retired" state badge with {colors.ink-faint} dot.
The Shaping entry becomes clickable and navigable: link to /engagement/[id]/shaping.
The count displayed: number of active Shapings, or "0" if none exist.
The Shaping room badge becomes a clickable link to the Shaping room.
New proxy routes (CC confirms exact substrate paths):
| Frontend route | Substrate endpoint |
|----------------|-------------------|
| GET /api/engagements/[id]/shapings | List Shapings |
| POST /api/engagements/[id]/shapings | Create Shaping |
| PATCH /api/engagements/[id]/shapings/[sid] | Amend rules |
| PATCH /api/engagements/[id]/shapings/[sid]/executor | Change executor |
| DELETE /api/engagements/[id]/shapings/[sid] | Retire Shaping |
| POST /api/engagements/[id]/shapes/produce | Produce Shape |
| GET /api/engagements/[id]/shapes | List Shape events |
| GET /api/engagements/[id]/seed/declared-shape-types | List DeclaredShapeTypes |
CC confirms exact substrate paths and adjusts. Some of these may already exist as proxy routes from earlier phases. "Do not duplicate" applies.
Auto-mode posture: Step 0 auto. Steps 1–3 auto, Checkpoint A. Steps 4–6 auto, Checkpoint B (final).
Step 0 — CR archival, substrate amendments, pre-flight.
docs/phase-crs/phase-21-cr-shaping-room-ui-v0_2.md.
Commit (substrate repo): Phase 21 step 0: CR v0.2 archival and substrate amendments (agent display name, shape event lineage).
Step 1 — Shaping room page, DeclaredShapeType sections, proxy routes.
Create the page at /engagement/[id]/shaping wrapped in EngagementRoomLayout. Implement DeclaredShapeType section structure (§5). Create proxy routes (§15). Handle the three conditional states (§4.3).
Verification: lint + tsc + build clean. Room renders with DeclaredShapeType headings.
Commit (frontend repo): Phase 21 step 1: shaping room page and declared shape type sections.
Step 2 — Shaping cards and CRUD modals.
Implement Shaping cards (§6). Create Shaping modal (§7), Amend Rules modal (§8), Change Executor modal (§9), Retire flow (§10). Retired Shapings section (§13).
Verification: lint + tsc + build + test clean. Operator can create, amend, change executor, and retire Shapings.
Commit (frontend repo): Phase 21 step 2: shaping cards and CRUD modals.
Step 3 — Shape production and Shape list.
Implement shape production trigger (§11). Shape list under Shapings (§12). Loading states and error handling.
Verification: lint + tsc + build + test clean. Operator can produce a Shape and see it listed.
Commit (frontend repo): Phase 21 step 3: shape production and shape list.
Checkpoint A — Shaping room functional. All CRUD operations work. Shape production works. Shape list shows lineage (Manifestation version, Shaping version, timestamp). Operator confirms before wiring and final steps.
Step 4 — Room switcher, lobby wiring, component tests.
Room switcher Shaping entry becomes clickable (§14). Lobby badge links to room. Write component tests for Shaping cards and key interactions.
Verification: lint + tsc + build + test clean.
Commit (frontend repo): Phase 21 step 4: room switcher wiring and component tests.
Step 5 — Implementation notes and tagging.
Create docs/phase-impl-notes/phase-21-implementation-notes-v0_1.md.
Commit (substrate repo): Phase 21 step 5: implementation notes.
Checkpoint B — Final. Both repos green. Tag both repos as phase-21-shaping-room-ui.
Phase 21 is accepted when:
/engagement/[id]/shaping.
On acceptance: tag both repos as phase-21-shaping-room-ui. Write implementation notes.
/engagement/[id]/shaping live.GET /engagements/{eid}/executors/available) replaces the typed-reference modals in a future phase.
> Read the Change Request document at the path I supply below. This is
> CR-2026-035 v0.2, the Phase 21 Change Request (second version;
> v0.1 was archived but halted at pre-flight with display-readiness
> gaps). You are the executing agent named in the CR.
>
> CR path: ~/Downloads/phase-21-cr-shaping-room-ui-v0_2.md
>
> v0.2 resolves three pre-flight gaps from v0.1 (agent display name,
> shape-event lineage, executor schema) and defers one (executor list
> endpoint — typed reference UX instead). See §3A for the three Step 0
> substrate amendments. See "What changed from v0.1" for the full gap
> table.
>
> Code baseline: substrate repo at HEAD on main with v0.1 CR archived.
> Frontend repo at HEAD on main post-Phase-20. Substrate: 1124 tests,
> 2 skips. Frontend: lint + tsc + build + test clean.
>
> Run Step 0 per §16 and §3A:
> 1. Archive this CR (v0.2) alongside v0.1 in docs/phase-crs/.
> 2. Execute Amendment A (agent executor display_name).
> 3. Execute Amendment B (shape-event lineage fields — migration,
> projector, schema, tests).
> 4. Full substrate test suite green.
> 5. Pre-flight checks per §3.2.
>
> Then Steps 1–3 auto, Checkpoint A halts for smoke-test.
> Steps 4–5 auto, Checkpoint B halts for tagging.
>
> Implementation notes at Step 5:
> docs/phase-impl-notes/phase-21-implementation-notes-v0_1.md
DUNIN7 — Done In Seven LLC — Miami, Florida Phase 21: Shaping Room UI — CR v0.2 — 2026-04-27