Housekeeping

README.md

@@ -76,22 +76,4 @@ Important reference surfaces:
 - `docs/specs/packer/`: packer specifications
 - `docs/vm-arch/`: VM and ISA architecture references
 
-These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
+These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
-
-## Discussion Workflow
-
-This repository uses a disciplined discussion workflow under `discussion/`:
-
-- `discussion/workflow/agendas/`
-- `discussion/workflow/decisions/`
-- `discussion/workflow/plans/`
-- `discussion/lessons/`
-- `discussion/index.ndjson`
-
-The expected execution flow is:
-
-```text
-agenda -> decision -> plan -> implement -> lesson
-```
-
-Do not create new workflow artifacts in legacy `docs/**/agendas`, `docs/**/decisions`, `docs/**/pull-requests`, or `docs/**/learn` paths.

discussion/index.ndjson

@@ -1,6 +1,6 @@
-{"type":"meta","next_id":{"DSC":37,"AGD":40,"DEC":36,"PLN":78,"LSN":51,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":37,"AGD":40,"DEC":36,"PLN":78,"LSN":52,"CLSN":1}}
 {"type":"discussion","id":"DSC-0036","status":"open","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[],"plans":[],"lessons":[]}
-{"type":"discussion","id":"DSC-0035","status":"in_progress","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[{"id":"AGD-0038","file":"AGD-0038-pbs-lsp-editor-assistance-wave-1.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-pbs-lsp-editor-assistance-wave-1.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-05-08","ref_agenda":"AGD-0038"}],"plans":[{"id":"PLN-0075","file":"PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]},{"id":"PLN-0076","file":"PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]},{"id":"PLN-0077","file":"PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md","status":"open","created_at":"2026-05-08","updated_at":"2026-05-08","ref_decisions":["DEC-0035"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
 {"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}
 {"type":"discussion","id":"DSC-0033","status":"done","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-08","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0033-frontend-visual-theme-spec-and-css-retirement/LSN-0050-frontend-owned-visual-themes-with-structured-contract-and-host-adapters.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]}
 {"type":"discussion","id":"DSC-0032","status":"done","ticket":"studio-new-lsp-api-and-v1-boundary","title":"Novo boundary entre lsp-api, lsp-v1 e a extensao VS Code","created_at":"2026-05-05","updated_at":"2026-05-07","tags":["studio","lsp","vscode","protocol","api","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0032-studio-new-lsp-api-and-v1-boundary/LSN-0047-project-scoped-lsp-boundary-and-protocol-containment.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]}

discussion/workflow/agendas/AGD-0038-pbs-lsp-editor-assistance-wave-1.md

@@ -1,207 +0,0 @@
----
-id: AGD-0038
-ticket: pbs-lsp-editor-assistance-wave-1
-title: Wave 1 de assistencia editorial via LSP para PBS no VS Code
-status: accepted
-created: 2026-05-08
-resolved: 2026-05-08
-decision: DEC-0035
-tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
----
-
-## Pain
-
-O stack atual de PBS no VS Code ja entrega duas capacidades relevantes:
-
-- diagnostics basicos;
-- semantic highlighting com tema frontend-owned.
-
-Mas ele ainda nao entrega o minimo de assistencia editorial para um fluxo real de escrita de codigo:
-
-- nao existe `completion`;
-- `hover` ainda eh placeholder;
-- nao existe `signature help`.
-
-Sem isso, o editor continua servindo mais como viewer colorido com erros do que como ambiente minimamente utilizavel para escrever PBS com conforto.
-
-## Context
-
-Domain owner: `studio`
-
-Subdomains touched:
-
-- `studio/lsp`
-- `compiler/pbs`
-- `compiler/general`
-
-Estado atual observado no codigo:
-
-- o servidor anuncia `hover` e `semanticTokens`, mas nao anuncia `completionProvider`, `signatureHelpProvider` ou `documentFormattingProvider`;
-- o bridge interno do LSP so expõe `describeServer`, `analyzeDocument`, `hover`, `semanticTokens` e `onSave`;
-- `hover` hoje retorna texto fixo, sem usar simbolo, assinatura, tipo ou docs;
-- o pipeline do compiler ja consegue analisar overlay do documento e possui superficies semanticas e de linking relevantes no PBS;
-- o highlighting recente ja resolve bastante informacao lexical e parte da superficie stdlib/imports.
-
-Esta agenda trata apenas da wave 1 de assistencia editorial.
-Ela nao tenta fechar todo o problema de IDE features.
-
-## Open Questions
-
-- Qual deve ser o escopo minimo de `completion` para chamarmos essa wave de utilizavel?
-- [x] Qual deve ser o escopo minimo de `completion` para chamarmos essa wave de utilizavel?
-  R: keywords, nomes locais em escopo, simbolos importados/publicos, e members apos `.` para superfícies reconhecidas (`service`, `host`, `builtin type`, `struct` e constructors/funcoes relacionados). Sem isso, a feature ainda nao ajuda na descoberta real da API.
-- `completion` deve nascer apenas com heuristicas lexicais/sintaticas, ou ja deve usar semantica e linking do compiler onde isso for viavel?
-- [x] `completion` deve nascer apenas com heuristicas lexicais/sintaticas, ou ja deve usar semantica e linking do compiler onde isso for viavel?
-  R: deve nascer compiler-backed sempre que a informacao ja existir de forma confiavel no pipeline semantico/linking. Heuristica local pode existir apenas como complemento estritamente limitado para casos ainda nao resolvidos, nunca como segunda semantica canônica.
-- Em `hover`, quais informacoes sao obrigatorias na primeira entrega:
-  assinatura, kind, modulo de origem, tipo inferido, documentacao?
-- [x] Em `hover`, quais informacoes sao obrigatorias na primeira entrega:
-  assinatura, kind, modulo de origem, tipo inferido, documentacao?
-  R: obrigatorios: `kind`, assinatura quando aplicavel, modulo/origem quando relevante, e tipo/shape basico quando houver. Documentacao textual eh desejavel para stdlib e builtins, mas nao deve bloquear a wave 1 se a infraestrutura de docstring ainda nao existir. Se a linguagem vier a adotar algo como `Document(...)` com markdown pronto para hover, isso deve nascer em discussao propria; nesta wave atual, basta preparar o local de consumo para documentacao opcional quando ela existir.
-- `signature help` deve usar a mesma fonte semantica de `hover/completion`, ou pode nascer numa implementacao mais local para chamadas conhecidas?
-- [x] `signature help` deve usar a mesma fonte semantica de `hover/completion`, ou pode nascer numa implementacao mais local para chamadas conhecidas?
-  R: deve usar a mesma base semantica. O objetivo da wave eh justamente evitar tres caminhos tecnicos diferentes para responder "qual assinatura esta sendo chamada?".
-- Como tratar membros de stdlib, aliases importados, services, hosts, builtin types e metodos de struct sem criar uma segunda semantica paralela no LSP?
-- [x] Como tratar membros de stdlib, aliases importados, services, hosts, builtin types e metodos de struct sem criar uma segunda semantica paralela no LSP?
-  R: o LSP deve perguntar ao compiler por uma superficie editorial/resolutiva unica, derivada das mesmas fontes usadas para analise, linking, stdlib e metadata do frontend. O LSP nao deve reconstruir manualmente tabelas paralelas de membros.
-- Esta wave deve incluir `go to definition`, ou isso deve ficar explicitamente fora do escopo para nao diluir a entrega?
-- [x] Esta wave deve incluir `go to definition`, ou isso deve ficar explicitamente fora do escopo para nao diluir a entrega?
-  R: deve ficar fora do escopo desta wave. Ele eh um proximo passo natural, mas nao eh requisito para chamar `completion + hover + signature help` de minimamente utilizaveis.
-- Formatacao e identacao automatica devem ficar fora desta agenda como non-goal explicito?
-- [x] Formatacao e identacao automatica devem ficar fora desta agenda como non-goal explicito?
-  R: sim. Podem virar discussao/plan posterior. Nesta wave, elas seriam custo adicional sem impacto proporcional comparado a completion/hover/signature help.
-
-## Options
-
-### Option A - Completion e hover por heuristica leve, com signature help posterior
-
-- **Approach:** implementar `completion` usando contexto local, imports, keywords e alguns casos de member access, implementar `hover` com informacao minima, e deixar `signature help` para uma wave seguinte.
-- **Pro:** menor custo inicial e menor risco de travar na arquitetura semantica.
-- **Con:** pode criar uma primeira entrega inconsistente, especialmente em chamadas de stdlib e tipos importados, e pode forcar refactor cedo demais depois.
-- **Maintainability:** media.
-
-### Option B - Wave 1 coerente com completion, hover e signature help sobre uma mesma base semantica
-
-- **Approach:** desenhar uma pequena superficie de assistencia editorial no LSP que use uma base comum para resolver simbolos, membros e assinaturas. Entregar juntos:
-  - completion minimo utilizavel;
-  - hover real;
-  - signature help em chamadas.
-- **Pro:** evita duplicacao conceitual e produz uma experiencia de editor mais consistente desde a primeira wave.
-- **Con:** custo maior de desenho e implementacao agora.
-- **Maintainability:** forte.
-
-### Option C - Adiar assistencia semantica e depender do VS Code + snippets
-
-- **Approach:** manter diagnostics e colors como estao, adicionar no maximo snippets ou pequenas ajudas na extensao.
-- **Pro:** quase nenhum custo de backend.
-- **Con:** nao resolve o problema real; o editor continua insuficiente para escrita cotidiana de PBS.
-- **Maintainability:** fraca.
-
-## Tradeoffs
-
-Option C nao fecha a dor real e deve ser descartada.
-
-Option A parece atraente para ganhar velocidade, mas carrega um risco ruim:
-
-- introduzir `completion`, `hover` e depois `signature help` por caminhos tecnicos diferentes;
-- duplicar logica entre parser local, heuristicas e linking;
-- e transformar a wave 2 num retrabalho de consolidacao.
-
-Option B custa mais, mas o custo eh justificavel porque estas tres features se apoiam nas mesmas perguntas:
-
-- o que este simbolo representa?
-- quais membros ele expõe?
-- qual eh a assinatura desta chamada?
-- qual o modulo/origem deste item?
-
-Se essas perguntas forem respondidas por uma base comum, a wave 1 fica mais coerente e abre caminho natural para futuras features como `definition`, `references` e `inlay hints` via LSP.
-
-## Recommendation
-
-Seguir com **Option B**.
-
-A recomendacao eh abrir uma wave 1 coerente de assistencia editorial com:
-
-- `completion` minimo utilizavel;
-- `hover` funcional;
-- `signature help` funcional.
-
-Escopo minimo recomendado para `completion`:
-
-- keywords;
-- simbolos locais em escopo;
-- nomes importados/publicos relevantes;
-- members apos `.` para stdlib, builtin types, structs e services/hosts reconhecidos.
-
-Escopo minimo recomendado para `hover`:
-
-- kind do simbolo;
-- assinatura quando aplicavel;
-- modulo/origem quando relevante;
-- tipo ou shape basico quando isso existir de forma confiavel.
-
-Escopo minimo recomendado para `signature help`:
-
-- chamadas de funcao/metodo/construtor;
-- parametro ativo;
-- labels consistentes com a mesma representacao de assinatura usada no hover.
-
-## Discussion
-
-O ponto principal desta agenda nao eh “adicionar IDE features” genericamente.
-
-O ponto principal eh definir a primeira wave de superfícies de assistencia que tiram o PBS no VS Code do estado de:
-
-- diagnostics + coloracao
-
-para um estado de:
-
-- escrita assistida minima, com descoberta de API e leitura de assinatura.
-
-Isso exige disciplina de boundary.
-
-O VS Code extension nao deve inventar semantica local.
-O servidor LSP deve continuar sendo o owner da assistencia editorial.
-
-Da mesma forma, o LSP nao deve criar uma semantica paralela desconectada do compiler se ja existe informacao aproveitavel em parser, linking, stdlib e superficies semanticas do PBS.
-
-Tambem vale explicitar o que fica fora desta agenda:
-
-- formatter completo;
-- identacao automatica robusta de documento;
-- quick fixes;
-- definition/references;
-- rename;
-- code actions mais amplas.
-
-Esses itens podem virar agenda posterior.
-
-Tambem fica registrado um criterio importante de arquitetura:
-
-- o primeiro passo nao eh encher o protocolo de features;
-- o primeiro passo eh criar uma base editorial coerente no lado `compiler/pbs` + `studio/lsp` que consiga responder simbolo, members e assinatura;
-- `completion`, `hover` e `signature help` sao projeções diferentes sobre a mesma base.
-
-E um criterio adicional de preparacao editorial:
-
-- a wave 1 deve prever um campo/superficie opcional de documentacao no modelo editorial resolvido por simbolo;
-- mas a autoria dessa documentacao na linguagem PBS, inclusive eventual anotacao `Document(...)` com markdown, fica fora desta agenda e pode seguir para discussao separada.
-
-## Resolution
-
-Resolucao preliminar:
-
-- a wave 1 deve ser considerada valida quando o VS Code conseguir oferecer descoberta minima de API, leitura de assinatura e ajuda em chamadas sem depender de conhecimento local na extensao;
-- `completion`, `hover` e `signature help` devem nascer sobre uma mesma base compiler-backed;
-- `go to definition`, formatter e outras features de IDE ficam explicitamente fora do escopo.
-
-Se esta leitura fizer sentido, o proximo passo eh aceitar a agenda e fechar uma `decision` que:
-
-1. defina o escopo normativo exato de `completion`, `hover` e `signature help`;
-2. fixe o boundary entre `compiler/pbs`, `studio/lsp` e `tools/vscode-extension`;
-3. declare explicitamente os non-goals desta wave;
-4. determine se a base deve nascer compiler-backed desde o inicio ou com alguma heuristica local estritamente limitada.
-
-## Next Step
-
-Se voce concordar com o enquadramento, eu converto esta agenda em `accepted` e escrevo a `decision` normativa da wave 1 de assistencia editorial para PBS no VS Code.

discussion/workflow/decisions/DEC-0035-pbs-lsp-editor-assistance-wave-1.md

@@ -1,192 +0,0 @@
----
-id: DEC-0035
-ticket: pbs-lsp-editor-assistance-wave-1
-title: Wave 1 de assistencia editorial via LSP para PBS no VS Code
-status: accepted
-created: 2026-05-08
-accepted: 2026-05-08
-agenda: AGD-0038
-plans: [PLN-0075, PLN-0076, PLN-0077]
-tags: [studio, lsp, vscode, compiler, compiler-pbs, editor, completion, hover, signature-help]
----
-
-## Context
-
-O stack atual de PBS no VS Code ja entrega diagnostics basicos e semantic highlighting frontend-owned, mas ainda nao oferece assistencia editorial minima para escrita cotidiana de codigo.
-
-Hoje:
-
-1. nao existe `completion`;
-2. `hover` existe apenas como placeholder;
-3. nao existe `signature help`;
-4. o servidor ainda nao anuncia capabilities correspondentes para essas superficies;
-5. o compiler e o frontend PBS ja possuem informacao semantica, de linking, stdlib e metadata suficiente para nao precisarmos inventar uma segunda semantica local na extensao.
-
-Esta decisao trata apenas da primeira wave de assistencia editorial para PBS no VS Code.
-Ela nao cobre formatter, identacao automatica robusta, quick fixes, `go to definition`, `references`, `rename` nem code actions gerais.
-
-## Decision
-
-O repositório SHALL entregar uma wave 1 de assistencia editorial via LSP para PBS no VS Code com tres superfícies funcionais:
-
-1. `completion`;
-2. `hover`;
-3. `signature help`.
-
-Esta wave SHALL ser considerada valida quando essas tres superfícies permitirem:
-
-1. descoberta minima de API;
-2. leitura de assinatura em simbolos e chamadas;
-3. ajuda de chamada sem dependencia de conhecimento semantico local na extensao VS Code.
-
-Esta decisao ALSO locks que:
-
-1. `completion`, `hover` e `signature help` MUST nascer sobre uma mesma base editorial compiler-backed;
-2. o LSP MUST ser o owner operacional da assistencia editorial;
-3. a extensao VS Code MUST atuar apenas como cliente/adaptador do protocolo, e MUST NOT reconstruir semantica propria para simbolos, members ou assinaturas;
-4. heuristicas locais no LSP MAY existir apenas como complemento temporario e estritamente limitado para lacunas nao resolvidas, mas MUST NOT virar uma segunda semantica canônica;
-5. `go to definition`, formatter, identacao automatica robusta, quick fixes, `references`, `rename` e code actions amplas MUST ficar fora desta wave.
-
-## Rationale
-
-As tres features desta wave respondem essencialmente ao mesmo conjunto de perguntas:
-
-1. que simbolo eh este?
-2. quais members ele expõe?
-3. qual assinatura ele tem?
-4. de onde ele vem?
-
-Implementa-las por caminhos tecnicos diferentes introduziria:
-
-1. duplicacao entre parser local, heuristicas e linking;
-2. incoerencia entre o que aparece em `completion`, `hover` e `signature help`;
-3. retrabalho na wave seguinte.
-
-Portanto, a primeira entrega precisa nascer sobre uma base editorial unificada, reaproveitando o que o compiler e o frontend PBS ja sabem sobre:
-
-1. escopo local;
-2. imports e aliases;
-3. stdlib;
-4. builtin types;
-5. services, hosts, structs, enums, constructors, functions e methods.
-
-## Technical Specification
-
-### 1. Shared Editorial Resolution Surface
-
-`compiler/pbs` e `studio/lsp` MUST introduzir uma superficie editorial resolvida comum para uso de `completion`, `hover` e `signature help`.
-
-Essa superficie MUST ser capaz de responder, de forma compiler-backed:
-
-1. identidade do simbolo;
-2. `kind` do simbolo;
-3. modulo/origem quando relevante;
-4. assinatura ou shape quando aplicavel;
-5. members disponíveis para receivers reconhecidos;
-6. documentacao opcional quando existir, sem bloquear esta wave.
-
-Essa superficie MAY ser exposta por novos modelos internos do compiler, novos adapters no bridge do LSP, ou ambos.
-Mas ela MUST permanecer derivada do compiler e MUST NOT ser reautoriada na extensao.
-
-### 2. Completion Scope
-
-`completion` MUST ser entregue como superfície minima utilizavel.
-
-Na wave 1, isso MUST cobrir pelo menos:
-
-1. keywords da linguagem;
-2. nomes locais em escopo;
-3. simbolos importados/publicos relevantes;
-4. members apos `.` para superfícies reconhecidas, incluindo `service`, `host`, `builtin type`, `struct`, e call surfaces relacionadas.
-
-`completion` SHOULD expor labels, kinds e detalhes coerentes com a mesma base usada por `hover`.
-
-`completion` MUST NOT depender de tabela hardcoded na extensao para stdlib ou members de PBS.
-
-### 3. Hover Scope
-
-`hover` MUST deixar de ser placeholder e passar a ser simbolo-resolved.
-
-Na wave 1, o hover MUST incluir quando disponivel:
-
-1. `kind` do simbolo;
-2. assinatura quando aplicavel;
-3. modulo/origem quando relevante;
-4. tipo ou shape basico quando isso existir de forma confiavel.
-
-`hover` MAY incluir documentacao textual opcional.
-Mas a autoria de documentacao em PBS, incluindo eventual anotacao como `Document(...)`, MUST seguir discussao separada e MUST NOT bloquear esta wave.
-
-### 4. Signature Help Scope
-
-`signature help` MUST ser implementado para chamadas de:
-
-1. funcao;
-2. metodo;
-3. construtor.
-
-Na wave 1, ele MUST informar:
-
-1. a assinatura ativa;
-2. o parametro ativo;
-3. labels coerentes com a mesma representacao de assinatura usada no hover.
-
-`signature help` MUST usar a mesma base editorial de resolucao usada por `completion` e `hover`.
-
-### 5. Boundary Responsibilities
-
-`compiler/pbs`:
-
-1. MUST continuar sendo a fonte de verdade de semantica, linking e metadata relevante para simbolos e call surfaces;
-2. MUST fornecer a base necessaria para resolucao editorial de simbolos, members e assinaturas.
-
-`studio/lsp`:
-
-1. MUST projetar essa base editorial em endpoints/protocol features adequados;
-2. MUST anunciar as capabilities LSP necessarias para `completion`, `hover` e `signature help`;
-3. MUST manter o transporte fiel ao modelo compiler-backed.
-
-`tools/vscode-extension`:
-
-1. MUST consumir o protocolo como cliente;
-2. MUST NOT carregar tabelas paralelas de membros, stdlib ou assinaturas como fonte principal;
-3. MAY conter apenas a logica estrutural normal de integração exigida pelo VS Code.
-
-### 6. Documentation Preparation Rule
-
-Esta wave MUST preparar um campo ou superfície opcional para documentacao editorial resolvida por simbolo.
-
-Mas esta decisao ALSO locks que:
-
-1. a surface de autoria dessa documentacao em PBS nao faz parte desta wave;
-2. a sintaxe ou contrato de linguagem para documentacao authored deve ser discutido separadamente;
-3. a ausencia dessa autoria nao bloqueia `completion`, `hover` nem `signature help` da wave 1.
-
-### 7. Explicit Non-Goals
-
-Esta decisao MUST NOT:
-
-1. incluir formatter completo;
-2. incluir identacao automatica robusta de documento;
-3. incluir `go to definition`;
-4. incluir `references`;
-5. incluir `rename`;
-6. incluir quick fixes;
-7. incluir code actions mais amplas;
-8. definir o modelo de autoria de documentacao em PBS.
-
-## Constraints
-
-1. A wave 1 MUST priorizar coerencia entre `completion`, `hover` e `signature help` sobre cobertura enciclopedica de todos os casos.
-2. A extensao VS Code MUST permanecer thin; a inteligencia editorial MUST ficar no compiler/LSP.
-3. A implementacao MUST favorecer evolucao futura para `definition`, `references`, `documentation`, e outras editor features sem exigir reescrita conceitual da base editorial.
-4. A implementacao MUST evitar surfaces duplicadas para stdlib, aliases, members e signatures.
-5. Qualquer plan derivado desta decisao MUST separar claramente:
-   - base editorial compiler-backed;
-   - projeção LSP/protocolo;
-   - integração VS Code.
-
-## Revision Log
-
-- 2026-05-08: Initial draft from AGD-0038.
-- 2026-05-08: Accepted and decomposed into PLN-0075, PLN-0076, and PLN-0077.

discussion/workflow/plans/PLN-0075-pbs-editorial-resolution-surface-for-symbols-members-and-signatures.md

@@ -1,135 +0,0 @@
----
-id: PLN-0075
-ticket: pbs-lsp-editor-assistance-wave-1
-title: PBS Editorial Resolution Surface for Symbols, Members, and Signatures
-status: open
-created: 2026-05-08
-completed:
-tags: [compiler, compiler-pbs, editor, completion, hover, signature-help, semantics]
----
-
-## Objective
-
-Introduce a compiler-backed editorial resolution surface in `compiler/pbs` that can answer symbol identity, kind, origin, signature/shape, callable details, and receiver members for use by LSP `completion`, `hover`, and `signature help`.
-
-## Background
-
-`DEC-0035` requires all three editor-assistance features to be built over one shared compiler-backed base. The current repository already has useful pieces:
-
-- parser and AST for PBS;
-- semantic validation and flow analysis;
-- stdlib and import visibility rules;
-- semantic token classification;
-- builder-pipeline overlay analysis.
-
-What is still missing is an explicit editorial surface designed for interactive symbol resolution instead of only diagnostics or coloring.
-
-## Scope
-
-### Included
-
-- Define internal compiler-side models for editorial symbol resolution.
-- Resolve local names, imported/public symbols, and recognized member surfaces.
-- Resolve callable signatures for functions, methods, and constructors.
-- Provide optional documentation slot(s) in the model without defining authored PBS documentation syntax.
-- Add PBS-focused tests for symbol/member/signature resolution.
-
-### Excluded
-
-- LSP protocol capability changes.
-- VS Code client behavior.
-- Authored documentation syntax such as `Document(...)`.
-- `go to definition`, `references`, `rename`, formatter, or code actions.
-
-## Non-Goals
-
-- Rebuilding the full compiler around IDE concerns.
-- Solving every ambiguous or partial parse state in wave 1.
-- Designing a generic multi-language IDE framework before PBS proves the model.
-
-## Execution Steps
-
-### Step 1 - Define editorial resolution models in compiler-owned surfaces
-
-**What:** Introduce explicit models for resolved symbols, member candidates, callable signatures, and optional documentation payload.
-**How:** Add compiler-owned DTO/model types that can express:
-
-1. symbol identity and kind;
-2. declared/imported origin;
-3. callable label/signature shape;
-4. receiver member entries;
-5. optional documentation text field.
-
-The model must be expressive enough for `completion`, `hover`, and `signature help` without forcing each consumer to reinterpret raw AST nodes.
-**File(s):** `prometeu-compiler/prometeu-compiler-core/src/main/java/**` and/or `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/**` depending on final ownership split.
-
-### Step 2 - Build PBS symbol resolution for local and imported surfaces
-
-**What:** Resolve names in editorial contexts.
-**How:** Reuse parser, name/linking, stdlib import knowledge, and any existing semantic tables to resolve:
-
-1. local bindings in scope;
-2. declared top-level PBS symbols;
-3. imported/public symbols and aliases;
-4. stdlib-owned surfaces currently recognized by the frontend.
-
-The implementation must avoid duplicating semantic truth already present in compiler/linking logic.
-**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`.
-
-### Step 3 - Build member and callable resolution
-
-**What:** Resolve members and callable signatures for recognized receiver and call surfaces.
-**How:** Support at minimum:
-
-1. member lookup after `.` for services, hosts, builtin types, and structs;
-2. direct callable lookup for functions and constructors;
-3. active-call signature resolution for later `signature help` use.
-
-This step must produce stable labels/details that can be reused unchanged by LSP features.
-**File(s):** `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/**`.
-
-### Step 4 - Add editorial conformance tests
-
-**What:** Lock the compiler-backed editorial contract before LSP integration.
-**How:** Add tests for:
-
-1. local variable and parameter resolution;
-2. imported service/host/builtin-type resolution;
-3. member lookup after `.` on recognized surfaces;
-4. callable signature extraction for function/method/constructor cases;
-5. optional documentation field stability when absent.
-
-**File(s):** PBS/compiler test suites under `prometeu-compiler/**/src/test/java/**`.
-
-## Test Requirements
-
-### Unit Tests
-
-- Model invariants for symbol/member/signature payloads.
-- Resolver tests covering locals, imports, aliases, members, and constructors.
-
-### Integration Tests
-
-- Compiler-backed overlay/editorial tests using representative PBS snippets and stdlib imports.
-
-### Manual Verification
-
-- Inspect resolved payloads in tests or debug output and confirm they are sufficient to drive all three editor features without ad hoc reinterpretation.
-
-## Acceptance Criteria
-
-- [ ] Compiler-side editorial models exist for symbols, members, signatures, and optional documentation.
-- [ ] PBS can resolve local names, imported/public symbols, and recognized member surfaces.
-- [ ] Function, method, and constructor signatures are available through the shared editorial surface.
-- [ ] No consumer is required to reconstruct signature/member meaning from raw AST-only data.
-
-## Dependencies
-
-- `DEC-0035` accepted and normatively locked.
-- Existing PBS semantic and import/linking infrastructure remains the truth source.
-
-## Risks
-
-- Overfitting the first resolver to the current stdlib shape may hurt future fronts or future PBS growth.
-- Mixing diagnostics-only semantics with editorial semantics carelessly may produce partial or contradictory answers.
-- Incomplete member resolution can make `completion` appear flaky even if `hover` works.

discussion/workflow/plans/PLN-0076-lsp-completion-hover-and-signature-help-over-editorial-resolution.md

@@ -1,121 +0,0 @@
----
-id: PLN-0076
-ticket: pbs-lsp-editor-assistance-wave-1
-title: LSP Completion, Hover, and Signature Help over Editorial Resolution
-status: open
-created: 2026-05-08
-completed:
-tags: [studio, lsp, protocol, completion, hover, signature-help, editor]
----
-
-## Objective
-
-Expose `completion`, real `hover`, and `signature help` through the project-scoped LSP stack by projecting the compiler-backed editorial resolution surface into explicit protocol capabilities and request handlers.
-
-## Background
-
-`DEC-0035` requires `studio/lsp` to be the operational owner of these editor features while remaining faithful to compiler-backed symbol, member, and signature resolution. The current LSP path only handles diagnostics, semantic tokens, and a placeholder hover.
-
-## Scope
-
-### Included
-
-- Extend the internal bridge/API with completion and signature-help operations.
-- Replace placeholder hover with symbol-resolved hover.
-- Announce LSP capabilities for completion and signature help.
-- Add message models/mappers/tests for the new request/response paths.
-
-### Excluded
-
-- Creation of the underlying compiler editorial model itself.
-- Authored documentation syntax.
-- VS Code-specific UI behavior beyond normal LSP consumption.
-
-## Non-Goals
-
-- `go to definition`, `references`, `rename`, formatter, code actions, or quick fixes.
-- Rich workspace-wide indexing beyond what the shared editorial surface already provides.
-
-## Execution Steps
-
-### Step 1 - Extend the LSP bridge contract
-
-**What:** Add compiler-backed editor-assistance operations to the bridge.
-**How:** Evolve `LanguageServiceBridge` and related internal messages to support at minimum:
-
-1. completion requests;
-2. symbol-resolved hover payloads;
-3. signature-help requests.
-
-The bridge contract must align structurally with the shared editorial resolution surface rather than inventing a second feature-specific abstraction.
-**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/**`, `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/**`.
-
-### Step 2 - Implement compiler-backed request handling
-
-**What:** Wire LSP requests to compiler-backed editorial resolution.
-**How:** Update `CompilerLanguageServiceBridge` so it:
-
-1. resolves completion candidates from local/import/member contexts;
-2. resolves hover payloads from symbol identity, origin, and signatures;
-3. resolves active call signatures for `signature help`.
-
-This step must remove the current fixed hover placeholder.
-**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/**`.
-
-### Step 3 - Announce and map protocol capabilities
-
-**What:** Make the server advertise the new feature set and map payloads into lsp4j types.
-**How:** Update protocol mappers and text-document service so the server announces:
-
-1. `completionProvider`;
-2. `signatureHelpProvider`;
-3. improved `hoverProvider` backed by real payloads.
-
-Map completion items, hover markdown, and signature-help structures into concrete LSP responses.
-**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/**`, `.../mapping/**`.
-
-### Step 4 - Add transport and conformance tests
-
-**What:** Prevent regression to placeholder/editor-local behavior.
-**How:** Add tests that verify:
-
-1. capabilities are announced correctly;
-2. completion returns compiler-backed candidates;
-3. hover no longer returns the baseline placeholder;
-4. signature-help returns deterministic active-signature information.
-
-**File(s):** `prometeu-lsp/prometeu-lsp-v1/src/test/java/**`.
-
-## Test Requirements
-
-### Unit Tests
-
-- DTO/model invariants for completion, hover, and signature-help payloads.
-- Mapper tests for lsp4j conversion.
-
-### Integration Tests
-
-- LSP request/response tests using realistic PBS snippets with locals, imports, and member access.
-
-### Manual Verification
-
-- Connect the VS Code extension and confirm server capabilities include completion and signature help.
-- Confirm hover content changes with the hovered symbol rather than returning static baseline text.
-
-## Acceptance Criteria
-
-- [ ] The LSP bridge exposes completion and signature-help operations in addition to diagnostics, hover, and semantic tokens.
-- [ ] Hover is symbol-resolved and no longer hardcoded placeholder text.
-- [ ] The server advertises completion and signature-help capabilities.
-- [ ] Completion, hover, and signature help all derive from the same compiler-backed editorial surface.
-
-## Dependencies
-
-- `DEC-0035` accepted and normatively locked.
-- `PLN-0075` for the shared compiler-backed editorial resolution surface.
-
-## Risks
-
-- Protocol mapping can drift from compiler payload shape if feature-specific shortcuts are added.
-- Active parameter/signature calculation may be brittle around incomplete syntax unless request handling is conservative.
-- Completion can feel noisy if candidate ranking or filtering is too weak in wave 1.

discussion/workflow/plans/PLN-0077-vscode-consumption-and-wave-1-editor-assistance-validation.md

@@ -1,103 +0,0 @@
----
-id: PLN-0077
-ticket: pbs-lsp-editor-assistance-wave-1
-title: VS Code Consumption and Wave 1 Editor Assistance Validation
-status: open
-created: 2026-05-08
-completed:
-tags: [vscode, extension, editor, completion, hover, signature-help, validation]
----
-
-## Objective
-
-Keep the VS Code extension thin while validating that the new LSP-delivered `completion`, `hover`, and `signature help` features actually produce a minimally usable PBS editing experience end to end.
-
-## Background
-
-`DEC-0035` explicitly requires the extension to remain a client/adaptor rather than a second semantic engine. Because VS Code already knows how to consume LSP completion, hover, and signature-help responses, the extension work should be small and mostly about ensuring transport, configuration, and real validation are correct.
-
-## Scope
-
-### Included
-
-- Confirm the extension does not need or gain local semantic tables for stdlib, members, or signatures.
-- Adjust only the minimal extension/bootstrap behavior needed for the new LSP features to flow correctly.
-- Add verification coverage and manual validation guidance for the full wave.
-
-### Excluded
-
-- Compiler-side editorial resolution logic.
-- LSP-side protocol feature implementation.
-- Formatter/indentation, code actions, or non-wave-1 IDE features.
-
-## Non-Goals
-
-- Turning the extension into a feature-rich semantic client.
-- Adding hardcoded completion/signature content for PBS inside TypeScript runtime code.
-
-## Execution Steps
-
-### Step 1 - Verify thin-client integration boundaries
-
-**What:** Confirm the extension remains a pure LSP consumer for the new features.
-**How:** Review and adjust the extension only where necessary so completion, hover, and signature help are obtained from the LSP session without client-side semantic fallback tables.
-**File(s):** `tools/vscode-extension/src/**`, `tools/vscode-extension/package.json`.
-
-### Step 2 - Add any minimal structural configuration required by VS Code
-
-**What:** Keep static contribution surfaces minimal and structural.
-**How:** If VS Code requires additional structural contribution metadata for the new features, add only that metadata. Do not add curated PBS semantic or signature data into the extension package.
-**File(s):** `tools/vscode-extension/package.json`.
-
-### Step 3 - Add validation coverage for end-to-end editor assistance
-
-**What:** Lock the no-local-semantics rule and the end-to-end feature expectations.
-**How:** Add tests or deterministic verification steps that ensure:
-
-1. the extension connects and receives the feature set from the server;
-2. no local completion/signature tables were introduced;
-3. the user-facing wave can be exercised end to end.
-
-**File(s):** `tools/vscode-extension/**`, existing validation harnesses if present, and related docs/test notes.
-
-### Step 4 - Define manual smoke scenarios for wave 1 usability
-
-**What:** Make the wave verifiable as a product experience rather than only a protocol exercise.
-**How:** Document and run manual checks for:
-
-1. keyword and local-name completion;
-2. imported stdlib/member completion after `.`;
-3. hover on locals, imported services, builtin types, and methods;
-4. signature help during function/method/constructor calls.
-
-**File(s):** extension verification notes or adjacent implementation docs/tests as appropriate.
-
-## Test Requirements
-
-### Unit Tests
-
-- Any extension-side helpers introduced for structural integration only.
-
-### Integration Tests
-
-- End-to-end or near-end-to-end validation that VS Code consumes the server feature set without local semantic duplication.
-
-### Manual Verification
-
-- Open representative PBS files in VS Code and verify `completion`, `hover`, and `signature help` behavior matches the expected wave-1 scope.
-
-## Acceptance Criteria
-
-- [ ] The extension remains thin and contains no new hardcoded PBS semantic tables for members or signatures.
-- [ ] VS Code can consume the new LSP completion, hover, and signature-help responses without extension-side semantic authorship.
-- [ ] Wave-1 smoke scenarios are documented and manually verifiable.
-
-## Dependencies
-
-- `DEC-0035` accepted and normatively locked.
-- `PLN-0076` for the actual LSP feature delivery.
-
-## Risks
-
-- It is easy to accidentally patch around server gaps with client-local logic; this plan must resist that.
-- Validation can become too protocol-centric and miss real usability failures if manual smoke scenarios are weak.