Version. 0.2
Date. 2026-04-27
Author. Marvin Percival (DUNIN7), prepared via Claude.
Target. /Users/dunin7/loomworks (substrate) and /Users/dunin7/loomworks-ui (frontend) on DUNIN7-M4 (MacMini).
Priority. Standard.
Confidential. Internal.
Supersedes. CR-2026-033 v0.1. v0.1 did not include the organization rationale. v0.2 adds a rationale field to the ordering structure: the AI explains its grouping logic alongside the groups, so the Operator evaluates the reasoning rather than auditing every assertion placement.
Companion to. Phase 19 scoping note v0.1, Phase 11 CR v0.1 (Manifestation substrate), Phase 18 CR v0.2 (Manifestation room UI), methodology v0.18.
Status. Second draft. Adds organization rationale (prompt, data model, display). All other content unchanged from v0.1 except sections noted in the changelog.
Phase 19 transforms the Manifestation from a bookmark into an organized body of knowledge. An AI reads the seed and all committed assertions at the engagement-version, then produces a grouped, labeled ordering of assertion references with a rationale explaining the organizing logic. That ordering and rationale are stored on the Manifestation and displayed in the Manifestation room. Shapings consume Memory through this ordering rather than encountering assertions in contribution-time sequence.
The rationale enables the Operator to evaluate the organization at scale. With 12 assertions the Operator can check every placement. With 200, they cannot — but they can read a paragraph explaining why the AI chose these groups, what principle it followed, and how the material was distributed. The Operator evaluates the logic, not every placement.
The work has three substrate components (ordering storage, LLM organization service, integration into preview/derive) and two frontend components (organized display in the Manifestation room, proposed ordering in the preview modal).
Layer 1 — Methodology document v0.18. The Manifestation is the product of the second step in the pipeline. Memory accumulates haphazardly; the Manifestation organizes it. The methodology says the Manifestation is derived from Memory — Phase 19 makes "derived" mean "read, understood through the seed, and organized" rather than "bookmarked."
Layer 2 — Reference Design v0.1.2. S-3 (the comprehensive manifestation): the Manifestation captures all of Memory at a point in time. Phase 19 adds that it captures it in an organized form.
Layer 3 — Playground Specification v0.10. Sec-C.1 (Manifestation derivation). The spec does not prescribe the internal structure of the Manifestation; Phase 19 makes an implementation choice about what derivation produces.
phase-18-manifestation-room-ui. 1110 tests, 2 environment-gated skips.phase-18-manifestation-room-ui. Lint + tsc + build clean. Eleven surfaces.CC confirms before Step 1:
uv run pytest -v reports 1110 passed, 2 skipped.alembic heads shows a single head. CC notes the next migration number.derive_manifestation function is located. Phase 19 modifies it to include the LLM organization step.preview_manifestation function (or equivalent) is located. Phase 19 modifies it to produce a proposed ordering.organized_groups field (or equivalent name — CC confirms the naming convention).get_api_key(engagement_id, "anthropic", db) or equivalent. CC confirms the function signature.
Archive this CR to docs/phase-crs/phase-19-cr-organized-manifestation-v0_2.md at Step 0 before Step 1 begins.
The Manifestation gains a field organized_groups (nullable JSON). The structure is defined in Section 5. Nullable for backward compatibility — Phase 18 Manifestations have organized_groups = None and display gracefully (Section 11).
The preview endpoint calls the LLM to produce the proposed ordering. The preview response includes the proposed groups and rationale. When the Operator confirms, the derive endpoint stores the ordering that was previewed — it does not re-run the LLM. Implementation options: (a) the preview returns the ordering in the response, the frontend sends it back in the derive request body; (b) the preview stores a transient cache keyed by engagement + engagement-version, and derive reads from it. CC decides the implementation — the constraint is: the Operator sees exactly what gets stored.
The organization prompt is specified in Section 6. It is a system prompt + user message pair. The prompt is part of the CR because the quality of the organization depends on it, and the Operator should be able to review it.
The AI produces a brief rationale explaining its grouping logic: what organizing principle it followed (derived from the seed), how it distributed assertions, and why. The rationale is stored alongside the ordering and displayed in the Manifestation room and the preview modal. The Operator evaluates the logic of the grouping, not every individual placement.
class AssertionRef(BaseModel):
assertion_id: UUID
version: int
class ManifestationGroup(BaseModel):
label: str
assertion_refs: list[AssertionRef]
class ManifestationOrdering(BaseModel):
rationale: str
groups: list[ManifestationGroup]
The rationale field is a plain-language paragraph (1–4 sentences) explaining the AI's organizing logic.
After the LLM produces the ordering, the system validates:
rationale field is present and non-empty.If validation fails, the derivation fails with an error. The Operator can retry (the LLM may produce a valid ordering on the next attempt).
You are organizing the Memory of a Loomworks engagement into logical groups.
You will receive:
1. The engagement's seed — this establishes the purpose of the engagement and why the assertions exist.
2. A list of committed assertions — these are pieces of knowledge contributed by people, each with an ID and content.
Your task: organize these assertions into labeled groups that structure the knowledge logically, and explain your reasoning.
Rules:
- Every assertion must appear in exactly one group. Do not drop any assertion.
- Use the seed's purpose as your organizing principle. The groups should reflect the facets of the engagement's subject matter.
- Order assertions within each group so that related assertions are adjacent and the group reads coherently from top to bottom.
- Order the groups themselves so that foundational knowledge comes before derived or applied knowledge.
- If an assertion does not fit any logical group given the seed's purpose, place it in a group labeled "Uncategorized" at the end.
- Use one level of grouping only. No sub-groups.
- Aim for 2-7 groups. Fewer than 2 means the grouping is not useful. More than 7 means the groups are too fine-grained. Adjust based on the number and diversity of assertions.
- Group labels should be plain language, not technical jargon. They are for human readers.
Write a brief rationale (1-4 sentences) explaining:
- What organizing principle you followed (derived from the seed's purpose).
- How you distributed the assertions across groups.
- If any assertions were placed in "Uncategorized" and why.
Respond with JSON only. No preamble, no markdown fences, no explanation outside the rationale field. The JSON structure:
{
"rationale": "Brief explanation of the organizing logic.",
"groups": [
{
"label": "Group label here",
"assertion_ids": ["uuid-1", "uuid-2"]
}
]
}
The assertion_ids array within each group is ordered — the first assertion in the array should be read first.
## Seed
{seed_content}
## Assertions
{for each assertion:}
ID: {assertion_id}
Content: {assertion_content}
{end for}
claude-sonnet-4-20250514 (or the latest Sonnet available — CC confirms the model string from the Anthropic SDK).
The LLM returns JSON. The system parses it, extracts rationale, maps assertion_ids to AssertionRef objects (looking up the current version of each assertion at the engagement-version), and validates per Section 5.3. If the LLM returns malformed JSON or the response fails validation, the preview returns an error and the Operator can retry.
The existing preview endpoint gains an LLM call. The flow:
ManifestationOrdering (with rationale and groups).
The preview response gains a new field: proposed_ordering: ManifestationOrdering | None. For engagements with no committed assertions, proposed_ordering is None (nothing to organize).
The derive endpoint stores the ordering. Implementation per D2 — the ordering that was previewed is what gets stored. The derive request body gains a field for the ordering, or the derive endpoint reads it from a preview cache. CC decides the mechanism.
The Manifestation's organized_groups field is populated with the ordering JSON (including the rationale).
On re-derivation, the preview produces a fresh ordering (S5 — fresh each time). The new Manifestation stores the new ordering. The prior Manifestation's ordering and rationale are preserved (part of the superseded Manifestation's data).
The Manifestation gains organized_groups: dict | None = None. This is the JSON structure from Section 5.1, stored in the Manifestation's event payload. Default None for backward compatibility.
One migration: adds organized_groups to the manifestation_view projection (if the view materializes this field) or confirms the field passes through the existing JSONB payload mechanism. CC determines whether a migration is needed based on how the Manifestation's data flows through memory_events → current_memory_objects → manifestation_view. If the field lives in the JSONB payload and the views already pass through arbitrary payload fields, no migration is needed — just the model change.
ManifestationResponse gains organized_groups: ManifestationOrdering | None = None.
The preview response gains proposed_ordering: ManifestationOrdering | None = None.
When a Manifestation has organized_groups (not null), the room's main content area shows the organized assertions.
Layout:
{typography.body} with {colors.ink-faint}, styled in italic per the brand's considered temperament. This is the first thing the Operator reads after the metadata — it explains the logic of what follows.{typography.h3}.{components.card}), each showing:{typography.body}.#N) in {typography.mono}.{typography.caption}.The compact header shows: "Version [N] · [total assertion count] assertions in [group count] groups · Derived [timestamp] by [name]".
The preview modal from Phase 18 gains the proposed ordering display. When the preview response includes proposed_ordering:
Modal content:
{typography.caption}.{typography.h3}.{typography.body}, italic. This is the first content in the modal body — the Operator reads the reasoning before seeing the groups.{typography.body-em}.{typography.caption}.Modal actions:
{components.button-ghost}.{components.button-primary}.
The Loomworks engagement already has a Manifestation (Version 1, derived during Phase 18 testing) with organized_groups = None. The Manifestation room must handle this:
organized_groups is null, display the Phase 18 summary card (assertion count, relationship count, derived-at, derived-by). No organized view. No rationale.The LLM call requires an Anthropic API key on the engagement. If no key is configured:
/engagement/[id]/settings.
test_organize_assertions — Unit test the organization service. Mock the LLM response (including rationale). Verify the output is parsed into ManifestationOrdering with correct group structure and rationale.
test_organize_assertions_validation — Mock LLM responses with: missing assertions, duplicate assertions, unknown assertion IDs, empty rationale. Verify validation catches each.
test_organize_assertions_uncategorized — Mock an LLM response with an "Uncategorized" group. Verify it is accepted and placed last.
test_organize_assertions_malformed_json — Mock a malformed LLM response. Verify the service raises an appropriate error.
test_preview_with_ordering — Call the preview endpoint for an engagement with committed assertions and a configured API key (LLM mocked). Verify the response includes proposed_ordering with groups and rationale.
test_preview_no_assertions — Call preview for an engagement with no committed assertions. Verify proposed_ordering is None.
test_preview_no_api_key — Call preview for an engagement without an Anthropic key. Verify appropriate error (503 or 422).
test_derive_stores_ordering — Preview (mocked LLM), then derive. Verify the stored Manifestation has organized_groups populated with the previewed ordering and rationale.
test_derive_backward_compatible — Verify Phase 18 Manifestations (no ordering) are retrievable and return organized_groups: null.
test_rederive_fresh_ordering — Derive once. Add an assertion. Re-derive (mocked LLM returns different ordering and rationale). Verify the new Manifestation has the new ordering and the superseded one retains its original.
Auto-mode posture: Steps 1–4 auto, Checkpoint A. Steps 5–7 auto, Checkpoint B (final).
Step 0 — Pre-flight and CR archival.
Archive this CR. Run pre-flight checks (Section 3.2).
Commit: Phase 19 step 0: CR archival and pre-flight.
Step 1 — Ordering data model and migration (if needed).
Add organized_groups field to the Manifestation model. Create migration if needed (Section 8.2). Update ManifestationResponse schema.
Verification: uv run pytest -v green. Existing Manifestation tests pass (backward compatible).
Commit: Phase 19 step 1: ordering data model.
Step 2 — Organization service.
Implement the LLM organization service: prompt construction (Section 6), LLM call, response parsing (including rationale), validation (Section 5.3). The service takes seed content + assertions → returns ManifestationOrdering. Write tests (Section 13.1: test_organize_assertions, test_organize_assertions_validation, test_organize_assertions_uncategorized, test_organize_assertions_malformed_json).
Verification: uv run pytest -v green.
Commit: Phase 19 step 2: organization service.
Step 3 — Integrate into preview and derive.
Modify the preview endpoint to call the organization service and return proposed_ordering (with rationale). Modify the derive endpoint to store the ordering. Write tests (test_preview_with_ordering, test_preview_no_assertions, test_preview_no_api_key, test_derive_stores_ordering, test_derive_backward_compatible, test_rederive_fresh_ordering).
Verification: uv run pytest -v green.
Commit: Phase 19 step 3: preview and derive with ordering.
Checkpoint A — Substrate complete. LLM organization service tested (mocked). Preview returns proposed ordering with rationale. Derive stores it. Backward compatible with Phase 18 Manifestations. Operator confirms before frontend work begins.
Step 4 — Organized display in Manifestation room.
Update the Manifestation room to display organized assertions when organized_groups is present (Section 9). Show rationale in italic below the header. Implement the graceful fallback for Phase 18 Manifestations (Section 11). Implement the API key requirement messaging (Section 12).
Verification: lint + tsc + build clean.
Commit (frontend repo): Phase 19 step 4: organized manifestation display with rationale.
Step 5 — Preview modal with proposed groups and rationale.
Update the preview modal to show the rationale first, then proposed group labels and assertion counts (Section 10). Expandable assertion content within groups.
Verification: lint + tsc + build clean. Operator can preview a derivation, read the rationale, see proposed groups, then confirm.
Commit (frontend repo): Phase 19 step 5: preview modal with rationale and proposed groups.
Step 6 — Implementation notes and tagging.
Create docs/phase-impl-notes/phase-19-implementation-notes-v0_1.md.
Commit (substrate repo): Phase 19 step 6: implementation notes.
Checkpoint B — Final. Both repos green. Tag both repos as phase-19-organized-manifestation.
Phase 19 is accepted when:
On acceptance: tag both repos as phase-19-organized-manifestation. Write implementation notes.
> Read the Change Request document at the path I supply below. This is
> CR-2026-033 v0.2, the Phase 19 Change Request (second version;
> v0.1 did not include the organization rationale). You are the
> executing agent named in the CR.
>
> CR path: ~/Downloads/phase-19-cr-organized-manifestation-v0_2.md
> (confirm the latest approved version if more than one is present in
> Downloads).
>
> v0.2 drafts against the Phase 19 scoping note v0.1 (seven settled
> decisions S1–S7) plus an eighth decision (D4, rationale) settled
> after the scoping note was written. This phase adds LLM-based
> assertion organization with rationale to Manifestation derivation.
>
> Code baseline: tag phase-18-manifestation-room-ui on both repos.
> Substrate: 1110 tests, 2 skips. Frontend: lint + tsc + build clean.
>
> Run pre-flight (Step 0) per Section 3.2. CRITICAL: confirm the
> derive_manifestation and preview_manifestation function locations,
> the Manifestation data model, the API key store access pattern, the
> seed content retrieval pattern, and the assertion query pattern for
> version-pinned reads. The organization prompt is specified in §6 —
> implement it as written, including the rationale instruction.
>
> Per Section 3.3: archive this CR to
> docs/phase-crs/phase-19-cr-organized-manifestation-v0_2.md at Step 0.
>
> Per Section 14, seven steps with two checkpoints. Auto-mode posture:
> Steps 1–4 accept auto-mode-proceed; Checkpoint A halts until
> Operator confirms. Steps 5–7 auto; Checkpoint B (final) halts for
> tagging.
>
> The LLM is mocked in all substrate tests. Integration testing
> (with a real Anthropic key) happens at Checkpoint A when the
> Operator smoke-tests the preview endpoint manually.
>
> Pre-flight surprises stop at Step 0 and drive a CR v0.3 revision.
>
> Implementation notes at Step 6:
> docs/phase-impl-notes/phase-19-implementation-notes-v0_1.md
v0.2 (2026-04-27). Added organization rationale (D4). ManifestationOrdering gains rationale: str. Prompt (Section 6.1) gains rationale instruction. Validation (Section 5.3) gains non-empty rationale check. Frontend display (Section 9.1) shows rationale in italic below the header. Preview modal (Section 10) shows rationale as first content in modal body. Test suite (Section 13.1) updated for rationale validation. Acceptance gate (Section 15) gains items 3 and 6 for rationale. Test projection updated to ~10 (was ~9).
v0.1 (2026-04-27). Initial draft. Seven scoping decisions consumed. Organization prompt specified. Ordering structure, preview/derive integration, frontend display, test suite. No rationale field.
DUNIN7 — Done In Seven LLC — Miami, Florida Phase 19: Organized Manifestation — CR v0.2 — 2026-04-27