implements PLN-0092

This commit is contained in:
2026-07-15 06:55:26 +01:00
parent ad2ae00f39
commit 917b0e1b9a
19 changed files with 955 additions and 18 deletions
@@ -0,0 +1,63 @@
---
id: PLN-0092
ticket: pbs-symbol-documentation-and-hover-markdown
title: Specify PBS Doc attribute and markdown text block syntax
status: done
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Update the PBS normative specs so `DEC-0039` is reflected before code changes begin. This plan is the specification gate for the `[Doc(markdown = """...""")]` feature.
## Objective
Define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for compiler-owned PBS symbol documentation.
## Dependencies
- Requires accepted decision `DEC-0039`.
- Must be completed before parser, semantic, LSP, and stdlib implementation plans are accepted as complete.
## Scope
- Add `[Doc(markdown = """...""")]` to the PBS attribute surface.
- Define triple-quoted documentation text blocks as documentation-only payloads, not runtime strings.
- Define documentable named API declarations and explicitly exclude parameters.
- Define normalization, duplicate handling, invalid shape diagnostics, and non-runtime lowering rules.
## Non-Goals
- Implement lexer, parser, semantics, or LSP code.
- Define general multiline runtime strings.
- Define VSCode rendering details beyond the compiler/LSP ownership boundary.
## Execution Method
1. Update `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md` with the canonical `[Doc(markdown = """...""")]` syntax, allowed declaration sites, attribute ordering rule, and text block delimiter rules.
2. Update `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` with reserved `Doc` validation, duplicate rejection, parameter exclusion, empty normalized payload rejection, and non-documentable target diagnostics.
3. Update `docs/specs/compiler-languages/pbs/11. AST Specification.md` with an AST representation for documentation attributes and documentation text block payloads.
4. Update `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` with required diagnostic categories for unterminated text block, invalid `Doc` shape, duplicate `Doc`, empty payload, and invalid target.
5. Update `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` with the rule that stdlib, SDK, and interface modules use the same authored `Doc` surface.
## Acceptance Criteria
- Specs define all normative rules from `DEC-0039` without deferring syntax or semantics to implementation judgment.
- The specs explicitly state that `"""..."""` is documentation-only for this feature.
- The specs explicitly state that parameters never receive `[Doc]` in v1.
- The specs identify propagation boundaries: compiler resolves, LSP transports, editor renders.
## Tests
- Run any existing spec conformance tests that validate PBS spec references.
- No code behavior tests are required in this plan.
## Affected Artifacts
- `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md`
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
- `docs/specs/compiler-languages/pbs/11. AST Specification.md`
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
@@ -0,0 +1,62 @@
---
id: PLN-0093
ticket: pbs-symbol-documentation-and-hover-markdown
title: Implement PBS lexer support for documentation text blocks
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Add lexical support for triple-quoted documentation text blocks required by `[Doc(markdown = """...""")]`.
## Objective
Teach the PBS lexer to tokenize documentation text blocks without turning triple quotes into a general runtime string feature.
## Dependencies
- Depends on `PLN-0092` for the normative syntax.
## Scope
- Add a dedicated token kind for documentation text block payloads or an equivalent lexer representation.
- Recognize `"""` open and close delimiters.
- Preserve source text and spans for parser and diagnostics.
- Report unterminated documentation text blocks with useful span information.
## Non-Goals
- Parse or validate `[Doc]` attribute shapes.
- Normalize indentation.
- Lower documentation to runtime artifacts.
- Add general multiline string expressions.
## Execution Method
1. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java` with a documentation text block token if a distinct token is the cleanest local pattern.
2. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java` to recognize `"""..."""` and preserve its raw lexeme and span.
3. Ensure ordinary string scanning remains unchanged for `"..."`.
4. Add or update lexer diagnostics in `LexErrors.java` only if existing unterminated-string diagnostics cannot accurately represent unterminated documentation text blocks.
5. Add focused tests in `PbsLexerTest` for valid text blocks, multiline payloads, embedded single quotes/double quotes, and unterminated blocks.
## Acceptance Criteria
- The lexer can tokenize a multiline documentation text block.
- Unterminated documentation text blocks produce a deterministic diagnostic.
- Ordinary string literals keep current behavior.
- `"""..."""` is not accepted as an expression-level runtime string by this plan.
## Tests
- `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test` or the repository-equivalent targeted compiler frontend test task.
- Focused `PbsLexerTest` cases for documentation text blocks.
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/LexErrors.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/lexer/PbsLexerTest.java`
@@ -0,0 +1,59 @@
---
id: PLN-0094
ticket: pbs-symbol-documentation-and-hover-markdown
title: Extend PBS attribute parser and AST for Doc markdown payloads
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Extend parsing and AST representation so `[Doc(markdown = """...""")]` can be represented structurally before semantic validation.
## Objective
Parse documentation text block attribute values and expose them in AST without accepting alternate `Doc` shapes as valid semantics.
## Dependencies
- Depends on `PLN-0092`.
- Depends on `PLN-0093` for lexer support.
## Scope
- Extend attribute values to carry documentation text block payloads.
- Preserve raw payload and spans needed for normalization and diagnostics.
- Keep parser recovery consistent with existing attribute parsing.
## Non-Goals
- Validate whether `Doc` is allowed on a declaration.
- Normalize the text block.
- Attach documentation to semantic symbols.
## Execution Method
1. Update `PbsAst.AttributeValue` variants in `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` to include a documentation text block value or equivalent typed payload.
2. Update `PbsAttributeParser` so attribute arguments can parse `markdown = """..."""`.
3. Keep existing string, int, and bool attribute argument parsing unchanged.
4. Ensure parser diagnostics remain syntax-level: malformed attribute structure is parse error; invalid `Doc` shape is left to semantic validation where possible.
5. Add parser tests proving `Doc` attributes parse on top-level and nested declaration forms that already support attributes.
## Acceptance Criteria
- `[Doc(markdown = """...""")]` parses into a distinct AST value or unambiguous attribute value representation.
- Existing attributes such as `[Init]`, `[Frame]`, `[Host(...)]`, and `[InitAllowed]` continue to parse.
- Invalid generic attribute syntax still recovers at the same boundaries as before.
## Tests
- Targeted parser tests under `prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser`.
- Existing PBS parser test suite.
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsAttributeParser.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser/PbsParserTest.java`
@@ -0,0 +1,59 @@
---
id: PLN-0095
ticket: pbs-symbol-documentation-and-hover-markdown
title: Implement documentation text block normalization
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Implement the normalization algorithm required before semantic validation and editor exposure.
## Objective
Produce normalized Markdown text from a raw documentation text block using the rules locked by `DEC-0039`.
## Dependencies
- Depends on `PLN-0092`.
- Depends on `PLN-0094` for AST access to raw text block payloads.
## Scope
- Strip incidental leading and trailing empty lines.
- Compute and remove common indentation from non-empty lines.
- Preserve internal line breaks and Markdown content after normalization.
- Provide a single reusable normalization implementation for parser/semantics/editorial surfaces.
## Non-Goals
- Render Markdown.
- Sanitize Markdown for a specific editor.
- Reflow authored text.
## Execution Method
1. Add a small normalization helper in the PBS frontend package, colocated with parser or semantic support according to local patterns.
2. Feed the helper raw documentation text block content without delimiters.
3. Normalize line endings deterministically before indentation calculation if existing source handling requires it.
4. Validate empty/whitespace-only content after normalization.
5. Add unit tests for no indentation, common indentation, blank first/last lines, mixed blank internal lines, Markdown lists, code spans, and whitespace-only payloads.
## Acceptance Criteria
- Normalized output matches the spec for all required indentation cases.
- Whitespace-only content is detectable after normalization.
- The normalizer does not interpret Markdown and does not alter non-indentation content.
## Tests
- New focused unit tests for the normalizer.
- Parser/semantic tests that consume normalized output through `[Doc]`.
## Affected Artifacts
- New or existing PBS frontend helper under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs`
- Corresponding tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs`
@@ -0,0 +1,64 @@
---
id: PLN-0096
ticket: pbs-symbol-documentation-and-hover-markdown
title: Validate Doc attribute semantics and diagnostics
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Enforce the semantic contract of `[Doc]` after syntax can represent it.
## Objective
Reject invalid `Doc` usage and produce clear diagnostics for all invalid shapes and targets required by `DEC-0039`.
## Dependencies
- Depends on `PLN-0092`.
- Depends on `PLN-0094`.
- Depends on `PLN-0095`.
## Scope
- Reserve `Doc` as a compiler-recognized attribute.
- Accept only `Doc(markdown = """...""")`.
- Reject aliases, positional arguments, extra arguments, duplicate `Doc`, empty normalized payload, parameter targets, and non-documentable targets.
- Keep duplicates as semantic errors rather than parse errors.
## Non-Goals
- Attach documentation to final symbol metadata.
- Expose documentation through LSP.
- Author stdlib documentation.
## Execution Method
1. Locate existing declaration and reserved attribute validators, including `PbsDeclarationSemanticsValidator`, `PbsDeclarationRuleValidator`, and interface-module reserved attribute checks.
2. Add `Doc` validation in the semantic phase that already validates declaration attributes.
3. Define allowed declaration categories according to the spec: named API declarations that can carry attributes.
4. Add or extend `PbsSemanticsErrors` diagnostics for invalid `Doc` target, invalid shape, duplicate attribute, missing `markdown`, extra arguments, and empty payload.
5. Add tests covering valid declaration targets and every invalid case.
## Acceptance Criteria
- Every invalid shape named by `DEC-0039` produces a semantic diagnostic.
- Parameters never accept `[Doc]`.
- Duplicate `[Doc]` on one declaration is rejected semantically.
- Existing reserved attributes keep their current behavior.
## Tests
- `PbsSemanticsDeclarationsTest`
- `PbsInterfaceModuleSemanticsTest`
- `PbsDiagnosticsContractTest`
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationRuleValidator.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
- PBS semantics tests
@@ -0,0 +1,60 @@
---
id: PLN-0097
ticket: pbs-symbol-documentation-and-hover-markdown
title: Attach Doc metadata to PBS semantic symbols
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Once `[Doc]` is syntactically and semantically valid, attach normalized documentation to compiler-owned semantic symbol data.
## Objective
Make documentation available from resolved PBS symbols without requiring LSP or editor code to reparse source.
## Dependencies
- Depends on `PLN-0095`.
- Depends on `PLN-0096`.
## Scope
- Introduce an internal documentation metadata model with format and text.
- Attach normalized Markdown to documented named API symbols.
- Preserve the distinction between documentation metadata and runtime semantics.
## Non-Goals
- Render hover markdown.
- Write stdlib documentation content.
- Lower documentation into runtime artifacts.
## Execution Method
1. Add a compiler-side documentation metadata model, for example `format = markdown` plus normalized `text`.
2. Extend symbol or editorial-resolution structures so documented declarations expose this metadata.
3. Update symbol collection/binding paths for functions, methods, structs/classes, services, hosts, builtin/stdlib declarations, and interface declarations.
4. Ensure imported/stdlib declarations can carry the same metadata once parsed.
5. Add compiler tests proving documentation is attached to the intended declaration and not to parameters or unrelated symbols.
## Acceptance Criteria
- Resolved symbols can expose documentation as structured metadata, not an untyped hover-only string.
- Documentation metadata is absent for undocumented symbols.
- Documentation does not change type checking, name resolution, or runtime behavior.
## Tests
- Focused PBS semantic/editorial support tests.
- Existing name resolution and declaration tests to catch regressions.
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics`
- `PbsEditorialResolvedSymbol`
- `PbsEditorialSupportService`
- Symbol/declaration binding code touched by documented declaration categories
@@ -0,0 +1,60 @@
---
id: PLN-0098
ticket: pbs-symbol-documentation-and-hover-markdown
title: Expose Doc metadata through PBS editorial and LSP surfaces
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Transport compiler-resolved documentation through the existing PBS editorial and LSP message boundaries.
## Objective
Expose normalized Markdown documentation to LSP consumers without source reparsing.
## Dependencies
- Depends on `PLN-0097`.
## Scope
- Extend compiler editorial result models to include documentation metadata.
- Extend LSP baseline messages where required.
- Keep documentation as Markdown-oriented structured data at the boundary.
## Non-Goals
- Final hover layout composition.
- VSCode automated rendering tests.
- Runtime artifact changes.
## Execution Method
1. Extend PBS editorial models such as `PbsEditorialResolvedSymbol`, completion candidates, or hover source models with optional documentation metadata.
2. Extend LSP API records under `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages` only where the baseline protocol needs to carry documentation.
3. Update bridge code under `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler` to map compiler documentation to LSP baseline messages.
4. Preserve backward-compatible behavior for symbols without documentation.
5. Add tests proving the LSP service receives compiler-resolved documentation.
## Acceptance Criteria
- LSP-facing code consumes compiler-resolved documentation metadata.
- No LSP code reparses PBS source to discover `[Doc]`.
- Existing completion, hover, and signature help behavior remains stable for undocumented code.
## Tests
- PBS editorial support tests.
- LSP bridge tests.
- Existing `prometeu-lsp` protocol mapping tests.
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
- Related LSP tests
@@ -0,0 +1,60 @@
---
id: PLN-0099
ticket: pbs-symbol-documentation-and-hover-markdown
title: Render Doc markdown in hover composition
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Use transported documentation metadata in hover output while preserving the compiler/LSP/editor ownership boundary.
## Objective
Compose hover Markdown from signature/kind metadata and normalized `[Doc]` documentation.
## Dependencies
- Depends on `PLN-0098`.
## Scope
- Add documentation content to PBS hover composition.
- Keep Markdown rendering responsibility in the editor/client.
- Preserve hover behavior for undocumented symbols.
## Non-Goals
- Automate VSCode visual tests.
- Define a full documentation website generator.
- Change signature help parameter documentation behavior.
## Execution Method
1. Locate the PBS hover composition path in `PbsEditorialSupportService` and LSP bridge/mapping code.
2. Compose hover Markdown in deterministic order: signature/kind surface, documentation Markdown, then origin/type/shape metadata as currently appropriate.
3. Avoid escaping or reflowing normalized Markdown beyond safe composition separators.
4. Ensure undocumented symbols keep existing hover output.
5. Add hover tests with paragraphs, lists, and code spans from `[Doc]`.
## Acceptance Criteria
- Hover includes normalized authored Markdown for documented symbols.
- Hover does not include empty documentation sections.
- Markdown lists do not become accidental code blocks due to indentation.
- VSCode validation remains manual for this wave.
## Tests
- PBS editorial hover tests.
- LSP hover mapping tests that assert `MarkupKind.MARKDOWN` payloads.
## Affected Artifacts
- `PbsEditorialSupportService`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping`
- Hover-related tests
@@ -0,0 +1,60 @@
---
id: PLN-0100
ticket: pbs-symbol-documentation-and-hover-markdown
title: Author Doc metadata for stdlib SDK and interface declarations
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Apply the new documentation model to repository-owned PBS stdlib, SDK, and interface declarations.
## Objective
Author English `[Doc(markdown = """...""")]` documentation for stdlib/API surfaces so editor assistance has useful content.
## Dependencies
- Depends on `PLN-0092`.
- Should run after `PLN-0096` so authored docs are validated by compiler tests.
- Benefits from `PLN-0099` for hover verification but does not require it to author source docs.
## Scope
- Add English Markdown documentation to stdlib, SDK, and interface declarations.
- Document parameters inside the owning declaration Markdown.
- Keep documentation concise and API-focused.
## Non-Goals
- Add `[Doc]` to parameters.
- Generate external documentation sites.
- Change stdlib semantics or host binding behavior.
## Execution Method
1. Inventory stdlib and SDK PBS files under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib`.
2. Add `[Doc(markdown = """...""")]` to public named API declarations that users see in completion/hover.
3. Document parameter meaning inside callable Markdown when needed.
4. Ensure host/interface declarations use the same `Doc` shape.
5. Run stdlib compile and interface conformance tests.
## Acceptance Criteria
- Public stdlib/SDK declarations that are user-facing have concise English documentation.
- No parameters receive `[Doc]`.
- Existing stdlib behavior and host ABI bindings are unchanged.
## Tests
- `PbsGateUStdlibCompileTest`
- `PbsGateUSdkInterfaceConformanceTest`
- Relevant PBS frontend tests.
## Affected Artifacts
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/**`
- Stdlib/interface compile tests
@@ -0,0 +1,58 @@
---
id: PLN-0101
ticket: pbs-symbol-documentation-and-hover-markdown
title: Protect runtime artifacts from Doc metadata lowering
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Guard the decision that `[Doc]` is compile/editor metadata and must not be lowered into runtime artifacts by default.
## Objective
Ensure documentation metadata does not affect IR, bytecode, cartridge output, stack behavior, or runtime validation.
## Dependencies
- Depends on `PLN-0097`.
- Should be validated before end-to-end conformance closure.
## Scope
- Confirm lowering ignores `Doc` metadata.
- Add regression tests comparing runtime-facing output with and without docs where practical.
- Protect constant pool and cartridge artifacts from documentation payload bloat.
## Non-Goals
- Define a future packaging format for documentation.
- Remove compiler/editor metadata before LSP consumption.
## Execution Method
1. Inspect PBS lowering paths under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering`.
2. Ensure documented declarations lower identically to undocumented declarations for runtime-facing IR/backend artifacts.
3. Add golden or structural tests comparing compiled output for equivalent documented and undocumented programs.
4. Ensure large documentation payloads do not appear in runtime constant pools unless a future decision explicitly changes that.
## Acceptance Criteria
- Runtime-facing artifacts are unchanged by adding `[Doc]`.
- Compiler/editor metadata remains available before lowering for LSP/editor consumers.
- Golden artifact tests or equivalent regression tests cover this boundary.
## Tests
- `PbsGoldenArtifactsTest`
- Backend/lowering tests relevant to PBS IR output.
- Any artifact comparison test already used by the compiler frontend.
## Affected Artifacts
- PBS lowering package
- Golden artifact test resources if needed
- Compiler backend artifact tests
@@ -0,0 +1,62 @@
---
id: PLN-0102
ticket: pbs-symbol-documentation-and-hover-markdown
title: Add end-to-end Doc documentation conformance coverage
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
## Briefing
Close the feature with end-to-end tests that prove the whole `[Doc]` contract works across compiler and LSP boundaries.
## Objective
Validate that syntax, normalization, semantics, metadata attachment, LSP exposure, hover composition, stdlib docs, and runtime exclusion all satisfy `DEC-0039`.
## Dependencies
- Depends on `PLN-0092` through `PLN-0101`.
## Scope
- Add integrated compiler tests for valid and invalid `[Doc]`.
- Add LSP tests for hover documentation payloads.
- Add conformance coverage for normalization and runtime exclusion.
- Define a manual VSCode checklist for final visual validation.
## Non-Goals
- Automate VSCode UI rendering.
- Add new documentation syntax beyond `[Doc(markdown = """...""")]`.
- Reopen decision scope.
## Execution Method
1. Create one or more fixture PBS files using `[Doc]` on functions, methods, structs/classes when available, services, hosts, and interface declarations.
2. Add negative fixtures for parameters, duplicate `Doc`, empty payload, missing `markdown`, extra arguments, alias names, and invalid targets.
3. Add LSP tests proving hover transports Markdown and does not reparse source.
4. Add runtime artifact tests proving docs do not lower.
5. Record a short manual VSCode validation checklist covering paragraph rendering, list rendering, code spans, indentation behavior, and undocumented-symbol fallback.
## Acceptance Criteria
- All decision rules have at least one compiler or LSP test.
- Manual VSCode validation scope is documented but not automated.
- The feature can be implemented without returning to the agenda or decision for missing requirements.
## Tests
- Full relevant PBS frontend test suite.
- Relevant LSP module tests.
- Runtime/lowering golden tests.
- Manual VSCode checklist execution before final housekeeping.
## Affected Artifacts
- PBS frontend tests and fixtures
- LSP tests and fixtures
- Golden/runtime artifact tests
- Optional manual validation note in the implementation PR or plan completion record