agendas, decisions and specs changes

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

@@ -0,0 +1,99 @@
+# PBS AST Agenda
+
+Status: Active
+
+## Purpose
+
+Drive closure of `11. AST Specification.md` as the frontend contract between parser output and IRBackend lowering input.
+
+## Context
+
+PBS now has syntax and static-semantics rules, but AST needs a sharper normative boundary so implementations and tests stay aligned.
+
+This agenda focuses on:
+
+- required AST node families for v1 PBS,
+- source-attribution invariants (`file/start/end`) in AST,
+- parser recovery constraints,
+- and Gate U evidence for AST behavior.
+
+## Scope Boundary
+
+In scope:
+
+- parser-produced AST contract,
+- declaration/statement/expression shape obligations,
+- source span and parent-child structural invariants,
+- AST-facing deterministic rejection behavior.
+
+Out of scope:
+
+- full static semantics (owned by `4`),
+- IRBackend lowering contract details (owned by `13`),
+- VM/runtime/bytecode/verifier/loader concerns.
+
+## Decisions To Produce
+
+1. Decide mandatory AST node families for v1 source surface.
+2. Decide structural invariants for valid and recovered AST.
+3. Decide attribution invariants required for diagnostics and lowering.
+4. Decide deterministic parser/AST rejection and recovery boundaries.
+5. Decide minimum Gate U fixture evidence for AST.
+
+## Core Questions
+
+1. What is the minimum AST contract that all PBS frontends must expose?
+2. Which syntax forms must have explicit node-level representation versus deterministic rejection?
+3. What AST guarantees must hold even after parser recovery?
+4. How strict must span/attribution fidelity be for conformance?
+5. Which AST fixtures are mandatory to prevent regression?
+
+## Proposed Workshop Sequence
+
+### Workshop 1: AST Contract and Root Model
+
+- root/file model,
+- canonical node-family baseline,
+- mandatory attribution fields.
+
+### Workshop 2: Declarations and Type Surfaces
+
+- declaration node obligations,
+- callable/type/const/module-level declaration shape,
+- barrel/linking-facing declaration needs.
+
+### Workshop 3: Statements and Expressions
+
+- statement/expression node obligations,
+- precedence/associativity representation expectations,
+- unsupported-form rejection boundaries.
+
+### Workshop 4: Diagnostics, Recovery, and Gate Evidence
+
+- syntax-phase diagnostics attribution from AST,
+- recovery invariants,
+- Gate U fixture baseline for AST.
+
+## Expected Spec Material
+
+The resulting `11` content should close:
+
+- AST contract baseline,
+- structural and attribution invariants,
+- recovery/rejection rules,
+- and test-evidence hooks for conformance.
+
+## Non-Goals
+
+- Freezing one parser implementation architecture.
+- Freezing backend/IRVM decisions.
+- Replacing static semantics with AST rules.
+
+## Inputs
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/4. Static Semantics Specification.md`
+- `docs/pbs/specs/11. AST Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
+- `docs/general/specs/13. Conformance Test Specification.md`

docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md

@@ -0,0 +1,54 @@
+# PBS AST Workshop 1
+
+Status: Active
+
+## Purpose
+
+Close the top-level AST contract for `11. AST Specification.md`:
+
+- file/root model,
+- minimum node-family baseline,
+- mandatory attribution fields.
+
+## Decisions To Produce
+
+1. Root/file node contract and per-file AST boundary.
+2. Mandatory attribution fields on AST nodes (`file/start/end`).
+3. Which families are mandatory in v1 AST (declaration/statement/expression categories).
+4. Contract status: obligations-based versus one mandatory in-memory class hierarchy.
+
+## Candidate Decisions
+
+### 1. Obligations-First AST Contract
+
+- Spec defines required observable AST obligations.
+- Internal object model remains implementation-defined.
+
+### 2. Attribution Is Mandatory
+
+- Nodes consumed by diagnostics or lowering must carry stable source attribution.
+- Missing attribution on mandatory nodes is non-conformant.
+
+### 3. Root Boundary Is Per Source File
+
+- Parser output is one root per file.
+- Root must preserve deterministic child ordering.
+
+## Questions To Resolve
+
+1. Which minimal node families are required immediately for v1 conformance?
+2. Which optional node metadata may remain implementation-defined for now?
+3. What is the minimum integrity rule for recovered AST after parse errors?
+
+## Expected Outputs
+
+1. Decision note on AST contract model.
+2. Decision note on attribution minimums.
+3. Section targets for `11. AST Specification.md`.
+
+## Inputs
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/11. AST Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+- `docs/pbs/agendas/11. AST Agenda.md`

docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md

