joulespec: a standard for energy-accounted specification conformance #561

Merged

dcharlot merged 1 commit from joulespec/standard-v0.1 into main 2026-11-01 08:17:51 -05:00

Conversation 0 Commits 1 Files changed 17 +4639 -2

dcharlot commented 2026-11-01 08:05:26 -05:00

Owner

Copy link

The gap

Specification-driven practice converged on prose an agent interprets and a human reads. The difficulties catalogued wherever it is examined — specs drifting from the code they describe, generated artifacts trusted past their evidence, no method for checking that an implementation conforms, a review burden heavy enough that practitioners report preferring to read the code — are measurement problems wearing a methodology costume. They persist because the specification is a document: a clause cannot be addressed, so nothing binds to it; conformance is a sentence in a review, so it cannot be graded or capped; the cost of the ceremony is an anecdote, so the argument about whether it earns its overhead has no units and cannot be settled.

joulespec/1 leaves the prose alone and changes what the specification is.

Four things it makes computable

1. Addressing — renaming is free, rewording is not (SPEC §1.2, §2.1). A clause carries a label and an obligation: the content address of its kind and text, with the label deliberately excluded. Evidence binds to the obligation.

C1      "The endpoint rejects unauthenticated requests."        → b3:9f4c…
auth-2  "The endpoint rejects unauthenticated requests."        → b3:9f4c…  same obligation
C1      "The endpoint should reject unauthenticated requests."  → b3:2e71…  different obligation

Binding to a label inverts both halves — evidence survives the edit that changed the requirement and breaks on the edit that renamed it. That inversion is how drift goes unobserved; it is an addressing problem, not a discipline problem.

This corrects our own prior art. joule-code-spec shipped the signed, content-addressed clause and the citation binding a coding op to it — and its citations bind by clause label, with one notion of coverage: a clause is covered when something claims it. That is the E0 rung here.

2. A ladder ordered by one question (SPEC §2.5, §2.6) — how hard would it be for this obligation to be violated without this evidence noticing?

E0	cited	The implementer says so. Where prevailing practice lands.
E1	reviewed	A second party read the artifact, once.
E2	exercised	A named check ran and passed — and flatters: a test with no assertion passes, as does one whose fixture never reaches the condition the clause cares about.
E3	falsifiable	The same check is on record failing against a named counter-artifact. The first rung where green means something, and the cheapest strong one.
E4	proved	No input violates it, under a formalization cross-checked by a key other than the prover's.

A proof under a merely declared formalization grades E2, not E4 — it is machine-checked evidence that the something is this clause on the prover's word. Demotion rather than refusal: the proof is not fake. The crate never formalizes a clause itself, and independence is computed from key disjointness, never read from a producer's flag — a review signed by the citing key is the citation again.

The ladder is ordered by re-checkability, not diligence: a review is bound to the state a person looked at, a named check runs again against any later state.

