sow: sovereign-agent-v1-unit11-store-expansion-pilot-start
project: sovereign-agent
unit: 11
status: ACCEPTED
authority: principal
base_commit: e9a067087b8cd09f33d046b9402f4c0976167c5e
governing_documents:
- docs/sows/sovereign-agent-v1-educational-control-plane.md (sequencing amendment 6)
- docs/rulings/2026-08-30-unit11-scope.md (Unit 11 scope ruling, all six holdings binding)
- docs/rulings/2026-08-30-unit11-local-closure-supersedes-real-deployment-gate.md
(withdraws the real-deployment pilot-start gate this document's own §4 and
"Final Unit 11 closure conditions" originally required; Unit 11 closes on
the merged, reviewed implementation operating against local,
learner-controlled SQLite -- no real pilot-start act, governance receipt,
or production deployment required)
work_branch: unit-11/store-expansion-pilot-start
runtime: Python 3.14
runtime_dependencies:
- pydantic
This SOW is the Principal’s implementation direction for Unit 11, incorporating the
Principal’s Unit 11 scope ruling (docs/rulings/2026-08-30-unit11-scope.md) in full.
Filing and reviewing this SOW does not, by itself, authorize implementation — the same boundary Unit 10’s own SOW had to state explicitly after an earlier correction, restated here from the start rather than discovered by review. Merging this SOW establishes the reviewed implementation contract; it does not start implementation.
The sequence is:
main. Merging establishes the contract; it does not start
implementation.main from a clean clone, confirming the merge introduced no drift
from the reviewed head.e9a06708 if main has advanced past this SOW’s own merge.A second, independent authorization gate governs the real pilot-start act
specifically (Holding 1 of the governing ruling): even after Unit 11’s
implementation is itself merged, gated, and verified on clean main (the “Review
and merge ritual” steps below, through step 10), the real pilot-start act against
the named pilot organization requires its own separate Principal authorization,
distinct from and later than implementation authorization. This document’s own
status stays PROPOSED, and Unit 11 is not closed, until that separately-
authorized real pilot-start act executes and its durable governance receipt is
filed — implementation being merged and verified on main is necessary but not
sufficient for this document’s ACCEPTED flip or for Unit 11’s closure. See
“Review and merge ritual” steps 11-14 for the exact closing sequence this
requires.
A changed SOW head invalidates an earlier co-sign. Branch reconciliation must use an
allowed, auditable PR-based mechanism; do not substitute a local history rewrite for
the denied git rebase, git merge, or force-push mechanisms.
Close the three components the governing ruling authorized:
inventory.changed -> wake gate -> Pulse ->
replenishment pipeline generalizes without inventing new signal kinds, effect
kinds, or core organizational primitives.Unit 11 does not perform the real pilot start, does not run credentialed provider smokes, does not conduct the Andrea live evaluation, does not claim pilot completion or proof-pack acceptance, and does not release. All of that remains Unit 12’s, per the governing ruling’s Holding 4 and the boundary collected in that ruling’s own grounding.
Terminology, per the governing ruling’s Holding 5, binding on this SOW and its
own deliverables, not merely a note for future work: this document and everything
it produces uses “30-day Store pilot” for the operational production run this
unit’s mechanism starts, “Andrea live evaluation” when referring to Unit 12’s
own future timed human learner session (never “soak” unqualified), and, if the
unrelated v0.6-era concept needs mentioning at all, “v0.6 infrastructure soak”
by its full name. Historical docs/v0.6-soak.md and site/v0.6-soak/ remain
untouched by this unit.
Expand src/reference_organizations/store/__init__.py’s seed() (currently
:59-76, hardcoding exactly one Product(sku="SKU-TEA", ...)) into a small
catalog of at least two distinct SKUs, each with independent stock levels and
reorder points, and independent supplier/replenishment routing where the existing
model already permits it.
Minimum accepted behavior, verbatim from the governing ruling:
inventory.changed -> wake gate -> Pulse -> replenishment
vocabulary remains intact.Do not add new signal kinds, effect kinds, governance concepts, or core
organizational primitives merely to make the expansion appear larger. The point
is proving the accepted pipeline generalizes, not inventing new production
surfaces. If a design choice would require touching src/sovereign_agent/ core
primitives beyond what multi-SKU support genuinely requires, stop and report — that
is a stop condition, not a judgment call to make silently.
This is not a nice-to-have; the governing ruling and the Principal’s authorization of this SOW both name it as a binding acceptance requirement. Prove, with real tests, not prose:
record_sale’s signal-per-occurrence discipline (Unit 9’s
own fix, src/reference_organizations/store/__init__.py’s dedupe_key
suffixing) extends correctly to multiple SKUs — no signal for SKU A can be
conflated with, replace, or be replaced by a signal for SKU B.store_wake_gate,
src/reference_organizations/store/pulse_gate.py) correctly maps each qualifying
signal to exactly the one outcome for its own SKU — never a different SKU’s
outcome, never an ambiguous match across SKUs.pulse_wake_decisions/pulse_origins structured
attribution chain (established in Unit 9, docs/v1-unit9-pulse-proactive-work.md)
correctly distinguishes concurrent or sequential decisions for different SKUs —
each decision’s source_signal_id traces back to the correct SKU’s own signal,
never conflated.run_pulse_once passes, each produce their own
canonical governed replenishment chain (SOW, assignment, receipt) — never a
shared or cross-attributed chain.tests/test_pulse.py’s existing concurrency tests are the
precedent to extend, not fork).A concurrent race MUST be proven with real, separate database connections — the same discipline every prior unit’s own proof matrix has required (Unit 8’s fencing tests, Unit 9’s Pulse tests). A pair of mocks calling one shared helper does not prove the SQLite-boundary property this matrix requires.
| Chapter | Directory | Teaching responsibility |
|---|---|---|
| 8 | ch08_the_store_becomes_a_catalog |
Replace the single-product fixture with a genuine multi-product catalog. |
| 9 | ch09_each_product_has_its_own_threshold |
Independent stock state and reorder decisions per SKU. |
| 10 | ch10_one_signal_wakes_one_need |
Signal-to-SKU binding; no cross-product wake or replenishment. |
| 11 | ch11_replenishment_scales_without_losing_governance |
Multiple governed replenishment chains while preserving idempotency, evidence, and fencing. |
| 12 | ch12_the_pilot_begins_with_a_receipt |
Execute and inspect the pilot-start mechanism while distinguishing “started” from “finished.” |
Each chapter must match book/CONTENT-SOURCE.md’s existing contract exactly (as
extended by Unit 10): a chNN_<slug>/ directory containing README.md,
solution.py, and INSTRUCTOR.md. README.md carries, in order: ## Learning
objective, an exercise section, expected observations with real command output,
## Learner verification command, ## Explain it back. solution.py must import
the production package at module top level and must not copy implementation
(class Database/CREATE TABLE forbidden, matching
scripts/verify_curriculum.py:138’s existing heuristic). INSTRUCTOR.md must carry
all seven sections Unit 10 established: teaching intent, prerequisite knowledge,
likely misconceptions, observation checkpoints, discussion prompts, facilitation
timing, exercise debrief and assessment guidance.
Each chapter’s exercise must import and run production code with a real, exercise-able entry point — no teaching forks. Chapter 12 specifically must not accidentally start the real 30-day pilot during the curriculum gate or any test run: its exercise must operate against an exercise-scoped, disposable pilot identity, structurally distinct from the real named pilot organization the separately-authorized pilot-start act (§4 below) targets — never the same database, never the same pilot identity value, never reachable by accident through a shared default.
Chapter 7’s existing closing gesture (book/ch07_the_organization_wakes_itself/
README.md’s final lines, “There is no Chapter 8 yet — Unit 11 is where the
Store’s own governed territory expands…”) must be updated with a forward link to
Chapter 8, matching the established forward-chaining pattern (each non-last chapter
ends with a Next: link to the immediate next chapter). Chapters 8-11 each need
their own forward link; Chapter 12, now the last chapter, needs none but should
close coherently.
Correction (2026-08-30): an earlier version of this section required the governance receipt to commit inside the same atomic SQLite transaction as the pilot-start mechanism itself, while a later paragraph described the receipt as matching this project’s own acceptance-record convention (a filed, durable document, not a database row) — an internal contradiction, and a sequencing error the Principal caught directly: the governance receipt cannot exist in the same transaction as the mechanism’s own internal write, because the receipt documents that the SEPARATELY AUTHORIZED real pilot-start act actually happened — an event that, by construction, occurs later than and outside of this unit’s own implementation. Corrected below: the mechanism’s own atomicity is scoped to exactly the SQLite record and event it produces; the governance receipt is a distinct, later artifact, filed only after the real act executes under its own separate authorization — never a component of the mechanism’s internal transaction.
Build an explicit, durable pilot-start act producing, atomically, in one transaction, exactly two things:
pilot.started event (or equivalently explicit event kind — name
it once, use it consistently, matching Unit 8’s own “one canonical failure-
category term” discipline).Required behavior of this two-write transaction, proven with real tests:
relay.claim(), fencing.acquire_actor_lease(), create_pulse_work()’s own
UNIQUE(source_signal_id)), not a preflight SELECT.pilot.started
event commit together or not at all — nothing else is part of this transaction.This unit builds the mechanism and proves it with tests. It does not invoke it against the real named pilot organization. Chapter 12’s own exercise (§3) invokes it only against a disposable, exercise-scoped identity. The real pilot-start act requires the separate Principal authorization named in “Authorization” above and in the governing ruling’s Holding 1 — that authorization, and the act it authorizes, are both explicitly outside the implementation PR and implementation-acceptance scope, but required for final Unit 11 closure.
The governance receipt is not built or filed by this unit’s own implementation. It belongs to a later step in the ruled sequence, entirely outside the implementation PR and implementation-acceptance scope, but required for final Unit 11 closure:
main (this SOW’s
own scope, ending here).pilot.started event
described above, against the real pilot organization this time, not a
disposable exercise identity.PROPOSED -> ACCEPTED
flip for this document (in a later, separate reviewed change, per this
project’s own standing convention) and Unit 11’s final closure follow.This SOW’s own implementation-acceptance conditions (below) end at step 1. Steps 2-5 are outside the implementation PR and implementation-acceptance scope, but required for final Unit 11 closure (see “Final Unit 11 closure conditions” below), and require their own separate authorization and review at each step.
Extend scripts/verify_curriculum.py’s REQUIRED_CHAPTERS/RUNNABLE/
RUNNABLE_ARGS from 8 to 13 entries, following the exact pattern Unit 10 already
established growing from 4 to 8 — nothing in the current structure assumes exactly
8 chapters.
Every existing mechanical guarantee (chapter-scoped Pulse guard, instructor-note structure, chapter-sequence coherence, frontmatter absence, import-not-copy, execute-not-merely-import) must continue to apply to all 13 chapters, unweakened.
New mutation-check obligation, matching this project’s own established discipline: for every new guarantee this unit adds (the multi-SKU isolation checks, the pilot-start idempotency/refusal checks, Chapter 12’s disposable-identity enforcement if made mechanically checkable), demonstrate a plausible break the check catches, confirm the mutation actually landed (diff-stat), then restore and confirm green.
main does
not mean the 30-day pilot has finished, and does not even mean it has started,
and does not by itself flip this document’s status to ACCEPTED — only the
separately-authorized real pilot-start act, followed by its filed governance
receipt, followed by the separate reviewed status flip, means any of that.
Stated in “Authorization” above, in §4, and in “Review and merge ritual” steps
11-14.Do not:
src/sovereign_agent/ primitives merely to make the Store expansion appear
larger;The nine credentialed provider tests remain deselected and explicitly deferred to Unit 12.
scripts/verify_source_budget.py scopes only to src/sovereign_agent/. At this
SOW’s base commit: 27/40 modules, 6139/6250 nonblank lines, 7/30 root exports —
111 lines of headroom. Store-domain code (src/reference_organizations/store/) and
curriculum content (book/) live outside this budget, as they have since Unit 9’s
own SOW established the same split for pulse_gate.py.
If implementation genuinely requires more src/sovereign_agent/ core-primitive
code than the remaining 111-line headroom — for example, if the pilot-start
mechanism’s own structured tables/functions cannot fit inside sovereign_agent
without exceeding it, or must live there rather than in reference_organizations/
for architectural reasons — stop and request a precise budget amendment before
writing code, matching F-U9-1’s own precedent (that unit’s budget was raised from
6000 to 6250, explicitly not as a target, only as permission to implement the
correct solution without compressing correctness to fit or padding to consume
headroom). Do not silently exceed the current ceiling. Do not treat a granted
amendment as license to pad.
Run at the exact implementation head:
uv lock --check
make verify
python scripts/verify_curriculum.py
python scripts/verify_source_budget.py
git diff --check
Run verify_curriculum.py twice consecutively. Build the wheel, install into a
clean Python 3.14 environment outside the source tree, run sovereign-agent
--help, sovereign-agent doctor, sovereign-agent demo store --mode simulated
--root /tmp/<somewhere-outside-source> from that installed wheel. Run every new
chapter’s solution.py exercise directly and confirm it executes cleanly,
producing the real captured output that goes into that chapter’s README — never a
guessed expected-observations block. Live-provider tests remain deselected and
must be reported as unrun.
unit-11/store-expansion-pilot-start; it does not open or
merge its own PR.pilot.started event inserted directly, bypassing the real
mechanism — matching the same discipline Unit 10’s Pulse-guard mutation
check already established for pulse.* events.CHANGES_REQUESTED.main from a clean clone.docs/v1-unit11-store-expansion-pilot-start.md (the documentation
deliverable this unit adds) against merged behavior.Correction (2026-08-30): the original version of steps 11-12 flipped this
document’s own status to ACCEPTED and treated Unit 11 as closed immediately
after step 10, with the real pilot-start act and its governance receipt
positioned as merely unauthorized-for-now rather than as required prior steps
in the closure sequence itself. That contradicted ruling Holding 1 (“Unit 11
closes only after that act and its governance receipt are durably verified”)
and the corrected §4 sequence above. The steps below restore the ruled order:
this unit’s implementation is gated and audited (through step 10, above) and
sits in that state — reviewed, merged, verified on main, but this document
still PROPOSED — until the separately-authorized real pilot-start act and
its filed governance receipt both exist. Only then does the status flip and
final closure follow.
PROPOSED and Unit 11 is
not yet closed. Merged, verified behavior on main is not, by itself,
Unit 11’s closure.ACCEPTED, in a separate, reviewed change, matching step 11’s original
intent but now correctly sequenced after the real act rather than before
it.If main advances, reconcile through an auditable PR-based path and rerun gates
and review on the resulting exact head. A prior co-sign does not survive a head
change.
Add docs/v1-unit11-store-expansion-pilot-start.md, following the shape
established by docs/v1-unit7-workspace-lifecycle.md through
docs/v1-unit10-curriculum-completion.md: status header (status PROPOSED until a
separate reviewed acceptance flip), the contract as testable properties, a verified
“how to check this document against the repository” command block (every command
run and confirmed working before being written into the doc), a budget-impact
statement, a “what this unit did not do” section (explicitly naming that the real
pilot-start act was not performed), and explicit non-claims.
Update CHANGELOG.md following the established per-unit style. Update
book/README.md’s chapter index to include Chapters 8-12.
Correction (2026-08-30): this section was previously titled “Acceptance conditions” and opened “Unit 11 is accepted only when…” — but its own bullets require the real pilot-start act to NOT have happened and no governance receipt to exist yet, which describes implementation acceptance, not final Unit 11 acceptance. Elsewhere this document correctly states Unit 11 closes only after both the real act and its receipt exist. Renamed and reworded below to remove that contradiction; see “Final Unit 11 closure conditions” below for what completes the unit.
The Unit 11 implementation is technically accepted only when the Principal can inspect the merged tree and confirm:
src/sovereign_agent/ budget is respected, or a precise amendment was
requested and granted before implementation, never silently exceeded or
compressed against;Proceed first by filing and reviewing this SOW. Do not begin implementation before it is merged unchanged or a subsequent Principal ruling amends it.
Added 2026-08-30, alongside the “Implementation-acceptance conditions” rename above, to state explicitly what completes Unit 11 — distinct from, and later than, implementation acceptance. Unit 11 is closed only when all of the following hold, in this order:
main clone (Review-and-merge-ritual steps
1-10).pilot.started event (§4’s mechanism, invoked for real this time,
not Chapter 12’s disposable exercise identity) — confirmed durable, not
merely attempted.PROPOSED -> ACCEPTED in a separate,
reviewed change (Review-and-merge-ritual step 13).main has been gated once more from a clean clone after that flip lands
(Review-and-merge-ritual step 14).Only after all six hold is Unit 11 closed and Unit 12 eligible to begin.