docs: correct a false compatibility claim, add the governance a standard needs - #46
Merged
Merged
Conversation
…ard needs Two gaps between what this repository says about itself and what is true. ## The 0.7.2 release note was wrong docs/releases/0.7.2.md claimed "100% backward compatible with 0.7.1" and "No breaking changes". The compatibility gate added in #44 disproved it: $defs/notification gained additionalProperties: false, so a contract carrying any extra member on a build.execution.notifications[] entry validated under 0.7.1 and is rejected by 0.7.2. The page now names the change, shows the contract that breaks, and links to the waiver holding the evidence. Finding a false claim and leaving it standing because it is old would make the gate decorative. Also: docs/schema/versions.md said "the latest version is 0.7.4" and did not list 0.7.5 at all, while 0.7.5 is published in schema/, announced in the README and targeted by the whole conformance corpus. The public Schema Versions page was a release behind. Both linked 0.7.5 assets were confirmed present before linking them. ## The repo had no governance files at all 0 of 5, while forge-cli has 5/5 and forge-cli-sdk and FLUX have 4/5. A repository describing itself as "the open, declarative standard for Data Products" offered no route to contribute and no way to report a vulnerability privately. Added: CONTRIBUTING.md leads with the rule that surprises everyone: schema/ is vendored from forge-cli and a PR editing it will be reverted by the next sync. Says what IS editable here, and sets the corpus bar as falsifiability rather than case count. GOVERNANCE.md steward-maintainer, stated plainly rather than dressed up as multi-vendor governance that does not exist. Names the conflict of interest -- the maintainers also ship a commercial control plane on FLUID -- and lists the structural mitigations: MIT, no CLA, DCO, compatibility enforced by CI, ambiguities written down. SECURITY.md private vulnerability reporting, with a threat model appropriate to a spec repo: a schema that fails open, a case that passes for the wrong reason, a gate that cannot fail. CODE_OF_CONDUCT.md Contributor Covenant 2.1, with a reporting route. NOTICE is deliberately NOT added. It has to name a legal entity, and the estate currently carries five different copyright strings -- "Agentics Transformation Limited" (forge-cli), "Agentics Transformation Pty Ltd" (forge-cli-sdk), "Ltd" (flux-engine), "The FLUX Project authors" (flux-spec) and "fluid-steward" (this repo's LICENSE). Picking one here would bake in a guess. That decision is the owner's. ## Removed fluid-schema-0.3.1 -- a 12 KB JSON schema at the repo root with no .json extension, an $id pointing at open-data-protocol.org (not a domain we control) labelled "v2.0", never present in schema/, never listed in versions.md, never rendered to specs/, and referenced by nothing. Recoverable with `git show 550dea8:fluid-schema-0.3.1`. ## Verified Link-check's base-prefix rule run locally (passes). VuePress build green -- and because that build exits 0 even when a page fails to render, both edited pages were checked in the rendered HTML: the correction and its example appear, the heading no longer claims full compatibility, the only surviving instance of the old phrase is inside the quoted correction, and versions.html shows 0.7.5 as latest with both linked assets present in dist/. Corpus 480/480, meta-test 19/19, compat gate clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
fas89
added a commit
that referenced
this pull request
Sep 13, 2026
…struction Two things that had quietly stopped being true. 1. mutation_coverage.py ran nowhere. `run.py` answers "do the cases pass" — a corpus of zero cases answers that perfectly. `mutation_coverage.py` answers the harder question: delete a constraint from the schema and see whether any case notices. It has been in this repo, runnable, documented and wired into nothing, so the figure could have fallen to zero between releases in silence. The floor is the current number rounded down (40.7% -> 40), not a target. That is where mutation-testing gates converge (Stryker, mutmut): a break threshold set where you actually are catches a regression on day one, whereas an aspirational one goes red immediately and gets deleted by day three, which is worse than no gate. Deliberately NOT a ratchet, and the divergence is on purpose. Ratchets exist to absorb run-to-run noise; there is none here, because the run is deterministic — mutate the schema, replay the corpus, count. A fixed floor does the same work with less machinery, and raising it stays a deliberate edit made when a corpus wave earns it. Proven to fail, three ways: --min-coverage 41 exits 1 against today's tree; trimming the metadata group to a single case drops it below 40 and turns the gate red; restoring it goes green again. 2. A waiver told the next reader to fix something already fixed. compat-waivers.txt said docs/releases/0.7.2.md "should be corrected to name this change". It was corrected, in #46 — the note now opens "One breaking change, corrected here after the fact". The instruction outlived the work. The waiver line itself stays, permanently: 0.7.2 is published and its history cannot be rewritten, so the gate has to be told this break is known rather than new. The comment now says that, and says what a waiver must never become — a way to quiet the gate about a break nobody dealt with. This one was dealt with by correcting the release note, not by adding the line. Corpus 480/480 and meta-test 19/19 unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
fas89
added a commit
to fas89/fluid
that referenced
this pull request
Oct 4, 2026
…struction Two things that had quietly stopped being true. 1. mutation_coverage.py ran nowhere. `run.py` answers "do the cases pass" — a corpus of zero cases answers that perfectly. `mutation_coverage.py` answers the harder question: delete a constraint from the schema and see whether any case notices. It has been in this repo, runnable, documented and wired into nothing, so the figure could have fallen to zero between releases in silence. The floor is the current number rounded down (40.7% -> 40), not a target. That is where mutation-testing gates converge (Stryker, mutmut): a break threshold set where you actually are catches a regression on day one, whereas an aspirational one goes red immediately and gets deleted by day three, which is worse than no gate. Deliberately NOT a ratchet, and the divergence is on purpose. Ratchets exist to absorb run-to-run noise; there is none here, because the run is deterministic — mutate the schema, replay the corpus, count. A fixed floor does the same work with less machinery, and raising it stays a deliberate edit made when a corpus wave earns it. Proven to fail, three ways: --min-coverage 41 exits 1 against today's tree; trimming the metadata group to a single case drops it below 40 and turns the gate red; restoring it goes green again. 2. A waiver told the next reader to fix something already fixed. compat-waivers.txt said docs/releases/0.7.2.md "should be corrected to name this change". It was corrected, in open-data-protocol#46 — the note now opens "One breaking change, corrected here after the fact". The instruction outlived the work. The waiver line itself stays, permanently: 0.7.2 is published and its history cannot be rewritten, so the gate has to be told this break is known rather than new. The comment now says that, and says what a waiver must never become — a way to quiet the gate about a break nobody dealt with. This one was dealt with by correcting the release note, not by adding the line. Corpus 480/480 and meta-test 19/19 unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
fas89
added a commit
that referenced
this pull request
Oct 4, 2026
docs: correct a false compatibility claim, add the governance a standard needs
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.
Two gaps between what this repository says about itself and what is true. Both are unblocked follow-ups to the conformance work in #44 and #45.
1. The 0.7.2 release note was wrong
docs/releases/0.7.2.mdclaimed "100% backward compatible with 0.7.1" and "No breaking changes". The compatibility gate added in #44 disproved it:$defs/notificationgainedadditionalProperties: false, so a contract carrying any extra member on abuild.execution.notifications[]entry validated under 0.7.1 and is rejected by 0.7.2.The page now names the change, shows the contract that breaks, and links to the waiver holding the evidence. Finding a false claim and leaving it standing because it's old would make the gate decorative.
Also:
docs/schema/versions.mdsaid "the latest version is 0.7.4" and didn't list 0.7.5 at all — while 0.7.5 is published inschema/, announced in the README, and targeted by the entire conformance corpus. The public Schema Versions page was a release behind. Both linked 0.7.5 assets were confirmed present before linking them.2. The repo had no governance files at all
0 of 5 — while
forge-clihas 5/5 andforge-cli-sdkandflux-spechave 4/5. A repository describing itself as "the open, declarative standard for Data Products" offered no route to contribute and no way to report a vulnerability privately.CONTRIBUTING.mdschema/is vendored from forge-cli, and a PR editing it gets reverted by the next sync. Says what is editable here, and sets the corpus bar as falsifiability, not case count.GOVERNANCE.mdSECURITY.mdCODE_OF_CONDUCT.mdNOTICEis deliberately not added. It has to name a legal entity, and the estate currently carries five different copyright strings: "Agentics Transformation Limited" (forge-cli), "Agentics Transformation Pty Ltd" (forge-cli-sdk), "Ltd" (flux-engine), "The FLUX Project authors" (flux-spec), and "fluid-steward" (this repo'sLICENSE). Picking one here would bake in a guess. That decision is yours — and it's the same one gating the Command Center licence fix.3. Removed
fluid-schema-0.3.1— a 12 KB JSON schema at the repo root with no.jsonextension, an$idpointing atopen-data-protocol.org(not a domain we control) labelledv2.0, never present inschema/, never listed inversions.md, never rendered tospecs/, referenced by nothing. Recoverable withgit show 550dea8:fluid-schema-0.3.1if you'd rather keep it.Tested
This is the first PR to touch
docs/**, so it's the first to triggerlink-check. I ran its exact base-prefix rule locally — passes.VuePress build is green, but that build exits 0 even when a page fails to render, so I checked the rendered HTML rather than the exit code:
releases/0.7.2.html(34 KB) contains the correction and theretryOnFailureexample<h2>now reads "Backward compatibility with 0.7.1 — one narrowing change"schema/versions.htmlrenders "latest version is 0.7.5", and both linked assets are present indist/Corpus 480/480, meta-test 19/19, compat gate clean.
Still open
required_status_checksonmainis empty, so every gate in this repo — including the conformance suite — is advisory at merge time.🤖 Generated with Claude Code