Pular para conteúdo

AUR-017: Fixar standards de artefatos interoperáveis

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

This is a research/decision card. It does not ship an emitter, parser, or publisher for any of the four standards it fixes; it fixes the design contract dependent adapter cards implement against. The observable behavior is the acceptance lint itself: tests/acceptance/AUR-017.sh deterministically resolves the artifacts below and either passes or names exactly which one is incomplete.

Behavior

tests/acceptance/AUR-017.sh (selector AC-001) reads the artifacts this card owns and checks that they resolve to one consistent, versioned decision per standard, without making any network request:

  1. .board/research/interoperability.md — a "Standards matrix" table that fixes SARIF, unified diff, JSON Schema, and OpenAPI, one row per standard, each with a [label](url) source, a Version, an ISO-8601 Date, a Validator cell, and an Interoperability role cell — plus a prose "Interoperability context: MCP" section, since MCP is the reason the JSON Schema pin is an external interoperability boundary and not an internal choice, even though MCP itself has no fixed artifact version in this card's Outcome.
  2. standards/contracts/versions.yaml — the single source of truth for the exact pinned version (and, for SARIF and JSON Schema, the exact schema/dialect URI) per standard.
  3. standards/contracts/<format>/validator.md — names the real validator tool and version a later adapter card will run, and the bounded structural rule this card's own lint checks in its place.
  4. standards/contracts/<format>/fixtures/valid.* and invalid.* — one minimal example each format's structural rule accepts and rejects.

The lint also re-checks the three literal terms the Outcome/Given clause names directly (SARIF 2.1.0, OpenAI, MCP), case-sensitive, in .board/research/interoperability.md.

Contract

  • tests/specs/AUR-017/formats.txt and tests/specs/AUR-017/allowed-source-domains.txt are the single source of truth for, respectively, the exact four standard names the matrix and standards/contracts must resolve, and the hostnames a matrix Source link may cite. tests/acceptance/AUR-017.sh reads both instead of duplicating the lists.
  • A matrix row's Version cell must match a semantic-version-like pattern (2.1.0, 3.10), a JSON-Schema-style draft-date identifier (2020-12), or an immutable post identifier (post 1904957253456941061) paired with its Date — the same three shapes AUR-020 fixed, reused rather than reinvented.
  • Each standard's matrix Version cell must equal standards/contracts/versions.yaml's pinned version for that standard, and each standard's fixtures/valid.* must itself declare that same pinned version (and, where applicable, the pinned schema/dialect URI). Divergence between the matrix, the pin, or the fixture — the shape of MUT-001 — fails with the same typed code: AUR-017/AC-001/undecided-standard.
  • A Source cell whose host is not in tests/specs/AUR-017/allowed-source-domains.txt, or whose Version cannot be resolved as versioned/dated — the shape of MUT-002 — fails the same way.
  • Each format's fixtures/invalid.* must be rejected by this card's own bounded structural lint for the single reason its validator.md names; a fixture that lint accepts by mistake also fails with AUR-017/AC-001/undecided-standard.
  • This card produces no SARIF emitter, diff generator, schema author, or OpenAPI publisher, and it does not install or invoke any of the named validator tools. The SARIF, unified-diff, JSON Schema, and OpenAPI surfaces it fixes are implemented by dependent O05-review, O06-scm, O04-agents/O11-mcp, and integration adapter cards, not here.

Limits

There is no separate limits file for this card; the only bounded quantities it fixes are the exact pinned versions and schema/dialect URIs in standards/contracts/versions.yaml, which a consumer repository may not raise past what is declared there without a separate, reviewed change to that file.

Example (no secret)

Running the acceptance test directly, with no network access and no secret material of any kind:

$ ./.board/bin/oci-run --profile bootstrap-readonly-v1 --card AUR-017
{"card":"AUR-017","scenario":"AC-001","selector":"AC-001","standards_fixed":4,"criteria_columns":2,"result":"pass"}

A failing example — the SARIF fixture's $schema value edited to a different host:

$ tests/acceptance/AUR-017.sh
AUR-017/AC-001/undecided-standard: sarif valid fixture rejected by lint: schema mismatch: got "https://example.invalid/sarif-schema-2.1.0.json" want "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json"

Diagnosis

  • AUR-017/AC-001/undecided-standard: required artifact absent: <path> (or ... is empty: <path>) — one of interoperability.md, standards/contracts/versions.yaml, standards/contracts/README.md, or a tests/specs/AUR-017/* fixture is missing or empty. Restore it from the card's owned paths.
  • AUR-017/AC-001/undecided-standard: research is missing required term: <term> — one of the three literal Outcome terms (SARIF 2.1.0, OpenAI, MCP) was removed from .board/research/interoperability.md.
  • AUR-017/AC-001/undecided-standard: standard <name> ... — the matrix row for that standard is missing, duplicated, has no versioned source, has a non-ISO date, cites a non-allowlisted source host, or has an empty criterion cell. Fix the offending cell in the "Standards matrix" table.
  • AUR-017/AC-001/undecided-standard: standard <name> matrix version (...) diverges from standards/contracts/versions.yaml (...) — the matrix Version cell and the pin in versions.yaml disagree; make them equal.
  • AUR-017/AC-001/undecided-standard: <format> valid fixture rejected by lint: <reason> — the format's fixtures/valid.* no longer satisfies its own validator.md rule (commonly: its embedded version or schema/dialect URI no longer matches versions.yaml after a version bump). Migrate the fixture.
  • AUR-017/AC-001/undecided-standard: <format> invalid fixture was accepted by lint; it must be rejected — the format's fixtures/invalid.* was edited into something the structural lint no longer rejects; restore a fixture that fails for the single reason its validator.md names.
  • AUR-017/AC-001/infrastructure: ... — a required host tool is missing or the repository root could not be resolved; this is never a behavioral result and never counts as RED evidence for this card.