implement PLN-0031 structural anchor semantic surface spec

discussion/index.ndjson

@@ -14,4 +14,4 @@
 {"type":"discussion","id":"DSC-0013","status":"done","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-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
 {"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]}
 {"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]}
-{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"review","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"review","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}
+{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"review","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]}

discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md

@@ -2,9 +2,9 @@
 id: PLN-0031
 ticket: studio-editor-scope-guides-and-brace-anchoring
 title: Structural anchor semantic surface specification for Studio semantic read
-status: review
+status: done
 created: 2026-04-03
-completed:
+completed: 2026-04-03
 tags:
   - studio
   - specs
@@ -96,10 +96,10 @@ If a separate schema subsection or appendix is needed, add it within the relevan
 
 ## Acceptance Criteria
 
-- [ ] The semantic-read spec defines a dedicated structural-anchor surface separate from `documentSymbols`.
-- [ ] The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
-- [ ] The contract is language-agnostic and does not assume braces as the only structural delimiter.
-- [ ] The spec text is sufficient for a frontend and Studio implementation plan without reopening DEC-0014.
+- [x] The semantic-read spec defines a dedicated structural-anchor surface separate from `documentSymbols`.
+- [x] The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
+- [x] The contract is language-agnostic and does not assume braces as the only structural delimiter.
+- [x] The spec text is sufficient for a frontend and Studio implementation plan without reopening DEC-0014.
 
 ## Dependencies
 

docs/specs/studio/5. Code Editor Workspace Specification.md

@@ -21,6 +21,7 @@ This specification stabilizes:
 - the mixed editable and hard `read-only` file-opening model,
 - the responsive tab baseline,
 - the editor-owned composition surfaces that host save and semantic-read UX,
+- the gutter-based active-structure indicator model for semantic editor scopes,
 - the editor-local save surfaces,
 - and the workspace boundary with the integrated frontend semantic-read phase.
 
@@ -46,6 +47,7 @@ The `Code Editor` workspace must assume:
 - 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,
 - the integrated frontend semantic-read phase may add diagnostics, symbols, outline-facing structure, definition, and highlight for frontend documents,
+- the integrated frontend semantic-read phase may later add dedicated structural-anchor metadata for exact scope-indicator anchoring,
 - frontend semantic presentation contract data comes from frontend-owned metadata published through `FrontendSpec`,
 - and the current wave must not depend on semantic behavior to remain coherent.
 
@@ -211,6 +213,7 @@ Rules:
 
 - 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.
+- Exact anchor positions for semantic scope indicators must come from frontend-owned structural metadata rather than Studio-local text scanning when that metadata is available.
 - 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.
@@ -220,6 +223,40 @@ Rules:
 - The workspace must not surface this condition as a product-facing editor error.
 - The workspace must not treat semantic-read over editorial snapshots as authorization for frontend save, mutation, or build participation.
 
+## Scope Indicator Rules
+
+The default semantic scope-indicator surface in the Code Editor must remain the gutter.
+
+The first active-state wave must render at most two simultaneous semantic indicators:
+
+- `activeContainer`
+- `activeScope`
+
+The editor must not restore the previous full ancestry stack as the default active-state presentation.
+
+`activeScope` must be selected as the smallest structural range that contains the caret.
+
+`activeContainer` must be selected as the immediate structural ancestor of `activeScope`.
+
+If no valid structural ancestor exists, the editor may omit `activeContainer`.
+
+The editor must not promote a higher semantic owner such as function, type, or module when a nearer structural ancestor exists.
+
+The concrete visual presentation of `activeContainer` and `activeScope` remains frontend-owned. This specification intentionally does not fix:
+
+- colors,
+- stroke style,
+- dashed versus solid treatment,
+- opacity,
+- thickness,
+- or equivalent visual-emphasis details.
+
+The Studio editor must only preserve the semantic distinction between the two indicator roles.
+
+Exact guide start and end anchoring must consume the dedicated structural-anchor semantic surface defined by the integrated semantic-read specification.
+
+The editor must not treat local brace scanning heuristics as the final production contract for exact anchor placement.
+
 ## Status Bar Rules
 
 The status bar must remain mostly passive in this wave.

docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md

@@ -20,6 +20,7 @@ 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 dedicated semantic surface used for structural anchors and guide-aware editor structure,
 - the packaging expectations for the public `prometeu-lsp` API surface,
 - and the explicit exclusions that remain outside this phase.
 
@@ -88,6 +89,8 @@ The minimum semantic capability set of this phase must include:
 - go-to-definition for frontend documents;
 - frontend semantic highlight.
 
+The phase may ship the dedicated structural-anchor surface after the baseline capability set is stable, but Studio and frontend implementations must treat that surface as the canonical source of exact scope-indicator anchoring once it exists.
+
 ## Highlight Ownership Rules
 
 - frontend highlight must come from semantic information provided through `prometeu-lsp`;
@@ -101,6 +104,38 @@ The minimum semantic capability set of this phase must include:
 - this condition must not become a product-facing Studio error and may at most produce normal development logs;
 - non-frontend highlight may remain on the existing Studio-local highlighting path in this phase.
 
+## Structural Anchor Semantic Surface
+
+Exact structural anchoring for editor scope indicators must not be overloaded into `documentSymbols`.
+
+`documentSymbols` remains the outline and navigation surface.
+
+Guide-oriented structure must be exposed through a dedicated semantic surface for structural anchors and related guide metadata.
+
+That dedicated surface must be frontend-owned and language-agnostic.
+
+The contract must describe generic structural positions rather than PBS-specific brace semantics.
+
+The surface must be able to represent structures whose boundaries are expressed by:
+
+- braces;
+- keywords;
+- indentation-derived blocks;
+- or mixed delimiter schemes.
+
+At minimum, the dedicated structural-anchor surface must be able to communicate:
+
+- structural ranges that can participate in active-scope selection;
+- immediate parentage or equivalent information needed to recover the nearest ancestor relationship;
+- exact structural anchor positions used for guide start and end placement;
+- enough structural identity to distinguish the active structural range from its immediate container.
+
+The semantic-read contract must not require Studio to scan source text in order to discover the final structural anchor positions.
+
+Temporary local heuristics may exist only as development aids. They must not become the canonical production contract.
+
+The exact serialized schema of this dedicated surface may evolve in implementation plans, but any accepted schema must preserve the invariants above.
+
 ## Packaging Rules
 
 The public `prometeu-lsp` API should follow flat packaging similar to `prometeu-packer-api`.