sovereign-agent

Ruling: Unit 12 scope — release evaluation, proof pack, Andrea protocol, provider truthfulness, release sequence

This ruling records the Principal’s decision on the seven open questions the read-only Unit 12 scope descent surfaced but explicitly did not resolve. The descent itself (.unit12/SCOPE-DESCENT.md at the time of this ruling, untracked investigation evidence — corrected additively by Master after independent re-verification found a false branch-naming claim, then independently re-confirmed correct by Sparring) is superseded as the citable scope authority by this file. No code, curriculum content, or SOW exists for Unit 12 yet; this ruling authorizes scope only, not implementation, and not the SOW’s own authoring — see “Next authorized action” below.

The seven questions this ruling answers

  1. What replaces the withdrawn pilot-completion language. The top-level SOW’s done_when clause and sequencing amendment 6 (docs/sows/sovereign-agent-v1-educational-control-plane.md:14-21,62-68) still describe Unit 12 as “finishing” a real 30-day pilot — a premise docs/rulings/2026-08-30-unit11-local-closure-supersedes-real-deployment-gate.md already withdrew for Unit 11’s own closure, without saying what replaces it for Unit 12.
  2. What a “proof pack” concretely means for a pilot that never ran in real deployment.
  3. The Andrea live evaluation’s own parameters — duration, sampling, participant count, repeated sessions, aggregation, and pass/fail criteria — all left undecided by Holding 4 of the Unit 11 scope ruling.
  4. What “completes all curriculum verification” requires beyond the existing 13-chapter mechanical gate.
  5. What “release” means for this project, mechanically — no version-bump, tagging, or publishing process for the sovereign-agent package itself exists anywhere in the ratified record, as distinct from the book’s own publication (already settled by docs/rulings/2026-08-27-book-publication-destination.md).
  6. How credentialed provider smokes close honestly — nine tests remain deselected under docs/rulings/2026-08-26-deferral-unit6-smokes.md; what Unit 12 must do to close that deferral without fabricating credential evidence.
  7. Whether the soak-terminology naming collision needs a corrective note in living documents, and how far that correction reaches without rewriting history.

Holding 1 — replace “finish the pilot” with a local release-evaluation cycle

Unit 12 does not finish or simulate a real 30-day pilot.

The superseded definition (docs/sows/sovereign-agent-v1-educational-control-plane.md:21):

30-day Sovereign Store pilot -> redacted proof pack accepted

becomes:

local, learner-controlled Sovereign Store release evaluation -> redacted Unit 12 proof pack accepted

Unit 12 may exercise the accepted pilot-start mechanism (start_pilot, src/reference_organizations/store/pilot.py, built and independently falsified in Unit 11) against disposable local SQLite identities. It does not need a pilot.completed event, elapsed-time simulation, production database, or governance receipt — none of that mechanism exists, and this holding does not create it.

The proof pack closes the educational release-evaluation cycle; it does not prove operational endurance. A genuine deployment pilot remains future ZEO Go work, matching docs/rulings/2026-08-30-unit11-local-closure-supersedes-real-deployment-gate.md’s own holding 7 (“A genuine 30-day deployment pilot belongs to a later, separately authorized operational program — most naturally ZEO Go… — not to completion of this Python textbook”).

Holding 2 — define the redacted proof pack

Unit 12 must file a machine-verifiable manifest at:

docs/evidence/unit12/proof-pack.json

It records:

Allowed provider statuses, exactly these four:

Raw credentials, prompts, provider transcripts, personal identifiers, and unredacted environment dumps must never be committed.

A verifier must reject missing fields, unknown statuses, digest mismatches, path escape, secret-shaped content, and any claim that NOT_RUN means PASS.

Sparring verifies the pack technically. Principal accepts the release candidate. Neither act claims a real pilot occurred.

Holding 3 — define the Andrea live evaluation

Unit 12 creates a new full-curriculum evaluation record; it does not rewrite either historical Andrea evaluation (docs/andrea-alpha-evaluation.md, docs/andrea-chapters-0-7-evaluation.md).

Parameters:

  1. Participant: at least one real Andrea-profile learner — comfortable with Python scripts/notebooks, unfamiliar with this implementation, and not an author or reviewer of it.
  2. Environment: fresh laptop or notebook-style environment, Python 3.14, cold checkout/install, no pre-run exercises, no credentialed provider required.
  3. Duration: 60 minutes maximum for the complete session; the first truthful accepted outcome must still occur within 10 minutes (matching the top-level SOW’s own existing done_when clause, docs/sows/sovereign-agent-v1-educational-control-plane.md:19, which this holding does not touch).
  4. Sampling and repetition: one fresh participant and one complete cold-start session are sufficient for 1.0. If a blocking defect causes changes, acceptance requires a new cold-start session against the corrected exact head; prior evidence remains preserved, not overwritten.
  5. Scoring: retain Tasks 1-7 (docs/andrea-chapters-0-7-evaluation.md, confirmed at this ruling’s base commit to score a maximum of 14 across seven two-point tasks) and add:
    • Task 8: multi-SKU isolation;
    • Task 9: pilot-start structured evidence, replay, and refusal;
    • Task 10: distinguish the local mechanism from a real 30-day deployment and identify ZEO Go as the production graduation path.

    Each task scores 0-2; maximum 20 (14 existing + 3 new tasks x 2). Do not average across participants.

  6. Pass criteria: at least 17/20; no zero on truth-critical Tasks 2, 7, 8, 9, or 10; first accepted outcome within 10 minutes; complete session within 60 minutes.

