docs(guide): long-form GUIDE.md with scrut-tested examples#23
Open
srnnkls wants to merge 3 commits into
Open
Conversation
Add GUIDE.md as the long-form companion to the README: features and authoring DX up front (mental model, first rule, stdlib vocabulary, writing when, the then verbs, synthesis, layering, packages, debugging), implementation and design motivations under a closing under-the-hood section. Back every worked example with tests/guide.md, a scrut suite over tests/guide_rules/ and tests/guide_rules_global/ fixtures, so the guide cannot drift from the binary.
Rewrite "What when cannot express" so every inert shape (sibling refs, let-over-input, input-dependent if, computed counts, close) is paired with the concrete, loadable pattern to use instead. Fix the count example: bare string/_ in a when matcher is rejected (E0501), so use a regex element. Back the alternatives with tests/guide_rules_alts/ and a scrut section proving each one compiles and fires.
Owner
Author
|
Updated: rebased onto Also added: each subsumption footgun in the guide now names a loadable alternative, backed by |
Incorporates the parser change that groups each invocation with its own command, subcommand, action, targets, and flags. Documents the flat-list over-match (cat README && rm .env) and the calls join that matches only a single call that both runs a read verb and targets a secret.
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.
What
Adds
GUIDE.md, the long-form companion to the README, plus a scrut suite that keeps its worked examples honest.The guide is ordered features-and-DX first, internals-and-design last:
when(subsumption, the parsed view, structural negation, whatwhencan't express), the fivethenverbs, how decisions combine, global/project layering, package organization, and the explain/vet/diagnostics loop.Tests
tests/guide.mdis a scrut suite (mirroringtests/policies.md/tests/diagnostics.md) asserting every worked example byte-for-byte, with fixtures undertests/guide_rules/(project layer) andtests/guide_rules_global/(global layer, for the layering examples). It's picked up automatically bymise run test-integration(globtests/*.md).Every output in the guide was captured from a real build, not written from memory.
scrut test -w . tests/*.md→ 88/88 pass (12 new, no regressions)go test ./tests/→ pass (the coverage/drift Go tests scan onlytests/policies/, so the new fixture dirs don't perturb them)Notes
tool.#Bash & list.MatchN(...)) don't emit a caret frame — only the leaf/kind/disjunction shapes intests/diagnostics.mddo — so the guide's explain test asserts exit codes (0 fired / 1 missed), which are deterministic.settings.jsonsnippet, since that schema is Claude Code's, not fas's. Easy to add if wanted.