prometeu-studio/discussion/workflow/plans/PLN-0015-propagate-dec-0009-into-studio-specs.md

id	ticket	title	status	created	completed	tags
PLN-0015	studio-editor-document-vfs-boundary	Propagate DEC-0009 into Studio shell, editor, and VFS specs	done	2026-03-31	2026-03-31	studio vfs specs editor shell

Briefing

Translate DEC-0009 into the normative Studio specification set before code migration starts, so the new prometeu-vfs boundary is explicit in shell, editor, and module-level documentation.

Objective

Make the accepted prometeu-vfs project-document boundary normative in Studio specs without adding scope beyond the current read-only editor wave.

Background

DEC-0009 locks the following architectural choices:

• Studio accesses project-document filesystem state through prometeu-vfs.
• prometeu-vfs is project-session owned rather than editor-focus owned.
• prometeu-vfs exposes structural project data, not visual tree state.
• the first migration wave carries only current EditorWorkspace capabilities;
• manual refresh remains in scope, while watchers and public event APIs remain out of scope.

The current spec set documents shell and editor behavior, but it does not yet define the prometeu-vfs boundary explicitly.

Dependencies

• DEC-0009 accepted and normatively locked

Scope

Included

• add or update Studio normative text for the prometeu-vfs boundary
• propagate project-session ownership rules into the shell spec
• propagate structural tree, support-rule ownership, and prometeu-vfs document access rules into the Code Editor spec
• update the Studio specs index if a new Studio spec is introduced

Excluded

• implementation code
• public event API exposure
• watcher-based refresh
• new editor capabilities beyond the current read-only wave

Non-Goals

• redesign the shell
• define a public event catalog for prometeu-vfs
• generalize prometeu-vfs into a product-wide filesystem abstraction

Execution Method

Step 1 - Introduce a Normative prometeu-vfs Boundary Spec

What: Create a dedicated Studio spec for the project-document boundary so DEC-0009 does not have to be split awkwardly across unrelated shell and editor documents.

How: Add a new Studio spec that defines:

• prometeu-vfs module role
• project-session ownership
• filesystem-backed first-wave contract
• structural tree contract
• RPC-first public API baseline
• manual refresh rule
• non-goals for public events and watchers

File(s):

• docs/specs/studio/6. Project Document VFS Specification.md

Step 2 - Propagate Session Ownership into the Shell Spec

What: Update shell-level architecture rules so the shell explicitly owns project-session services that survive workspace focus changes.

How: Amend the shell spec to state that workspace-local composition may consume project-session-owned services such as prometeu-vfs, while shell/workspace responsibility boundaries remain intact.

File(s):

• docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md

Step 3 - Propagate Editor-Local Boundary Rules

What: Update the Code Editor spec so all project-tree and document access rules point to prometeu-vfs instead of direct filesystem readers inside the workspace.

How: Amend the editor spec to state that:

• the navigator consumes a structural tree entity provided by prometeu-vfs
• the editor opens files through prometeu-vfs
• support and unsupported-file rules belong to prometeu-vfs
• visual tree state remains in Studio UI
• refresh remains manual

File(s):

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

Step 4 - Update the Studio Spec Index

What: Keep the Studio spec corpus discoverable after adding the new boundary spec.

How: Update the index/read-order document to include the new prometeu-vfs spec and place it in a reading order that preserves shell -> shared boundary -> workspace detail.

File(s):

• docs/specs/studio/README.md

Test Requirements

Unit Tests

• none

Integration Tests

• none

Manual Verification

• verify the new spec set contains no contradiction between shell ownership, prometeu-vfs ownership, and Code Editor ownership
• verify the new spec wording does not introduce watchers, public events, write semantics, or non-project content by implication

Acceptance Criteria

• DEC-0009 is fully represented in the Studio spec corpus without reopening the agenda
• shell, prometeu-vfs, and editor responsibilities are separated unambiguously
• the spec set states that prometeu-vfs provides structural data only, not visual tree state
• the spec set states that the first wave remains limited to current editor capabilities
• the spec set states that refresh is manual and watchers remain out of scope

Affected Artifacts

• docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md
• docs/specs/studio/5. Code Editor Workspace Specification.md
• docs/specs/studio/6. Project Document VFS Specification.md
• docs/specs/studio/README.md

Risks

• splitting the rules across too many documents could make the boundary harder to follow
• forcing all rules into the editor spec could bury project-session ownership in a workspace-local document
• imprecise wording here would leak directly into implementation scope