seaweedfs/sw-block/design/v3-batch-process.md

V3 Batch Process

Date: 2026-04-26 Status: ACTIVE — applies to all batches from G5-5 onward Supersedes: ad-hoc per-batch governance (kickoff + mini-plan + G-1 + closure report + forward-carry checklist + QA scenario catalogue, 5+ artifacts)

---

§1 The flow

plan → (G-1 if V2 PORT) → code → test → close

One mini-plan doc per batch. One PR. One close.

---

§2 The single mini-plan doc

v3-phase-15-<batch-id>-mini-plan.md — the only artifact per batch. Sections in order:

§	Content	Required when
§1 Scope	What this batch delivers; what it does NOT (explicit non-claims)	Always
§2 Acceptance criteria	Numbered list, each verifier-named (test or evidence), SINGLE source of truth	Always
§3 Invariants	INV IDs to inscribe at close + their test pointers; ledger updated by PR (not after)	Always
§4 G-1 V2 read	Inline: PORT items + V3-NATIVE items + hidden invariant audit	Only if V2 muscle PORT batch
§5 Forward-carry consumed	What this batch inherits from prior batch's §close	Always (even if "none")
§6 Risks + mitigations	Short table	Always
§7 Sign table	architect ratify §1-§6 once at start; architect single-sign §close at close	Always
§close	Appended at batch close: deltas vs §1-§6 + evidence pointers + forward-carries to next batch	Appended at close (not separate doc)

Total per batch: 1 doc, 1 commit lifecycle (init → §close append → architect sign). No separate closure report, no separate G-1 doc, no separate forward-carry checklist, no separate QA scenario catalogue.

---

§3 What earned its keep — KEEP

These survived T4 with track record. Don't drop:

Discipline	When it applies	What it catches
G-1 V2 PORT read (inline §4)	V2 muscle ports only	Hidden invariants, architectural pins, placement decisions pre-code (5 saves on T4)
Mini-plan acceptance criteria (§2)	Always	Ambiguous closes; PR review checklist
Invariant ledger discipline (§3 + v3-invariant-ledger.md)	Always	"Claim without test = wish" rule
m01 -race verification	Always for any concurrency-touching code	Windows-blind concurrency bugs (caught 2 engine bugs at T4d-4 part C)
Architect single-sign at close	Always	Scope drift, stale references, silent narrowing

---

§4 What was overhead — DROP

Practice	Reason dropped
Separate kickoff PROPOSAL doc	Mini-plan §1-§6 ratification is the same thing
Separate G-1 V2 read doc	Inline §4 of mini-plan
Separate closure report doc	§close section of mini-plan
Separate forward-carry checklist	§5 of next-batch mini-plan
Separate QA scenario catalogue	Author tests directly when ready (catalogue went stale 100% of the time)
Multi-version doc churn (v0.1 → v0.5)	One ratification + one close-sign per batch; mid-flight revisions only if SCOPE changes
Cross-doc invariant restatement (catalogue + checklist + ledger + mini-plan + closure)	Ledger is sole source of truth; other docs reference by INV ID
G-N sub-batch invention (G5-1..G5-6 style)	Architect picks T-track OR G-N batches at kickoff, not both for same gate

---

§5 Sign cycles — compressed

Was: kickoff ratify → mini-plan ratify → G-1 ratify → code → close ratify (4-5 architect signs per batch)

Now: mini-plan §1-§6 ratify → code → §close architect sign (2 signs per batch)

Mid-flight revisions ONLY when scope changes (architect re-ratifies the changed §). Doc-hygiene fixes don't need ratification — apply, commit, move on.

---

§6 Decision rules

§6.1 G-1 yes/no

