docs: correct the --no-update claim in the CI and pre-commit recipes - #70
Merged
Conversation
Both recipes claimed that `mdvs check --no-update` fails with a
`Disallowed` violation when a commit adds a new frontmatter field. It
does not. Verified against the current binary:
Checked 2 files — no violations, 1 new field(s)
EXIT: 0
`check/validate.rs` iterates the fields declared in mdvs.toml rather than
the keys found in a file, and the canonical schema is emitted with
`additionalProperties: true`, so a key that appears in no
`[[fields.field]]` entry is never examined. `Disallowed` means something
narrower — a *declared* field appearing outside its `allowed` globs.
Also verified what auto-update actually does, since the old text was
vague: re-inference only ever adds new fields. It does not widen an
existing field's type or relax its constraints, so a bad category value
or a wrong type fails in both modes. The real difference is that
auto-update rewrites mdvs.toml on disk mid-run while `--no-update`
leaves it alone and reports new fields instead.
`--no-update` is still the right default in CI and in a hook; the
justification changes, not the advice. Adds a section documenting the
undeclared-field gap explicitly, with a working jq gate for anyone who
wants it to break the build today:
mdvs check --no-update --output json | jq -e '.new_fields | length == 0'
The reference pages (commands/check.md, concepts/validation.md) already
described this correctly — only the two recipes had drifted.
Co-Authored-By: Claude <noreply@anthropic.com>
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.
Both recipes documented a validation gate that does not exist.
The false claim
ci.mdandpre-commit.mdeach stated thatmdvs check --no-updatefails with aDisallowedviolation when a commit adds a new frontmatter field. Verified against the current binary — it exits 0:check/validate.rs:150iterates the fields declared inmdvs.tomlrather than the keys found in a file, anddsl_to_canonicalemits the root schema withadditionalProperties: true, so a key appearing in no[[fields.field]]entry is never examined.Disallowedmeans something narrower: a declared field appearing outside itsallowedglobs.This matters because anyone following the CI recipe believes they have a gate against schema drift that isn't there.
What auto-update actually does
The old text was also vague on the flag's real effect, so I measured it:
--no-updatemdvs.toml, exit 0categoriesRe-inference only ever adds fields — it never widens an existing field's type or relaxes its constraints. The real difference is that auto-update rewrites
mdvs.tomlon disk mid-run, while--no-updateleaves it alone and reports new fields instead.--no-updateremains the right default in CI and in a hook. The justification changes, not the advice.Changes
ci.md— rewrote the--no-updatesection around the measured behavior; added acheckdoes not fail on undeclared fields section; fixed a second instance of the same falsehood in the "Whatcheckdoes" list (✓ Disallowed fields (anything not in mdvs.toml and not in ignore)→ the correct narrow meaning).pre-commit.md— replaced the inherited claim. The hook framing is stronger for it: without--no-update, committing a new field silently editsmdvs.tomlin your working tree mid-commit, leaving a modification you never staged.For anyone who wants the gate today, the new section documents a workaround, verified to exit non-zero only when a new field is present:
Notes
getting-started.md:121looks like the same bug but is correct —sensor_typeis a declared field withallowed = ["projects/alpha/notes/**"], so placing it in a blog post is genuinelyDisallowed. Left as-is.commands/check.md:37,concepts/validation.md:121) already described this accurately. Only the two recipes had drifted — an argument for recipes citing the reference pages rather than restating them.