Change Request — Conversational seed editor (revise via considerations) — v0.1

Document: cr-seed-editor-v0_1 Version: v0.1 Date: 2026-06-28 Type: Phase change request — engine + Operator Layer. This is the first piece of the seed-surface work that is a new capability (a new classifier intent + a conversational driver), not surfacing-what-exists. The substrate (versioning, corrections-preserved, revise_seed) is built; the intent, driver, and surface are new. Consumer: Claude Code (executor). Branch base: engine main @ 5ccc3d7; OL feat-companion-surface @ 86663aa (the seed-viewer is landed and verified; the editor extends it). Governing scoping note: loomworks-seed-viewer-scoping-note-v0_1 (the editor was named there as the next piece after the viewer) + this session's seed-editor decisions. Grounding: loomworks-seed-model-grounding-inspection-v0_1 + the seed-editor CR-drafting grounding pass (the revise_seed/considerations path, the classifier idiom, the authority gate, the viewer's SeedPayload baseline — engine @ 5ccc3d7, OL @ 86663aa).

Plain-language summary

You can see your engagement's seed now (the viewer). This lets you change it — by telling the Companion in plain words. You say "make the voice warmer and less clinical," the Companion proposes the revised wording, and you approve it in the conversation. The change becomes a new version of the seed; the old version is kept (the seed never overwrites — every version is preserved). Nothing changes until you approve. This first version edits the five core commitments (what the work is, who it's for, the voice, the constraints, the success conditions); editing contributors, agents, or extra assertions comes later.

What's true today (grounded)

The revision substrate is fully built — and reachable only through the considerations machinery:

• revise_seed (creation.py:229) takes prior_seed, an AmendedSeedFields object (per-field deltas, all optional + a required amendment_rationale), an amending_party, a consideration_id. It version-bumps (id same, version+1), records wasRevisionOf → the prior version, qualified with the consideration id and rationale. Corrections-preserved is automatic — the prior version is retained, never overwritten.
• It has exactly one caller and no thin entrypoint. The only path to revise_seed is: open_consideration(triggering_reason="contributor_initiated", assertions_in_scope=[MemoryRef(seed_id, seed_version)] …) → [optional advance_consideration_stage] → close_consideration(terminal_state="amend", amended_seed_fields=AmendedSeedFields(…), closing_party=<human>, _induction_agent, _agent_runner) → _close_seed_amend → amend_seed_with_induction → revise_seed. A conversational driver must reproduce exactly this sequence. "Pinning the seed" = naming the seed's MemoryRef in assertions_in_scope at open time.
• The authority gate is inherited for free, and strict. _close_seed_amend Gate 2 (considerations.py:893-901): closing_party.kind != "contributor" → SeedAmendmentAuthorisationError; and the closer must be in the seed's initial_contributors. Same shape as the commit gate (AgentCannotCommitError), stricter. The editor must NOT add its own check — it inherits the gate by closing through close_consideration. The human close IS the approval seam.
• No revision intent exists. The classifier (classifier.py:48-119) has no revise_seed/amend_seed/edit_seed intent. request_revision exists but targets specs/artifacts/drafts, not the seed apparatus. A new intent follows the four-part idiom (enum + handler + dispatch + instruction template), per ask_about_past_input/create_engagement_*.

The viewer gives a partial baseline (this bounds v1):

• fetchSeed → SeedPayload (seed.ts:35-43) carries the five editable commitment fields + version + seedId. Enough to revise the five commitments with no new fetch.
• It omits initial_contributors/initial_agents (UUIDs stripped by design), additional_assertions, and revision metadata. AmendedSeedFields can amend those — so editing them needs an extended payload, deferred (v1 is the five fields).
• AmendedSeedFields requires amendment_rationale — SeedPayload has no source for it. The conversational flow must collect the rationale (the "why" of the change). This is a real, named piece of the flow, not optional.
• The viewer's action row (SeedViewer.tsx:75, gated on state.kind === "ok") is where a "revise" affordance attaches.

Seed alignment

On the seed's spine. The seed is the engagement's foundation document; revising it is an Operator-authority, corrections-preserved act — both of which the substrate already enforces (the human-close gate; the automatic version-bump-and-retain). This CR adds the conversational way in to a capability the seed's own discipline already governs. The approve-in-conversation flow mirrors the add-side held→commit pattern (propose → human approves → commit) — the same human-approval shape applied to the seed. Nothing is revised without the human; nothing is overwritten.

The flow (decided — approve-in-conversation)

The decided shape (this session): the Companion proposes the revision conversationally; the Operator approves in the conversation; that approval is the human closing_party that closes the consideration with terminal_state="amend". Then the viewer re-fetches and shows the new version.

This mirrors the add-side held→commit gate and the create conversation — voice-first, the approval shape the Operator already knows. The alternative (approve-on-the-viewer, a document-diff approval surface) was set aside for consistency with the conversational, held→commit posture.

The turn-by-turn flow:

