docs: schema contracts guide + contract attribution on write-failure output#269
Merged
Conversation
New docs/contracts.md — the full producer→consumer tour (declare + adopt, composed enforcement, the two-rung verification ladder, evolution patterns, housekeeping), with every command output pasted from a live run against the shipped CLI. Touch-ups: cli.md command group + exit 67, api.md surface/errors/ canonicalContractHash, concepts.md Contract entry, mkdocs nav. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KJCxogamrSUZ7etFGsnoD1
The core tags a failing allOf branch with its contract name (specs/behaviors/contracts.md "a failing write says which obligation it violated") and the ContractError printer already rendered it, but the ValidationError printer dropped it — an upsert rejected by a contract looked identical to one rejected by the local schema. Append the [contract-name] tag when present; verified live against a declaring sheet. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KJCxogamrSUZ7etFGsnoD1
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
1 participant
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
Consumer-facing documentation for the schema-contracts feature that just landed (PRs #265/#267/#268) — the docs site had zero coverage.
docs/contracts.md— the full tour: contract documents and naming,adopt+implements(producer side), composed write-time enforcement, the two-rung consumer verification ladder (openSheet({ contract })),canonicalContractHash, evolution patterns (additive multi-implements, breaking-change bridges), and housekeeping (sync/export/prune). Every command output is pasted from a live run against the built CLI in a scratch repo, not invented.docs/cli.md(gitsheets contractscommand group + exit code 67),docs/api.md(module surface,openSheetcontract option,ContractErrorrow,canonicalContractHashutility),docs/concepts.md(Contract entry),mkdocs.ymlnav.Plus one small fix the live run surfaced
fix(cli): the write-failure printer dropped the contract attribution the core provides — an upsert rejected by a contract looked identical to one rejected by the local schema, contradicting the spec's "a failing write says which obligation it violated." Issue lines now append[<contract-name>]when present (theContractErrorprinter already did this;ValidationError's didn't).Verified:
npm test -w gitsheets388/388, type-check clean, live CLI run confirms the tag renders.🤖 Generated with Claude Code
https://claude.ai/code/session_01KJCxogamrSUZ7etFGsnoD1