Skip to content

docs: correct the route ladder, refusal wording and verifier count - #3

Merged
DivyamTalwar merged 1 commit into
mainfrom
docs/v1-release-corrections
Sep 3, 2026
Merged

DivyamTalwar merged 1 commit into
mainfrom
docs/v1-release-corrections

Conversation

@DivyamTalwar

Copy link
Copy Markdown
Owner

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.md listed delegate before audit. The decision ladder in references/call-sheet.md and the shipped docs/images/routes.png both 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.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 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_api values and that the binary is the authority. An earlier entry in the same file had already retracted precisely that: WireApi is a oneOf carrying the single variant responses, so schema and binary agree.

docs/images/proof.png had 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.md quoted 155 as if fixed. Measured here:

environment result
PATH=/usr/bin:/bin (what CI asserts) verify 1.0.0: passed 154, failed 0
Claude CLI on PATH verify 1.0.0: passed 155, failed 0

The 155th check is the optional claude plugin validate --strict manifest validation. 154 is the invariant floor; the verdict never changes, only the count. Docs now say so.

New artwork

proof.png is 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: the ERROR: prefix rather than REFUSED:, the specification arriving on stdin (< spec.md — there is no --task flag), 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

sh scripts/verify.sh    -> passed 155, failed 0   (Claude CLI present)
sh scripts/verify.sh    -> passed 154, failed 0   (PATH=/usr/bin:/bin)
sh tests/run-tests.sh   -> passed 143, failed 0
sh scripts/cast-call.sh --lane terra --check -> CHECK PASSED, with and without codex on PATH

Risk

Documentation and one image. No script, manifest, lane profile, or test behaviour changes.

Follow-up

This should land before v1.0.0 is tagged, so the release ships docs that agree with the code.

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.
@DivyamTalwar
DivyamTalwar merged commit 74d3116 into main Sep 3, 2026
2 checks passed
@DivyamTalwar
DivyamTalwar deleted the docs/v1-release-corrections branch September 3, 2026 11:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant