52 lines
2.1 KiB
Markdown
52 lines
2.1 KiB
Markdown
---
|
|
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.
|