docs(arch): council lifecycle divergence decisions (REQ-031, AUDIT §193)

Add ARCHITECTURE.md §"Council Voice/Council Interface — Lifecycle Type
Divergence Decisions (v0.4)": documents P1-1 (Proposal/VoteOption absent,
deferred to v0.5+ governance runtime — feat: rejected by D-001), P1-2
(SignalKind 4-vs-5: the 4-source shape is intentional per AUDIT rationale;
Freeholder is eligibility, Guild is council tier, Capital is committed-
capital per vision §9.1), P2 (bearers ValidateGenesis no-op correct per spec).

test(council): TestSignalKindShapeIntentional regression guard (REQ-031)

Add intent-assertion test locking the 4-source SignalKind shape with the
AUDIT §193 P1-2 rationale in the doc comment. A future agent changing
SignalKindCount 4→5 must update this test, surfacing the rationale. No
locked-const change, no production .go files modified (D-050).

Verification: go test ./... green; only types_test.go modified in x/**.

---ci---
project: oy
phase: 2
milestone: v0.4
status: execute
tag_base: v0.3.x
milestone_type: nfr
reqs: [REQ-031]
---/ci---
This commit is contained in:
2026-08-17 23:31:55 +00:00
parent 92966cb9c5
commit 7d1468b442
2 changed files with 85 additions and 1 deletions
+52
View File
@@ -109,6 +109,58 @@ func TestSignalKindCountLockedConst(t *testing.T) {
}
}
// TestSignalKindShapeIntentional (REQ-031, AUDIT §193 P1-2) is a regression
// GUARD that documents and locks the 4-source SignalKind shape. It is NOT a
// shape change — the existing TestSignalKindCountLockedConst already locks
// the count. This test adds the INTENT documentation so a future agent who
// changes SignalKindCount from 4 to 5 (e.g., to "restore" the spec's 5-source
// VoiceSource list) must also update this test, surfacing the AUDIT rationale
// for review.
//
// AUDIT §193 P1-2 rationale (why SignalKind is 4 sources, NOT the spec's 5):
//
// The v0.2 P3-01-01 deliverable specified VoiceSource with 5 sources
// (Stash/Standing/Vouch/Freeholder/Guild). The implementation uses
// SignalKind with 4 sources (Stash/Standing/Vouch/Capital). The 4-source
// shape is a defensible design refinement:
// - Freeholder is an ELIGIBILITY property (upstream in x/standing), not
// a voice signal. A Freeholder-eligible Reach is a precondition for
// voting, not a signal that feeds a vote's weight.
// - Guild is a COUNCIL TIER (one of the three councils is the Guild
// Council), not a voice signal. Including Guild as a signal kind
// would conflate the council tier with the signal source.
// - Capital is committed-capital (vision §9.1, one of the four
// Freeholder signals per REQ-005), which the spec's VoiceSource list
// omitted. Adding Capital corrects the spec to match vision §9.1's
// four-signal definition (REQ-005: "Four Freeholder signals locked").
//
// The 4-source shape matches REQ-005 exactly. The spec deliverable text
// was wrong, not the implementation. v0.4 (D-050) DOCUMENTS this and
// locks the 4-source shape; changing it to 5 is a locked-const change
// rejected by the D-001 refinement-only filter and deferred to a future
// milestone that re-litigates REQ-005's signal definition.
//
// See .ciagent/oy/ARCHITECTURE.md §"Council Voice/Council Interface —
// Lifecycle Type Divergence Decisions (v0.4, REQ-031)" for the full rationale.
func TestSignalKindShapeIntentional(t *testing.T) {
// LOCKED: 4 sources. Changing this to 5 requires updating this test's
// intent block AND re-litigating REQ-005's four-signal definition.
const expectedSignalCount = 4
if types.SignalKindCount != expectedSignalCount {
t.Fatalf("SignalKindCount = %d, want %d (REQ-031 intent guard: the 4-source shape is intentional per AUDIT §193 P1-2; see ARCHITECTURE.md v0.4 divergence section before changing this)", types.SignalKindCount, expectedSignalCount)
}
want := []types.SignalKind{types.SignalStash, types.SignalStanding, types.SignalVouch, types.SignalCapital}
all := types.AllSignalKinds()
if len(all) != len(want) {
t.Fatalf("AllSignalKinds() len = %d, want %d", len(all), len(want))
}
for i, s := range all {
if s != want[i] {
t.Errorf("AllSignalKinds()[%d] = %q, want %q (REQ-031 intent guard: the 4-source shape {Stash, Standing, Vouch, Capital} is intentional per AUDIT §193 P1-2; Freeholder and Guild are NOT signal kinds)", i, s, want[i])
}
}
}
// TestAllSignalKindsNames asserts the 4 signal names (Stash, Standing,
// Vouch, Capital) cross-ref v0.1 x/standing FreeholderSignals (StashMaturity,
// MultiDomainStanding, CommunityEndorsement, CommittedCapital).