---
id: LSN-0021
ticket: pbs-learn-to-discussion-lessons-migration
title: PBS Diagnostics and Conformance Governance Legacy Import
created: 2026-03-27
tags: [compiler, pbs, legacy-import, diagnostics, conformance, governance]
---

## Context

Legacy import from `docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md`.

This lesson preserves the durable governance rules that survived the migration of broad policy ownership into general compiler specs.

## Key Decisions

### Diagnostics are stable by identity, not prose

**What:** Diagnostic correctness is keyed by stable identity fields rather than by localized or rendered wording.

**Why:** Conformance and regression evidence must survive wording changes and localization.

**Trade-offs:** Tooling must carry identity fields seriously, but the resulting diagnostic contract is auditable and stable.

### Published claims require executable evidence

**What:** Conformance, compatibility, and support claims must be backed by maintained tests or artifact checks appropriate to the claim level.

**Why:** Published support without executable proof creates documentation debt and ambiguous promises.

**Trade-offs:** Governance becomes stricter, but support language stops drifting away from the real implementation.

## Patterns and Algorithms

- Prefer general compiler specs as the live owner for cross-language governance.
- Keep PBS-local guidance only for PBS-specific deltas and lessons.
- Align claim scope, tests, and compatibility language together.
- Be explicit when a surface is rescope-only rather than partially supported.

## Pitfalls

- Leaving superseded local policy docs around as if they still owned the contract.
- Publishing support claims without maintained evidence.
- Allowing compatibility matrices and tests to drift apart.
- Leaving rescope decisions implicit, especially for deferred execution surfaces.

## Takeaways

- Diagnostics and conformance must stay executable and auditable.
- Once general specs take ownership, PBS-local records should become lesson material rather than live policy.
- Honest rescoping is better than ambiguous “deferred” support language.