Batch type	G-1 needed?
V2 muscle port (weed/storage/blockvol/* source)	YES — inline §4
V3-native (no V2 source; component framework or new design)	NO
Mixed (some PORT items + some V3-native)	YES for the PORT items only

§6.2 T-track vs G-N batch naming

Implementation weight	Naming
Substantial new code (>500 LOC)	T-track (T5, T6, ...)
Mostly verification + missing pieces	G-N batches (G_x_-1, G_x_-2, ...)
Architect picks at kickoff	Don't mix both for same gate

§6.3 When to skip the mini-plan entirely

Hotfix-class single-commit changes (1-line + regression test, like f6084ee BlockStore walHead) don't need a mini-plan. Architect-approved hotfix PR + ledger update if invariant-affecting.

---

§7 Doc lifecycle rules

1. One mini-plan doc per batch. No separate kickoff/closure/checklist/catalogue artifacts.
2. Inscribe invariants in v3-invariant-ledger.md ONLY at close. Other docs reference by INV ID.
3. Update v3-dev-roadmap.md at every gate-close (not batch-close — gate-close).
4. Doc edits that don't change scope don't need architect ratification — fix typos, fix stale refs, commit, move on.
5. Stale doc refs at close-sign time = QA's fault. Run grep -r <stale-ref> before submitting closure for sign.

---

§8 What to keep current as control docs

These are first-order references; keep updated as batches close:

Doc	Owner	Update trigger
v3-dev-roadmap.md	QA	every gate-close
v3-architecture.md	architect	component/responsibility/flow changes
v3-phase-15-mvp-scope-gates.md	architect	scope changes (e.g. G9A added 2026-04-26)
v3-invariant-ledger.md	sw + QA	every batch-close (PR-atomic)
v3-block-behavior-contract-index.md	architect	new behavior contract ratifications
v3-product-placement-authority-rationale.md	architect	placement architecture changes
v2-v3-contract-bridge-catalogue.md	sw + QA	V2→V3 entity bridge updates

Everything else is per-batch (mini-plan) or methodology (v3-phase-development-model.md, this doc).

---

§9 First trial: G5-5

This process gets its first trial at G5-5 (m01 hardware first-light). Concretely:

• ONE doc: v3-phase-15-g5-5-mini-plan.md
• §close appended at batch close, not separate report
• Forward-carries from G5-4 (criteria 3+4) consumed in §5
• §close pushes any G5-5 carries forward to G5-6
• Architect: ratify §1-§6 once + sign §close at close
• No separate kickoff, no separate closure report, no separate checklist

If G5-5 closes cleanly under this process, codify as default for G5-6 + G6 + onward.

---

§10 Process change protocol

This doc evolves like any other:

• New batch tries something different → propose change here
• 3+ batches use the new pattern successfully → codify
• Process change requires architect sign (same §8C.2 rule applies)

Do NOT auto-port T4 governance template forward. Each batch asks "does this step earn its keep" at kickoff.

---

§11 Honesty principle

Documentation overhead that doesn't catch bugs is ceremony. Documentation that catches bugs is discipline.

Drop ceremony. Keep discipline.

---

§12 Architect review checklist

Architect review is not plan authorship. It is the system-level check that prevents drift.

Every mini-plan ratification and §close sign must answer:

Check	Question
Scope truth	What is done, what is explicitly not done, and what product risk remains?
V2 / new-build decision	Is this a full V2 port, partial V2 port, reference-only read, explicit reject, or V3-native design? Does it need a new gate?
Engine / adapter impact	Does this change authority, session fate, recovery, durability, projection, or truth ownership? If yes, where is the invariant and adversarial test?
Product usability level	What can an operator or user actually do end-to-end after this batch? Which test proves it? Which next gate makes it more usable?

Close signs should include a short statement of:

Done:
Not done:
Product level reached:
Next gate that makes it usable:

---

§13 Failure modes this process must prevent

These are the observed sources of waste. Every batch should actively check them.

Failure mode	Required countermeasure
V2 porting drift	Top-down mapping: V2 behavior → V3 product contract → truth owner → accepted/rejected semantics → invariant/test
Engine/adapter change without reason	Require reason, truth-domain impact, bad state prevented, and proof test
Function close means happy path only	Acceptance must include stale input, reordering/overlap where relevant, partial progress, retry/restart, and explicit non-claims
Product unusable despite green tests	Mini-plan must name the end-to-end operator/user path and whether it is real, simulated, manual, or deferred
Missing architecture component	If a batch discovers a product component late (for example placement or binary wiring), update v3-architecture.md or the gate before continuing

---

§14 Who owns what step

All three "architects" are AI agents; user routes messages between them. Per-agent action lists (§15) reduce routing overhead.

Architect role	Owner agent	Scope
System architect	architect agent (cursor)	Product, scope, behavior contracts, gate definitions, close sign
Function/process architect	QA agent (claude-code)	Process discipline, verification, system-level drift detection, doc lifecycle
Code-ownership architect	sw agent (cursor)	Implementation feasibility, code shape, framework state

Based on what actually worked across T4 + G5:

Step	Owner	Why
Gate scope (which gate, what it promises, dependencies)	architect	Product requirements + V3 architectural discipline
Batch sketch (mini-plan §1-§6)	sw	Knows the code + implementation feasibility + framework state; can commit to what's deliverable
G-1 V2 read (when V2 PORT)	sw	Owns the V3 target where V2 muscle lands
Mini-plan ratification	architect (signs §1-§6) + QA (reviews)	Architect: scope drift / missing bindings / V2 lessons. QA: invariant + acceptance discipline.
Code + unit tests	sw	—
Component scenarios + m01 verification	QA	Independent perspective; framework + hardware coverage
Ledger inscription (PR-atomic)	sw	Lands with code in same PR
§close append	sw drafts; QA verifies evidence pointers	Sw: facts. QA: acceptance discipline.
Close sign	architect	Single-sign per §8C.2; caught stale refs + scope drift multiple times

Why sw plans (not architect):

• Sw knows what's feasible + what frameworks exist + what shortcuts are safe
• Architect-drafted plans miss implementation realities (catch up via reviewer cycle anyway)
• Sw self-commits to scope they can deliver — fewer revision cycles
• Architect ratifies SCOPE (caught 2 binding clarifications at G5-4 v0.2→v0.3) but doesn't need to author implementation detail

Why QA reviews + verifies (doesn't plan):

• Independent third party; not advocate for either scope or implementation choice
• Catches discipline gaps (invariant inscription, acceptance criteria coverage) sw + architect miss
• Owns m01 hardware verification + component scenarios

Edge case — process changes (this doc): QA proposes; architect signs (same as any scope-affecting change).

Edge case — hotfix-class (per §6.3): sw can self-author + self-merge with QA spot-review. Architect ratifies if invariant-affecting.

---

§15 Inter-agent communication discipline

Every response from QA, sw, or architect MUST end with an explicit per-agent action list. The user routes messages between agents — communication overhead is real cost.

Mandatory format at end of every substantive response:

## Next actions

| Agent | Action |
|---|---|
| **architect** | <specific action OR "none — standing by"> |
| **sw** | <specific action OR "none — standing by"> |
| **QA** | <specific action OR "none — standing by"> |

Rules:

1. Every agent gets a row, even if "none — standing by"
2. Actions must be concrete + executable ("commit X", "review Y", "decide path A vs B"), NOT vague ("consider Z")
3. If an action depends on another agent's prior action, name the dependency: "after sw lands G5-5, run -race ×10 on m01"
4. Skip the table only for genuinely no-decision-needed acknowledgements (e.g., one-line confirmations)

Why: user's current load is ~90% copy-paste routing between agents. Explicit per-agent action lists at end of every response cut routing time. Every agent reads "what's MY action" without parsing a wall of text.

This rule applies to every agent's outputs, not just QA's. Sw + architect responses to QA reviews must end with the same per-agent action list.