docs: correct the route ladder, refusal wording and verifier count - #3
Merged
Merged
Conversation
Problem
A conformance pass over the published v1.0.0 found four documentation defects,
three of which contradicted artwork or code already shipped in the same repo.
Root cause
- The routes table in SKILL.md listed `delegate` before `audit`. Both the
decision ladder in references/call-sheet.md and the shipped docs/images/
routes.png use solo -> audit -> delegate -> full -> ensemble. The table was
the only surface disagreeing with the contract it defines.
- SKILL.md read "A later call sheet may only escalate... Never silently
downgrade" while role-contracts.md instructs downgrading an unsatisfiable
`ensemble` to sequential `full`. Read together the two forbade a reduction
the contract elsewhere requires.
- CHANGELOG stated the config schema "still advertises all three" wire_api
values and that the binary is the authority. An earlier entry in the same
file had already retracted exactly that claim: WireApi is a oneOf carrying
the single variant `responses`, so schema and binary agree.
- docs/images/proof.png carried a caption typo ("the runtimie s own session
record") and predated the mutation warning, so it implied a refused run
leaves the tree untouched.
Approach
Reorder the routes table to the canonical ladder and say so in the table's
lead-in. Rewrite the escalation paragraph so reducing rigour is constrained
rather than forbidden, and name the one planned reduction. Correct the
CHANGELOG entry to agree with its own retraction. Regenerate proof.png from
the launch film's theme so README artwork and the film share one source: it
now shows the real `ERROR:` prefix, the specification arriving on stdin, and
the warning that a write-capable lane may already have changed the tree.
Document the verifier count honestly. 154 is the invariant floor a machine
with neither CLI runs and CI asserts; 155 requires the optional Claude plugin
validator. WALKTHROUGH quoted 155 as if it were fixed.
Add a four-command smoke test to the Quickstart. None of the four calls a
model or writes outside a temp dir, so a new user can confirm an install
before trusting anything.
Verification
sh scripts/verify.sh -> passed 155, failed 0 (Claude CLI present)
-> passed 154, failed 0 (PATH=/usr/bin:/bin)
sh tests/run-tests.sh -> passed 143, failed 0
Every smoke-test command was run as written; cast-call.sh --lane terra --check
returns CHECK PASSED with and without codex on PATH.
Impact
Documentation and one image only. No script, manifest, lane profile or test
behaviour changes.
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
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.
Summary
A conformance pass over published v1.0.0 found four documentation defects. Three of them contradicted artwork or code already shipped in this same repository, which is the part worth fixing before the release is tagged.
What was wrong
The routes table disagreed with its own contract.
SKILL.mdlisteddelegatebeforeaudit. The decision ladder inreferences/call-sheet.mdand the shippeddocs/images/routes.pngboth use solo → audit → delegate → full → ensemble. The table was the only surface in the repo that disagreed with the contract it defines.Escalation wording forbade a reduction the contract requires.
SKILL.mdread "A later call sheet may only escalate… Never silently downgrade", whilerole-contracts.mdinstructs downgrading an unsatisfiableensembleto sequentialfull. Read together they contradicted each other. Reducing rigour is now described as constrained — it needs the same written evidence an escalation does — rather than forbidden, and the one planned reduction is named.The CHANGELOG contradicted its own retraction. One entry stated the published config schema "still advertises all three"
wire_apivalues and that the binary is the authority. An earlier entry in the same file had already retracted precisely that:WireApiis aoneOfcarrying the single variantresponses, so schema and binary agree.docs/images/proof.pnghad a caption typo and an outdated claim. It read "the runtimie s own session record", and it predated the mutation warning — implying a refused run leaves the working tree untouched. It does not.The verifier count is environment-dependent
WALKTHROUGH.mdquoted 155 as if fixed. Measured here:PATH=/usr/bin:/bin(what CI asserts)verify 1.0.0: passed 154, failed 0PATHverify 1.0.0: passed 155, failed 0The 155th check is the optional
claude plugin validate --strictmanifest validation. 154 is the invariant floor; the verdict never changes, only the count. Docs now say so.New artwork
proof.pngis regenerated from the launch film's own theme, so README artwork and the video share one source and cannot drift. It now shows the real output: theERROR:prefix rather thanREFUSED:, the specification arriving on stdin (< spec.md— there is no--taskflag), and the warning that a write-capable lane may already have modified the tree.Quickstart smoke test
Four commands, none of which calls a model, spends a token, or writes outside a temp dir. Each was run as written before being documented.
Verification
Risk
Documentation and one image. No script, manifest, lane profile, or test behaviour changes.
Follow-up
This should land before
v1.0.0is tagged, so the release ships docs that agree with the code.