Repository navigation
Truth reconciliation: consumer #1 wired, public contract states what ships (CLOUD-198) - #109
Merged
Merged
Conversation
CLOUD-198 Truth reconciliation: every committed claim is true or marked planned
The 2026-08-07 alignment audit found 44 places where a committed artifact contradicts a spec commitment or a shipped doc describes behaviour that does not exist (see project document Alignment audit 2026-08-07 — Conflict & divergence register). This issue tracks the mechanical subset: make each claim true, or rewrite it as a plan pointing at its issue. No feature work. Scope (register numbers in parentheses):
Ready
CLOUD-71 Land `batten.toml` at this repo's root
Why Acceptance
|
…sitory
Refs: CLOUD-71
Three committed files asserted that the checked-in batten.toml is what
`batten check` runs against this repository. Nothing did: no hk step, no
mise task, no workflow invoked the binary, so the engine's one configured
rule had never executed anywhere. The assertion becomes a mechanism:
mise.toml batten-check — `cargo run --quiet -p batten -- check`, so
the gate judges the working tree's engine and config as the
pair that ships
hk.pkl a batten-check step in the shared gate, chained after `test`
so one cargo build holds the target-dir lock at a time; no
glob, because any file can carry a violation
tests/cli.rs the committed batten.toml pinned behaviourally: it loads,
and its rule fires on the shape it names, pointer-only and
byte-stable
The bash gates this repo runs are not migrated here: none of them is a
content predicate the current rule table can express (path existence,
reference resolution, exemption lists) — each such gap is capability-issue
material on the board, not a reason to widen this change.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VS5eTnMTruCWytpAk2gW7k
Refs: CLOUD-198 House style §2: bare invocation lists subcommands and never performs a default action. The shipped binary printed nothing and exited 0, and the comment claiming clap had already offered help was false — neither arg_required_else_help nor subcommand_required was set, and the exit-code table blessed the silence by asserting only the code. clap now renders the subcommand listing on its error path (stderr, exit 2), so stdout stays the answer channel and a script can never mistake the listing for an answer. Pinned by a behavioural test over the compiled binary; the exit-table case updated to the new contract. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VS5eTnMTruCWytpAk2gW7k
…rest
Refs: CLOUD-198
The consumer-facing files published four false claims, some across all 15
releases:
README exit table said 70 for internal error; the binary exits 3
(exit.rs pins it). Zero-config/init/doctor were described as
present; none exists — now a roadmap line naming CLOUD-70 and
CLOUD-66, with today's requirement stated. The hook inversion
is marked planned (CLOUD-40). Setup now goes through mise, so
the front page stops contradicting the repo's own top rule
and stops skipping the setup that makes the bats suites run.
The status note records that no public install path exists.
CHANGELOG the hand-written body claimed a dual MIT/Apache license; the
repo ships Apache-2.0 only. release-plz owns this file; the
stale body is gone.
CONTRIBUTING cross-check no longer claims macOS coverage that moved to
darwin-link.
example the copy-me template could never produce a finding: 13 of 29
lines documented a key no gate reads, no [[rule]] existed,
and the one lowering path it advertised is refused by the
raise-only floor. It now ships a live rule and names the
floor; a test asserts the rule fires.
Cargo.toml keywords trimmed to shipped capabilities.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VS5eTnMTruCWytpAk2gW7k
Refs: CLOUD-198
Five places restated a fact some other artifact owns, and each had drifted:
AGENTS.md the numbered non-negotiables are what DoR/DoD cites as
"rules 2, 3, 4, 5", but position 5 held configuration-
narrowness, so the spec's output-and-exit citation
misresolved. The exit contract is now rule 5; config
narrowness moves to 6 — which config.rs:9 already cited
as 6, so the crate's citations now all resolve. The Done
column points at the Done definition instead of restating
it as "released" (the release mapping is CLOUD-192).
Surrounding prose tightened to pay the context-budget
gate for the insertion.
toolchain.md claimed "three PreToolUse hooks"; settings.json wires
five. The count is gone; the settings file is the
authoritative list.
rust.md carried a scaffold-era module tree that called the
command surface empty; mem:core owns the map.
mem:toolchain-and-hooks
stated the context-budget default as 6000; the gate's
default is 3500. Edited in place: the Serena tools that
own memory writes are unavailable in this session, and
the change is a one-word correction with no rename or
reference change, so the guard's rewrite machinery has
nothing to do.
severity.rs module doc described per-rule severity as authored in
batten.toml; Rule has no such field and rejects one.
Now stated as CLOUD-61's pending wiring.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VS5eTnMTruCWytpAk2gW7k
wenzowski
force-pushed
the
claude/committed-vs-docs-alignment-z1pb7a
branch
from
August 7, 2026 20:37
f3fb599 to
de50ee4
Compare
wenzowski
marked this pull request as ready for review
August 7, 2026 20:39
Contributor
Author
|
/fast-forward |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The 2026-08-07 alignment audit (registers attached to CLOUD-198 and the Batten project documents) found the repo's committed claims and its committed behaviour had come apart. This branch closes the mechanical subset:
feat(gate): consumer ci: check in the main-branch protection ruleset #1 is now a mechanism, not an assertion.batten checkruns in the shared hk gate (batten-checkstep + mise task), evaluating the committedbatten.tomlon every commit and in CI; a behavioural test pins that the committed config loads and its rule fires. Previously zero of hk/mise/CI invoked the binary while three committed files claimed otherwise.fix(cli): bare invocation lists subcommands (house style §2) on clap's error path — stderr, exit 2 — instead of printing nothing and exiting 0. Test updated + new behavioural test.docs(contract): the public contract states what ships. README exit table70→3(the binary exits 3, pinned by test); zero-config/init/doctorrewritten as roadmap naming CLOUD-70/CLOUD-66; hook inversion marked planned (CLOUD-40); setup goes through mise; status note records that no public install path exists (recorded distribution deferral). CHANGELOG's hand-written body removed — it claimed a dual MIT/Apache license that does not exist; release-plz owns the file.batten.example.tomlships a live[[rule]](a copied config can now actually produce a finding, asserted by test) and names the strictness floor. CONTRIBUTING stops claiming macOS coverage that moved todarwin-link. Cargo keywords trimmed to shipped capabilities.docs(graph): one authority per fact. AGENTS.md non-negotiables renumbered so DoR/DoD's "rules 2, 3, 4, 5" citations resolve (exit contract inserted at 5 — whichconfig.rs:9already cited); Done column points at the Done definition; guard count replaced by a pointer to.claude/settings.json; stale scaffold-era module tree deleted;mem:toolchain-and-hookscontext-budget default corrected 6000→3500;severity.rsmodule doc no longer describes a config field the schema rejects.Why
Refs CLOUD-198 (tracking issue, register-linked) and CLOUD-71 (consumer #1). Full conflict register: Alignment audit 2026-08-07 — Conflict & divergence register (Linear project documents).
Verification
mise run cigreen locally per commit (pre-commit gate, including the newbatten-checkstep)bare_invocation_lists_subcommands,the_committed_repo_config_gates_a_repository, example-config rule-fires assertionmise run verifybefore readying, per the workflow contract🤖 Generated with Claude Code
https://claude.ai/code/session_01VS5eTnMTruCWytpAk2gW7k