From e5b00383a5ebca2bc0ae1da1fbbaa8d8d4429ac7 Mon Sep 17 00:00:00 2001 From: Qwynn Marcelle Date: Sun, 9 Aug 2026 10:08:47 -0400 Subject: [PATCH] docs(meta-257): add the ratified conformance taxonomy Records the vocabulary that separates standard conformance from first-party adapter parity from external consumer conformance, so that adapter behaviour cannot become the contract by citation. The taxonomy half of META-257 is ratified. The contract classes in the final section remain provisional pending second-adapter evidence (META-260), and are marked as such in the document. Companion to docs/migration/identity-catalog.md, which named this document as the taxonomy half's destination. --- docs/migration/conformance-taxonomy.md | 91 ++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/migration/conformance-taxonomy.md diff --git a/docs/migration/conformance-taxonomy.md b/docs/migration/conformance-taxonomy.md new file mode 100644 index 0000000..0a0a0f8 --- /dev/null +++ b/docs/migration/conformance-taxonomy.md @@ -0,0 +1,91 @@ +# Conformance taxonomy + +Ratified vocabulary for distinguishing standard conformance from first-party adapter parity from external consumer conformance. This is the taxonomy half of META-257; boundary ratification waits for second-adapter evidence (META-260). + +## Why this vocabulary exists + +A contract harvested from one implementation is not a contract; it is a description. Without a vocabulary that separates "the standard says this" from "our adapter does this," the first adapter's shape leaks into the contract by citation. "Provisional" is not a load-bearing safeguard — provisional ratifications become canonical through repeated reference. + +This taxonomy prevents that leak by making the three conformance classes structurally distinct. + +## The three conformance classes + +### 1. Standard conformance + +**Definition:** A workspace.json artifact (file, schema, reference-reader output, rules evaluation) conforms to the published standard when it satisfies the normative contracts in `workspacejson/standard` — not when it matches any particular adapter's behavior. + +**Owner:** `workspacejson/standard` + +**Test:** An artifact is standard-conformant if a reference reader built from the published spec (not from any adapter's source) reads it without error and produces the expected evidence. + +**What it is not:** Standard conformance does not require any first-party runtime. An external consumer who writes a workspace.json reader from the published spec and produces valid evidence is standard-conformant. + +### 2. First-party adapter parity + +**Definition:** Two or more first-party adapters (Codex, Claude Code, VS Code, CI) exhibit parity when they produce identical behavior on identical inputs against identical workspace.json artifacts. This is internal QA, not a standard contract. + +**Owner:** `workspacejson/integrations` + +**Test:** Run both adapters against the same fixture workspace.json and compare outputs (exit codes, evidence, hook decisions, MCP responses). The parity receipt mechanism (META-241) is an example of this test. + +**What it is not:** Adapter parity does not define the standard. If all first-party adapters share a behavior that the standard does not specify, that behavior is adapter convention, not standard conformance. A second adapter that differs from the first in an unspecified area is not non-conformant — it is revealing an underspecification. + +### 3. External consumer conformance + +**Definition:** A consumer who has no access to first-party internals (Linear issues, private packages, adapter source, internal discussions) conforms to the standard when they can read, evaluate, and act on workspace.json artifacts using only published materials. + +**Owner:** The external consumer + +**Test:** Cold read — give an agent or human only the published spec, npm package, and README. Can they produce a conformant reader? Can they interpret a workspace.json artifact correctly? What do they find ambiguous? + +**What it is not:** External consumer conformance does not require matching first-party adapter behavior in unspecified areas. The external consumer's interpretation of an underspecified area is valid evidence of underspecification, not a conformance failure. + +## Relationship between the three classes + +```text +Standard conformance (spec-owned) + ├── First-party adapter parity (internal QA, proves the standard is implementable) + └── External consumer conformance (proves the standard is adoptable without insider knowledge) +``` + +- Standard conformance is the only class that defines normative contracts. +- First-party adapter parity is evidence that the standard is implementable, not a definition of the standard. +- External consumer conformance is evidence that the standard is adoptable, not a weaker form of parity. +- A gap between adapter parity and external conformance reveals an underspecification in the standard, not a failure of the external consumer. + +## Capability support classification + +When recording adapter capabilities against the standard: + +| Classification | Meaning | +| -- | -- | +| **native** | The provider's public API directly supports this capability. | +| **adapted** | The provider's API does not directly support this, but an adapter can synthesize it with documented limitations. | +| **unavailable** | The provider's API does not support this and no adapter synthesis is possible. | + +Absence of a capability is **unavailable**, never inferred as safe. "Adapted" must document its limitations; it is not a synonym for "works well enough." + +## What this vocabulary prevents + +1. **Contract harvesting:** "Codex does X, so the standard requires X" — prevented because adapter behavior is parity, not conformance. +2. **Provisional drift:** "We provisionally ratified X" becoming "X is canonical" — prevented because the taxonomy makes clear which class a claim belongs to. +3. **Underspecification hiding:** "All our adapters do X the same way" implying "X is specified" — prevented because parity is explicitly not conformance. +4. **External exclusion:** "You're not conformant because you don't match our adapter" — prevented because external conformance is measured against the spec, not against adapters. + +## Contract classes (provisional) + +These are the contract classes from META-257. They are provisional until second-adapter evidence (META-260) forces changes. The vocabulary above governs their interpretation. + +1. **Stable standard-owned inputs/results** — artifact discovery/read/validation status; standard/rules evidence and conformance fixtures. +2. **Provisional integration delivery contracts** — changed path/changeset request; deterministic gate result with evidence references; availability/provenance receipt. +3. **Narrow optional capability ports** — authorization exception; batch changeset acquisition; workspace watch/invalidation; native advisory review (only if equivalent semantics are later proven). + +## Exit criteria for provisional interfaces + +Every provisional interface must declare: + +- What evidence would stabilize it (second adapter? external consumer? cold read?) +- What evidence would retire it (no adapter supports it? standard drops it?) +- What evidence would change it (second adapter differs in a way that forces a contract change?) + +An interface with no exit criteria is not provisional; it is permanent in disguise.