machine-readable-json.md

Machine-Readable JSON Compatibility

Every public --format json document identifies its top-level contract with schemaVersion. Consumers must select a parser from that value rather than from the Renma package version, command name, field order, or an implementation path.

Contract identifiers

Command or output	Top-level schemaVersion	Repository compatibility assurance
scan	renma.scan.v2	Representative whole-document golden
catalog	renma.catalog.v1	Representative whole-document golden
graph	renma.graph.v1	Representative whole-document golden
readiness	renma.readiness.v2	Representative whole-document golden
ownership	renma.ownership.v1	Representative whole-document golden
diff	renma.diff.v1	Representative revision-diff whole-document golden
ci-report	renma.ci-report.v1	Representative revision-report whole-document golden
inspect outline	renma.inspect-outline.v1	Representative whole-document golden
inspect --lines	renma.inspect-slice.v1	Representative whole-document golden
guide skill	renma.skill-authoring-guide.v2	Representative whole-document golden
scaffold	renma.scaffold.v1	Representative whole-document golden
suggest-metadata	renma.metadata-suggestion.v1	Representative whole-document golden
suggest-semantic-split	renma.semantic-split-suggestion.v1	Representative whole-document golden
skill-index	renma.skill-index.v1	Representative whole-document golden
trust-graph	renma.trustGraph.v2	Published JSON Schema plus frozen semantic contract fixture
bom	renma.repository-context-bom.v3	Published JSON Schema plus whole-document golden
execution-contract	renma.experimental-execution-contract.v1	Explicitly experimental tests; no stable 1.x assurance

The test-owned PUBLIC_JSON_SCHEMA_VERSIONS registry mirrors this table and separates stable identifiers from the explicitly experimental execution contract. Repository tests compare the registry and this documentation so a public top-level document cannot be added, removed, or renamed on only one side without adding runtime inventory code.

The compatibility-assurance column is also intentional release evidence. The golden suite normalizes checkout-local paths and package-derived versions, then compares the complete serialized document. The Trust Graph uses its published Draft 2020-12 schema and an exact semantic contract fixture instead because those guards are stronger than adding a second representative golden.

renma.trustGraph.v2 intentionally retains its established camel-case spelling. It is already a published stable identifier used by the schema, producers, tests, and consumer documentation. Renaming it for stylistic consistency would itself be a breaking wire-contract change, so Renma 1.x keeps the spelling and its compatibility test locks that decision.

The execution contract remains explicitly experimental under its documented compatibility policy. Published BOM, Trust Graph, and Skill Authoring Handoff JSON Schemas remain the normative schemas for those artifacts. A versioned nested object, such as inspection coverage or a Skill Discovery diff, keeps its own identifier; the outer identifier does not replace or reinterpret it.

Readiness v2 replaces the producerless layout.disallowed_skill_assets check with skills.support_integrity. The replacement uses authoritative inspectionCoverage issues marked as static Skill-support expectations, plus missing-reference Finding evidence where no coverage issue is intentionally created. Excluded, symlinked, unreadable, oversized, depth-limited, and unsupported explicit support fails the check; unrelated repository coverage issues do not. Finding suppression does not turn authoritative support-inspection incompleteness into a pass. Because BOM embeds the Readiness check collection, BOM v3 carries the same breaking migration. Consumers of Readiness v1 or BOM v2 must update check-ID allowlists, maps, and comparisons; the old check ID has no alias in the new contracts.

formatJsonDocument is also used internally as a serialization utility. An internal object does not become a public contract merely because it can be serialized, and internal working values do not receive schemaVersion blindly.

For scan consumers, the public TypeScript ScanJsonDocument models the wire shape with literal schemaVersion: "renma.scan.v2" and format: "json". Renma's pre-serialization core scan model has no supported public library producer and remains internal; formatJson() remains the authoritative serializer. Its dedicated toScanJsonDocument() projection explicitly selects every supported top-level field; it never spreads the internal ScanResult model into the wire document.

Scan v2 replaces the three overlapping pre-1.0 projections (findings, legacy diagnostics, and diagnosticsV2) with one canonical normalized diagnostics array. Suppressed results use the same diagnostic shape under suppressedDiagnostics, paired with their suppression evidence. Consumers must branch on schemaVersion and migrate field access rather than treating v2 as an additive v1 extension.

When diagnostics.severity applies to a scan finding, its existing details.findingSeverity value is the repository-effective severity and the additive details.defaultSeverity and details.severitySource fields preserve producer-default traceability. Diff v1 may add an optional diagnosticSeverityPolicy object when severity policy changes; CI report v1 may add the corresponding optional evaluation. Existing documents without configured severity policy retain their established shape, so these additions do not require new top-level schema identifiers.

Only stable IDs registered on the configurable scan-Finding surface are valid keys. Stable raw diagnostic IDs are rejected at configuration load time because this policy does not alter their transport severity.

