Version. 0.1
Date. 2026-06-09
Status. Feature note. Records a capability that is fully built but had no standalone record artifact — seed modification, the operations that change a seed after it exists. Covered until now as principle (architecture specification §02: "corrections to the seed are governance-bearing operations") and as practice (the candidate seed's own versioning discipline), but not written up as a feature in one place. This note closes that gap. Operator-facing. HTML primary, Markdown source alongside.
Author posture. Descriptive — this records built behaviour, grounded against engine code on main (a2d760b). Where a behaviour is a governance discipline rather than a mechanical step, the discipline is named.
Grounded against. loomworks-engine on main: the seed routes in src/loomworks/api/engagements.py, the seed models in src/loomworks/api/schemas.py, the candidate-amendment handler in creation.py, the committed-amendment orchestration in seed_amendment.py, and the consideration-close dispatch in considerations.py. Reads the architecture specification §02 and the candidate seed v0.12 as the governing principle/practice.
A seed is an engagement's frame of reference — what the work is, who it's for, the voice, the constraints, what done looks like. Seeds are not fixed once written; they can be modified. How they're modified depends on whether the engagement has been committed yet, and the difference is deliberate.
Before an engagement commits, its seed is a candidate — still being shaped. Amending it is a direct, ordinary operation: change any of the eight seed fields, leave the rest as they are, and a new version lands. This happens repeatedly during the back-and-forth of getting a seed right before commit.
After an engagement commits, its seed is governance-bearing — the engagement and its Memory rest on it — so amending it is not a casual edit. It goes through a ceremony: a consideration is opened, the amendment carries a written rationale, and the amended seed is re-run through induction. The engagement only moves to the new seed if induction converges; if it doesn't, the engagement stays on its existing seed and the attempted amendment is preserved as history. Only the engagement's founding committer can trigger this.
Both paths version the seed — every amendment is a new version of the same seed, and the revision chain is kept. Nothing is overwritten; the trajectory is preserved.
A seed before commit and a seed after commit are the same artifact at different stakes.
A candidate seed is a draft. Nothing rests on it yet — no committed Memory, no active engagement. Getting it right is iterative: draft, induct, see what's missing, amend, induct again. Amendment here should be frictionless, because the whole point of the candidate stage is to converge a good seed before anything depends on it.
A committed seed is load-bearing. The engagement is active; assertions have been contributed against this frame; Manifestations and Shapings have been derived assuming it. Changing it is a governance event, not an edit — it can invalidate downstream work and it changes the frame every future contribution is read against. So amendment here is gated, rationalized, re-inducted, and authorized.
The architecture specification §02 names this principle directly: the seed evolves with the engagement; corrections to the seed are governance-bearing operations. The two paths are how that principle is built — frictionless where nothing rests on the seed, ceremonial where everything does.
Route. POST /engagements/{engagement_id}/seed — "amend a candidate seed." Handler: amend_candidate_seed.
What can change. Eight fields, each optional — an omitted field carries forward unchanged, so an amendment touches only what it names:
what_the_work_iswho_consumes_the_workvoice_of_the_workconstraintssuccess_conditionsinitial_contributorsinitial_agentsadditional_assertions
The guard. The route loads the seed only if the engagement is in candidate state; if it is anything else, the route returns a 409 conflict ("seed operations require candidate state"). So this path cannot touch a committed engagement's seed — the candidate path and the committed path are kept strictly apart at the door.
Versioning. Each amendment writes a new seed version — same seed id, version incremented. The amendment chain (revise_seed → v2, v3, …) is preserved.
Lifecycle. This is a plain Engine operation, iterated across induction cycles. The typical rhythm before commit: draft the seed, run induction (POST /engagements/{engagement_id}/seed/induct), read the findings, amend, induct again — until the seed converges and the engagement is ready to commit.
A committed seed is amended only through a consideration, never through a direct route. The candidate route's own guard enforces this: once the engagement leaves candidate state, the direct route refuses, and the route's description points the caller to the consideration path.
The mechanism. Seed-amendment closures flow through close_consideration: when a consideration with a seed in scope is closed, the dispatcher selects the seed-amendment handler. The amendment carries AmendedSeedFields — the same eight modifiable fields as the candidate path, plus a required amendment_rationale, so a future reader of the seed's revision chain can see why each revision happened.
Re-induction and convergence gating. The orchestration (amend_seed_with_induction) does three things in order:
So a committed seed cannot be changed into an incoherent state: the amendment must survive re-induction to take effect. A failed amendment is recorded, not silently dropped, and it does not move the engagement.
Authorization. This path is restricted to the engagement's founding committer — the person whose commit established the engagement. Seed-amendment triggering and induction are gated on created_by_person_id. Dedicated error codes mark the failure modes: seed_amendment_trigger_restricted (not the founding committer), seed_amendment_authorisation_failed, and seed_amendment_induction_divergent (the amendment didn't converge).
Why a ceremony, not a route. Opening a consideration makes the amendment a deliberate, recorded episode with a rationale — it sits in the engagement's governance trail, not in an edit history. This is the Operator-authority and Discovery disciplines applied to the most load-bearing artifact in an engagement: the change is surfaced, reasoned, re-validated, and authorized, and the prior seed is preserved.
seed_amendments as a tracked quantity.
Seed amendment is an Engine capability, not a Companion-exclusive one — the routes and the consideration ceremony are Engine primitives any authorized caller reaches. The Companion makes it pleasant where it touches conversation: amendment content can be authored conversationally and committed via the brief path (seed_commit_from_brief), and a candidate seed is substantially shaped through the conversational creation flow. But the amendment mechanics — the candidate route, the consideration ceremony, the re-induction, the founding-committer gate — are the Engine's, and they hold whether the caller is the Companion or an Operator working Operator-direct. This is consistent with the founding axiom: the Companion never does anything the raw API cannot; it only makes the API pleasant.
When the agent driver exists (specified in the Companion functional specification §9, deferred to the OVA/vprogs substrate), a delegated agent acting as Companion could in principle trigger operations on the Operator's behalf. Committed-seed amendment is the most governance-heavy of these — founding-committer-gated, ceremony-bound. Whether, and how, an agent's delegation contract may include so governance-bearing an operation is an open design question, not addressed by the current delegation-contract design or the seed-amendment code. It is recorded here and in the queued-directions document as a seam to resolve when the agent driver is scoped for build — not a present gap, since the agent driver is not yet built.
Built. Candidate-seed amendment (Phase 25) and committed-seed amendment (Phase 6), both with versioning, the strict candidate/committed guard, re-induction-and-convergence gating on the committed path, and founding-committer authorization. Grounded against engine main a2d760b.
Documented. This note (the standalone feature record); the architecture specification §02 (the governance-bearing principle); the candidate seed v0.12 (the versioning-and-amendment practice).
Open seam. Agent-delegation-meets-seed-amendment (§6) — recorded in queued-directions, to be taken up with the agent-driver build.
DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks — seed modification — feature note — v0.1 — 2026-06-09