1. Trigger. The Operator says something like "make the voice warmer" / "change who this is for" / "add a constraint" — OR clicks the "revise" affordance on the viewer, which seeds a revise conversation. Either way the revise_seed intent classifies.
2. Propose. The Companion, given the current seed (the viewer's SeedPayload baseline) and the requested change, composes the proposed AmendedSeedFields — the changed field(s) + a drafted amendment_rationale — and presents the proposal in the conversation (shows the proposed new wording, names which field, states the rationale). It does NOT yet write anything. (Analogous to a held draft — proposed, not committed.)
3. Approve. The Operator approves in the conversation (a confirm turn / affordance). This is the human-gated moment. On approval, the driver runs the full considerations sequence — open (pinning the seed) → close(amend, the proposed fields, the human as closing_party, the induction agent + runner). The gate (_close_seed_amend Gate 2) enforces the human + contributor-membership requirement; the driver inherits it.
4. Confirm + re-render. On a successful close, revise_seed has version-bumped and preserved the prior version. The Companion confirms ("the voice is updated — version N"), and the viewer re-fetches to show the new version.

On rejection / refinement: if the Operator says "no, warmer than that" before approving, the proposal is re-composed (no consideration opened/closed yet — nothing written). Only approval opens-and-closes. (Mirrors the held-card refine-before-commit.)

Decisions (settled, grounded)

1. Conversational-first, approve-in-conversation (decided). Companion proposes, human approves in chat, the approval closes the consideration.
2. Fork A — wrap the considerations machinery, do not bypass it. The driver orchestrates open→[advance]→close; it does not lift the 409 (which is on creation, not revision) and does not reach revise_seed directly (there's no thin entrypoint, and bypassing would skip the authority gate and the version-bump provenance).
3. The authority gate is inherited, not rebuilt. The human close enforces it. The driver must perform the close with a human closing_party in the seed's initial_contributors. (Implication: the Operator must be a listed contributor on the seed — confirm at Step 0 that the Operator creating/owning an engagement is in initial_contributors; if an owner could be absent from that list, that's a gap to surface, not work around.)
4. v1 scopes the five commitment fields — what_the_work_is, who_consumes_the_work, voice_of_the_work, constraints (list), success_conditions. No new fetch needed (the viewer's SeedPayload provides them). Editing initial_contributors/initial_agents/additional_assertions is deferred (needs an extended payload; named, not built).
5. amendment_rationale is collected in the flow — required by the substrate; the Companion drafts it from the Operator's stated reason ("warmer, less clinical" → rationale), shown in the proposal. If the Operator's request carries no clear reason, the Companion asks. Not optional.
6. constraints is a list — the editor handles add/remove/edit of list items, not a single text blob.

Scope boundary — what this does NOT do

• No editing of contributors/agents/additional-assertions — deferred (extended payload needed).
• No approve-on-the-viewer diff surface — approval is conversational (the viewer shows the result, not a pre-approval diff).
• No bypass of considerations — the driver wraps the real machinery; the authority gate and version provenance are inherited.
• No new authority check — the substrate's human-close gate is the seam.
• No merge to main — lands on feat-companion-surface; merge is a separate (and increasingly weighty) authorization.

The build — steps

Per-step commits, suite green at each, halt-before-push. Engine + OL.

Step 0 — inspect before building (no code) — heaviest Step 0 of the arc

Confirm against engine 5ccc3d7 / OL 86663aa:

1. The owner-in-initial_contributors question (Decision 3 implication). Confirm that the Operator who owns/created an engagement IS in the seed's initial_contributors — because the close gate requires the closer be a listed contributor. Trace a real engagement (e.g. Goosey/E0007): is Marvin in E0007's seed initial_contributors? If an owner can be absent from that list, the editor would refuse a legitimate owner's revision — surface this as a finding before building, do not work around it.
2. The induction agent + runner the close requires. close_consideration(terminal_state="amend", …) needs _induction_agent + _agent_runner. Where do these come from on a normal request path — are they already constructed somewhere the driver can obtain them, or does the driver assemble them? Show the real source (how does any existing seed-amend close get them today, if any path exercises it).
3. The four-part intent idiom, traced live against ask_about_past_input (read-class) AND create_engagement_ (commit/proposer-class, the closer analog): the enum entry + gloss, the _route_ handler shape, the route_intent dispatch branch, the instruction template. The seed editor is a proposer-then-human-close flow — closer to create_engagement_* (which proposes then commits) than to the read-only recall. Confirm which template to mirror.
4. How a multi-turn propose→approve flow is held across turns. The add-side held→commit holds a proposed state between turns (the held card). Does an analogous "proposed but not yet approved" carrier exist the seed-revise proposal can reuse, or does the proposal live in conversation state until approval? (The proposal must survive from the propose turn to the approve turn without writing anything.) Show the add-side held mechanism as the reference.
5. The viewer attach point — SeedViewer.tsx:75 action row; how the "revise" affordance seeds a revise conversation (does it send a converse turn with an intent hint, like the create page's intent_hint? — ChatView create-mode is the reference).

Report findings — especially Step 0.1, which could be a blocking finding — then build.

Step 1 — Engine: the revise_seed intent + handler (propose side)

• Add revise_seed to IntentLabel (classifier.py:48) + its gloss + the intent_classifier.md mirror, with examples ("make the voice warmer," "change who this is for," "add a constraint that…").
• _route_revise_seed handler (router.py, mirroring create_engagement_* proposer shape) — given the engagement + the Operator's requested change, composes the proposed AmendedSeedFields (changed fields + drafted amendment_rationale) and returns it as a proposal (operation_data carrying the proposed amendment), NOT a write. The proposal is presented to the Operator; nothing is opened/closed yet.
• Dispatch branch in route_intent (router.py:2673).
• intent_instructions/revise_seed.md instruction template — how the Companion composes the proposed fields + rationale and presents them.

Suite expectation: the intent classifies ("make the voice warmer" → revise_seed, not request_revision or general_conversation); the handler composes a proposed AmendedSeedFields with a rationale; nothing is written (no consideration opened). Tests for classify + propose-without-write.

Step 2 — Engine: the approve→close orchestration (write side)

• On the Operator's approval turn, the driver runs the considerations sequence: open_consideration(contributor_initiated, pinning the seed's MemoryRef) → close_consideration(terminal_state="amend", amended_seed_fields=<the proposed fields>, closing_party=<the human Operator>, _induction_agent, _agent_runner).
• The close inherits the authority gate (_close_seed_amend Gate 2) — no new check.
• On success: the new version exists (version-bumped, prior retained); the Companion confirms ("updated — version N").
• The proposed fields must carry from the propose turn (Step 1) to the approve turn — per the Step-0.4 holding mechanism.

Suite expectation: approval opens-and-closes the consideration, revise_seed bumps the version and records wasRevisionOf, the prior version is retained (assert both versions exist), the authority gate refuses an agent/non-contributor closer (assert SeedAmendmentAuthorisationError), and a pre-approval refine does NOT write. End-to-end test against a real engagement seed in the DB (the standing lesson — not a green suite alone; prove the version actually bumped and the prior survived).

Step 3 — OL: the viewer "revise" affordance + conversational confirm

• A "revise" affordance in SeedViewer.tsx:75 (gated on state.kind === "ok"), styled with the action-row vocabulary — seeds a revise conversation (an intent_hint-style opener, per the ChatView create-mode reference).
• The conversational propose→approve renders in the existing transcript (the Companion's proposal turn shows the proposed change + rationale; the Operator's approval is a confirm turn/affordance — reuse the held-card confirm pattern if it fits, per Step 0.4).
• On success, the viewer re-fetches (fetchSeed) and shows the new version.

Suite expectation: the revise affordance renders on the loaded viewer; clicking it opens the revise flow; an approved revision re-renders the viewer at the new version. Component/surface tests.

Acceptance

• An Operator can revise the seed by conversation. "Make the voice warmer" → the Companion proposes the revised voice + a rationale → the Operator approves in the conversation → a new seed version exists, the prior version preserved, the viewer shows version N.
• Nothing is written without approval. A proposal that is refined or rejected before approval opens/closes no consideration and writes nothing.
• The authority gate holds — the close is human-gated (an agent/non-contributor closer is refused with SeedAmendmentAuthorisationError); the editor adds no check of its own.
• Corrections-preserved — proven against a real engagement: after a revision, BOTH versions exist in the event log, the new one carries wasRevisionOf → the prior, with the rationale.
• v1 scope — the five commitment fields are editable; contributors/agents/additional-assertions are not (deferred, no UUID surface).
• Real data, end-to-end — verified against a real engagement seed (the standing lesson: prove the version bumped in the DB, not just a green suite).
• Suite green at each step; engine + OL typecheck + lint + vocabulary-wall clean.
• (Pre-existing tsc errors at the 86663aa baseline — the 3 TagChipArea + 1 RefreshFocusOnIntent — are not this CR's.)

What this sets up / depends on (named)

• Depends on: the seed viewer (landed, verified) — the editor attaches to it and reuses its baseline.
• Sets up: the generator integration (a generated seed flows into a real engagement; the revise machinery is how it's refined post-creation) and future membership/assertion editing (the extended-payload v2).
• The feat → main merge weight. This CR, when built, adds the fifth (and largest) piece to feat-companion-surface. The merge decision is increasingly weighty — flagged, not part of this CR.

DUNIN7 — Done In Seven LLC — Miami, Florida Change Request — Conversational seed editor (revise via considerations) — v0.1 — 2026-06-28 Adds a revise_seed intent + a conversational driver that proposes AmendedSeedFields (incl. the required rationale), and on the Operator's in-conversation approval orchestrates the considerations open→close that version-bumps the seed and preserves the prior version. The authority gate (human + contributor-membership) is inherited from the considerations close, not rebuilt. v1 edits the five commitment fields; the viewer's affordance seeds the flow. Engine 5ccc3d7 + OL 86663aa. Step 0.1 (owner-in-initial_contributors) is a potential blocking finding to confirm first.