diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 2dabbef8..b80e9891 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -11,4 +11,4 @@ {"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]} {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]} {"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]} -{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[{"id":"PLN-0019","file":"PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0020","file":"PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0021","file":"PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0022","file":"PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0023","file":"PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0024","file":"PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0025","file":"PLN-0025-implement-fe-semantic-highlight-consumption.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0013","status":"open","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[{"id":"AGD-0013","file":"AGD-0013-studio-editor-write-wave-supported-non-frontend-files.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"},{"id":"AGD-0014","file":"AGD-0014-studio-editor-frontend-edit-rights.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31"}],"decisions":[{"id":"DEC-0010","file":"DEC-0010-studio-controlled-non-frontend-editor-write-wave.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0013"},{"id":"DEC-0011","file":"DEC-0011-studio-frontend-read-only-minimum-lsp-phase.md","status":"accepted","created_at":"2026-03-31","updated_at":"2026-03-31","ref_agenda":"AGD-0014"}],"plans":[{"id":"PLN-0019","file":"PLN-0019-propagate-dec-0010-into-studio-and-vfs-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0020","file":"PLN-0020-build-dec-0010-vfs-access-policy-and-save-core.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0021","file":"PLN-0021-integrate-dec-0010-editor-write-ui-and-workflow.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0010"]},{"id":"PLN-0022","file":"PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0023","file":"PLN-0023-scaffold-flat-packed-prometeu-lsp-api-and-session-seams.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0024","file":"PLN-0024-implement-read-only-fe-diagnostics-symbols-and-definition.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]},{"id":"PLN-0025","file":"PLN-0025-implement-fe-semantic-highlight-consumption.md","status":"review","created_at":"2026-03-31","updated_at":"2026-03-31","ref_decisions":["DEC-0011"]}],"lessons":[]} diff --git a/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md b/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md index 7671e5d7..4e5e8637 100644 --- a/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md +++ b/discussion/workflow/plans/PLN-0022-propagate-dec-0011-into-studio-vfs-and-lsp-specs.md @@ -2,9 +2,9 @@ id: PLN-0022 ticket: studio-editor-write-wave-supported-non-frontend-files title: Propagate DEC-0011 into Studio, VFS, and LSP specs -status: review +status: done created: 2026-03-31 -completed: +completed: 2026-03-31 tags: [studio, lsp, vfs, specs, frontend-boundary] --- diff --git a/docs/specs/studio/5. Code Editor Workspace Specification.md b/docs/specs/studio/5. Code Editor Workspace Specification.md index 295f569c..78f2c4f9 100644 --- a/docs/specs/studio/5. Code Editor Workspace Specification.md +++ b/docs/specs/studio/5. Code Editor Workspace Specification.md @@ -20,9 +20,9 @@ This specification stabilizes: - the `Project Navigator` role and scope, - the mixed editable and hard `read-only` file-opening model, - the responsive tab baseline, -- the passive `Outline`, helper, and status-bar surfaces, +- the editor-owned composition surfaces that host save and semantic-read UX, - the editor-local save surfaces, -- and the explicit deferral of semantic/LSP behavior. +- and the workspace boundary with the integrated frontend semantic-read phase. ## Authority and Precedence @@ -32,6 +32,7 @@ This specification extends: - [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md) - [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md) - [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md) +- [`7. Integrated LSP Semantic Read Phase Specification.md`](7.%20Integrated%20LSP%20Semantic%20Read%20Phase%20Specification.md) If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local editor behavior. @@ -44,7 +45,7 @@ The `Code Editor` workspace must assume: - frontend-scoped supported documents remain hard `read-only`, - all project files remain visible in the editor workspace even when only some are frontend-relevant, - `prometeu.json` plus the selected frontend may identify source roots worth tagging, -- future semantic providers such as LSP may arrive later, +- the integrated frontend semantic-read phase may add diagnostics, symbols, outline-facing structure, definition, and highlight for frontend documents, - and the current wave must not depend on semantic behavior to remain coherent. This workspace may consume Studio project metadata and Studio-owned workspace framework primitives, but it must not infer a semantic-provider contract beyond keeping the path open for later integration. @@ -58,7 +59,7 @@ The `Code Editor` workspace is: - project-aware, - file-oriented, - mixed-mode in this wave, with editable supported non-frontend documents and hard `read-only` frontend documents, -- and explicitly not a semantic IDE surface yet. +- and not a full semantic IDE surface yet. The workspace must help the user: @@ -66,14 +67,17 @@ The workspace must help the user: - identify frontend-relevant source roots visually, - open supported files into editor tabs, - save editable non-frontend documents through editor-local commands, +- consume frontend semantic-read UX provided through the integrated LSP phase when that phase is active, - understand the active file context, -- and understand that semantic/editor-automation features are not part of this wave. +- and understand that frontend editing and broader IDE automation remain outside this wave. The workspace must not pretend to offer: - merge behavior, -- active outline semantics, -- or LSP-backed coding assistance. +- frontend editing, +- completion, +- rename, code actions, or formatting, +- or editor-owned semantic inference that bypasses the integrated LSP phase. ## Baseline Layout @@ -190,17 +194,28 @@ Rules: ## Outline Rules - The `Outline` region must exist structurally in this wave. -- It must remain passive. -- It may show a discreet placeholder state. -- It must not fake semantic outline structure before real semantic ownership exists. +- Before the integrated LSP semantic-read phase is implemented, it may show a discreet placeholder state. +- When the integrated LSP semantic-read phase is active, the `Outline` region may render frontend document-symbol structure and workspace-symbol-backed navigation owned by that phase. +- The workspace must not fake semantic outline structure before real semantic ownership exists. ## Helper Region Rules - The helper region must exist structurally in this wave. -- It must remain passive. +- Before the integrated LSP semantic-read phase is implemented, it may remain passive. - It exists only to stabilize workspace composition and reserve future space. +- It may later host diagnostics or related semantic-read detail for frontend documents without changing workspace ownership. - It must not become a substitute for the shell-level `Activity` surface. +## Integrated Semantic-Read Boundary + +- Frontend documents remain hard `read-only` even when semantic-read capabilities are active. +- Diagnostics, document symbols, workspace symbols, outline-facing structure, definition, and frontend highlight must come through the integrated LSP semantic-read phase rather than from editor-local inference. +- Opened frontend documents must be analyzed from the VFS-owned in-memory snapshot exposed through `prometeu-vfs`. +- Unopened frontend documents may be analyzed from filesystem-backed state exposed through the same `prometeu-vfs` boundary. +- Non-frontend highlight may remain Studio-local in this phase. +- Frontend highlight must come from the integrated LSP semantic-read phase and use frontend-owned color semantics. +- The workspace must not treat semantic-read over editorial snapshots as authorization for frontend save, mutation, or build participation. + ## Status Bar Rules The status bar must remain mostly passive in this wave. @@ -252,13 +267,11 @@ Persisting that state across Studio executions is deferred. - merge/conflict resolution - watcher-driven automatic refresh - public `prometeu-vfs` event APIs -- active outline behavior - helper panel functionality -- semantic analysis surfaces -- LSP integration details -- autocomplete, go-to-definition, symbols, rename, code actions, or semantic diagnostics while typing -- a normative editor event contract in this wave +- editor-owned semantic analysis that bypasses the integrated LSP phase - frontend editing +- completion, rename, code actions, or formatting +- a normative editor event contract in this wave - any implication that editor-owned in-memory snapshots participate in the build ## Exit Criteria @@ -269,5 +282,6 @@ This specification is complete enough when: - the `Project Navigator` and tab responsibilities are explicit, - editor-local `Save` and `Save All` are part of the normative workspace contract, - hard frontend `read-only` behavior is explicit in both warning and status-bar surfaces, +- the workspace boundary with the integrated frontend semantic-read phase is explicit, - placeholder versus functional regions are clearly separated, -- and deferred semantic/LSP behavior is clearly outside the current contract. +- and excluded frontend editing and completion behavior are clearly outside the current contract. diff --git a/docs/specs/studio/6. Project Document VFS Specification.md b/docs/specs/studio/6. Project Document VFS Specification.md index dd2feaaf..1ffcef81 100644 --- a/docs/specs/studio/6. Project Document VFS Specification.md +++ b/docs/specs/studio/6. Project Document VFS Specification.md @@ -22,6 +22,7 @@ This specification stabilizes: - structural tree and document access responsibilities, - canonical frontend scope and access policy ownership, - editorial snapshot and save ownership for editable non-frontend documents, +- the semantic-read consumer boundary used by the integrated LSP phase, - the RPC-first public API baseline, - and explicit first-wave exclusions such as public event publication and watchers. @@ -43,7 +44,7 @@ If this document conflicts with shell-wide Studio rules, the shell specification - the boundary is project-scoped rather than product-global, - the boundary must outlive workspace focus changes for an opened project, - Studio UI remains the owner of visual tree state and error presentation, -- and future consumers such as `prometeu-lsp` may depend on this boundary later. +- and the integrated `prometeu-lsp` phase consumes this boundary as a semantic-read client rather than as a persistence owner. `prometeu-vfs` must not infer: @@ -154,6 +155,19 @@ Rules: - future persistence may be added later without redesigning the access model; - and the current reservation must not be treated as authorization for build participation or broader product-wide state ownership. +## Semantic-Read Consumer Boundary + +`prometeu-vfs` must remain the source-of-truth document substrate consumed by the integrated LSP semantic-read phase. + +Rules: + +- opened frontend documents must be exposed to `prometeu-lsp` from the in-memory editorial snapshot held by `prometeu-vfs`; +- unopened frontend documents may be exposed to `prometeu-lsp` from filesystem-backed state through the same boundary; +- `prometeu-lsp` must not bypass `prometeu-vfs` with ad hoc filesystem reads inside Studio UI code; +- `prometeu-lsp` must not become the owner of save, persistence, or access policy; +- semantic analysis over editorial snapshots must remain separate from build-facing document ownership; +- and this boundary must remain suitable for frontend diagnostics, symbols, definition, and highlight without implying frontend edit rights. + ## Support and Plugin Rules Support and unsupported-file decisions belong to `prometeu-vfs`. @@ -191,7 +205,7 @@ Rules: Rules: -- `prometeu-vfs` may later serve `prometeu-lsp` as a consumer-facing substrate; +- `prometeu-vfs` serves `prometeu-lsp` as a consumer-facing substrate for the semantic-read phase; - `prometeu-lsp` remains a separate layer and must not be renamed into `prometeu-vfs`; - `prometeu-vfs` must not absorb packer responsibilities; - `prometeu-vfs` must not redefine asset ownership; @@ -217,5 +231,6 @@ This specification is complete enough when: - the structural tree contract is explicitly non-visual, - frontend scope and access policy ownership are explicit, - editable non-frontend snapshot and save ownership are explicit, +- the semantic-read consumer boundary with `prometeu-lsp` is explicit, - the RPC-first public API rule is explicit, - and deferred public events and watchers are clearly out of scope. diff --git a/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md b/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md new file mode 100644 index 00000000..df2b3c71 --- /dev/null +++ b/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md @@ -0,0 +1,124 @@ +# Integrated LSP Semantic Read Phase Specification + +## Status + +Active + +## Applies To + +- `prometeu-studio` +- `prometeu-vfs` +- `prometeu-lsp` +- the frontend read-only semantic phase in the Studio `Code Editor` workspace + +## Purpose + +Define the normative Studio contract for the integrated frontend semantic-read phase that arrives before any frontend editing release. + +This specification stabilizes: + +- the phase boundary between semantic read and frontend editing, +- the ownership relationship between `prometeu-vfs`, `prometeu-lsp`, and the Studio editor, +- the minimum semantic capability set for frontend documents, +- the packaging expectations for the public `prometeu-lsp` API surface, +- and the explicit exclusions that remain outside this phase. + +## Authority and Precedence + +This specification extends: + +- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md) +- [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md) + +If this document conflicts with shell-wide Studio rules, shell rules control shell behavior, the Code Editor specification controls workspace-local editor UX, the VFS specification controls document-boundary ownership, and this document controls the integrated semantic-read phase itself. + +## Normative Inputs + +The integrated semantic-read phase must assume: + +- frontend-scoped documents remain hard `read-only`, +- editable non-frontend documents remain governed by the controlled write wave, +- `FrontendSpec.allowedExtensions` remains the source of truth for frontend scope, +- `prometeu-vfs` owns document state, snapshots, persistence, and access policy, +- and semantic-read over editorial snapshots must remain separate from build-facing ownership. + +## Phase Boundary + +This phase is a semantic-read phase for frontend documents, not a frontend editing phase. + +Rules: + +- frontend documents must remain hard `read-only` throughout this phase; +- no capability in this phase may imply frontend save, mutation, or edit-right release; +- the future release of frontend editing requires a separate explicit decision; +- completion, rename, code actions, and formatting remain outside this phase. + +## Ownership Rules + +- `prometeu-vfs` owns document state, access policy, editorial snapshots, and persistence. +- `prometeu-lsp` is a semantic consumer above `prometeu-vfs`. +- the Studio `Code Editor` owns UX surfaces that render semantic-read output. +- build-facing document ownership remains outside this phase. + +`prometeu-lsp` must not become the owner of: + +- save, +- persistence, +- document access policy, +- or frontend edit-right release. + +## Document Source-of-Truth Rules + +- opened frontend documents must be analyzed from the in-memory snapshot exposed by `prometeu-vfs`; +- unopened frontend documents may be analyzed from filesystem-backed state exposed through the same `prometeu-vfs` boundary; +- Studio UI code must not bypass `prometeu-vfs` with ad hoc file loading for semantic-read behavior; +- semantic-read over editorial snapshots must not be treated as canonical build input by implication. + +## Minimum Capability Set + +The minimum semantic capability set of this phase must include: + +- diagnostics for frontend documents; +- document symbols for frontend documents; +- workspace symbols for frontend documents; +- outline-facing structural symbol data; +- go-to-definition for frontend documents; +- frontend semantic highlight. + +## Highlight Ownership Rules + +- frontend highlight must come from semantic information provided through `prometeu-lsp`; +- frontend highlight must use frontend-owned color semantics rather than a Studio-local fallback token scheme; +- non-frontend highlight may remain on the existing Studio-local highlighting path in this phase. + +## Packaging Rules + +The public `prometeu-lsp` API should follow flat packaging similar to `prometeu-packer-api`. + +Rules: + +- public contract surfaces should remain shallow and explicit; +- packages such as `dtos`, `messages`, and `events` are the preferred shape for public API grouping where those surfaces exist; +- deep public packaging by internal implementation concern should be avoided; +- runtime or implementation layering may exist internally, but it must not leak into the public contract surface by default. + +## Non-Goals + +- frontend editing +- frontend save policy +- completion +- rename +- code actions +- formatting +- build participation inferred from editorial snapshots +- external-editor compatibility requirements + +## Exit Criteria + +This specification is complete enough when: + +- the semantic-read versus frontend-editing phase boundary is explicit, +- `prometeu-vfs` and `prometeu-lsp` ownership remains unambiguous, +- the minimum semantic capability set is explicit, +- frontend and non-frontend highlight ownership is clearly separated, +- and the excluded editing and completion capabilities remain unambiguous. diff --git a/docs/specs/studio/README.md b/docs/specs/studio/README.md index 9b6d380a..451bba6a 100644 --- a/docs/specs/studio/README.md +++ b/docs/specs/studio/README.md @@ -56,6 +56,7 @@ The current Studio core corpus is: 4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md) 5. [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md) 6. [`6. Project Document VFS Specification.md`](6.%20Project%20Document%20VFS%20Specification.md) +7. [`7. Integrated LSP Semantic Read Phase Specification.md`](7.%20Integrated%20LSP%20Semantic%20Read%20Phase%20Specification.md) ## Reading Order @@ -66,7 +67,8 @@ Recommended order: 3. components module policy; 4. assets workspace behavior; 5. project document VFS boundary; -6. code editor workspace behavior. +6. code editor workspace behavior; +7. integrated LSP semantic-read behavior. ## Current Wave Notes @@ -77,4 +79,5 @@ Normative reminders: - editable scope is limited to supported non-frontend textual documents classified by `prometeu-vfs`; - frontend-scoped supported documents remain hard `read-only`; - the editor-local `Save` and `Save All` surfaces belong to the `Code Editor` workspace rather than the shell; -- editorial in-memory snapshots remain outside build-facing state. +- editorial in-memory snapshots remain outside build-facing state; +- frontend semantic-read capability lands before any frontend editing release and is documented by the integrated LSP phase specification.