Record wrong answers as curriculum findings. Use a participant alias; commit no recording or personal data.

Holding 4 — complete curriculum verification mechanically

The final 1.0 curriculum is Chapters 0-12: 13 chapters, confirmed as the current chapter count at this ruling’s base commit (python scripts/verify_curriculum.py -> “13 chapters, 13 exercises”). Unit 12 adds no Chapter 13.

Unit 12 must:

The existing scripts/verify_curriculum.py remains the structural gate; Unit 12 adds a distinct release gate rather than overloading one script with unrelated release responsibilities.

Holding 5 — define “release”

“Release” means publishing Sovereign Agent 1.0.0 to PyPI as the executable textbook — not publishing the book site (already settled, separately, by docs/rulings/2026-08-27-book-publication-destination.md, which governs zeo-site and does not use the word “release”) and not declaring production readiness.

Sequence:

  1. Merge and accept Unit 12 implementation.
  2. Produce 1.0.0rc1; publish through the existing TestPyPI path.
  3. Verify the candidate artifact from outside the repository.
  4. File and review the redacted proof pack.
  5. Obtain separate Principal authorization for the final release.
  6. Set the final version and tag the authorized exact commit v1.0.0.
  7. Let the existing trusted-publisher workflow publish to PyPI.
  8. Verify PyPI JSON, wheel and sdist installation, Python floor, dependency metadata, CLI, README, repository provenance, and artifact digests.
  9. Correct installation documentation to describe the actually published 1.x line.
  10. Close Unit 12 only after a separate reviewed PROPOSED -> ACCEPTED change and clean-main gate.

The publish infrastructure this sequence uses already exists and is unchanged by this holding: .github/workflows/publish.yml, confirmed at this ruling’s base commit — tags matching v*.*.*a*/b*/rc* publish to TestPyPI, tags matching bare v*.*.* publish to PyPI via the trusted-publisher OIDC flow (id-token: write), both gated behind a build-and-verify job that installs the built wheel into a clean venv and runs sovereign-agent doctor. The current pyproject.toml version is confirmed 1.0.0.dev1 at this ruling’s base commit.

Merging Unit 12 implementation does not itself authorize either release tag.

Holding 6 — credentialed provider smokes are conditional, truthful evidence

Claude, Codex, and Cursor remain optional external integrations. Sovereign Agent 1.0 must remain fully teachable without installing or authenticating any of them.

For each provider:

An unavailable or unauthenticated provider does not block the offline educational release and must be recorded as NOT_RUN, not silently deselected and not reported as verified.

If a live assignment is attempted and fails because of Sovereign Agent behavior, release is blocked until fixed or that integration is explicitly removed from the supported claim. Providers with no LIVE_PASS must be described as included adapters with offline contract coverage, not live-verified integrations.

This closes docs/rulings/2026-08-26-deferral-unit6-smokes.md’s own deferral (confirmed at this ruling’s base commit: nine tests collected under the live marker, deselected by default, exactly matching that ruling’s holding 2) by narrowing the release claim honestly; it does not fabricate missing credential evidence. That ruling’s own holdings 1-3 (Unit 6 accepted on offline evidence; the smokes have not run; default CI never needs a credential) are unaffected and remain binding.

Holding 7 — correct “soak” terminology without rewriting history

Current Unit 12 language is Andrea live evaluation.

Filing and sequencing

Master may file this decision as this append-only Unit 12 scope ruling and update the rulings index. This filing must:

After the ruling is merged and verified on clean main, Master may prepare — but not implement — the Unit 12 SOW. The SOW must include the proof-pack schema, the Andrea protocol, the installed-wheel curriculum gate, the provider evidence matrix, the release-candidate/final-release separation, and mutation checks.

If Unit 12 requires changing src/sovereign_agent/, only 42 nonblank lines remain under the current ceiling (27/40 modules, 6208/6250 nonblank lines, 7/30 root exports, confirmed by scripts/verify_source_budget.py at this ruling’s base commit). Stop and request a precise budget ruling before implementation; do not compress correctness to fit, and do not raise the ceiling preemptively.

No Unit 12 implementation, real pilot start, credentialed provider smoke, release, or PyPI publication is authorized by this ruling.

How to check this ruling against the repository

# Confirms the current budget headroom Holding 7 (filing/sequencing) cites
python scripts/verify_source_budget.py

# Confirms the superseded pilot-completion language is still present,
# unedited, at its cited location (Holding 1)
grep -n "30-day Sovereign Store pilot -> redacted proof pack accepted" \
  docs/sows/sovereign-agent-v1-educational-control-plane.md

# Confirms the current chapter count Holding 4 cites
python scripts/verify_curriculum.py

# Confirms the current Andrea Chapters 0-7 scoring maximum Holding 3 cites
grep -n "maximum 14\|Tasks 1-6" docs/andrea-chapters-0-7-evaluation.md

# Confirms the nine deselected live-marked tests Holding 6 cites
uv run --python 3.14 pytest tests/test_providers_live.py --collect-only -q -m live

# Confirms the publish workflow Holding 5 cites already exists unchanged
test -f .github/workflows/publish.yml && echo "publish.yml exists"
grep -n "version = " pyproject.toml

# The rulings index and directory agree
python scripts/verify_curriculum.py
This site is open source. Improve this page.