3. Drift is a partition, not a warning (SPEC §4). Diffing revisions by address yields kept / relabelled (editorial, no evidence lost) / reworded (that clause's evidence invalidated) / added / removed — from which the two sets a revision review actually wants fall out: what just lost its evidence, and what starts unevidenced. A freed label reused by a new clause is an addition, not a rewording, because the old obligation still stands. The other direction needs no diff at all: a witness is bound to the artifact state it observed, so earlier evidence is reported stale rather than counted.

4. The ceremony has a price (SPEC §5). Witnesses and work each carry their joules, so the receipt seals the specified share — how much energy went into work citing no clause, the measured form of agents producing features nobody requested — and microjoules per falsifiable obligation. That denominator is deliberately the rung whose evidence can fail: a figure per attempted obligation rewards ceremony, and this family's other per-unit figures count accepted tokens and verified proofs rather than attempts.

Evaluation and receipts

The specification's grade is its weakest owed obligation, absent entirely when any has no surviving evidence — averaging would let nine proved obligations conceal one nobody looked at (SPEC §3.2). Non-goals are first-class and excluded from the cap, so an unwitnessed non-goal is correct; evidence that one was implemented is a flag that blocks conformance however good the rest is (§3.3). Nothing is dropped quietly: an unverifiable witness, one naming another specification, and one naming an obligation the spec does not state are each reported — that last being the normal aftermath of a rewording (§3.1).

Receipts are derived from the specification, artifact, witnesses and work, never from a verdict handed in (§6.1) — a verdict is an ordinary struct, and an interface that signed one would let a producer construct the grade it wanted. Sealed as joulespec/1 JCR-1 (canonical det-CBOR under COSE_Sign1, Ed25519), byte-compatible with the family verifiers. The core admits no nulls and several figures are legitimately absent, so those keys are omitted rather than zeroed: a reader finding no grade knows none was established, where one finding E0 would believe otherwise (§6.2).

CI

joulespec-rs joins the standards matrix on linux with a new opt-in clippy: true flag that gates a workspace at zero warnings on its own runner. Deliberately not added to the macOS lint step — that exists for code only a macOS host can compile, and the matrix comments are explicit about not sending platform-neutral work to the contended Mac. The flag is per-entry rather than repo-wide because several workspaces are not at zero yet, and a gate that fails on arrival teaches people to pass --no-verify.

The modules cite their normative sections, so check-spec-refs binds the code to the specification mechanically — which this standard of all of them should do.

Verification

On the M3 Ultra build host, all under --locked:

• cargo check --workspace --all-targets — clean
• cargo clippy --workspace --all-targets -- -D warnings — zero warnings
• cargo test --workspace — green

Repo checks run locally: no vanity metrics (515 files), every SPEC § citation resolves (1942 across 17 standards), every lockfile current (60), tests-in-CI, workflow concurrency.

The honest limit (SPEC §8)

JouleSpec cannot tell whether a clause says what its author meant. Software can satisfy every clause of its specification and be unfit for purpose, because the specification was incomplete — and an incomplete specification is exactly the case where every clause is covered. A grade is a property of evidence, not of software. An E3 witness establishes that one check can fail, not that it would catch every way the obligation could break.

🤖 Generated with Claude Code

## The gap Specification-driven practice converged on prose an agent interprets and a human reads. The difficulties catalogued wherever it is examined — specs drifting from the code they describe, generated artifacts trusted past their evidence, no method for checking that an implementation conforms, a review burden heavy enough that practitioners report preferring to read the code — are **measurement problems wearing a methodology costume**. They persist because the specification is a *document*: a clause cannot be addressed, so nothing binds to it; conformance is a sentence in a review, so it cannot be graded or capped; the cost of the ceremony is an anecdote, so the argument about whether it earns its overhead has no units and cannot be settled. `joulespec/1` leaves the prose alone and changes what the specification **is**. ## Four things it makes computable **1. Addressing — renaming is free, rewording is not** (SPEC §1.2, §2.1). A clause carries a label *and* an **obligation**: the content address of its kind and text, with the label deliberately excluded. Evidence binds to the obligation. ``` C1 "The endpoint rejects unauthenticated requests." → b3:9f4c… auth-2 "The endpoint rejects unauthenticated requests." → b3:9f4c… same obligation C1 "The endpoint should reject unauthenticated requests." → b3:2e71… different obligation ``` Binding to a label inverts both halves — evidence survives the edit that changed the requirement and breaks on the edit that renamed it. That inversion *is* how drift goes unobserved; it is an addressing problem, not a discipline problem. This **corrects our own prior art.** `joule-code-spec` shipped the signed, content-addressed clause and the citation binding a coding op to it — and its citations bind by clause **label**, with one notion of coverage: a clause is covered when something claims it. That is the `E0` rung here. **2. A ladder ordered by one question** (SPEC §2.5, §2.6) — *how hard would it be for this obligation to be violated without this evidence noticing?* | | | | |---|---|---| | `E0` | `cited` | The implementer says so. Where prevailing practice lands. | | `E1` | `reviewed` | A second party read the artifact, once. | | `E2` | `exercised` | A named check ran and passed — and flatters: a test with no assertion passes, as does one whose fixture never reaches the condition the clause cares about. | | `E3` | `falsifiable` | The same check is on record **failing** against a named counter-artifact. The first rung where green means something, and the cheapest strong one. | | `E4` | `proved` | No input violates it, under a formalization cross-checked by a key other than the prover's. | A proof under a merely *declared* formalization grades `E2`, not `E4` — it is machine-checked evidence that the something is this clause on the prover's word. Demotion rather than refusal: the proof is not fake. The crate never formalizes a clause itself, and independence is **computed from key disjointness**, never read from a producer's flag — a review signed by the citing key is the citation again. The ladder is ordered by **re-checkability, not diligence**: a review is bound to the state a person looked at, a named check runs again against any later state. **3. Drift is a partition, not a warning** (SPEC §4). Diffing revisions by address yields `kept` / `relabelled` (editorial, no evidence lost) / `reworded` (that clause's evidence invalidated) / `added` / `removed` — from which the two sets a revision review actually wants fall out: what just lost its evidence, and what starts unevidenced. A freed label reused by a new clause is an *addition*, not a rewording, because the old obligation still stands. The other direction needs no diff at all: a witness is bound to the artifact state it observed, so earlier evidence is reported **stale** rather than counted. **4. The ceremony has a price** (SPEC §5). Witnesses and work each carry their joules, so the receipt seals the **specified share** — how much energy went into work citing no clause, the measured form of agents producing features nobody requested — and **microjoules per falsifiable obligation**. That denominator is deliberately the rung whose evidence *can fail*: a figure per *attempted* obligation rewards ceremony, and this family's other per-unit figures count accepted tokens and verified proofs rather than attempts. ## Evaluation and receipts The specification's grade is its **weakest** owed obligation, absent entirely when any has no surviving evidence — averaging would let nine proved obligations conceal one nobody looked at (SPEC §3.2). Non-goals are first-class and excluded from the cap, so an unwitnessed non-goal is *correct*; evidence that one **was** implemented is a flag that blocks conformance however good the rest is (§3.3). Nothing is dropped quietly: an unverifiable witness, one naming another specification, and one naming an obligation the spec does not state are each reported — that last being the normal aftermath of a rewording (§3.1). Receipts are derived from the specification, artifact, witnesses and work, **never from a verdict handed in** (§6.1) — a verdict is an ordinary struct, and an interface that signed one would let a producer construct the grade it wanted. Sealed as `joulespec/1` JCR-1 (canonical det-CBOR under COSE_Sign1, Ed25519), byte-compatible with the family verifiers. The core admits no nulls and several figures are legitimately absent, so those keys are **omitted** rather than zeroed: a reader finding no grade knows none was established, where one finding `E0` would believe otherwise (§6.2). ## CI `joulespec-rs` joins the standards matrix on `linux` with a new opt-in **`clippy: true`** flag that gates a workspace at zero warnings on its own runner. Deliberately *not* added to the macOS lint step — that exists for code only a macOS host can compile, and the matrix comments are explicit about not sending platform-neutral work to the contended Mac. The flag is per-entry rather than repo-wide because several workspaces are not at zero yet, and a gate that fails on arrival teaches people to pass `--no-verify`. The modules cite their normative sections, so `check-spec-refs` binds the code to the specification mechanically — which this standard of all of them should do. ## Verification On the M3 Ultra build host, all under `--locked`: - `cargo check --workspace --all-targets` — clean - `cargo clippy --workspace --all-targets -- -D warnings` — zero warnings - `cargo test --workspace` — green Repo checks run locally: no vanity metrics (515 files), every `SPEC §` citation resolves (1942 across 17 standards), every lockfile current (60), tests-in-CI, workflow concurrency. ## The honest limit (SPEC §8) JouleSpec cannot tell whether a clause says what its author meant. Software can satisfy every clause of its specification and be unfit for purpose, because the specification was incomplete — and an incomplete specification is exactly the case where every clause is covered. **A grade is a property of evidence, not of software.** An `E3` witness establishes that one check *can* fail, not that it would catch every way the obligation could break. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 1 commit 2026-11-01 08:05:26 -05:00

joulespec: a standard for energy-accounted specification conformance ... 5a7af57afb

Specification-driven practice converged on prose an agent interprets and a
human reads. The difficulties catalogued wherever it is examined -- specs
drifting from the code they describe, generated artifacts trusted past their
evidence, no method for checking conformance, a review burden heavy enough
that practitioners report preferring to read the code -- are measurement
problems rather than methodology ones, and they persist for one reason: the
specification is a document. A clause cannot be addressed, so nothing binds
to it; conformance is a sentence in a review, so it cannot be graded or
capped; the cost of the ceremony is an anecdote, so the argument about
whether it earns its overhead has no units.

joulespec/1 leaves the prose alone and changes what the specification is.

Addressing (SPEC 1.2, 2.1). A clause carries a label AND an obligation: the
content address of its kind and text, with the label deliberately excluded.
Evidence binds to the obligation, so renaming a clause loses no evidence
while rewording one invalidates exactly that clause's evidence. Binding by
label inverts both halves -- it survives the edit that changed the
requirement and breaks on the edit that renamed it -- which is the mechanism
by which drift goes unobserved rather than a discipline failure.

This corrects our own prior art. joule-code-spec shipped the signed,
content-addressed clause and the citation binding a coding op to it, and its
citations bind by clause LABEL with a single notion of coverage: a clause is
covered when something claims it. That is the E0 rung here.

The ladder (SPEC 2.5, 2.6), ordered by one question -- how hard would it be
for this obligation to be violated without this evidence noticing?

  E0 cited        the implementer says so; where prevailing practice lands
  E1 reviewed     a second party read the artifact, once
  E2 exercised    a named check ran and passed -- and flatters: a test with
                  no assertion passes, as does one whose fixture never
                  reaches the condition the clause cares about
  E3 falsifiable  the same check is on record FAILING against a named
                  counter-artifact: the first rung where green means
                  something, and the cheapest strong one
  E4 proved       no input violates it, under a formalization cross-checked
                  by a key other than the prover's

A proof under a merely declared formalization grades E2, not E4: it is
machine-checked evidence that the something is this clause on the prover's
word. Demotion rather than refusal -- the proof is not fake. The crate never
formalizes a clause itself, and independence is computed from key
disjointness, never read from a producer's flag: a review signed by the
citing key is the citation again.

Evaluation (SPEC 3). A specification's grade is its WEAKEST owed obligation,
absent entirely when any has no surviving evidence; averaging would let nine
proved obligations conceal one nobody looked at. Non-goals are first-class
and excluded from the cap -- an unwitnessed non-goal is correct -- while
evidence that one WAS implemented is a flag that blocks conformance however
good the rest is. Nothing is dropped quietly: an unverifiable witness, one
naming another specification, and one naming an obligation the spec does not
state are each reported, that last being the normal aftermath of a rewording.
Ties break on address, so reordering the inputs cannot change the verdict.

Drift (SPEC 4) is a partition over addresses, not a warning: kept,
relabelled (editorial, no evidence lost), reworded (that clause's evidence
invalidated), added, removed -- from which the two sets a revision review
wants fall out. A freed label reused by a new clause is an addition, not a
rewording, because the old obligation still stands. The other direction needs
no diff: a witness is bound to the artifact state it observed, so evidence
from an earlier state is stale rather than counted.

Cost (SPEC 5). Witnesses and work each carry their joules, so the receipt
seals the specified share -- how much energy went into work citing no clause,
the measured form of agents producing features nobody requested -- and
microjoules per falsifiable obligation. That denominator is deliberately the
rung whose evidence can fail: a figure per ATTEMPTED obligation rewards
ceremony, and this family's other per-unit figures count accepted tokens and
verified proofs rather than attempts. Absent where nothing reaches the bar; a
cost per unit of nothing is not a small number.

Receipts (SPEC 6) are derived from the specification, artifact, witnesses and
work -- never from a verdict handed in. A verdict is an ordinary struct, and
an interface that signed one would let a producer construct the grade it
wanted. Sealed as joulespec/1 JCR-1 (canonical det-CBOR under COSE_Sign1,
Ed25519), byte-compatible with the family verifiers. The core admits no
nulls and several figures are legitimately absent, so those keys are OMITTED
rather than zeroed: a reader finding no grade knows none was established,
where one finding E0 would believe otherwise. Each receipt carries the
per-clause audit, because which obligation is the weak one is the actionable
fact and must be answerable from the receipt alone.

CI: joulespec-rs joins the standards matrix on `linux` with a new opt-in
`clippy: true` flag that gates the workspace at zero warnings on its own
runner. Deliberately not added to the macOS lint step -- that exists for code
only a macOS host can compile, and this workspace has no Apple anything. The
flag is per-entry rather than repo-wide because several workspaces are not at
zero yet, and a gate that fails on arrival teaches people to pass
--no-verify.

The modules cite their normative sections, so check-spec-refs binds the code
to the specification mechanically -- which this standard of all of them
should do.

cargo check/clippy/test --workspace --all-targets --locked: green, zero
warnings, on the M3 Ultra build host.

Co-Authored-By: Claude Opus 5 <[email protected]>

dcharlot merged commit 2860585f5a into main 2026-11-01 08:17:51 -05:00

dcharlot referenced this pull request from a commit 2026-11-01 08:17:53 -05:00

Merge pull request 'joulespec: a standard for energy-accounted specification conformance' (#561) from joulespec/standard-v0.1 into main

dcharlot referenced this pull request 2026-11-01 08:30:11 -05:00

joulespec: what the prior art changed — anchoring, vacuity, footprints, a second axis #562

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!561

No description provided.