# PR-06 Project-Scoped Studio State and Activity Persistence

Domain owner: `docs/studio`

## Briefing

Move Studio-local project persistence under each project root and make shell activity durable per project.

The target model is:

- each project owns a `.studio/` directory;
- `.studio/` is created when a new project is created;
- shell activity is stored inside that project-local directory and restored when the project is opened;
- activity retention is capped at a fixed maximum of `500` entries;
- the same `.studio/` root becomes the reserved home for future Studio project configuration.

## Objective

Make Studio state project-scoped instead of application-global where the data is inherently tied to one project, starting with activity persistence and the project-local Studio storage root.

After this change:

- opening a project reloads its recent activity feed;
- new activity entries are appended to that project's persisted history;
- persisted history is trimmed to the latest `500` entries;
- newly created projects already contain the `.studio/` structure expected by Studio.

## Dependencies

- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- current project creation flow in `ProjectCatalogService`
- current shell activity mapping and rendering in `StudioActivityFeedControl`

## Scope

- define the project-local Studio storage convention under `.studio/`
- persist shell activity entries per project
- restore persisted activity when a project shell opens
- enforce a hard retention cap of `500` entries
- create `.studio/` during new-project scaffolding
- reserve `.studio/` as the home for future project-local Studio settings
- replace the current scaffolded `.workspace/` directory with `.studio/`

## Non-Goals

- no redesign of activity event semantics or severity mapping
- no cross-project merged activity history
- no migration of global launcher data such as known projects
- no broad persistence pass for every workspace in this PR
- no attempt to define every future file that may live under `.studio/`

## Execution Method

1. Define the `.studio/` storage contract for Studio-owned project data.
   Proposed baseline layout:
   - `.studio/activities.json` for persisted shell activity history
   - `.studio/settings.json` reserved for project-local Studio configuration

2. Introduce a small project-local storage path abstraction.
   It should centralize resolution of `.studio/`, activity storage, and future settings storage from `ProjectReference.rootPath()`.

3. Add an activity persistence service/repository.
   Responsibilities:
   - load persisted entries for a project;
   - store entries after append;
   - normalize malformed or missing files into an empty history;
   - trim persisted and in-memory history to the latest `500` records.

4. Refactor `StudioActivityFeedControl` to become project-aware at construction time.
   The control should:
   - hydrate its initial list from persisted project activity;
   - append new mapped entries to memory and persistence;
   - preserve the existing duplicate-suppression behavior unless it conflicts with durable history expectations.

5. Update shell composition to pass the active `ProjectReference` into the activity feed.
   `MainView` should instantiate the feed for the currently opened project instead of a project-agnostic global feed.

6. Update project creation scaffolding.
   `ProjectCatalogService.createProject(...)` must create `.studio/` and stop creating `.workspace/`.
   If needed, opening an older project may lazily create `.studio/` on first persistence write.

7. Propagate the contract to Studio specs and tests.
   The shell spec should state that shell activity is project-scoped, restored on open, and retained with a bounded history.

## Acceptance Criteria

- opening a project with an existing `.studio/activities.json` restores that project's recent activity feed before new events arrive
- activity produced while a project is open is persisted under that project's `.studio/` directory
- persisted activity history never exceeds `500` entries
- newly created projects contain `.studio/`
- new-project tests no longer expect `.workspace/`
- opening a project without `.studio/activities.json` still works and initializes an empty feed

## Validation

- unit tests for project scaffolding asserting `.studio/` creation
- unit tests for activity storage load/save behavior
- unit tests for retention trimming to `500`
- unit tests for activity-feed hydration from persisted entries
- unit tests for malformed or missing activity storage fallback
- smoke validation opening two different projects and confirming isolated activity histories

## Affected Artifacts

- `prometeu-studio/src/main/java/p/studio/projects/ProjectCatalogService.java`
- `prometeu-studio/src/main/java/p/studio/window/MainView.java`
- `prometeu-studio/src/main/java/p/studio/controls/shell/StudioActivityFeedControl.java`
- new Studio project-storage service/repository classes under `prometeu-studio/src/main/java/p/studio/...`
- `prometeu-studio/src/test/java/p/studio/projects/ProjectCatalogServiceTest.java`
- new activity persistence tests under `prometeu-studio/src/test/java/p/studio/...`
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`