Skip to content

Assumption ledger: an entry whose only evidence is the spec cannot be "settled" — spike critical-path mechanisms before materialization #336

Description

@norrietaylor

Context. The consumer pilot's input spec was a strong PRD that fused requirements with an implementation hypothesis overlay (a kernel fd-passing contract, a third-party per-client filter API, a rootless privilege mechanism, a DNS resolution path). The pipeline transcribed hypotheses into requirement IDs, and the assumption ledger marked the costliest unknowns "settled" citing the spec itself ("settled | spec R1.5") — circular evidence. Consequence: the two spikes went to a cheap library choice while the actual top risks went unspiked and detonated late — a load-bearing attach protocol (34 h stall → mid-run spike), the rootless mechanism (external-reviewer pivot, still open in remediation), the filter/ACL API (a requirement went dead, a use-case never shipped). One spike's own Finding A contradicted its recommendation and nothing caught it until a human's "Hold — do not merge" forced a mid-run re-scope.

Problem. The framework had the right early artifacts — assumption ledger, spike primitive (#229), spec gate — and they under-verified. The ledger admits circular citations; the (fast, plan-folding) spike workflow was pointed at low-risk targets.

Fix (adversarial evidence standard):

  • A ledger entry citing only the spec/PRD as evidence is not "settled" — at most "assumed." "Settled" requires independent evidence: a spike, an existing code anchor with file:line, or an executed probe.
  • Any unvalidated mechanism on the critical path (fd-pass, syscall/UAPI contract, third-party API shape, privilege model) must spike before materialization, not after strand.
  • Spike-target selection is risk-ranked (cost-if-wrong × uncertainty), not convenience-ranked.
  • A spike whose own findings contradict its recommendation must flag, not auto-fold.

Acceptance criteria:

  • The ledger gate rejects "settled" entries whose only citation is the spec/PRD.
  • Materialization blocks on any critical-path mechanism still marked "assumed"/unspiked.
  • Spike recommendations are checked against their own findings for contradiction.

Relates to: #229 (the spike primitive this builds on), spec gate. This is the input-quality half of the demoability shortfall (companion: demoability gate #334).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions