Skip to content

docs: correct a false compatibility claim, add the governance a standard needs - #46

Merged
fas89 merged 1 commit into
mainfrom
docs/truth-and-governance
Sep 7, 2026
Merged

fas89 merged 1 commit into
mainfrom
docs/truth-and-governance

Conversation

@fas89

@fas89 fas89 commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

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.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.

build:
  execution:
    notifications:
      - type: slack
        target: "#data-alerts"
        condition: failure
        retryOnFailure: true   # accepted by 0.7.1, 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.md said "the latest version is 0.7.4" and didn't list 0.7.5 at all — while 0.7.5 is published in schema/, 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-cli has 5/5 and forge-cli-sdk and flux-spec 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.

File What it does
CONTRIBUTING.md Leads with the rule that surprises everyone: schema/ 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.md Steward-maintainer, stated plainly rather than dressed up as multi-vendor governance that doesn't exist. Names the conflict of interest — the maintainers also ship a commercial control plane on FLUID — and lists structural mitigations: MIT, no CLA, DCO, compatibility enforced by CI, ambiguities written down.
SECURITY.md Private vulnerability reporting, with a threat model suited 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 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 .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/, referenced by nothing. Recoverable with git show 550dea8:fluid-schema-0.3.1 if you'd rather keep it.

Tested

This is the first PR to touch docs/**, so it's the first to trigger link-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 the retryOnFailure example
  • the <h2> now reads "Backward compatibility with 0.7.1 — one narrowing change"
  • the only surviving instance of "100% backward compatible" is inside the quoted correction
  • schema/versions.html renders "latest version is 0.7.5", and both linked assets are present in dist/

Corpus 480/480, meta-test 19/19, compat gate clean.

Still open

required_status_checks on main is empty, so every gate in this repo — including the conformance suite — is advisory at merge time.

🤖 Generated with Claude Code

…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
fas89 merged commit 2557fbb into main Sep 7, 2026
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
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