housekeep

2026-04-07 05:33:18 +01:00 · 2026-04-07 05:33:18 +01:00 · 5b03fe6cfd
commit 5b03fe6cfd
parent 49b2715158
13 changed files with 58 additions and 1437 deletions
--- a/discussion/index.ndjson
+++ b/discussion/index.ndjson
@ -7,7 +7,7 @@
 {"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
 {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
 {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
-{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-06","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"in_progress","created_at":"2026-03-30","updated_at":"2026-04-06"}],"decisions":[{"id":"DEC-0022","file":"DEC-0022-studio-debug-workspace-native-integration.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0009"}],"plans":[{"id":"PLN-0043","file":"PLN-0043-debug-workspace-first-wave-surface.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0022"]},{"id":"PLN-0044","file":"PLN-0044-runtime-handshake-selective-integration.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0021","DEC-0022"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
 {"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"}]}
@ -20,4 +20,4 @@
 {"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
 {"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
 {"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
-{"type":"discussion","id":"DSC-0022","status":"open","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-06","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[{"id":"AGD-0023","file":"AGD-0023-studio-play-stop-shipper-phase-1.md","status":"in_progress","created_at":"2026-04-06","updated_at":"2026-04-06"},{"id":"AGD-0024","file":"AGD-0024-studio-play-stop-runtime-run-cartridge.md","status":"in_progress","created_at":"2026-04-06","updated_at":"2026-04-06"}],"decisions":[{"id":"DEC-0020","file":"DEC-0020-studio-play-stop-build-pack-preparation.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0023"},{"id":"DEC-0021","file":"DEC-0021-studio-play-stop-runtime-run-from-build.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0041","file":"PLN-0041-shipper-preparation-foundation.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020"]},{"id":"PLN-0042","file":"PLN-0042-shared-execution-session-and-log-contracts.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020","DEC-0021","DEC-0022"]},{"id":"PLN-0045","file":"PLN-0045-play-stop-end-to-end-execution-flow.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020","DEC-0021","DEC-0022"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
--- a/discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md
+++ b/discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md
@ -0,0 +1,56 @@
 ---
 id: LSN-0022
 ticket: studio-play-stop-cartridge-flow
 title: Studio Play/Stop and Debugger Workspace Integration
 status: done
 created: 2026-04-07
 tags: [studio, play-stop, debugger, runtime, shipper]
 ---
 ## Summary
 This lesson covers the implementation of the first wave of the `Play/Stop` flow in Studio and its integration with a native `DebugWorkspace`.
 The feature enables developers to:
 - Press `Play` to build, pack, and run the current project in the configured runtime.
 - Automatically navigate to a `DebugWorkspace` that shows merged preparation and runtime logs.
 - Press `Stop` to kill the active runtime process.
 ## Key Decisions
 Based on `DEC-0020`, `DEC-0021`, and `DEC-0022`:
 1.  **Preparation Pipeline**: The `Play` flow orchestrates existing domain operations: `build` -> `validate pack` -> `pack` -> `manifest generation`. All artifacts are kept in `build/`, avoiding a redundant `cartridge/` directory for this wave.
 2.  **Runtime Command**: The runtime is executed externally as `"<runtimePath>" run build` with the project root as its working directory.
 3.  **Process Ownership**: Studio owns exactly one active runtime process handle per project shell.
 4.  **Merged Logs**: Preparation logs (build, pack validation, pack) and runtime logs (stdout/stderr) are merged into a single execution-session stream.
 5.  **Native Debugger Workspace**: A native `DebugWorkspace` hosts the execution session and acts as the primary log sink. It is not an external launcher but a real Studio workspace.
 6.  **Shared Session State**: The execution state (`idle`, `preparing`, `connecting`, `running`, etc.) lives outside the visual workspace lifecycle in a shared `StudioExecutionSessionService`.
 ## Implementation Details
 ### `StudioPlayStopCoordinator`
 The main orchestrator for the `Play` and `Stop` actions. It:
 - Manages the `preparing` -> `connecting` -> `running` state machine.
 - Invokes the `StudioShipperService` for preparation.
 - Spawns the external runtime process using `StudioExternalRuntimeProcessLauncher`.
 - Merges log streams from both preparation and runtime into the `StudioExecutionSessionService`.
 ### `DebugWorkspace`
 A Studio `Workspace` implementation that reflects the `StudioExecutionSnapshot`. It uses `DebugWorkspaceProjection` to transform the session logs into a display-ready format.
 ### `StudioShipperService`
 Aggregates the domain-specific tasks (compiler build, packer pack) and generates the mandatory `manifest.json` in the `build/` directory.
 ## Common Pitfalls & Anti-Patterns
 -   **Redundant Checks**: Do not add manual `manifest.json` existence checks before spawning. The success of the preparation pipeline already guarantees its presence according to the contract.
 -   **State Duplication**: Avoid tracking execution state in both the shell and the workspace. The shared `StudioExecutionSessionService` is the single source of truth.
 -   **Technical Linkage**: Do not hard-link the Studio codebase with the legacy `../debugger` repository. Selective migration of protocol/session logic is preferred.
 ## References
 -   `DEC-0020`: Build and pack preparation.
 -   `DEC-0021`: External runtime execution.
 -   `DEC-0022`: Native `DebugWorkspace` integration.
 -   `PLN-0045`: End-to-end execution flow.
--- a/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md
+++ b/discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md
@ -1,186 +0,0 @@
 ---
 id: AGD-0009
 ticket: studio-debugger-workspace-integration
 title: Integrar ../debugger ao Studio como workspace dedicado
 status: in_progress
 created: 2026-03-30
 resolved: 2026-04-06
 decision: DEC-0022
 tags:
  - studio
  - debugger
  - workspace
  - integration
  - shell
 ---
 ## Pain
 O shell do Studio ja anuncia `WorkspaceId.DEBUG` e exibe `Debug` na workspace rail, mas nao registra nenhum workspace concreto para esse slot.
 Hoje isso deixa o produto num estado inconsistente:
 - a shell promete um `Debugger/Profiler` como workspace baseline;
 - `MainView` publica a opcao `Debug` na navegacao;
 - `WorkspaceHost` exige que o workspace esteja registrado;
 - a implementacao real do `Debug` continua fora do Studio, no sibling repo `../debugger`.
 Sem uma discussion canonica, a integracao tende a cair em um de tres atalhos ruins:
 - abrir o debugger como app externo e fingir que isso equivale a um workspace;
 - embutir a aplicacao JavaFX existente dentro do Studio sem alinhar ciclo de vida, eventos e theming;
 - reescrever tudo no Studio e perder o que o `../debugger` ja estabilizou em protocolo, controle de execucao e estado.
 ## Context
 Domain owner: `studio`
 Owner surface: `docs/specs/studio`
 Cross-domain input: sibling repo `../debugger`
 Normative upstream dependencies:
 - `DEC-0020` for `Play` preparation through `build -> validate pack -> pack -> manifest`
 - `DEC-0021` for runtime execution through external `"<runtimePath>" run build` and `Play/Stop` process ownership
 Superficies relevantes hoje:
 - `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` ja define `Debugger/Profiler` como parte do baseline workspace set;
 - `docs/specs/studio/2. Studio UI Foundations Specification.md` exige um modelo de workspaces orientado a eventos, com bus por workspace e republishing para o bus global;
 - `prometeu-studio/src/main/java/p/studio/window/MainView.java` ja inclui `WorkspaceId.DEBUG` na rail, mas o `register(...)` correspondente esta comentado;
 - `prometeu-studio/src/main/java/p/studio/workspaces/Workspace.java` exige um contrato de `rootNode()`, `load()`, `unLoad()` e integra o workspace a um `StudioWorkspaceEventBus`;
 - `../debugger` ja existe como aplicacao JavaFX separada, com `Application`/`Stage`, FXML, Dagger, i18n, cliente DevTools, protocolo TCP/JSONL e controle de execucao.
 O boundary de produto tambem ja aponta a direcao correta:
 - o shell do Studio deve enquadrar workspaces sem absorver detalhe operacional;
 - logs e detalhe de execucao pertencem ao workspace que os possui;
 - o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades.
 As discussoes mais recentes de `Play/Stop` tambem reduziram o primeiro corte que interessa agora:
 - o `DebugWorkspace` e o destino futuro dos logs de `build`, validacao de `pack`, `pack` e runtime;
 - `Play/Stop` continua dono do fluxo operacional de `run` nesta wave;
 - o valor principal a reaproveitar do `../debugger` agora esta em filosofia, politicas de debug/remote connection, sessao, protocolo e modelos de eventos, nao em bootstrap de app standalone nem em copia literal de codigo;
 - o objetivo imediato nao e portar "o debugger inteiro", mas sim dar ao Studio uma superficie de execucao e observabilidade nativa.
 - nao precisamos comecar perfeitos: a primeira wave pode ser deliberadamente simples, desde que entregue handshake com o runtime e sink de logs suficiente para destravar `Play/Stop`.
 Constraint for this agenda:
 - esta agenda trabalha em conjunto com `AGD-0023`/`DEC-0020` e `AGD-0024`/`DEC-0021`;
 - ela NAO pode reinterpretar pipeline de preparacao, politica de execucao, ownership de `Play/Stop` ou trocar `run` por `debug` por inferencia;
 - qualquer mudanca nesses contratos exige revisao explicita das decisions upstream, nao convergencia lateral dentro desta agenda.
 ## Open Questions
 - [x] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
 - Resposta proposta: o primeiro corte deve ser menor e nativo ao contrato de workspace do Studio, focado em sink de logs de execucao/preparacao e politicas de debug/remote connection.
 - [x] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
 - Resposta proposta: o `../debugger` deve ser tratado principalmente como referencia filosofica e arquitetural; sessao, protocolo, cliente de remote connection, politicas de debug e modelos de eventos/estado podem ser reaproveitados quando isso for util, mas nao ha autorizacao para copiar codigo 1:1 por inercia. Bootstrap `Application`/`Stage`, shell standalone e UI acoplada a esse host nao devem atravessar a fronteira como unidade de integracao.
 - [x] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
 - Resposta proposta: a topologia correta desta integracao e migracao seletiva para dentro do Studio, sem link tecnico entre os dois projetos. `../debugger` nao deve virar dependencia viva do Studio porque sera removido em breve. Copia 1:1 deve ser evitada por padrao, mas pode acontecer pontualmente quando for realmente util.
 - [x] Os detalhes do handshake com o runtime ja precisam nascer totalmente redesenhados no Studio, ou podem ser tirados do `../debugger` nesta wave?
 - Resposta proposta: os detalhes do handshake podem ser tirados do `../debugger` nesta wave, desde que entrem no Studio no shape nativo do workspace e sem copiar codigo 1:1 por inercia.
 - [x] Quem passa a ser o owner do ciclo de vida da sessao de debug: o `DebugWorkspace`, a shell do Studio, ou um servico compartilhado com a run surface?
 - Resposta proposta: o owner deve ser um servico/sessao compartilhado consumido pelo `DebugWorkspace`, enquanto `Play/Stop` continua acionando connect/attach/disconnect under the hood nesta wave.
 - [x] Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
 - Resposta proposta: `build` e `pack` permanecem owners de seus proprios logs, mas esses streams devem ser agregados, merged e sinkados para o destino de logs do `DebugWorkspace`; o workspace repassa apenas eventos resumidos relevantes para o bus global do Studio.
 - [x] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior?
 - Resposta proposta: o baseline inicial fecha apenas `debugger`; politicas de connect/disconnect manuais podem ficar mais relevantes quando a wave de profiling existir.
 - [ ] Como preservar tema, i18n e consistencia visual se parte da UI atual do `../debugger` ainda estiver em FXML e recursos proprios?
 - [x] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?
 - Resposta proposta: o `../debugger` e uma tentativa anterior e sera deletado quando o Studio estiver maduro o suficiente para representa-lo; ele nao deve ser mantido como destino paralelo nem receber novas mudancas durante esta integracao.
 - [x] O sink inicial de logs precisa nascer sofisticado, ou uma console/lista simples com origem visivel ja basta nesta wave?
 - Resposta proposta: uma console/lista simples com origem visivel ja basta nesta wave; merge e apresentacao podem melhorar depois.
 - [x] O `DebugWorkspace` deve abrir ja com estado basico de conexao como `connecting`, `connected` ou `failed`, mesmo com UI ainda crua?
 - Resposta proposta: sim; o workspace deve abrir com estado basico de sessao/conexao desde a primeira wave.
 ## Options
 ### Option A - Launcher externo a partir do Studio
 - **Approach:** O Studio oferece um ponto de entrada para abrir `../debugger` como processo/janela externa, mantendo a integracao dentro da shell apenas como acao de lancamento.
 - **Pro:** Menor custo inicial e reaproveitamento maximo da app atual.
 - **Con:** Nao entrega um workspace real do Studio, fragmenta estado/sessao e conflita com a baseline shell spec.
 - **Maintainability:** Fraca como arquitetura final. Pode servir no maximo como ponte temporaria, mas nao resolve o contrato de workspace.
 ### Option B - Embutir a UI atual do debugger quase inteira dentro de um workspace host
 - **Approach:** Reaproveitar FXML/controllers do `../debugger` e monta-los dentro de um `DebugWorkspace`, fazendo adaptacoes localizadas de DI, lifecycle e navegacao.
 - **Pro:** Reaproveita mais UI existente e acelera a primeira tela funcional.
 - **Con:** Carrega para dentro do Studio um bootstrap orientado a `Application`/`Stage`, com modelo proprio de lifecycle, theming e eventos que nao casa naturalmente com o contrato de workspace atual.
 - **Maintainability:** Media para baixa. Economiza reescrita imediata, mas cristaliza um boundary torto entre app standalone e workspace embutido.
 ### Option C - Workspace nativo do Studio com migracao seletiva inspirada no debugger
 - **Approach:** Tratar o `../debugger` como referencia arquitetural e fonte seletiva de detalhes uteis, migrando para o Studio apenas o que fizer sentido, em shape nativo ao contrato `Workspace` + bus tipado + lifecycle-managed controls, sem criar dependencia tecnica entre os dois repositorios.
 - **Pro:** Alinha shell spec, workspace framework e boundary de produto, sem descartar o investimento ja feito no debugger.
 - **Con:** Exige separar explicitamente o que e filosofia/padrao reutilizavel, o que e core realmente util e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
 - **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite absorver o valor estrutural do `../debugger` sem importar o host standalone como boundary errado nem copiar codigo por reflexo.
 ### Option D - Migracao integral do debugger para dentro do Studio
 - **Approach:** Absorver codigo e UI do `../debugger` para dentro dos modulos do Studio e tratar a aplicacao standalone como legado a ser aposentado.
 - **Pro:** Simplifica ownership futuro se o produto decidir convergir totalmente para uma unica shell.
 - **Con:** E a aposta mais cara e mais irreversivel, antes mesmo de fechar o contrato de integracao e o que ainda deve continuar independente.
 - **Maintainability:** Media. Pode ser boa no longo prazo, mas e prematura enquanto o boundary entre `workspace` e `app standalone` ainda nao esta fechado.
 ## Discussion
 O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto principal e decidir qual contrato queremos estabilizar entre:
 - a shell do Studio, que ja assume workspaces independentes e orientados a eventos;
 - o `DebugWorkspace`, que precisa ser um workspace real, com ownership claro de detalhe operacional;
 - e o `../debugger`, que hoje concentra bootstrap de app, protocolo, estado e UI numa aplicacao separada.
 Mas esse contrato agora tem limites claros:
 - `DEC-0020` ja fecha a preparacao;
 - `DEC-0021` ja fecha a execucao com `run build` e ownership de processo;
 - portanto a agenda 9 so pode definir a superficie que hospeda logs, sessao e politicas remotas compativeis com esses contratos.
 O fato de a rail ja ter `Debug` e a spec ja falar em `Debugger/Profiler` indica que a integracao nao e trabalho especulativo.
 Ela ja faz parte da topologia esperada do Studio.
 Por isso, as opcoes que preservam o debugger apenas como janela externa ou que arrastam a app inteira para dentro do host sem remodelar o boundary resolvem pouco:
 - a primeira evita o trabalho agora, mas nao entrega o produto prometido pela shell;
 - a segunda reaproveita UI, mas importa um modelo arquitetural que nao conversa bem com `Workspace`, `StudioWorkspaceEventBus`, theming compartilhado e lifecycle-managed controls.
 O caminho mais coerente parece ser separar o problema em duas camadas:
 1. um `debugger core` reaproveitavel, com sessao, protocolo, telemetria, logs e controle de execucao;
 2. uma composicao de `DebugWorkspace` nativa do Studio, que consome esse core como mais um workspace do shell.
 As decisoes recentes de `Play/Stop` deixam ainda mais claro o primeiro corte util:
 - o `DebugWorkspace` deve receber o sink de logs de `build`, validacao de `pack`, `pack` e runtime;
 - `build` e `pack` continuam possuindo seus proprios logs, mas o usuario deve ve-los merged no destino do debugger;
 - `Play/Stop` continua fazendo attach/connect/disconnect under the hood nesta wave, sem expor ainda uma superficie rica de comandos manuais;
 - o `core` de remote connection e politicas de debug do `../debugger` pode ser reaproveitado aqui;
 - profiler fica explicitamente fora do baseline inicial.
 Esse recorte tambem assume pragmatismo de wave 1:
 - o handshake com o runtime pode nascer a partir dos detalhes ja estabilizados no `../debugger`;
 - o sink de logs pode comecar como console/lista simples com origem visivel;
 - o `DebugWorkspace` precisa mostrar estado de sessao suficiente para o usuario entender se esta conectando, conectado ou falhou;
 - refinamentos de UX, estrutura de logs e comandos mais ricos podem vir depois.
 Isso nao obriga uma reescrita total imediata da logica do debugger.
 Obriga apenas que a UI e o bootstrap standalone parem de ser tratados como se fossem a fronteira certa de integracao.
 ## Resolution
 Recommended direction: seguir com **Option C**.
 A agenda deve convergir para uma decisao com os seguintes fechamentos:
 1. `Debug` no Studio deve virar um workspace real, nao apenas launcher de app externo;
 2. o `../debugger` deve ser tratado como referencia filosofica e fonte seletiva de reaproveitamento, nao como base para copia 1:1;
 3. a topologia desta wave deve ser migracao seletiva sem link tecnico entre os dois projetos;
 4. o boundary correto de reaproveitamento esta em servicos/protocolo/estado/politicas de remote connection do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao;
 5. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
 6. o primeiro corte deve ser focado em sink merged de logs de execucao/preparacao e sessao de debug remota consumida pelo workspace;
 7. `Play/Stop` deve continuar controlando under the hood o fluxo de connect/attach/disconnect nesta wave;
 8. `profiler` fica explicitamente fatiado para depois;
 9. o `../debugger` nao deve receber novas mudancas e sera deletado quando o Studio estiver maduro o suficiente para representa-lo;
 10. esta agenda deve permanecer estritamente compativel com `DEC-0020` e `DEC-0021`, sem avancar sinal sobre preparacao ou execucao;
 11. a primeira wave nao precisa ser perfeita: basta entregar handshake com o runtime, estado basico de sessao e sink de logs simples com origem visivel, deixando refinamentos para depois.
 Next step suggestion: converter esta agenda em uma `decision` que feche o modelo de integracao, o boundary de ownership entre `studio` e `../debugger`, a topologia de dependencias entre repositorios e o escopo da primeira wave de `DebugWorkspace` como superficie nativa de logs/sessao de execucao remota.
--- a/discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md
+++ b/discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md
@ -1,132 +0,0 @@
 ---
 id: AGD-0023
 ticket: studio-play-stop-cartridge-flow
 title: Play/Stop integration agenda for build/pack freshness-gated runtime preparation
 status: in_progress
 created: 2026-04-06
 resolved: 2026-04-06
 decision: DEC-0020
 tags: [studio, play-stop, build, pack, compiler, packer, manifest]
 ---
 ## Pain
 O botão `Play` do Studio hoje só alterna estado visual no shell.
 Ele ainda não aciona um fluxo operacional real para preparar um conjunto executável de artefatos em `build/`.
 Isso deixa o shell com uma affordance de execução sem pipeline correspondente e sem um contrato claro entre:
 - Studio shell,
 - compiler build,
 - compiler,
 - packer,
 - e a pasta `build/` do projeto.
 ## Context
 Domain owner: `studio`.
 Subdomínios referenciados: `compiler`, `packer`, `runtime`.
 Já existe um `ShipperWorkspace` no Studio e ele hoje chama `BuilderPipelineService.INSTANCE.build(...)`, mas esse fluxo atual é apenas um scratch inicial.
 Na prática, hoje ele está compilando bytecode e não deve ser tratado como o contrato definitivo de preparação de runtime do produto.
 O objetivo desta agenda não é fechar um pipeline de shipping nem materializar um `cartridge/` separado.
 O escopo desta wave é estritamente o mínimo necessário para o botão `Play` conseguir preparar artefatos rodáveis em `build/`:
 1. compilar o PBX necessário;
 2. executar o packer necessário;
 3. manter ou regenerar os artefatos de `build/` conforme frescor;
 4. gerar `manifest.json` em `build/`.
 Essa agenda trata apenas da preparação dos artefatos em `build/`.
 A execução `runtime run cartridge` ou equivalente apontando para `build/` fica em agenda separada dentro da mesma discussion.
 ## Open Questions
 - [x] O `Play` deve reutilizar exatamente o mesmo pipeline já acionado pelo `ShipperWorkspace`, ou deve haver um service/application layer dedicado para o shell chamar e o workspace apenas consumir?
 - Resposta proposta: `Play` não deve reaproveitar o scratch atual do `ShipperWorkspace`; ele deve orquestrar chamadas explícitas de `build` e `pack`, cada uma com sua própria política de frescor.
 - [x] Os artefatos rodáveis desta wave devem viver em `cartridge/` separado ou no próprio `build/`?
 - Resposta proposta: nesta wave o artifact root runnable deve ser `build/`; não há necessidade de materializar um `cartridge/` separado se o runtime pode consumir o mesmo contrato diretamente de `build/`.
 - [x] Quem decide se é necessário recompilar ou repackar quando o usuário aperta `Play`?
 - Resposta proposta: nesta wave, `Play` sempre chama `build` e `pack`; a política fina de drift/freshness fica explicitamente adiada para uma segunda etapa. Quando essa segunda etapa existir, cada domínio será owner de sua própria política de frescor.
 - [x] Onde deve viver o controle fino de frescor e drift para os artefatos produzidos?
 - Resposta proposta: quando a wave de drift existir, o controle fino viverá em arquivos dedicados por domínio sob `.studio/`, começando por `asset-workspace.json` e `editor-workspace.json`, separados do snapshot principal de restauração.
 - [x] O `manifest.json` runtime-facing deve ser derivado do `prometeu.json` do projeto com normalização adicional do Studio, ou copiado quase diretamente com apenas os campos estritamente runtime-facing?
 - Resposta proposta: o `manifest.json` deve ser sempre gerado de forma determinística em `build/`, a partir do build corrente e do owner metadata do projeto, sem cópia por conveniência.
 - [x] Como o shell distinguirá falha de build, falha de pack e falha de manifest para refletir estado útil no `Play/Stop`?
 - Resposta proposta: para o `Play`, basta distinguir `success` e `failed`; logs detalhados das operações devem acompanhar o resultado. `build` falhando bloqueia `pack`, e `manifest` só roda depois do sucesso do build/pack desta wave.
 ## Options
 ### Option A - `Play` sempre chama `build` e `pack`, e drift fica para uma wave posterior
 - **Approach:** Fazer o shell chamar explicitamente `build` e `pack` em toda execução de `Play`; nesta wave não há reuse por drift/freshness, apenas execução determinística com logs e geração final de `manifest.json`.
 - **Pro:** Destrava a integração do `Play` com o menor contrato correto, sem antecipar um sistema de freshness ainda não normatizado.
 - **Con:** Pode refazer trabalho desnecessário em execuções sucessivas até a wave de drift existir.
 - **Maintainability:** Boa, porque mantém o `Play` simples agora e deixa a otimização para uma agenda própria depois.
 ### Option B - `Play` inspeciona artefatos existentes e decide por conta própria se pode seguir
 - **Approach:** O shell observa presença ou timestamps de artefatos em `build/` e tenta inferir se basta reutilizar o que já existe.
 - **Pro:** Menos modelagem inicial de metadata e contratos.
 - **Con:** Move para o shell uma inteligência que pertence aos domínios de compiler e packer, além de abrir espaço para reuse incorreto sob drift parcial do workspace.
 - **Maintainability:** Fraca, porque o `Play` vira owner implícito de políticas que não são dele.
 ## Discussion
 O ponto central aqui não é apenas "rodar compile + packer".
 O problema real é separar claramente:
 - a orquestração do `Play`,
 - a responsabilidade de `build`,
 - a responsabilidade de `pack`,
 - e a futura política de frescor de cada artefato.
 Se o `Play` inferir por conta própria se precisa rebuildar ou repackar, o shell passa a absorver conhecimento que pertence a outros domínios.
 Isso cria uma fronteira errada: o shell deixa de ser apenas o caller de operações e passa a ser o árbitro de drift do projeto.
 Ao mesmo tempo, modelar agora um sistema fino de drift adicionaria complexidade antes da própria integração básica do `Play` existir.
 Por isso, esta agenda fecha a wave 1 com execução sempre explícita e adia a otimização de freshness para uma agenda própria.
 O contrato mais limpo é:
 1. `Play` pede `build`;
 2. `build` executa e retorna `success` ou `failed`, acompanhado de logs;
 3. `Play` pede `pack`;
 4. `pack` executa e retorna `success` ou `failed`, acompanhado de logs;
 5. `manifest.json` é sempre regenerado em `build/` a partir do build corrente e dos metadados do projeto;
 6. `Play` só verifica sucesso ou falha dessas operações antes de seguir para a execução.
 Os constraints já visíveis no repositório reforçam esse recorte:
 - o compiler atual escreve `build/program.pbx`;
 - o packer atual escreve `build/assets.pa` e companions de tooling, e o spec do packer afirma explicitamente que cartridge assembly não pertence ao domínio `packer`;
 - os projetos de teste já mostram `build/` contendo `program.pbx`, `assets.pa` e companions;
 - `ProjectLocalStudioSetup` já está carregado na `StudioProjectSession`, então o shell já possui o owner correto para coordenar preparation + future run sem precisar deduzir drift por presença oportunista de arquivo.
 Isso torna a fronteira recomendada mais concreta:
 1. `build/` é o artifact root runnable desta wave;
 2. compiler e packer continuam donos de seus artefatos dentro de `build/`;
 3. `Play` não usa presença de arquivo como regra de validade;
 4. drift e freshness ficam explicitamente fora do escopo desta wave e poderão viver em arquivos dedicados por domínio sob `.studio/`;
 5. o shell avança apenas quando `build`, `pack` e `manifest` reportarem sucesso.
 A recomendação inicial desta agenda é:
 1. fazer `Play` chamar explicitamente `build` e `pack`;
 2. manter `build` e `pack` como operações domain-owned com logs e resultado binário de sucesso/falha nesta wave;
 3. adiar o controle fino de drift/freshness para uma agenda própria posterior;
 4. promover `build/` como artifact root runnable desta wave;
 5. gerar `manifest.json` em `build/` sempre a partir do build corrente;
 6. tratar o resultado de cada operação como contrato explícito para o `Play`, sem heurística oportunista baseada apenas em presença de arquivo.
 ## Resolution
 Próximo passo sugerido: fechar uma decision de `studio` que trave o fluxo de preparação do `Play/Stop` com estas amarras normativas já explícitas:
 1. `Play` é apenas o orquestrador de `build`, `pack` e `manifest`;
 2. nesta wave, `build` sempre executa quando chamado pelo `Play`;
 3. nesta wave, `pack` sempre executa quando chamado pelo `Play`, e só é chamado se `build` tiver sucesso;
 4. o artifact root runnable desta wave é `build/`, não `cartridge/`;
 5. `manifest.json` é sempre gerado deterministicamente em `build/`, a partir do build corrente, e não copiado por conveniência;
 6. freshness e drift ficam fora do escopo desta wave e, quando tratados, usarão arquivos dedicados por domínio sob `.studio/`, como `asset-workspace.json` e `editor-workspace.json`;
 7. `Play` só segue adiante quando as operações necessárias reportarem sucesso.
--- a/discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md
+++ b/discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md
@ -1,128 +0,0 @@
 ---
 id: AGD-0024
 ticket: studio-play-stop-cartridge-flow
 title: Play/Stop integration agenda for runtime execution from build using project runtime setup
 status: in_progress
 created: 2026-04-06
 resolved: 2026-04-06
 decision: DEC-0021
 tags: [studio, runtime, play-stop, build, process, project-setup]
 ---
 ## Pain
 Mesmo depois que o Studio conseguir preparar `build/`, o botão `Play` continuará incompleto sem um contrato claro para executar o runtime configurado no projeto contra esse artifact root.
 Hoje o caminho do runtime já existe em `.studio/setup.json` via `ProjectLocalStudioSetup.prometeuRuntimePath`, mas esse valor ainda não participa de nenhuma execução real no shell.
 Sem essa definição, o `Play/Stop` corre o risco de virar:
 - um botão que prepara `build/` mas não executa nada;
 - ou um launcher improvisado, sem owner claro para processo, logs, lifecycle e falhas.
 ## Context
 Domain owner: `studio`.
 Subdomínios referenciados: `runtime`.
 O Studio já carrega `ProjectLocalStudioSetup` na `StudioProjectSession`.
 Portanto o runtime configurado por projeto já está disponível para consumo em runtime de aplicação.
 Após a decisão `DEC-0020`, esta agenda passa a assumir explicitamente que:
 - `Play` prepara `build/` como artifact root runnable;
 - `manifest.json` é gerado em `build/`;
 - não há `cartridge/` separado nesta wave.
 O comando desejado pelo usuário é conceitualmente:
 `runtime run build`
 usando o runtime configurado no projeto atual.
 Esta agenda não rediscute preparação de `build/`.
 Ela assume a saída de `DEC-0020` como pré-condição e foca no segundo passo do `Play`: iniciar, observar e interromper o processo de runtime.
 Também há um constraint de UX desta wave:
 - ao apertar `Play`, o usuário deverá ser levado para o futuro `DebuggerWorkspace`, mesmo que essa surface ainda não esteja construída;
 - até essa surface existir, os logs do runtime precisarão "ficar voando", isto é, viver provisoriamente fora do destino final pretendido;
 - a etapa de `pack` usada por `Play` deve preservar seu ciclo de validação antes da execução do runtime;
 - os logs de `build` e `pack` também devem convergir para o destino do debugger, porque é nessa surface que o usuário verá falhas de compilação, validação ou packing durante o fluxo do `Play`.
 Também há um constraint de escopo nesta wave:
 - checks adicionais de preflight antes do `build`, como arquivos do editor ainda não salvos, não entram agora;
 - quando essa wave futura existir, ela deverá bloquear o `Play` antes do `build` com erro explícito, em vez de ser tratada como detalhe implícito de runtime.
 ## Open Questions
 - [x] O `Play` deve falhar imediatamente quando `prometeuRuntimePath` estiver ausente, ou o shell deve oferecer algum repair path explícito antes de abortar?
 - Resposta proposta: nesta wave, o `Play` deve falhar imediatamente com erro explícito quando `prometeuRuntimePath` estiver ausente, inválido, inexistente ou não executável; repair path guiado fica para uma wave posterior.
 - [x] O Studio deve executar o runtime diretamente pelo binário configurado, ou por um wrapper/comando fixo resolvido a partir desse path?
 - Resposta proposta: o Studio deve executar como processo externo o binário configurado em `ProjectLocalStudioSetup.prometeuRuntimePath`, apontando para `build/` e usando o subcomando `run` nesta wave; uma futura wave de debugger poderá trocar esse subcomando para `debug`.
 - [x] O `Stop` deve encerrar apenas o processo de runtime ativo iniciado pelo shell atual, ou também limpar algum estado transitório adicional no Studio?
 - Resposta proposta: `Stop` deve encerrar apenas o processo de runtime ativo iniciado pelo `Play` atual; não deve limpar estado transitório adicional além do lifecycle desse processo.
 - [x] Onde os logs de stdout/stderr do runtime devem viver nesta primeira wave: activity feed, shipper logs, uma surface dedicada, ou combinação mínima dessas superfícies?
 - Resposta proposta: o destino final dos logs deve ser o futuro `DebuggerWorkspace`, e o `Play` deve navegar para essa surface ao iniciar a execução; até ela existir, stdout/stderr e também os logs de `build`/`pack` ficam provisoriamente em uma solução transitória desacoplada, enquanto o Activity Feed recebe apenas eventos resumidos de início, sucesso de término e falha.
 - [x] Como o shell deve serializar múltiplos cliques em `Play`: ignorar enquanto já está rodando, reiniciar, ou encadear stop + rerun?
 - Resposta proposta: enquanto já houver runtime ativo iniciado pelo shell atual, cliques adicionais em `Play` devem ser ignorados até o processo sair ou o usuário apertar `Stop`.
 - [x] O `pack` usado pelo `Play` pode empacotar diretamente, ou deve preservar o ciclo de validação antes da execução do runtime?
 - Resposta proposta: o `pack` usado pelo `Play` deve preservar seu ciclo de validação antes da execução; se a validação bloquear o pack, o runtime não deve iniciar.
 - [x] Checks extras antes do `build`, como arquivos não salvos no editor, entram nesta wave?
 - Resposta proposta: não; preflight adicional de `build`, incluindo arquivos ainda não salvos, fica explicitamente para uma wave posterior e não altera o contrato desta agenda.
 - [x] A execução da agenda 24 deve validar explicitamente a existência de `build/manifest.json` antes do spawn, ou isso fica implícito pelo sucesso da preparação?
 - Resposta proposta: isso fica implícito pelo sucesso da preparação definida em `DEC-0020`; a agenda 24 não adiciona check redundante de existência de `manifest.json` antes do spawn.
 ## Options
 ### Option A - Play/Stop controla um processo único de runtime do projeto ativo
 - **Approach:** O shell resolve o runtime configurado no `ProjectLocalStudioSetup`, executa diretamente o binário configurado contra `build/` como processo do projeto ativo, mantém handle desse processo e usa `Stop` para encerrar exatamente esse processo.
 - **Pro:** O comportamento do botão fica simples, previsível e diretamente alinhado ao modelo visual de toggle.
 - **Con:** Exige que o Studio introduza ownership explícito de processo, logs e cleanup, em vez de só alternar estado visual.
 - **Maintainability:** Boa, porque o shell passa a ter um contrato único de execução por projeto e um lifecycle claro.
 ### Option B - Play delega a execução ao workspace ou a um launcher externo sem handle direto no shell
 - **Approach:** O shell apenas dispara uma ação indireta e considera-se "running" sem possuir o processo como first-class state próprio.
 - **Pro:** Menor acoplamento inicial entre shell e camada de processo.
 - **Con:** O `Stop` fica semanticamente fraco ou enganoso, porque o shell não controla de verdade o processo que diz estar executando.
 - **Maintainability:** Fraca, porque o toggle visual deixa de corresponder ao lifecycle real da execução.
 ## Discussion
 O ponto mais importante desta agenda é alinhar o significado de `Stop`.
 Se o shell não possui o processo de runtime como state explícito, o botão vira só uma fantasia visual.
 Como o runtime path já é project-local setup carregado na sessão, o Studio já tem o owner certo para resolver o binário configurado.
 O que falta é explicitar o contrato operacional:
 1. validar que o runtime configurado existe e é executável;
 2. executar `build`;
 3. executar a validação de `pack`;
 4. executar `pack` somente quando a validação permitir;
 5. enviar os logs de `build` e `pack` para a surface de debugger/logs da execução;
 6. rodar como processo externo o runtime configurado contra `build/` no contexto do projeto ativo, usando `run` nesta wave;
 7. capturar stdout/stderr;
 8. refletir running/stopped/failure no shell;
 9. interromper o processo correto quando o usuário apertar `Stop`.
 A execução do runtime nesta agenda confia no contrato de preparação anterior.
 Portanto, esta wave não introduz preflight redundante para verificar novamente a existência de `build/manifest.json` antes do spawn.
 A recomendação inicial desta agenda é:
 1. fazer o shell ser owner de um único runtime-process handle por projeto ativo;
 2. resolver o comando a partir de `ProjectLocalStudioSetup.prometeuRuntimePath`;
 3. falhar de forma explícita quando o runtime do projeto estiver ausente ou inválido;
 4. definir `Stop` como término do processo iniciado pelo `Play` atual, e não como reset genérico de UI;
 5. ignorar novo `Play` enquanto o processo atual ainda estiver rodando;
 6. preservar a validação de pack antes do pack efetivo na preparação do `Play`;
 7. tratar o futuro `DebuggerWorkspace` como destino canônico da execução e dos logs de runtime, `build` e `pack`;
 8. enquanto o `DebuggerWorkspace` não existir, manter stdout/stderr e logs de preparação em uma solução transitória, usando o Activity Feed apenas para sinais resumidos de lifecycle;
 9. deixar checks extras de preflight antes do `build`, como arquivos não salvos, fora desta wave;
 10. fixar `run` como o subcomando de execução desta wave, deixando `debug` para uma futura wave de debugger;
 11. confiar no sucesso da preparação anterior sem adicionar preflight redundante de `manifest.json` antes do spawn.
 ## Resolution
 Próximo passo sugerido: fechar uma decision de `studio` que defina ownership de processo para `Play/Stop`, preserve o ciclo de validação + pack antes da execução do runtime, fixe a execução como processo externo do runtime configurado usando `run` contra `build/`, trate o `DebuggerWorkspace` como destino futuro da sessão de execução e explicite que checks extras de preflight do `build` ficam para uma wave posterior.
--- a/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md
+++ b/discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md
@ -1,147 +0,0 @@
 ---
 id: DEC-0020
 ticket: studio-play-stop-cartridge-flow
 title: Decision for Play/Stop build and pack preparation through build-owned artifacts
 status: accepted
 created: 2026-04-06
 accepted: 2026-04-06
 agenda: AGD-0023
 plans: [PLN-0041, PLN-0042, PLN-0045]
 tags: [studio, play-stop, build, pack, compiler, packer, manifest, shell]
 ---
 ## Decision
 Domain owner: `studio`.
 Referenced subdomains: `compiler`, `packer`, `runtime`.
 The Studio `Play` flow for this wave SHALL be implemented as an orchestration over existing domain operations, not as a separate shipping pipeline.
 The decision is:
 1. `Play` MUST call `build` first.
 2. `pack` MUST run only after `build` completes successfully.
 3. `Play` MUST treat `build/` as the runnable artifact root for this wave.
 4. `Play` MUST NOT materialize or depend on a separate `cartridge/` directory in this wave.
 5. `manifest.json` MUST be generated deterministically into `build/` from the current build result and project-owned metadata.
 6. `Play` MUST only need to evaluate whether each required operation succeeded or failed.
 7. Detailed operation logs MUST remain available alongside the operation results consumed by `Play`.
 8. The Studio shipper service MUST own preparation orchestration and preparation-log aggregation for this wave.
 9. Preparation logs MUST preserve at least the distinct channels `build`, `pack-validation`, and `pack`.
 10. Drift/freshness reuse logic is explicitly out of scope for this wave.
 11. A future drift/freshness wave MUST use domain-specific `.studio/` files rather than the main session-restoration snapshot.
 ## Rationale
 This decision intentionally keeps the first executable `Play` wave narrow.
 The repository already shows:
 - compiler ownership of `build/program.pbx`,
 - packer ownership of `build/assets.pa` and companion build artifacts,
 - and no accepted requirement that a separate `cartridge/` assembly step must exist before runtime execution.
 Creating a new shipper/materialization layer now would add an extra boundary before the base `Play` integration exists.
 Likewise, pushing drift/freshness inference into `Play` would make the shell the owner of compiler and packer validity rules, which is the wrong boundary.
 This decision therefore chooses the smallest correct operational split:
 - `Play` orchestrates,
 - `shipper` owns preparation orchestration and preparation-log aggregation,
 - `build` produces compiler artifacts,
 - `pack` produces packer artifacts,
 - `manifest` is generated after successful preparation,
 - and runtime execution in the next wave may consume `build/` directly.
 ## Technical Specification
 ### 1. Orchestration Order
 The `Play` preparation path MUST execute in this order:
 1. `build`
 2. `pack` (only if `build` succeeded)
 3. `manifest` generation in `build/`
 4. handoff to the runtime-execution flow covered by a separate agenda/decision wave
 `Play` MUST stop immediately on the first failed required step.
 No cancellation of the preparation phase is defined in this wave.
 ### 2. Artifact Root
 For this wave, `build/` is the canonical runnable artifact root.
 At minimum, the prepared runtime-facing output in `build/` SHALL include:
 - `program.pbx`
 - `assets.pa`
 - `manifest.json`
 Packer companion artifacts may remain in `build/` as domain-owned outputs.
 They do not redefine the minimum contract required by `Play`.
 ### 3. Result Contract
 The result contract consumed by `Play` for this wave MUST be binary at the control-flow level:
 - `success`
 - `failed`
 `Play` MUST NOT need to interpret finer-grained reuse or freshness states in this wave.
 Operational logs from `build`, `pack`, and manifest generation MUST remain available so the shell can surface useful diagnostics without owning domain-specific decision logic.
 For this wave, those preparation logs are owned and aggregated by the Studio shipper service.
 ### 4. Manifest Generation
 `manifest.json` MUST NOT be copied opportunistically from an older location.
 Instead, it MUST be generated on every successful preparation run:
 - in `build/`,
 - from the current build result,
 - and from project-owned metadata required by the runtime-facing manifest contract.
 ### 5. Drift and Freshness Deferral
 This decision does not authorize a freshness-based skip path yet.
 Rules:
 - `Play` MUST NOT infer artifact validity from file presence alone.
 - This wave MAY always execute `build` and `pack` when `Play` is pressed.
 - If a later wave introduces drift/freshness control, that logic MUST be discussed separately before implementation.
 - That later wave MUST keep operational metadata in dedicated domain files under `.studio/`, with the agreed initial direction being `asset-workspace.json` and `editor-workspace.json`.
 - That later wave MUST NOT mix such metadata into `.studio/state.json` by convenience.
 ### 6. Boundary With Existing Workspaces
 The current `ShipperWorkspace` scratch implementation does not become the normative backend for `Play` by inertia.
 This decision does not require:
 - a new shipping module,
 - a separate cartridge-materialization directory,
 - or Play-owned drift heuristics.
 Existing workspaces may remain useful as manual or diagnostic surfaces, but they MUST NOT redefine the `Play` preparation contract established here.
 ### 7. Preparation Logging Boundary
 For this wave, preparation logging MUST follow these rules:
 - build and pack remain owners of their own log production;
 - the Studio shipper service aggregates preparation output for user-facing consumption;
 - the aggregated preparation stream MUST preserve distinct source channels for `build`, `pack-validation`, and `pack`;
 - downstream debugger/execution surfaces consume that aggregated preparation output rather than redefining preparation ownership.
 ## Constraints
 1. This decision covers preparation only, not runtime process ownership or `Stop` behavior.
 2. This decision does not yet define the exact manifest field mapping beyond deterministic generation from current build inputs and project metadata.
 3. This decision does not yet define a drift fingerprint model.
 4. Any later attempt to skip `build` or `pack` based on freshness requires a new discussion wave or explicit revision of this decision.
 5. Any later reintroduction of `cartridge/` as a mandatory runtime root requires a new decision or explicit revision of this one.
 ## Revision Log
 - 2026-04-06: Initial draft from AGD-0023.
--- a/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md
+++ b/discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md
@ -1,174 +0,0 @@
 ---
 id: DEC-0021
 ticket: studio-play-stop-cartridge-flow
 title: Decision for Play/Stop runtime execution from build through external run process
 status: accepted
 created: 2026-04-06
 accepted: 2026-04-06
 agenda: AGD-0024
 plans: [PLN-0042, PLN-0044, PLN-0045]
 tags: [studio, runtime, play-stop, build, process, debugger, project-setup, logs]
 ---
 ## Decision
 Domain owner: `studio`.
 Referenced subdomains: `runtime`.
 This decision defines the runtime-execution contract that follows the preparation contract already described in `DEC-0020`.
 The decision is:
 1. `Play` MUST execute the configured runtime as an external process.
 2. The runtime executable path MUST come from `ProjectLocalStudioSetup.prometeuRuntimePath`.
 3. The external command for this wave MUST be exactly `"<runtimePath>" run build`.
 4. The process MUST run with the project root as its current working directory.
 5. `Play` MUST rely on the successful completion of the preparation pipeline and MUST NOT add a redundant manifest-existence preflight in this wave.
 6. `Play` MUST fail explicitly when the configured runtime path is missing, invalid, nonexistent, non-executable, or cannot be spawned.
 7. `Play` MUST own exactly one active runtime-process handle for the current project shell.
 8. While that process is active, additional `Play` actions MUST be ignored.
 9. `Stop` in this wave MUST kill the active runtime process directly.
 10. The future `DebuggerWorkspace` SHALL be the canonical destination of execution and logs.
 11. Until that workspace exists, runtime logs and shipper-provided preparation logs MUST flow to a temporary surface, while the Activity Feed only receives summarized lifecycle events.
 12. The shipper service remains the owner of preparation orchestration and aggregated preparation output.
 13. The `pack` step used by `Play` MUST preserve validation before packing, and runtime execution MUST NOT start if validation blocks the pack.
 14. Additional pre-build editor preflight checks, including unsaved-file detection, are explicitly deferred to a future wave.
 15. No cancellation of the preparation phase is supported in this wave.
 16. The future debugger wave MAY replace `run` with `debug`, but that is not authorized by this decision.
 ## Rationale
 `Play/Stop` only becomes semantically real if the shell owns the runtime process it claims to start and stop.
 After `DEC-0020`, the runnable artifact root for this wave is `build/`, and the preparation flow already owns generation of `manifest.json`.
 This means the runtime-execution wave does not need another packaging boundary and does not need redundant manifest-existence checks before spawn.
 The narrowest correct contract is therefore:
 - prepare through `build -> validate pack -> pack -> manifest`,
 - treat shipper as the owner of preparation output and aggregated preparation logs,
 - spawn the configured runtime externally with `run build`,
 - keep a single process handle,
 - and surface logs in the future debugger destination.
 This keeps responsibility boundaries clear:
 - preparation remains owned by the earlier preparation decision,
 - runtime-process ownership belongs to the shell,
 - and future debugger behavior remains a later wave rather than being guessed now.
 ## Technical Specification
 ### 1. Runtime Command
 For this wave, the Studio shell MUST construct and execute the runtime command as:
 `"<runtimePath>" run build`
 Rules:
 - `runtimePath` MUST be read from `ProjectLocalStudioSetup.prometeuRuntimePath`;
 - the process MUST execute with `cwd` equal to the project root;
 - no wrapper command is introduced in this wave;
 - no `debug` subcommand is introduced in this wave.
 ### 2. Execution Order
 `Play` preparation and execution MUST follow this order:
 1. `build`
 2. `pack` validation
 3. `pack` only if validation allows it
 4. runtime spawn with `run build`
 The shell MUST stop on first failure.
 If `build` fails, no pack validation, pack, or runtime spawn occurs.
 If pack validation blocks, no pack or runtime spawn occurs.
 If pack fails, runtime spawn does not occur.
 If preparation fails, no cancellation path is offered in this wave; the flow simply terminates in failure.
 ### 3. Preparation Contract Reliance
 This decision depends on `DEC-0020`.
 Rules:
 - the shell MUST rely on the success of the earlier preparation pipeline;
 - the shell MUST NOT add a redundant check for `build/manifest.json` existence before spawn in this wave;
 - a missing manifest after successful preparation is a violation of the earlier preparation contract, not a new runtime-execution rule.
 ### 4. Runtime Preflight
 Before spawning the external process, the shell MUST treat the following conditions as explicit preflight failures:
 - missing `prometeuRuntimePath`,
 - blank `prometeuRuntimePath`,
 - nonexistent runtime path,
 - non-executable runtime path,
 - spawn failure.
 This wave does not yet define a broader runtime repair flow.
 ### 5. Process Ownership and Stop Semantics
 The shell MUST own exactly one active runtime-process handle per active project shell.
 Rules:
 - `Play` while the process is active MUST be ignored;
 - `Stop` MUST target only the process started by the current `Play` flow;
 - `Stop` in this wave MUST kill that process directly;
 - `Stop` has no effect during `preparing` because preparation cancellation is not defined in this wave;
 - graceful debugger-oriented stop commands are deferred to a future debugger wave.
 ### 6. Logging and Debugger Destination
 The canonical destination for execution-session logs SHALL be the future `DebuggerWorkspace`.
 For this wave:
 - the shell MUST navigate toward that execution destination when `Play` starts, before runtime spawn is attempted;
 - logs from `build`, pack validation, `pack`, and runtime stdout/stderr MUST converge on that execution-log destination;
 - preparation logs arrive there through shipper-owned aggregated output;
 - until the `DebuggerWorkspace` exists, those logs MUST use a temporary/transitional surface;
 - the Activity Feed MUST remain a summary surface and MUST NOT become the primary full-log destination.
 ### 7. Shared Session State
 The Studio shell and debugger destination require shared execution state that exists independently of the visual lifecycle of the workspace.
 For this wave, the minimum state machine SHALL distinguish at least:
 - `idle`
 - `preparing`
 - `prepare_failed`
 - `connecting`
 - `running`
 - `runtime_failed`
 - `stopped`
 This state is not owned solely by the visual workspace.
 ### 8. Deferred Checks
 This decision explicitly defers:
 - unsaved-editor-file checks before `build`,
 - broader build preflight policy,
 - graceful runtime stop commands,
 - debugger-specific execution semantics,
 - and any redundant manifest-presence preflight beyond the contract already owned by `DEC-0020`.
 When introduced later, those concerns MUST be handled in a separate discussion wave or explicit revision.
 ## Constraints
 1. This decision covers external runtime execution through `run`, not debugger execution through `debug`.
 2. This decision assumes the preparation contract of `DEC-0020` without reopening it.
 3. This decision does not yet define the concrete temporary UI surface that will host execution logs before the `DebuggerWorkspace` exists.
 4. This decision does not yet define richer exit-code UX beyond success/failure lifecycle handling.
 5. This decision does not yet define restart semantics beyond ignoring repeated `Play` while active.
 ## Revision Log
 - 2026-04-06: Initial draft from AGD-0024.
--- a/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md
+++ b/discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md
@ -1,203 +0,0 @@
 ---
 id: DEC-0022
 ticket: studio-debugger-workspace-integration
 title: Decision for native Studio DebugWorkspace integration with selective debugger migration
 status: accepted
 created: 2026-04-06
 accepted: 2026-04-06
 agenda: AGD-0009
 plans: [PLN-0042, PLN-0043, PLN-0044, PLN-0045]
 tags: [studio, debugger, workspace, integration, logs, runtime, play-stop]
 ---
 ## Decision
 Domain owner: `studio`.
 Cross-domain reference: sibling repo `../debugger`.
 Normative upstream dependencies: `DEC-0020`, `DEC-0021`.
 This decision defines the first integration wave of `DebugWorkspace` inside Studio.
 The decision is:
 1. `Debug` in Studio MUST become a real native workspace, not an external launcher.
 2. This integration MUST remain compatible with `DEC-0020` and `DEC-0021` and MUST NOT reinterpret preparation or execution contracts by inference.
 3. The first wave of `DebugWorkspace` MUST focus on two capabilities only:
   - runtime/debug-session handshake sufficient for the current `Play/Stop` flow,
   - and merged execution-log sinking for preparation and runtime.
 4. The first wave does NOT need to be perfect. A simple but functional session state and log sink is sufficient.
 5. The `../debugger` repository MUST be treated as architectural reference and selective source of useful details, not as a dependency to be linked or a codebase to be copied wholesale.
 6. Studio MUST NOT create a technical linkage between the two projects for this wave.
 7. Copying code from `../debugger` MUST be avoided by default, but MAY be done selectively when concretely useful.
 8. The correct integration boundary is in useful session/protocol/remote-debug policy details, not in `Application`/`Stage` bootstrap or standalone UI hosting.
 9. `Play/Stop` MUST continue owning connect/attach/disconnect behavior under the hood in this wave.
 10. `DebugWorkspace` MUST consume shipper-provided aggregated preparation logs and runtime logs through a shared session/service boundary.
 11. `DebugWorkspace` MUST be the destination for merged logs from `build`, pack validation, `pack`, and runtime execution.
 12. Build and pack remain owners of their own logs, but the user-facing execution surface MUST show those logs merged in the debugger destination.
 13. The global Activity Feed MUST remain a summary surface rather than the primary raw-log destination.
 14. The first wave MUST exclude profiler-specific behavior.
 15. The standalone `../debugger` MUST NOT be evolved as part of this Studio integration and is expected to be removed once Studio becomes mature enough to replace it.
 ## Rationale
 Recent `Play/Stop` decisions made `DebugWorkspace` no longer speculative.
 `DEC-0021` already establishes that:
 - `Play` navigates toward the future debugger destination,
 - build, pack-validation, pack, and runtime logs converge there,
 - and `Play/Stop` owns the current run-process contract.
 That means the immediate job of agenda 9 is not to design the final debugger product.
 Its immediate job is to provide the native Studio surface that can host:
 - session state,
 - handshake with the runtime,
 - and a merged sink for execution-related logs.
 The existing `../debugger` still matters, but mostly as a source of tested ideas and useful protocol/session details.
 Treating it as a live dependency would be the wrong topological move because:
 - the Studio is intended to become the durable host,
 - the sibling debugger will be removed later,
 - and hard-linking the repositories now would increase migration cost for little value.
 The narrowest correct answer is therefore:
 - native `DebugWorkspace` in Studio,
 - selective migration only,
 - no direct project linkage,
 - a shared session/service boundary outside the visual workspace,
 - no profiler in the first cut,
 - and enough runtime handshake + log sinking to support the already-decided `Play/Stop` flow.
 ## Technical Specification
 ### 1. Upstream Contract Boundaries
 This decision is downstream of `DEC-0020` and `DEC-0021`.
 Rules:
 - `DEC-0020` remains authoritative for preparation through `build -> validate pack -> pack -> manifest`;
 - `DEC-0021` remains authoritative for runtime execution through external `"<runtimePath>" run build` and current `Play/Stop` process ownership;
 - this decision MUST NOT redefine those flows;
 - any attempt to change preparation or execution semantics requires explicit revision of the upstream decisions rather than reinterpretation here.
 ### 2. First-Wave Scope
 The first-wave `DebugWorkspace` MUST provide:
 - a native Studio workspace surface,
 - basic debug/run session state,
 - handshake behavior with the runtime sufficient for the current flow,
 - and a merged log sink for execution-related activity.
 The first wave MAY be visually simple.
 It does not need polished debugger UX yet.
 ### 3. Session and Handshake
 The workspace MUST expose enough session state to show at least:
 - connecting,
 - connected,
 - failed,
 - and equivalent stopped/disconnected state as needed by the current flow.
 Handshake details MAY be derived from `../debugger` where useful, but MUST be integrated into Studio-native session/workspace boundaries.
 For this wave:
 - `Play/Stop` remains the owner of under-the-hood connect/attach/disconnect behavior;
 - `DebugWorkspace` is the native surface that reflects and hosts that session;
 - the underlying session state MUST exist outside the visual workspace lifecycle so the Studio shell can react to it globally.
 ### 4. Logging
 The `DebugWorkspace` MUST be the merged sink destination for:
 - `build` logs,
 - pack-validation logs,
 - `pack` logs,
 - runtime stdout/stderr.
 Rules:
 - build and pack keep ownership of their own log production;
 - shipper owns the aggregation of preparation logs for user-facing consumption;
 - the debugger destination consumes merged preparation output plus runtime logs;
 - the initial merged sink MAY be a simple console/list with visible source/origin labels;
 - source/origin labels MUST preserve at least `build`, `pack-validation`, `pack`, and `runtime`;
 - the merged sink does not need sophisticated structure in the first wave;
 - the Activity Feed MUST only carry summarized lifecycle signals.
 ### 5. Shared Session State
 The first-wave debugger integration MUST consume a shared session/service boundary that is not owned solely by the visual workspace.
 At minimum, that shared state MUST distinguish:
 - `idle`
 - `preparing`
 - `prepare_failed`
 - `connecting`
 - `running`
 - `runtime_failed`
 - `stopped`
 The `DebugWorkspace` consumes and reflects this state.
 ### 6. Integration Topology
 The integration topology for this wave MUST be selective migration into Studio.
 Rules:
 - no composite build or equivalent live technical linkage with `../debugger`;
 - no requirement to keep the standalone debugger as a parallel supported surface;
 - no wholesale copy by inertia;
 - selective code migration is allowed when concretely useful.
 The intended direction is:
 - Studio becomes the durable host,
 - `../debugger` is not extended further for this effort,
 - and the sibling project may be removed once Studio matures enough.
 ### 7. Native Studio Shape
 `DebugWorkspace` MUST obey native Studio workspace rules for:
 - lifecycle,
 - event-bus integration,
 - theming,
 - i18n,
 - navigation under the Studio shell.
 This decision does not authorize embedding the standalone debugger bootstrap as the main integration unit.
 ### 8. Explicit Exclusions
 This decision does not yet define:
 - profiler integration,
 - polished final debugger UX,
 - a rich manual connect/disconnect control surface,
 - a final structured logging model,
 - cancellation of preparation,
 - or any change from `run` to `debug` in the runtime command path.
 Those concerns remain future waves.
 ## Constraints
 1. This decision is subordinate to `DEC-0020` and `DEC-0021`.
 2. This decision defines the first wave of `DebugWorkspace`, not the complete debugger product.
 3. This decision assumes selective use of `../debugger` knowledge/details without creating a permanent dependency.
 4. This decision does not authorize profiler behavior.
 5. This decision does not authorize changing current `Play/Stop` ownership semantics.
 ## Revision Log
 - 2026-04-06: Initial draft from AGD-0009.
--- a/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md
+++ b/discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md
@ -1,96 +0,0 @@
 ---
 id: PLN-0041
 ticket: studio-play-stop-cartridge-flow
 title: Ordered Plan 1 - Shipper preparation foundation for build, pack, and manifest
 status: review
 created: 2026-04-06
 completed:
 tags: [studio, play-stop, shipper, build, pack, manifest]
 ---
 ## Objective
 Implement the Studio shipper service as the owner of preparation orchestration for `build -> pack-validation -> pack -> manifest`, with deterministic output in `build/`.
 ## Background
 `DEC-0020` establishes that preparation is Studio-owned, that `build/` is the runnable artifact root, and that shipper owns preparation orchestration plus aggregation of preparation logs.
 This is the first and foundational plan in the family. Later plans depend on its service boundary and result contracts.
 ## Scope
 ### Included
 - Introduce or reshape a Studio-owned shipper service boundary.
 - Execute `build`, pack validation, `pack`, and manifest generation in the required order.
 - Produce deterministic preparation results and failure boundaries.
 - Preserve preparation log channels `build`, `pack-validation`, and `pack`.
 ### Excluded
 - External runtime spawning.
 - Debugger workspace UI.
 - Runtime handshake.
 - Drift/freshness reuse logic.
 ## Execution Steps
 ### Step 1 - Define the shipper service contract
 **What:** Add a Studio-owned service/API for preparation that exposes ordered preparation, result status, and preparation-log output.
 **How:** Introduce dedicated types for preparation request/result and channel-aware preparation log entries. Keep the service independent from UI controls and workspaces.
 **File(s):** `prometeu-studio/src/main/java/p/studio/.../shipper/*` (new package), existing `ShipperWorkspace` call sites as adapters only.
 ### Step 2 - Implement ordered preparation
 **What:** Execute compiler build, pack validation, pack, and manifest generation through the shipper service.
 **How:** Reuse existing compiler and packer entrypoints. Enforce stop-on-first-failure. Do not introduce cancellation. Ensure pack validation blocks pack when needed.
 **File(s):** `prometeu-studio` service layer, packer integration call sites, manifest generation implementation.
 ### Step 3 - Materialize the deterministic build contract
 **What:** Ensure successful preparation leaves `build/program.pbx`, `build/assets.pa`, and `build/manifest.json` in the expected state.
 **How:** Keep compiler and packer domain ownership of their artifacts, but make manifest generation part of shipper success. Preserve the absence of a separate `cartridge/` root.
 **File(s):** shipper implementation, manifest-generation code, any preparation DTOs/results.
 ### Step 4 - Publish channel-preserving preparation output
 **What:** Aggregate preparation output for downstream consumption while preserving per-channel identity.
 **How:** Build a merged-but-structured stream that labels entries as `build`, `pack-validation`, or `pack`. Expose it as shipper-owned output rather than UI-owned state.
 **File(s):** shipper service/result/log types, adapters from compiler and packer logs.
 ## Test Requirements
 ### Unit Tests
 - Verify shipper enforces the exact order `build -> pack-validation -> pack -> manifest`.
 - Verify pack validation failure stops the flow before pack.
 - Verify manifest generation only happens after successful build and pack.
 - Verify aggregated preparation logs preserve the three required source channels.
 ### Integration Tests
 - Exercise a successful preparation flow against a real project fixture and assert expected files exist in `build/`.
 - Exercise build failure and assert pack and manifest are skipped.
 - Exercise pack-validation failure and assert pack and manifest are skipped.
 ### Manual Verification
 - Trigger shipper preparation on a real Studio project and confirm `build/` contains the expected artifacts.
 - Inspect emitted preparation logs and confirm channel labels remain visible.
 ## Acceptance Criteria
 - [ ] A Studio-owned shipper service exists and is the sole owner of preparation orchestration.
 - [ ] Preparation executes in the exact decision-ordered sequence.
 - [ ] Preparation stops on first failure and does not support cancellation in this wave.
 - [ ] Successful preparation leaves the required runnable files in `build/`.
 - [ ] Preparation output preserves `build`, `pack-validation`, and `pack` channel identity.
 ## Dependencies
 - Accepted `DEC-0020`.
 - Existing compiler `build` entrypoint.
 - Existing packer validation and pack entrypoints.
 ## Risks
 - Hidden coupling to the current `ShipperWorkspace` scratch path may leak UI assumptions into the service boundary.
 - Manifest generation may become entangled with runtime policy if not kept narrow.
 - Log aggregation may collapse source identity if implemented as raw text concatenation.
--- a/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md
+++ b/discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md
@ -1,91 +0,0 @@
 ---
 id: PLN-0042
 ticket: studio-play-stop-cartridge-flow
 title: Ordered Plan 2 - Shared execution session and merged log contracts
 status: review
 created: 2026-04-06
 completed:
 tags: [studio, play-stop, debugger, session, logs, state]
 ---
 ## Objective
 Define and implement the shared execution-session boundary that exists outside visual workspace lifecycle and carries state plus merged log contracts for preparation and runtime.
 ## Background
 `DEC-0021` and `DEC-0022` require a shared state machine and a merged log destination independent of the visual `DebugWorkspace`. `DEC-0020` requires shipper-owned preparation log aggregation.
 This plan is intentionally cross-cutting and must land before the final orchestration and workspace consumption plans.
 ## Scope
 ### Included
 - Shared session/service boundary outside the visual workspace.
 - Minimum shared state machine: `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, `stopped`.
 - Structured merged log-entry contract with visible source identity.
 - Adapters for shipper-owned preparation output and runtime output to feed the shared session.
 ### Excluded
 - Final debugger workspace UI.
 - Runtime process spawning details.
 - Full handshake implementation details.
 - Profiler behavior.
 ## Execution Steps
 ### Step 1 - Define shared state and session contracts
 **What:** Introduce shared types and services for execution-session state.
 **How:** Create a Studio-owned session/service API not tied to `Workspace` lifecycle. Add explicit transitions for the minimum required states.
 **File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent shared execution package.
 ### Step 2 - Define merged log-entry contracts
 **What:** Add a structured log-entry model for merged execution logs.
 **How:** Require at least `source`, `message`, `severity`, and ordering metadata such as timestamp/sequence. Preserve the source channels `build`, `pack-validation`, `pack`, and `runtime`.
 **File(s):** shared execution/debug model package, service interfaces, DTOs/events.
 ### Step 3 - Connect shipper output to the shared session
 **What:** Feed shipper-owned preparation output into the shared session boundary.
 **How:** Adapt the shipper result/log stream into session log entries and preparation state transitions without moving ownership away from shipper.
 **File(s):** shipper adapters, shared session service, orchestration glue.
 ### Step 4 - Connect runtime output to the shared session
 **What:** Reserve the runtime side of the merged stream and state transitions for later orchestration plans.
 **How:** Define append/update APIs now so later runtime plans can publish `connecting`, `running`, `runtime_failed`, and `stopped` without changing the contract shape.
 **File(s):** shared session/service types and tests.
 ## Test Requirements
 ### Unit Tests
 - Verify legal state transitions for the minimum state machine.
 - Verify merged log entries preserve source identity and ordering metadata.
 - Verify shipper output can be appended without collapsing channels.
 ### Integration Tests
 - Feed a simulated preparation success/failure sequence into the shared session and assert resulting state and log stream.
 - Verify the shared session survives workspace recreation or absence.
 ### Manual Verification
 - Inspect a development build and confirm execution state remains available even if the visual debug surface is not yet mounted.
 ## Acceptance Criteria
 - [ ] A shared execution-session service exists outside the visual workspace lifecycle.
 - [ ] The minimum state machine is explicitly implemented.
 - [ ] Merged log entries preserve source identity for `build`, `pack-validation`, `pack`, and `runtime`.
 - [ ] Shipper preparation output can flow into the shared session without changing shipper ownership.
 ## Dependencies
 - Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
 - `PLN-0041` shipper preparation foundation.
 ## Risks
 - State transitions may become duplicated between shell, workspace, and service if ownership is not kept strict.
 - Log models that are too thin will force churn once the debugger surface exists.
 - Overdesign here could slow down the simple first wave the decisions explicitly allow.
--- a/discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md
+++ b/discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md
@ -1,90 +0,0 @@
 ---
 id: PLN-0043
 ticket: studio-debugger-workspace-integration
 title: Ordered Plan 3 - First-wave DebugWorkspace registration and temporary execution surface
 status: review
 created: 2026-04-06
 completed:
 tags: [studio, debugger, workspace, logs, shell]
 ---
 ## Objective
 Register a native `DebugWorkspace` in Studio and provide a first-wave temporary execution surface that consumes shared session state and merged logs.
 ## Background
 `DEC-0022` requires a real native workspace, not an external launcher. `DEC-0021` requires `Play` to navigate toward the debugger destination at the start of execution.
 This plan intentionally keeps the UI crude and execution-focused.
 ## Scope
 ### Included
 - Register a concrete `DebugWorkspace` in the Studio shell.
 - Consume the shared session/service boundary from `PLN-0042`.
 - Render simple session state and a simple merged log sink with visible source labels.
 - Provide a temporary but native in-Studio execution destination.
 ### Excluded
 - Polished final debugger UX.
 - Rich manual connect/disconnect controls.
 - Profiler behavior.
 - Standalone debugger bootstrap embedding.
 ## Execution Steps
 ### Step 1 - Register the workspace in the shell
 **What:** Make `WorkspaceId.DEBUG` point to a real workspace implementation.
 **How:** Add and register a native `DebugWorkspace` that follows Studio workspace lifecycle and event-bus rules.
 **File(s):** `prometeu-studio/src/main/java/p/studio/window/MainView.java`, `prometeu-studio/src/main/java/p/studio/workspaces/.../DebugWorkspace.java` (new).
 ### Step 2 - Add first-wave session state presentation
 **What:** Surface the shared session states in the workspace.
 **How:** Render a simple status area or equivalent control showing at least `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, and `stopped`.
 **File(s):** `DebugWorkspace` controls and supporting view models/bindings.
 ### Step 3 - Add the temporary merged log sink
 **What:** Show merged execution logs in a simple native Studio surface.
 **How:** Use a list/console style control with visible source labels and lightweight severity treatment. Consume the shared session log stream from `PLN-0042`.
 **File(s):** `DebugWorkspace` controls, log pane/control package.
 ### Step 4 - Preserve native Studio shape
 **What:** Keep lifecycle, theming, i18n, and shell-navigation compliance.
 **How:** Avoid importing the standalone debugger host/bootstrap. Use only Studio-native workspace composition.
 **File(s):** workspace implementation, i18n keys, theme/style files as needed.
 ## Test Requirements
 ### Unit Tests
 - Verify the workspace can consume session state updates and reflect them.
 - Verify merged log entries render with visible source identity.
 ### Integration Tests
 - Mount the workspace in a shell test and confirm it registers without throwing.
 - Feed synthetic session/log events and confirm the workspace updates without owning the underlying state.
 ### Manual Verification
 - Open the `Debug` workspace from the Studio shell.
 - Confirm session states and merged logs are visible in a simple but usable surface.
 ## Acceptance Criteria
 - [ ] `WorkspaceId.DEBUG` resolves to a real native workspace.
 - [ ] The workspace shows shared execution state.
 - [ ] The workspace shows merged logs with visible source identity.
 - [ ] The implementation stays within native Studio workspace boundaries.
 ## Dependencies
 - Accepted `DEC-0022`.
 - `PLN-0042` shared execution session and log contracts.
 ## Risks
 - The first-wave UI may accidentally hardcode temporary choices that later feel permanent.
 - Workspace ownership may drift into session ownership if bindings are not kept one-way.
--- a/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md
+++ b/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md
@ -1,80 +0,0 @@
 ---
 id: PLN-0044
 ticket: studio-debugger-workspace-integration
 title: Ordered Plan 4 - Runtime handshake integration from selective debugger knowledge
 status: review
 created: 2026-04-06
 completed:
 tags: [studio, debugger, runtime, handshake, remote-connection]
 ---
 ## Objective
 Integrate the minimum runtime/debug-session handshake needed for the current flow, using selective knowledge from `../debugger` without creating a project linkage.
 ## Background
 `DEC-0022` allows handshake details to be derived from `../debugger` while keeping Studio-native boundaries. `DEC-0021` reserves `debug` for the future but requires enough session behavior to support the current `run` flow and debugger destination.
 ## Scope
 ### Included
 - Study and selectively port the useful runtime-handshake behavior from `../debugger`.
 - Implement Studio-native handshake/session integration code.
 - Publish handshake state into the shared execution session boundary.
 ### Excluded
 - Composite build or live dependency on `../debugger`.
 - Full debugger feature parity.
 - Profiler behavior.
 - Manual rich connection-control UI.
 ## Execution Steps
 ### Step 1 - Identify the useful handshake slice
 **What:** Isolate the exact handshake/protocol/session behavior needed from `../debugger`.
 **How:** Read the sibling repo and extract only the minimum details necessary for the current run/debug-session handshake. Do not mirror the standalone app structure.
 **File(s):** Study `../debugger`; implement only Studio-native targets under `prometeu-studio`.
 ### Step 2 - Implement a Studio-native handshake service
 **What:** Add handshake/session integration code in Studio-native shape.
 **How:** Create a dedicated service or adapter layer that can publish `connecting`, `connected`, and failure information into the shared execution session.
 **File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent service package.
 ### Step 3 - Connect the handshake to the shared session
 **What:** Make handshake outcomes visible to shell and workspace consumers.
 **How:** Feed successful and failed handshake events into the session state machine and merged logs without requiring the visual workspace to own the protocol.
 **File(s):** shared session service, handshake adapter/service, tests.
 ## Test Requirements
 ### Unit Tests
 - Verify handshake success updates the shared session to the expected connected/running path.
 - Verify handshake failure updates the shared session to a failure state and emits visible log output.
 ### Integration Tests
 - Simulate the runtime handshake sequence and confirm session consumers receive the expected state transitions.
 ### Manual Verification
 - Run a development build and confirm the session reflects connecting/connected/failed without needing the standalone debugger app.
 ## Acceptance Criteria
 - [ ] Studio contains a native handshake/service implementation shaped for the current flow.
 - [ ] No technical linkage to `../debugger` is introduced.
 - [ ] Shared session state reflects handshake success and failure.
 - [ ] The implementation selectively reuses useful debugger knowledge without wholesale copying.
 ## Dependencies
 - Accepted `DEC-0021` and `DEC-0022`.
 - `PLN-0042` shared execution session and log contracts.
 - `PLN-0043` first-wave debug workspace surface.
 ## Risks
 - Porting too much from `../debugger` could drag standalone assumptions into Studio.
 - Porting too little may leave the current flow without a stable enough handshake.
--- a/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md
+++ b/discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md
@ -1,108 +0,0 @@
 ---
 id: PLN-0045
 ticket: studio-play-stop-cartridge-flow
 title: Ordered Plan 5 - End-to-end Play/Stop execution flow through shipper and DebugWorkspace
 status: review
 created: 2026-04-06
 completed:
 tags: [studio, play-stop, runtime, debugger, shipper, shell]
 ---
 ## Objective
 Wire the full first-wave `Play/Stop` flow end-to-end through shipper preparation, shared execution session state, native debugger destination, external runtime execution, and direct-stop behavior.
 ## Background
 `DEC-0020`, `DEC-0021`, and `DEC-0022` together now define the intended first-wave behavior. This plan is intentionally last because it integrates the service, session, workspace, and handshake pieces established in the earlier plans.
 ## Scope
 ### Included
 - `Play` navigation to the debugger destination at flow start.
 - Invocation of shipper preparation.
 - Propagation of preparation failure into the shared session and debugger destination.
 - External runtime spawn `"<runtimePath>" run build` in project root.
 - Runtime output publication into shared session and debugger destination.
 - Direct runtime kill on `Stop`.
 ### Excluded
 - Preparation cancellation.
 - Drift/freshness reuse.
 - `debug` command path.
 - Profiler behavior.
 ## Execution Steps
 ### Step 1 - Wire `Play` into the shared execution destination
 **What:** Make pressing `Play` move the user into the debugger destination immediately.
 **How:** Navigate to `DebugWorkspace` at the beginning of the flow, before runtime spawn, so preparation failures also appear there.
 **File(s):** shell/play controls, workspace selection/navigation logic, `MainView` or equivalent shell coordinator code.
 ### Step 2 - Invoke shipper preparation and reflect preparation state
 **What:** Start the shipper service and reflect `preparing` / `prepare_failed`.
 **How:** Transition the shared execution session into `preparing`, consume shipper aggregated preparation output, and stop on first preparation failure.
 **File(s):** play orchestration layer, shared session service adapters, shell controls.
 ### Step 3 - Spawn the external runtime process
 **What:** Execute the exact current-wave runtime command.
 **How:** Use `ProjectLocalStudioSetup.prometeuRuntimePath` and spawn `"<runtimePath>" run build` with `cwd = project root`. Transition through `connecting`, then `running`, or `runtime_failed` on failure.
 **File(s):** runtime orchestration service, shell controls, process-management code.
 ### Step 4 - Wire `Stop` semantics
 **What:** Kill the active runtime process directly.
 **How:** Keep one active process handle. Ignore repeated `Play` while active. During `preparing`, `Stop` remains a no-op because cancellation is out of scope.
 **File(s):** play/stop controls, runtime orchestration service, shared session service.
 ### Step 5 - Close the end-to-end loop
 **What:** Ensure all logs and state transitions reach the debugger destination consistently.
 **How:** Route shipper preparation output plus runtime output into the shared session/log sink. Keep the Activity Feed summary-only.
 **File(s):** orchestration layer, shared session adapters, workspace bindings.
 ## Test Requirements
 ### Unit Tests
 - Verify `Play` transitions the session to `preparing` before runtime spawn.
 - Verify repeated `Play` is ignored while runtime is active.
 - Verify `Stop` kills the active runtime process and does nothing during `preparing`.
 - Verify spawn failures become runtime preflight failures.
 ### Integration Tests
 - End-to-end success path: `Play` opens debugger destination, prepares successfully, spawns runtime, and exposes logs/state.
 - Build failure path: debugger destination opens and shows preparation failure without runtime spawn.
 - Pack-validation failure path: debugger destination opens and shows preparation failure without runtime spawn.
 - Runtime spawn failure path: debugger destination opens and shows runtime failure after successful preparation.
 ### Manual Verification
 - Press `Play` in Studio and confirm the shell navigates to `Debug`.
 - Confirm preparation logs appear before runtime output.
 - Confirm `Stop` kills a running runtime process.
 - Confirm repeated `Play` while running is ignored.
 ## Acceptance Criteria
 - [ ] `Play` opens the debugger destination immediately.
 - [ ] The flow executes shipper preparation before runtime spawn.
 - [ ] Preparation failures remain visible in the debugger destination.
 - [ ] Runtime spawn uses the exact command and working-directory contract from `DEC-0021`.
 - [ ] `Stop` kills only the active runtime process and does not cancel preparation.
 - [ ] The debugger destination shows merged preparation and runtime logs end-to-end.
 ## Dependencies
 - Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
 - `PLN-0041` shipper preparation foundation.
 - `PLN-0042` shared execution session and log contracts.
 - `PLN-0043` first-wave `DebugWorkspace` surface.
 - `PLN-0044` runtime handshake selective integration.
 ## Risks
 - End-to-end orchestration may reintroduce ownership confusion if shell, shipper, and debugger boundaries are not kept strict.
 - UI timing issues may surface when navigating to the debugger before preparation output begins.
 - Process-lifecycle bugs can leave the shell believing a runtime is still active after failure.