added agendas

docs/pbs/agendas/11. Diagnostics Agenda.md

@@ -0,0 +1,71 @@
+# PBS Diagnostics Agenda
+
+Status: Active
+
+## Purpose
+
+Drive the remaining discussions needed to close `11. Diagnostics Specification.md` without inventing backend or UI policy prematurely.
+
+## Context
+
+The diagnostics spec already fixes the minimum phase split and source-attribution baseline, but it still leaves open:
+
+- whether diagnostic codes are mandatory in v1,
+- which parts of wording are normative,
+- what cross-file attribution is required for import and barrel failures,
+- whether cost-facing warnings become part of conformance,
+- and how backend-facing failures map back to source once lowering and PBX mapping are closed.
+
+This agenda should keep the diagnostics contract narrow, deterministic, and implementable by more than one toolchain.
+
+## Decisions To Produce
+
+1. Decide the minimum normative diagnostic identity model for v1:
+   phase only, phase plus category, or stable machine-readable code.
+2. Decide the minimum normative attribution package:
+   file, primary span, secondary span/note requirements, and cross-file references.
+3. Decide which human-facing wording requirements are normative versus illustrative.
+4. Decide whether any qualitative cost diagnostics are mandatory in v1.
+5. Decide how lowering, verifier, and load-facing failures surface back into the PBS-facing diagnostics contract.
+
+## Core Questions
+
+1. Is a stable diagnostic code required for conformance, or is deterministic rejection phase and source attribution enough?
+2. For import, barrel, and cross-module lookup failures, what exact locations must be reported?
+3. Must notes and help text exist for certain classes of error, or are they optional tooling quality?
+4. Which backend-originated failures remain PBS diagnostics versus artifact-tool diagnostics?
+5. Are warnings part of the normative contract at all in v1, and if so which ones?
+
+## Expected Spec Material
+
+The resulting spec work should be able to add or close sections for:
+
+- diagnostic identity and stability,
+- source attribution rules,
+- cross-file attribution rules,
+- optional versus required notes/help,
+- warning taxonomy boundaries,
+- backend-facing diagnostic mapping boundaries,
+- and conformance hooks consumed by `13. Conformance Test Specification.md`.
+
+## Non-Goals
+
+- Designing IDE presentation, colors, or UX.
+- Building a complete trap taxonomy.
+- Standardizing localization.
+- Freezing one internal compiler error architecture.
+- Rewriting rejection rules already owned by syntax, semantics, or loader specs.
+
+## Inputs
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/4. Static Semantics Specification.md`
+- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
+- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
+- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
+- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
+- `docs/pbs/specs/11. Diagnostics Specification.md`
+- `docs/pbs/specs/12. IR and Lowering Specification.md`
+- `docs/pbs/specs/13. Conformance Test Specification.md`
+- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
+

docs/pbs/agendas/12. IR and Lowering Agenda.md

@@ -0,0 +1,73 @@
+# PBS IR and Lowering Agenda
+
+Status: Active
+
+## Purpose
+
+Drive the decisions needed to turn `12. IR and Lowering Specification.md` from a skeleton into a normative lowering contract that can guide implementation.
+
+## Context
+
+The language now has substantial source-level semantics, but lowering still lacks closure around:
+
+- which semantic obligations IR must preserve,
+- whether one canonical IR shape is normative,
+- how core constructs map into lowered control flow and data flow,
+- how services, contracts, callbacks, tuples, `optional`, and `result` lower,
+- and which invariants belong in lowering versus PBX/bytecode mapping.
+
+This agenda should keep the focus on semantic preservation and artifact obligations, not on one compiler's class hierarchy.
+
+## Decisions To Produce
+
+1. Decide the normative status of IR:
+   canonical IR, canonical obligations only, or hybrid.
+2. Decide the required lowering preconditions after parsing, resolution, and type checking.
+3. Decide the lowered forms required for expressions, control flow, abrupt completion, and propagation.
+4. Decide the lowering story for callbacks, services, contracts, tuples, `optional`, and `result`.
+5. Decide the boundary between this spec and `15. Bytecode and PBX Mapping Specification.md`.
+6. Decide the artifact invariants that must hold before verifier or loader stages.
+
+## Core Questions
+
+1. Which evaluation-order guarantees from dynamic semantics must be explicit in lowered form?
+2. Which memory and identity facts must remain explicit through IR rather than inferred later?
+3. Do callback formation and contract dispatch need dedicated runtime artifacts or only preserved semantic obligations?
+4. What is the minimal lowering model for builtin projections, builtin constants, and intrinsic member calls beyond what is already fixed?
+5. Which host-binding failures are lowering failures versus later verifier or loader failures?
+
+## Expected Spec Material
+
+The resulting spec work should be able to add or close sections for:
+
+- lowering preconditions,
+- preserved semantic obligations,
+- control-flow lowering,
+- callable lowering by category,
+- tuple, `optional`, and `result` lowering,
+- callback, service, and contract lowering,
+- builtin and host-binding lowering,
+- artifact invariants before PBX emission,
+- and source-to-artifact trace hooks consumed by diagnostics and conformance.
+
+## Non-Goals
+
+- Freezing optimizer internals.
+- Freezing one in-memory compiler IR data model.
+- Repeating the bytecode ISA.
+- Defining loader patching internals.
+- Designing performance heuristics.
+
+## Inputs
+
+- `docs/pbs/specs/4. Static Semantics Specification.md`
+- `docs/pbs/specs/6. VM-owned vs Host-backed.md`
+- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
+- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
+- `docs/pbs/specs/9. Dynamic Semantics Specification.md`
+- `docs/pbs/specs/10. Memory and Lifetime Specification.md`
+- `docs/pbs/specs/12. IR and Lowering Specification.md`
+- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
+- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
+- `docs/pbs/specs/16. Runtime Execution and Initialization Specification.md`
+

docs/pbs/agendas/13. Conformance Test Agenda.md

@@ -0,0 +1,65 @@
+# PBS Conformance Test Agenda
+
+Status: Active
+
+## Purpose
+
+Drive the decisions needed to turn `13. Conformance Test Specification.md` into an executable conformance contract for PBS v1.
+
+## Context
+
+The current conformance spec already defines a source-level baseline, but it still leaves open:
+
+- whether PBS has one conformance level or staged claims,
+- how diagnostics participate in conformance,
+- when artifact-level golden tests become mandatory,
+- how fixtures for stdlib environments, host registries, and capability grants are modeled,
+- and how compatibility promises are validated over time.
+
+This agenda should keep conformance practical and layered so the project can evolve from frontend tests to full-toolchain claims without ambiguity.
+
+## Decisions To Produce
+
+1. Decide the conformance-claim model:
+   one level only or staged levels such as frontend-only and full toolchain.
+2. Decide the normative oracle shape for diagnostics.
+3. Decide when artifact-level conformance becomes required in addition to source-level behavior.
+4. Decide the minimum fixture model for stdlib, host registry, capabilities, and runtime lines.
+5. Decide how compatibility and regression claims are encoded in the conformance corpus.
+
+## Core Questions
+
+1. Is a parser plus binder implementation allowed to claim partial conformance, and under what label?
+2. Do diagnostics tests assert codes, phases, spans, wording classes, or only acceptance and rejection?
+3. Which lowering and host-binding invariants require golden tests once `12` and `15` are closed?
+4. What is the smallest reusable fixture set that still exercises host-backed and stdlib-backed surfaces honestly?
+5. How should compatibility expectations across language, stdlib, and cartridge domains be tested over time?
+
+## Expected Spec Material
+
+The resulting spec work should be able to add or close sections for:
+
+- conformance levels or claim classes,
+- required positive and negative suites,
+- diagnostic oracle rules,
+- artifact-level oracle rules,
+- fixture model and environment assumptions,
+- regression and compatibility matrices,
+- and acceptance criteria for claiming PBS v1 support.
+
+## Non-Goals
+
+- Choosing one repository layout or test framework.
+- Turning benchmarks into conformance.
+- Replacing the normative specs with test precedent.
+- Freezing every temporary implementation quirk as a golden artifact.
+
+## Inputs
+
+- `docs/pbs/specs/11. Diagnostics Specification.md`
+- `docs/pbs/specs/12. IR and Lowering Specification.md`
+- `docs/pbs/specs/13. Conformance Test Specification.md`
+- `docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md`
+- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
+- `docs/pbs/specs/19. Verification and Safety Checks Specification.md`
+

docs/pbs/agendas/14. Name Resolution and Module Linking Agenda.md

@@ -0,0 +1,66 @@
+# PBS Name Resolution and Module Linking Agenda
+
+Status: Active
+
+## Purpose
+
+Drive the closure of `14. Name Resolution and Module Linking Specification.md` so frontend implementation can proceed without inventing lookup or linking rules.
+
+## Context
+
+This is the main unresolved frontend-facing spec. The current skeleton still leaves open:
+
+- exact lookup order across locals, top-level declarations, imports, builtin shells, and reserved surfaces,
+- shadowing and duplicate rules by namespace,
+- import alias and barrel-export matching behavior,
+- cross-module callable and overload visibility,
+- and the resolution model for builtin and host-backed stdlib shells.
+
+Without this closure, parser and AST work can proceed only as exploratory implementation rather than normative frontend work.
+
+## Decisions To Produce
+
+1. Decide deterministic lookup order for every relevant namespace.
+2. Decide shadowing, duplicate, and ambiguity rules for local, module, and imported names.
+3. Decide import alias resolution and barrel matching rules in enough detail for implementation.
+4. Decide the resolution model for builtin shells, builtin constants, intrinsic members, and host owners.
+5. Decide which rejections belong to static semantics and which belong to a distinct linking phase.
+
+## Core Questions
+
+1. What is the exact lookup order in value position, type position, callable position, and host-owner position?
+2. Do shadowing rules differ between locals, imports, top-level declarations, and builtin surfaces?
+3. How are callable overload sets formed across local module declarations and imports?
+4. When two imported modules make the same name visible, what is the exact ambiguity and rejection rule?
+5. Are reserved stdlib shells resolved as ordinary visible declarations with metadata, or do they have any special priority?
+
+## Expected Spec Material
+
+The resulting spec work should be able to add or close sections for:
+
+- scope construction,
+- namespace-specific lookup order,
+- import and alias resolution,
+- barrel export matching,
+- overload-set visibility across modules,
+- builtin and host-shell resolution,
+- linking-phase versus static-phase rejection boundaries,
+- and deterministic cross-module failure cases.
+
+## Non-Goals
+
+- Redefining grammar already fixed in core syntax.
+- Designing runtime loader behavior.
+- Freezing one symbol-table implementation.
+- Designing IDE auto-import behavior.
+
+## Inputs
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/4. Static Semantics Specification.md`
+- `docs/pbs/specs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
+- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
+- `docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md`
+- `docs/pbs/specs/14. Name Resolution and Module Linking Specification.md`
+- `docs/pbs/specs/18. Standard Library Surface Specification.md`
+

docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md

@@ -0,0 +1,63 @@
+# PBS Compatibility and Evolution Policy Agenda
+
+Status: Active
+
+## Purpose
+
+Drive the closure of `17. Compatibility and Evolution Policy.md` so PBS can make explicit promises before implementation and release claims expand.
+
+## Context
+
+The current skeleton identifies the right policy areas, but it still leaves open:
+
+- compatibility domains and windows,
+- the separation between source, stdlib, artifact, and runtime compatibility,
+- deprecation and removal duties,
+- migration-tooling versus documentation-only obligations,
+- and whether phased implementation claims need distinct compatibility labels.
+
+This agenda should produce a policy that is strict enough to protect users and toolchains, while still allowing deliberate evolution.
+
+## Decisions To Produce
+
+1. Decide the compatibility domains PBS speaks about normatively.
+2. Decide the compatibility promise and window for each domain.
+3. Decide the deprecation and removal policy for source, stdlib, and artifact surfaces.
+4. Decide when migration tooling is mandatory versus when written guidance is enough.
+5. Decide whether phased implementation or conformance claims need distinct compatibility labels.
+
+## Core Questions
+
+1. What exact promise is made to old source code, published cartridges, stdlib consumers, and emitted artifacts?
+2. Is PBX compatibility governed independently from source compatibility?
+3. How do stdlib-line changes affect downstream dependency projects over time?
+4. Which incompatible changes require migration tooling rather than only release notes?
+5. How are compatibility claims constrained by conformance level and runtime line?
+
+## Expected Spec Material
+
+The resulting spec work should be able to add or close sections for:
+
+- compatibility domains,
+- compatibility windows and support lines,
+- behavioral versus binary compatibility,
+- deprecation and removal discipline,
+- migration obligations,
+- compatibility matrices across language, stdlib, and runtime lines,
+- and labeling rules for partial or staged implementation claims.
+
+## Non-Goals
+
+- Defining one release calendar.
+- Replacing governance with case-by-case exceptions.
+- Treating every editorial clarification as a compatibility event.
+- Designing product marketing labels.
+
+## Inputs
+
+- `docs/pbs/specs/1. Language Charter.md`
+- `docs/pbs/specs/2. Governance and Versioning.md`
+- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
+- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
+- `docs/pbs/specs/13. Conformance Test Specification.md`
+- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`