R89.C — θ Phase 3 Staging — Behavioural Contract

Step 2 of the 5-step chain for β task 4f718f92-12d7-4176-a3c6-3682ba27aef9.

This contract specifies the behavioural shape of the output artefact — docs/guides/implementation/task-prompts/p3.1-theta-consensus.md — and the invariants every downstream executor inheriting from it must preserve.

1. Output artefact contract

1.1 Path 

docs/guides/implementation/task-prompts/p3.1-theta-consensus.md

1.2 Frontmatter (REQUIRED) 

---
title: "P3.1–P3.9 — θ Consensus — Agent Prompts"
tags: [phase-3, agents, prompts, p3, theta, consensus, bft, planning]
type: agent-prompts
status: staged
phase: 3
round: R89
updated: 2026-05-12
---

status: staged is a deliberate choice — the prompt file is ready BUT upstream dispatch is conditional on Phase 2 λ closing AND ADR-002/003 status movement. ready would imply dispatchable; staged accurately reflects the “waiting on the dep chain” reality.

1.3 Structural sections (REQUIRED, in order)

  1. Title (# P3 — θ Consensus — Agent Prompts)
  2. File intro block — multi-paragraph blockquote covering:
    • Axis goals
    • Dependency map (P0 + κ + λ + heritage)
    • Ordering rationale + wave structure
    • ADR-002 + ADR-003 status flags (both PROPOSED at R89 stage)
    • Roadmap budget reference (R121+, ~30 tasks / ~15 weeks per roadmap)
    • Round + base SHA + writeback expectations
  3. Design invariants block — numbered list of must-preserve constraints
  4. Group summary table — every sub-task with Depends-on + Effort + Unblocks
  5. Per-sub-task entries — 13 entries, each ≥80 lines
  6. “Back to index” footer with link-outs to:
    • task-prompts/index.md
    • task-breakdown.md §Phase 3
    • s06-consensus.md, s08-gossip.md
    • consensus.md concept doc
    • ADR-002, ADR-003
    • roadmap.md §Phase 3

1.4 Per-sub-task entry shape (REQUIRED — pattern-match kappa)

Every per-sub-task entry MUST contain, in order:

  1. ## §P3.X.Y — <Surface Name> — Phase 3 θ Wave <N> heading
  2. Spec source line — link to task-breakdown.md §P3.X.Y where applicable
  3. Concept reference line — link to consensus.md, s06-consensus.md, or s08-gossip.md (whichever is canonical for the surface)
  4. Worktree line — feature/p3-x-y-<slug>
  5. Branch command line — full git worktree add invocation
  6. Estimated effort line — S / M / L per kappa convention
  7. Depends on line — explicit task IDs (including in-flight λ deps)
  8. Unblocks line — explicit task IDs
  9. Files to create subsection — src/domains/consensus/... paths
  10. Acceptance criteria subsection — checkbox list, specific and testable
  11. Pre-flight reading subsection — minimum 4 file references
  12. Ready-to-paste agent prompt subsection — fenced code block titled text, self-contained, includes: pre-read list, worktree setup, file contents, acceptance criteria, success check, writeback block, forbiddens, next
  13. Verification checklist subsection — what the reviewer agent runs
  14. Writeback template subsection — fenced YAML
  15. Common gotchas subsection — bullet list

This is a byte-for-byte structural copy of kappa’s per-entry shape (see p1.1-kappa-rule-engine.md §P1.1.1 through §P1.5.5).

2. Content invariants (every executor downstream inherits these)

Every entry’s “Ready-to-paste agent prompt” subsection MUST embed these invariants verbatim or by literal reference (in a FORBIDDENS: block per kappa convention):

Invariant Source Why it’s binding
64-bit signed integer arithmetic (bigint); zero floating point consensus.md inheritance from κ Determinism for cross-node parity
No clock reads in vote / aggregation logic s06 §”clock reads forbidden” κ rule discipline inherited
Logical clocks only (Lamport); wall-clock NEVER in signed payload consensus.md §Gossip envelope Signed payloads must be deterministic
Ed25519 for signatures (per s06 step 1 of Event validation) s06 §Event validation, line 31 Standard public-key crypto for arbiter identity
Canonical JSON serialization (deterministic key order) task-breakdown.md P3.1.1 line 877 Vote-hash reproducibility
Aggregate-all-errors validator pattern inherited from P1.2.3 Multi-error per-pass discipline
Idempotent slashing (proof-hash dedup) task-breakdown.md P3.5.1 line 963 Re-submission must not double-slash
No external side effects before HARD finality s06 §Finality levels rule Rollback safety
Worktree-only (CLAUDE.md §3) CLAUDE.md Repo hygiene
Build + lint + test gates (CLAUDE.md §5) CLAUDE.md Inherited from κ

3. ADR-status disclosure invariant (CRITICAL)

The file intro block MUST contain a clearly visible ADR-status disclosure with the following shape:

> **ADR status at R89.C staging (2026-05-12):**
>
> - [ADR-002](...) — VRF — **PROPOSED, not Accepted.** ...
> - [ADR-003](...) — BFT library — **PROPOSED, not Accepted.** ...

This is non-negotiable. Downstream executors picking up a sub-task from this file MUST see at-a-glance that the ADRs are not yet ratified, so they can either:

  • Defer their dispatch until PM moves the ADRs to Accepted, OR
  • Ship a stub interface (per the spec-recommended Option A for VRF, Option C-spike for BFT) with a clear swap-in path

Wave-3 / Wave-4 entries that DIRECTLY depend on a PROPOSED ADR MUST repeat the disclosure in their own header.

4. λ dependency-disclosure invariant

The file intro block MUST contain a clearly visible λ-dependency disclosure:

> **Phase 2 λ Reputation is in flight at staging time.** Phase 3 executor
> dispatch BEGINS only after Phase 2 λ seals. P3.5.1 (Equivocation Slashing)
> consumes `P2.2.2 penalties`; P3.4.1 (STA) consumes `P2.1.1 reputation schema`.
> Staging the prompt file does NOT authorize Phase 3 dispatch.

5. Single-arbiter compatibility invariant

Every state-machine entry (P3.1.2 quorum, P3.2.1 finality) MUST include in its acceptance criteria a clause that the implementation degrades gracefully for n = 1:

  • quorum_threshold(1) = floor(2/3) + 1 = 1, i.e. single arbiter trivially reaches quorum on its own vote
  • Finality state machine produces QUORUM immediately for n = 1
  • This matches consensus.md §Phase 0 posture: “trivially finalized because n = 1”

This protects Phase 0 deployment compatibility — Phase 3 code, once written, must run cleanly in single-node mode without if (n > 1) branches scattered throughout.

6. Heritage prohibition

The prompt file MUST NOT cite:

  • claude/webhooks/signature.js (AMS donor, HMAC webhook validator)
  • claude/resilience/ (AMS donor rate limiter)
  • Pre-R53 src/ paths (e.g. src/server.js, src/consensus/voting.js WITHOUT a .ts extension)
  • data/ams.db references in spec context (it’s the Phase 0 task store)
  • gossip.py or vrf.py (donor Python — they’re documentation backing only)
  • AMS-era tool names (unified_*, gsd_workflow_*, roadmap_*)

If a heritage reference IS necessary (e.g. for spec backing), it must be clearly flagged as **HERITAGE:** per CLAUDE.md §9.2’s heritage-tagging rule.

7. Granularity contract

Target: 13 per-task entries. Acceptable: 12–15. Outside that range requires PM justification.

Mapping back to task-breakdown.md’s 7 canonical entries:

Canonical Granular split
P3.1.1 P3.1.1 alone (Vote Messages + Canonical Wire)
P3.1.2 P3.1.2 alone (Quorum Computation)
P3.1.3 P3.1.3 (Round/View SM) + P3.6.1 (VRF stub) — VRF extracted
P3.2.1 P3.2.1 alone (Finality SM)
P3.3.1 P3.3.1 (IHAVE/IWANT) + P3.3.2 (Bloom) + P3.3.3 (Fanout) — 3-way split
P3.4.1 P3.4.1 alone (Time Anchors)
P3.5.1 P3.5.1 alone (Equivocation Slashing)
(new) P3.7.1 MCP Tool Surface
(new) P3.8.1 Test Corpus + Parity Harness
(new) P3.9.1 Fork Trigger Hook (ι handoff stub)

Total: 13. The 3 “new” entries cover surface the canonical task-breakdown misses but spec demands: MCP tool wrapper, multi-node parity testing, and the ι handoff stub.

8. Wave-structure contract

The file intro MUST publish the wave structure:

Wave Sub-tasks Parallelism Gate
1 P3.1.1 solo post-Phase-2-λ-seal
2 P3.1.2, P3.3.1, P3.4.1 3-parallel post-P3.1.1
3 P3.1.3, P3.2.1, P3.5.1, P3.6.1 (VRF stub) 4-parallel post-P3.1.2
4 P3.3.2, P3.3.3, P3.7.1 3-parallel post-P3.3.1
5 P3.8.1, P3.9.1 2-parallel post-Wave-4

This is a planning artifact — the executor wave dispatcher (Sigma at phase-3 kickoff) MAY tighten or relax based on real-time signals. The 4- parallel Wave 3 sits at the documented “3-safe ceiling” + 1 (consistent with R87 κ Wave 7’s 3-parallel cap with a 4th in-progress).

9. Test-evidence contract

Phase 3 code, when shipped per these prompts, MUST produce:

  • State-machine slices (P3.1, P3.2, P3.5): pure-unit tests, property tests for quorum / finality monotonicity, no network dependence
  • Gossip slices (P3.3.x): mock-network tests, no real sockets
  • STA slice (P3.4.1): seeded-clock tests, no Date.now()
  • VRF stub (P3.6.1): deterministic inputs → deterministic outputs; conformance to RFC 9381 NOT required at stub stage per ADR-002 Option A
  • MCP tool surface (P3.7.1): in-process tests against the running server, using existing Phase 0 test harness pattern
  • Parity harness (P3.8.1): multi-arbiter simulation, faulty-node corpus (single-arbiter Byzantine, dual-arbiter equivocator, 4-arbiter PBFT-canonical)
  • Fork hook (P3.9.1): hook is fired with right payload; ι actual implementation NOT in scope

Each per-task entry MUST include a “Test plan” embedded in its acceptance criteria.

10. Writeback-block invariant

Every per-task entry’s “Ready-to-paste agent prompt” MUST include a writeback block using the modern signature (no donor-era session_id field, no literal task_id="P3.X.Y" strings — Colibri task IDs are UUIDs not numeric labels). Reference shape (from R88.A canonical fix):

WRITEBACK (after success, per CLAUDE.md §7):
task_update(id="<colibri-task-id-passed-in-by-PM>", status="done", progress=100)
thought_record(
  thought_type="reflection",
  content="task_id: <PM-supplied UUID>
branch: feature/p3-x-y-<slug>
worktree: .worktrees/claude/p3-x-y-<slug>
commit: <SHA>
tests: npm run build && npm run lint && npm test (<N>/<T> pass)
summary: <2-3 sentence what was done>
blockers: <residual risks or 'none'>"
)

The PM (at phase-3 kickoff) will pre-create β tasks per slice and pass the UUID into the dispatch packet. The prompt file must NOT hard-code a fake task_id like P3.1.1.

11. Out-of-scope (explicit non-deliverables)

The prompt file MUST NOT:

  • Implement any src/ code
  • Modify src/server.ts or any other live server file
  • Create database migrations
  • Add npm dependencies (merkletreejs, @noble/curves, etc. are referenced textually but not installed)
  • Stage prompts for ι Phase 5 work (only the hook surface in P3.9.1 is staged; the ι implementation itself is out of scope)
  • Stage prompts for π Phase 6 work
  • Resolve ADR-002 or ADR-003 (only flag their status)

12. Sign-off criteria

The prompt file is “contract-compliant” iff:

  • Frontmatter matches §1.2
  • All 6 structural sections present (§1.3)
  • All 13 entries match the per-entry shape (§1.4)
  • ADR-status disclosure present in intro (§3)
  • λ-dependency disclosure present in intro (§4)
  • Single-arbiter clause in P3.1.2 and P3.2.1 (§5)
  • Zero heritage citations except flagged HERITAGE blocks (§6)
  • Granularity in [12, 15] (§7)
  • Wave-structure table in intro (§8)
  • Test plan in every entry (§9)
  • Modern writeback block in every entry (§10)
  • No src/ deltas (§11)

Sign-off authority: R89.C verification step (Step 5) at docs/verification/r89-c-theta-phase-3-staging-verification.md.

Contract complete. Step 3 (packet) follows: ordering rationale, parallel opportunities, exact entry order, and the implementation packet for Step 4.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.