Diagnostic severity-policy changes compare effective severities resolved from the repository override or the static built-in authority; they do not infer a default from findings observed in either snapshot. The change direction may be weakening, tightening, neutral, or review_required. The last value is a conservative CI-review signal for IDs whose built-in Finding severity cannot be resolved to one static value. Diff summaries expose the corresponding neutral and review-required ID lists, and CI summaries count both without treating neutral changes as policy matches.

Skill Authoring Guide v2 replaces v1 because established interaction semantics changed. The overall Renma boundary is unchanged: the consuming LLM investigates, reasons, clarifies when needed, and edits; Renma supplies deterministic guidance and validates supplied structure; a human reviews meaningful decisions. In v2, interaction.phases contains adaptive authoring activities rather than a required ordered clarification algorithm, clarification is conditional on unresolved Blocking authoring decisions, question batching and blocker presentation are adaptive, and prerequisite-aware questioning is an invariant. Human review is owned explicitly by interaction.humanReviewRules, and externalTraversalApplicabilityRule dispatches consumers to the detailed externalTraversalRules when recursive external traversal may apply. The gate may be declared passed only after every creation-gate requirement is established, including the smallest justified asset structure, and no Blocking decision remains. This is an externally observable dependency, not a prescribed internal reasoning sequence.

Consumers must branch on schemaVersion: do not parse v2 using v1 assumptions about phase ordering, mandatory clarification, fixed question batches, or the last phase carrying human-review semantics. renma.skill-authoring-guide.v1 is not reinterpreted or emitted as the new contract.

Classification matchedRule and reasonCode values are open enums in JSON and in the public TypeScript wire types. Consumers must retain unfamiliar future strings and fail closed. The exported KnownAssetClassificationRule and KnownAssetClassificationReasonCode helpers describe only values known to the current Renma version and are appropriate for exhaustive handling followed by an unknown-value fallback.

Compatibility during 1.x

For a stable identifier, Renma 1.x may make backward-compatible additions:

• add optional fields;
• add new array entries or map keys where the contract already permits an open collection;
• add enum values only where the contract tells consumers to preserve or tolerate unknown values; and
• clarify prose without changing the meaning of structured fields.

Renma must use a new schema identifier for a breaking change, including removing or renaming a field, changing its type or established meaning, making an optional field unconditionally required for existing producers, changing closed-enum behavior, or reinterpreting identity and ordering rules. A package major version by itself is not a substitute for a schema version, and a schema version change still requires release notes and migration guidance.

Consumers should ignore unknown optional fields, preserve unknown open-enum values when forwarding evidence, and fail clearly when they do not support the document's top-level schemaVersion.

Renma 1.0 release-candidate freeze

The stable identifiers in the contract table are the Renma 1.0 release-candidate top-level JSON identities. Their exact command-to-identifier mapping is pinned independently of the producer constants, while the existing whole-document goldens, published schemas, and semantic fixtures continue to freeze document shape and meaning. The checked-in public TypeScript API snapshot separately freezes the supported npm type entrypoints.

This freeze does not include renma.experimental-execution-contract.v1, internal ScanResult fields, implementation module paths, diagnostic prose, or environment-derived values documented below. After the freeze, a breaking change to a stable JSON contract requires a new schema identity and migration guidance; updating producer code and documentation together is not sufficient.

Determinism and environment-derived values

Deterministic machine ordering uses ECMAScript UTF-16 code-unit comparison and does not depend on the host locale. The same command, repository bytes, configuration, explicit options, and relevant revision inputs therefore produce the same ordered projection across locale settings. This applies to serialized evidence, identity/digest inputs, diagnostic selection, and suppression selection. It does not mean every value is portable across machines.

The locale-independent ordering correction is an implementation bug fix that restores the stable-order promises already made by scan v1, catalog v1, graph v1, diff v1, CI report v1, Trust Graph v2, and the BOM ordering contract. Those contracts are not versioned again for the fix. The experimental execution contract remains v1 because its evidence digest was already specified as a deterministic projection and carries no long-term compatibility promise. Readiness and BOM versions change for the check-collection migration, not for the comparator fix.

In particular:

• top-level root, inspect paths, and semantic-split source or Skill paths may be absolute and therefore depend on checkout location;
• scaffold path echoes the caller's target spelling;
• BOM generatedAt is time-derived unless --omit-generated-at is used;
• BOM generator version and guide renmaVersion come from the installed Renma package;
• diff and CI endpoints reflect the supplied Git revisions and repository evidence; and
• operating-system error text is not a machine-readable success contract.

Golden compatibility fixtures normalize the absolute repository root where necessary. Consumers comparing portable identities should use documented content hashes, digests, stable IDs, repository-relative paths, or command options such as --omit-generated-at, not compare environment-derived fields as though they were universal constants.