@@ -0,0 +1,50 @@
+# PBS AST Workshop 2
+
+Status: Active
+
+## Purpose
+
+Close AST obligations for declaration and type-facing source surfaces in frontend scope.
+
+## Decisions To Produce
+
+1. Mandatory declaration-node families in v1 AST.
+2. Structural rules for declaration nesting and ordering.
+3. Deterministic rejection boundaries for unsupported declaration forms.
+4. Minimum declaration metadata needed by diagnostics and lowering.
+
+## Candidate Decisions
+
+### 1. Declaration Families Are Explicit
+
+- Top-level callable/type/const/import/module-facing constructs have explicit node families.
+- No implicit desugaring that hides declaration identity at AST boundary.
+
+### 2. Declaration Integrity Rules
+
+- Parent-child hierarchy and spans must remain coherent.
+- Duplicate or malformed declaration syntax remains parser/AST rejection, not silent AST repair.
+
+### 3. Lowering-Relevant Declaration Metadata
+
+- Declaration nodes expose minimally required identity/arity/return-surface hooks used by `13`.
+
+## Questions To Resolve
+
+1. Which declaration surfaces are mandatory now versus deferred?
+2. How much normalization is allowed at AST level before static semantics?
+3. Which malformed declaration shapes must still produce recoverable AST?
+
+## Expected Outputs
+
+1. Decision note on declaration AST model.
+2. Decision note on declaration rejection/recovery boundaries.
+3. Fixture targets for declaration AST coverage.
+
+## Inputs
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/4. Static Semantics Specification.md`
+- `docs/pbs/specs/11. AST Specification.md`
+- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
+- `docs/pbs/agendas/11.1. AST Workshop 1 - AST Contract and Root Model.md`

docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md

@@ -0,0 +1,50 @@
+# PBS AST Workshop 3
+
+Status: Active
+
+## Purpose
+
+Close AST obligations for statement and expression surfaces, including precedence/associativity representation and unsupported-form boundaries.
+
+## Decisions To Produce
+
+1. Mandatory statement/expression node families for v1 AST.
+2. Representation obligations for precedence and associativity outcomes.
+3. Deterministic rejection policy for unsupported statement/expression forms.
+4. Minimum node consistency rules used by diagnostics and lowering.
+
+## Candidate Decisions
+
+### 1. Parsing Outcomes Must Be Visible in AST Shape
+
+- Precedence and associativity results are reflected by explicit tree shape.
+- No hidden post-parse rewrites that change source-observable meaning.
+
+### 2. Unsupported Forms Are Deterministic Reject
+
+- Forms outside supported syntax/lowering slice must fail with stable diagnostics.
+- They must not collapse into permissive placeholder AST nodes.
+
+### 3. AST Consistency for Downstream Use
+
+- Statement/expression nodes needed by static semantics and lowering must always carry coherent spans and child structure.
+
+## Questions To Resolve
+
+1. Which expression forms are mandatory in v1 AST conformance?
+2. Which recoveries are acceptable without masking parse errors?
+3. What exact AST checks should Gate U fixtures assert?
+
+## Expected Outputs
+
+1. Decision note on statement/expression AST model.
+2. Decision note on unsupported-form policy.
+3. Fixture targets for precedence/associativity and rejection cases.
+
+## Inputs
+
+- `docs/pbs/specs/3. Core Syntax Specification.md`
+- `docs/pbs/specs/11. AST Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
+- `docs/pbs/agendas/11.2. AST Workshop 2 - Declarations and Type Surfaces.md`

docs/pbs/agendas/11.4. AST Workshop 4 - Diagnostics, Recovery, and Gate Evidence.md

@@ -0,0 +1,55 @@
+# PBS AST Workshop 4
+
+Status: Active
+
+## Purpose
+
+Close AST-facing diagnostics/recovery rules and Gate U evidence needed to finalize the AST contract.
+
+## Decisions To Produce
+
+1. Required diagnostics attribution behavior sourced from AST.
+2. Recovery invariants for parser output after syntax errors.
+3. Mandatory AST fixture corpus for Gate U evidence.
+4. Explicit deferred list for non-AST concerns.
+
+## Candidate Decisions
+
+### 1. AST Must Sustain Diagnostics Fidelity
+
+- Primary attribution for syntax diagnostics must remain stable and source-anchored.
+- Cross-file related spans are attached when required by diagnostics rules.
+
+### 2. Recovery Must Preserve Structural Integrity
+
+- Recovered AST may be partial, but must remain structurally coherent.
+- Recovery must not fabricate semantically valid shapes that hide syntax failure.
+
+### 3. Gate U Evidence Baseline
+
+- AST conformance evidence includes representative valid trees, invalid/recovery cases, and attribution assertions.
+
+## Questions To Resolve
+
+1. Which recovery behaviors are mandatory versus implementation-defined?
+2. What is the minimum fixture set to prevent AST regressions?
+3. Which AST-facing diagnostics codes must be frozen now?
+
+## Expected Outputs
+
+1. Decision note on AST diagnostics/recovery policy.
+2. Decision note on Gate U AST evidence baseline.
+3. Closure checklist for `11. AST Specification.md`.
+
+## Explicit Deferrals
+
+- IRBackend lowering details (owned by `13`),
+- backend/runtime/verifier concerns,
+- compatibility/publication policy.
+
+## Inputs
+
+- `docs/pbs/specs/11. AST Specification.md`
+- `docs/pbs/specs/12. Diagnostics Specification.md`
+- `docs/general/specs/13. Conformance Test Specification.md`
+- `docs/pbs/agendas/11.3. AST Workshop 3 - Statements and Expressions.md`