<!-- source: openspec/current/agents/maestro.md -->

---
title: Maestro
status: proposed
owner: pavel
audience: [pavel, ai, engineer]
tldr: Capability spec for the Maestro agent — routes work between agents, audits cross-agent state, surfaces decision points to Pavel. Substrate-pending.
---
# Maestro

> The coordinator. Routes work between agents, audits cross-agent state, surfaces decision points to Pavel.

---

## Status

**Substrate-pending — spec authored ahead of runtime (applied 2026-05-09 from change `add-agents-specs`).** Maestro is one of six agents declared in [`agents-overview.md`](../agents-overview.md); this is its canonical capability spec. The runtime substrate at `packages/muse/src/modes/maestro/` does not exist yet — Maestro is implemented as a fifth Muse mode (per `add-philosophy-foundation § Decisions captured` D-7) and lands in a follow-up code change after this spec merges. Storage substrate (`orchestra_journal` Supabase table, `_audit/` directory layout) is provisioned in Layer 2 by `add-knowledge-layout`. Until both ship, this spec is the contract; downstream code adapts to it.

The two cross-reference amendments tasked by [`agents-overview.md § Forward references — per-agent specs`](../agents-overview.md) — list Maestro as the fifth Muse mode in `muse.md`, add a Maestro cross-reference to `forge/README.md` — are deferred to a sibling change `amend-muse-forge-for-maestro` per `add-agents-specs/design.md` D-6.

---

## Function

Maestro coordinates the orchestra. Three responsibilities:

1. **Route work between agents.** Given a unit of work (Linear issue, Pavel-direct request, audit observation), Maestro decides which agent owns the work and hands it off. Routing decisions are recorded as append-only entries in the orchestra journal so the audit trail is preserved.
2. **Audit cross-agent state.** Maestro reads the orchestra journal and `agent_status` to detect drift — agents stuck on work that no longer matches their declared scope, work that crosses agent boundaries, decisions that have been made implicitly without being recorded. Audit observations are journal entries; Maestro does not act on them directly, it surfaces them.
3. **Surface decision points to Pavel.** When state is ambiguous (the routing target is unclear, two agents claim or disclaim ownership, scope creeps across boundaries), Maestro stops and surfaces the decision to Pavel rather than choosing silently.

Maestro is a router and an auditor, not an author. Explicit non-responsibilities:

- **Not authoring specifications.** Spec authoring is Muse Architect's discipline (see [`muse.md § Architect mode (v1)`](../muse.md)).
- **Not researching the world.** World research — tech beats, regional reports, society reads — is Atlas's discipline (Phase B; see [`agents-overview.md § Roster`](../agents-overview.md)).
- **Not producing market voice.** Drafts and campaigns are Echo's discipline (Phase B).
- **Not managing finance.** Cost ledgers, P&L, pricing rubrics are Pulse's discipline (Phase B).
- **Not writing code.** Code authorship and PR creation are Forge's discipline (see [`forge/README.md`](../forge/README.md)).

The non-responsibility list is load-bearing. Maestro's risk surface — privilege escalation, decision laundering — shrinks when its scope is bounded by negation. A reader who finds Maestro doing one of the listed non-responsibilities is finding a regression.

Maestro reads the workflow timeline and advances pieces per [`workflow.md § 4 Maestro control loop`](../workflow.md). The routing function is bound to the timeline contract; routing decisions cite the timeline stage as the work-item key.

---

## Runtime class

**Muse mode** at `packages/muse/src/modes/maestro/` — the fifth mode of `packages/muse/`, peer to Architect / Builder / Scout / Canvas. Per `add-philosophy-foundation § Decisions captured` D-7 (and the forward dependency flagged in [`agents-overview.md § Maestro as fifth Muse mode (forward dependency)`](../agents-overview.md)).

Implication of the Muse-mode runtime class:

- **Inherits Muse infrastructure.** Tool loop, cost guards, persona system, model selection, instruction-context resolution, streaming runtime — all reused from `packages/muse/src/orchestration/run_with_tools.ts` and the surrounding shared modules. Maestro does not reimplement these; it ships as a system-prompt + tool-permission-set + system-prompt-augmentation that loads into the existing Muse runtime.
- **No standalone package.** Maestro does not become `packages/maestro/`. The mode-of-Muse pattern keeps cross-cutting concerns (cost accounting, tool registry, persona priorities) in one place.
- **Invocation surface is Muse-shaped.** Maestro is invoked through the same paths that invoke Architect today — Studio canvas turn (`runMuseWithTools`), Forge subprocess (when Forge needs routing context), or future headless paths (`runMuseHeadless`). No new runtime entry point.

Substrate is **pending**. The directory `packages/muse/src/modes/maestro/` does not exist on disk in this change. Spec ships first; the mode implementation lands in a separate code change once this spec is reviewed and merged. The forward-dependency framing in [`agents-overview.md`](../agents-overview.md) is deliberate — until both spec and mode exist, Maestro is concept; once both ship, Maestro is operational.

---

## Model binding

Inline declaration for Phase A. When `_methodology/tools/agent-model-mapping.md` lands (separate Layer 0.5 change `add-tools-methodology`), this section becomes a forward-reference to the methodology row.

| Default model | Fallback chain | Reasoning |
|---|---|---|
| `claude-opus-4-8` | `claude-sonnet-4-6` | Maestro's failure cascades across the orchestra (bottleneck cascade — see § Risk matrix). The highest-tier model is required. The Sonnet fallback applies only on availability degradation (Anthropic API rate-limit / quota exhaustion), not as a cost-conscious downgrade — Maestro never falls back for budget reasons, only for rate-limit recovery. |

The binding is read by the Muse mode runtime (when `packages/muse/src/modes/maestro/` ships) via `MODELS.opus` / `MODELS.sonnet` from the existing Forge / Muse pricing constants (see [`forge/README.md § Anthropic API integration`](../forge/README.md)). Specifying a third-party identifier requires extending the model-pricing table (per `forge/README.md § Known gaps #6`, closed by RAP-166).

---

## Access scope

Read / write surface declared as an **explicit allowlist**. Anything not declared is denied. The runtime substrate (when it ships) reads this section and builds the permission boundary from it; implicit access ("all tables in public schema", "any file under repo root") is not permitted.

### DB tables

| Table | Operation | Notes |
|---|---|---|
| `orchestra_journal` | write (append-only) | Authoritative storage for routing decisions, handoff records, audit observations. Schema lands with Layer 2 `add-knowledge-layout`. |
| `orchestra_journal` | read | Replays state for routing decisions; queries by agent / time-range / event-type. |
| `agent_status` | read | Reads peer agents' status entries for routing context (current work item, declared scope, last-completion timestamp). |

In-place edits to `orchestra_journal` are not permitted. Corrections are themselves append-only entries that reference the corrected entry by id.

### File paths

| Path | Operation | Notes |
|---|---|---|
| `openspec/current/**` | read | Routing decisions cite canonical specs (capability spec for the receiving agent, related capabilities). |
| `openspec/_methodology/**` | read | Routing decisions cite operating principles (`studio-charter.md` today; further methodology documents as the corpus grows). |
| `openspec/archive/**` | read | Historical context — past changes that informed the current routing decision. |
| `openspec/changes/**` | read | In-flight change folders — Maestro reads to understand what work is currently scoped. |
| `~/.maestro/journal/<YYYY-MM-DD>.md` | write (append-only) | Filesystem rationale log — secondary mirror of `orchestra_journal` writes in human-readable Markdown. Reviewable without DB access. **Not** canonical — DB is the source of truth. Pattern parallels [`forge/README.md § Lessons-learned mechanism`](../forge/README.md) (`~/.forge/lessons-learned.md`). |

Maestro does **not** write source files, OpenSpec specs, OpenSpec change folders, or any artifact owned by another agent. Routing means handing work to the agent that owns the artifact; Maestro never bypasses the owner.

### External APIs

| API | Mode | Notes |
|---|---|---|
| Anthropic | model calls | Standard Muse pattern — direct `fetch` per [`forge/README.md § Anthropic API integration`](../forge/README.md). |
| Linear | read | Routing context: reads issue state, body, comments, labels, assignees. Used by `linear_get_issue` / `linear_list_issues` / `linear_search` tools. |
| Linear | — (no write) | Maestro does not comment on issues, transition states, or create issues. Forge owns Linear writes per [`forge/README.md § Linear API integration`](../forge/README.md). |
| GitHub | — (no read or write) | Maestro does not read repo metadata, branches, PRs. Forge owns GitHub access. |

### Tool permissions

Allowlist (Maestro is permitted to invoke):

- `read_file`
- `list_directory`
- `web_search`
- `linear_get_issue`
- `linear_list_issues`
- `linear_search`
- `linear_list_cycles`
- `read_openspec`
- `read_archive`

Denylist (Maestro is **not** permitted to invoke; future tool additions are denied by default unless explicitly added to the allowlist):

- `write_file`
- `edit_file`
- `bash`
- `write_mirror_field`
- `update_proposal` / `update_design` / `update_tasks` (Architect emit tools)
- Any future write tool

The allowlist matches the read-only profile declared in `agents-overview.md`. Maestro is not the authoring agent for any artifact.

---

## Communication patterns

Two-axis matrix. Communication graph in [`agents-overview.md § Communication graph`](../agents-overview.md) is the source of truth at orchestra level; this section restates Maestro's row with mode annotations.

### Inbound

| From | Mode | Examples |
|---|---|---|
| Pavel | sync request | "What's blocked on the orchestra right now?", "Route this work — Linear says assignee unclear", "Audit the muse-forge handoff for RAP-N" |
| Muse | async event (journal write) | Completion signals, handoff acknowledgements, status updates |
| Forge | async event (journal write) | Build outcomes, plan-acceptance signals, cancel events |
| Atlas (Phase B) | async event (journal write) | Beat completion, research deliverable announcements |
| Echo (Phase B) | async event (journal write) | Draft completion, review-gate observations |
| Pulse (Phase B) | async event (journal write) | Ledger-anchor decisions, cost surfaces |

### Outbound

| To | Mode | Examples |
|---|---|---|
| Pavel | decision surface (sync return) | Decision points requiring human judgment — boundary disputes, conflicting outputs, scope ambiguity, refusal cases |
| Muse | sync request | "Author the spec for this", "Audit this draft against `agents-overview.md`" |
| Forge | sync request | "Build from this approved spec", "Estimate this Linear issue" |
| Atlas (Phase B) | sync request | "Research this domain ahead of next Muse session" |
| Echo (Phase B) | sync request | "Draft a market-voice piece on this beat" |
| Pulse (Phase B) | sync request | "What's the cost anchor for this decision?" |

Phase A reality: only the **Muse ↔ Forge** edge is live in the orchestra (per [`agents-overview.md § Communication graph`](../agents-overview.md)). Maestro's outbound edges to Atlas / Echo / Pulse are forward-references — the contract is declared so those agents activate cleanly when Phase B ships.

The bilateral edge to Pavel is the only inbound sync edge. All other inbound traffic is async event / journal write. This is intentional: Maestro reads state, it does not block on agent responses. Routing decisions are computed from the journal snapshot at decision time, not from a live multi-agent rendezvous.

---

## Risk matrix

Five failure modes drawn from two taxonomies. Selection criteria: most-likely-to-manifest given Maestro's function (router + auditor) and runtime class (Muse mode). Tag identifies the originating taxonomy (`[Microsoft]` for single-agent failure modes per Microsoft Security Response Centre's AI failure-mode taxonomy; `[Cooperative AI]` for multi-agent failure modes per Cooperative AI Foundation's framework).

1. **`[Cooperative AI]` Bottleneck cascade.** Maestro is the single point of coordination across the orchestra. If Maestro hallucinates a routing decision, times out, or refuses to route, the entire chain stalls. Concrete example: Maestro routes spec-authoring work to Forge instead of Muse. Forge refuses (out of scope per [`forge/README.md`](../forge/README.md)). No fallback router exists. Work blocks until Pavel intervenes manually.

2. **`[Microsoft]` Privilege escalation.** Maestro reads broadly across the orchestra — `orchestra_journal`, `agent_status`, `openspec/current/**`, `openspec/_methodology/**`, `openspec/archive/**`, `openspec/changes/**`. A corrupted Maestro session could leak cross-agent context that the consuming caller is not authorised to see. Concrete example: Maestro's routing rationale cites an unfinished spec change in `openspec/changes/<slug>/`; the rationale is surfaced to a caller (e.g. via Linear comment) who should not see in-flight spec work.

3. **`[Cooperative AI]` Decision laundering.** Maestro routes work and surfaces decisions to Pavel. Risk: Pavel sees "Maestro decided X" when the underlying decision was Muse's (a passing comment in a draft proposal) or Forge's (implicit by tool refusal during build). Maestro becomes the attribution layer for decisions it did not actually make; the original decision-maker is obscured.

4. **`[Cooperative AI]` Memory poisoning.** Maestro depends on `orchestra_journal` accuracy. A corrupt entry — race condition on append, partial write, journal-replay logic bug — propagates as Maestro's view of state. Subsequent routing decisions are made from poisoned memory; the corruption compounds across sessions.

5. **`[Microsoft]` Refusal failure.** Maestro receives a routing request that does not cleanly map to any single agent — work crosses boundaries (Muse needs Forge feasibility input mid-spec), the request is ambiguous (Linear issue lacks a clear owner), or the routing target is in an unknown state (agent on long-running work, no completion signal). Failure mode: Maestro returns "cannot route" without surfacing why. Pavel does not get the decision point; the work silently stalls in the journal.

---

## Cross-cutting defenses

Each defense maps to one or more risks in § Risk matrix. Defenses are runtime contracts; enforcement code lands when the Maestro mode runtime ships in `packages/muse/src/modes/maestro/`.

| Defense | Applies to | Mechanism |
|---|---|---|
| **HitL gate on routing decisions** | Bottleneck cascade, Refusal failure | Maestro proposes a routing decision; Pavel approves or redirects before cross-agent handoff. The gate is mandatory for non-trivial routes; trivial routes (clear single owner, no boundary ambiguity) auto-proceed but write the rationale to the journal. |
| **Allowlist-only access scope** | Privilege escalation | Only the tools and paths declared in § Access scope are reachable. Future tool additions are denied by default. The Muse runtime tool registry filter (`getToolsForAnthropicAPI(role, projectSlug?)` in `packages/muse/src/tools/`) enforces the allowlist at the Anthropic API boundary — tools not on the list are not visible to the model. |
| **Append-only journal with attribution** | Decision laundering, Memory poisoning | Every journal entry carries an originating agent ID, a session ID, a content hash, and a monotonic sequence number. Decision-laundering risk shrinks because the journal records the *original* decision-maker, not just the routing outcome. Memory-poisoning risk shrinks because corruption is detectable via content-hash mismatch on replay. |
| **Idempotent routing** | Memory poisoning, Bottleneck cascade | Same journal-state input produces the same routing output. Replay-safe — if Maestro is restarted mid-decision, the next run reaches the same conclusion. The routing function is pure: `route(journalSnapshot, request) → decision`; no hidden state. |
| **Cost guard per session** | Bottleneck cascade (cost-driven failure) | Maestro session inherits Muse cost-guard primitives ([`muse.md § Cost guard`](../muse.md), [`forge/README.md § Cost tracking`](../forge/README.md)). Per-session budget cap; pre-flight estimation; warn-on-large-call. Excess routes to Pavel as a "extend session?" decision point rather than silent termination. |
| **Filesystem rationale log** | Decision laundering, Privilege escalation | Every routing decision writes a Markdown entry to `~/.maestro/journal/<YYYY-MM-DD>.md` with the rationale, the originating decision-maker (per attribution), the cited specs, the affected agents. Reviewable without DB access. Mirrors the journal but in human-readable form. |
| **Plan-mode for routing** | Refusal failure, Decision laundering | Maestro plans the route before executing the handoff. Plan output: intended agent, intended work boundary, intended journal entry shape, expected completion signal. Pavel reviews the plan when the HitL gate fires; otherwise the plan is recorded in the journal alongside the execution. Plan-mode parallels [`forge/README.md § Builder mode`](../forge/README.md) checkpoint pattern. |

The defenses are interdependent. HitL gate depends on plan-mode (Pavel needs a plan to approve). Append-only journal depends on idempotent routing (replay must reach the same decision). Allowlist-only access scope depends on Muse's tool registry filter (the runtime mechanism). Removing one defense weakens several risks; the matrix is not modular.

---

## Related capabilities

- [`agents-overview.md`](../agents-overview.md) — orchestra-level facts (roster, communication graph, storage ownership, phase ordering); source of truth at orchestra layer; this spec is the next layer of detail for Maestro specifically.
- [`muse.md`](../muse.md) — Muse capability spec. Maestro is implemented as the fifth mode of `packages/muse/` (per `add-philosophy-foundation` D-7); the muse.md amendment listing Maestro as a fifth mode lands in the sibling change `amend-muse-forge-for-maestro`.
- [`forge/README.md`](../forge/README.md) — Forge capability spec. Maestro routes engineering work to Forge; the forge/README.md cross-reference for Maestro lands in the same sibling change `amend-muse-forge-for-maestro`.
- [`platform.md`](../platform.md) — overall platform context; locates the agent orchestra inside the studio's capability map.
- [`../_methodology/studio-charter.md`](../../_methodology/studio-charter.md) — operating principles; § Agents and philosophy carries the studio-side framing for the orchestra.
- `_audit/` directory layout — Maestro's storage ownership per [`agents-overview.md § Storage ownership`](../agents-overview.md); ships in Layer 2 `add-knowledge-layout`.
- `packages/muse/src/modes/maestro/` — runtime substrate; ships in a follow-up code change after this spec merges.
- [`../../archive/2026-05-12-add-maestro-cli/design.md`](../../archive/2026-05-12-add-maestro-cli/design.md) — CLI invocation specifics: argv dispatch architecture, binary location (`packages/muse/bin/maestro/`), command list (`route`, `audit`, `doctor`), `--json`/exit-code wiring, and phase breakdown. Read this before extending or debugging the `maestro` binary.

---

## Model binding superseded by methodology doc (applied 2026-05-09 from change `add-tools-methodology`)

The inline [`## Model binding`](#model-binding) table earlier in this spec is **superseded** by [`openspec/_methodology/tools/agent-model-mapping.md § Per-agent default + fallback`](../../_methodology/tools/agent-model-mapping.md). A reader resolving Maestro's current model binding follows the link to the methodology row labelled "Maestro".

The original inline section stays as historical anchor (per `openspec/AGENTS.md` append-at-end convention — earlier prose is preserved; dated sections supersede). Phase A authored Maestro's model binding inline because the methodology doc did not yet exist; this dated section closes that loop.

Future per-agent capability specs (Phase B `agents/atlas.md` / `agents/echo.md` / `agents/pulse.md`) forward-ref the methodology doc from day one — they do not replicate the inline pattern. This Maestro amendment is the only retroactive cross-reference required.

This amendment closes the explicit forward-reference flagged in [`openspec/archive/2026-05-09-add-agents-specs/design.md § D-2`](../../archive/2026-05-09-add-agents-specs/design.md) ("When `add-tools-methodology` lands, this section becomes a forward-reference instead of an inline declaration").

---

## MVP CLI — deterministic telemetry commands (applied 2026-05-12 from change `bootstrap-cli-orchestra-mvp` Phase 3)

Phase 3 of `bootstrap-cli-orchestra-mvp` ships two deterministic CLI commands in `packages/muse/bin/maestro/commands/`:

### `maestro lineage <linear-id>`

Reads `~/.rapoport/events/YYYY-MM-DD.jsonl` (the append-only event log written by Forge and Muse via `@rapoport-studio/cli-core/events`), filters by `linearId`, and prints a chronological trace of all events tagged to that Linear issue.

```
maestro lineage RAP-456
maestro lineage RAP-456 --since 7d
maestro lineage RAP-456 --json
```

Output (TTY): timestamp, kind, cli, payload summary per event; totals row (model calls, total cost USD, draft→PR time in minutes).

Output (`--json`): `{ linearId, events: [...], totals: { modelCalls, costUSD, tokensIn, tokensOut, draftToPrMs } }`.

### `maestro metrics [--since 7d]`

Reads all events in the given time window and emits an aggregated summary:

```
maestro metrics
maestro metrics --since 30d
maestro metrics --json
```

Output (TTY): ideas drafted, PRs opened, total model spend, avg cost per idea, avg draft→PR time, failed builds, by-kind breakdown.

Output (`--json`): `{ since, until, totalEvents, totalCostUSD, byKind, ideasDrafted, prsOpened, failedBuilds, avgCostPerIdea, avgDraftToPrMs }`.

### Event source

Both commands read from `~/.rapoport/events/YYYY-MM-DD.jsonl`. This path is the canonical event log per `bootstrap-cli-orchestra-mvp/design.md § Event schema`. Neither command writes events or requires Anthropic API access — Maestro remains deterministic in MVP.

### Implementation note

The MVP commands are located in `packages/muse/bin/maestro/commands/` (not a separate `packages/maestro/` package). The existing `packages/muse/bin/maestro/` CLI scaffold (built in `add-maestro-cli`) is reused and extended with two new command modules. A standalone `packages/maestro/` package is deferred to v2 per `bootstrap-cli-orchestra-mvp/tasks.md § Phase 3`.

---

## Operational (v1.0) — runtime activated (applied 2026-05-20 from change `add-maestro-runtime-mvp`)

The [`## Status`](#status) line declaring "**Substrate-pending — spec authored ahead of runtime**" is **superseded** by this dated section. As of 2026-05-20, Maestro v1.0 is operational:

- `runMuseHeadlessMaestro` at `packages/muse/src/modes/maestro/headless.ts` is fully wired (Anthropic + Linear + best-effort Supabase). `maestro route <issue-key>` produces a real `routing_plan` row in `orchestra_journal` end-to-end.
- The validator `route()` at `packages/muse/src/modes/maestro/route.ts:57` enforces four invariants (`invalid_target` / `agent_claimed` / `stale_snapshot` / `agent_idle_required`) on every LLM-emitted `RoutingPlan` before any handoff.
- Cost cap plumbing — `MAESTRO_SESSION_CAP_USD` env override > `~/.studio/config.json#maestro.cost_cap_usd_per_session` > `$5.00` default. Cap breach raises `cost guard refused` (exit code 3 `COST_GUARD_REFUSED`).
- Forge emits `handoff_ack` (gated on `MAESTRO_HANDOFF_SESSION_ID` env) + `build_complete` (after PR opens) to `orchestra_journal` from `packages/forge/src/core/forge-events.ts:safeEmitOrchestraJournal`.
- Architect emits `spec_promoted` to `orchestra_journal` from `apps/studio/src/app/(auth-walled)/(canvas)/spec/[id]/turn/route.ts` after a successful triplet canvas-files UPSERT.
- 12-row risk register published at [`openspec/_methodology/orchestra-risk-register.md`](../../_methodology/orchestra-risk-register.md) — R1..R12 with MVP mitigations mapped to runtime defenses.
- Smoke test asset at `packages/forge/scripts/journal-smoke.ts` (invokable via `pnpm --filter @rapoport-studio/forge journal-smoke`) verifies the write → read → hash-roundtrip path against the live Supabase project.

**Out of v1.0 scope, tracked for follow-up changes:**

- `maestro audit` command body — deferred to `add-maestro-audit-pass`. The `audit` and `doctor` binaries from `archive/2026-05-12-add-maestro-cli` are present but their command bodies remain stubs.
- HitL gate on routing decisions — deferred to `add-maestro-hitl-gate`. v1.0 surfaces ambiguity to stdout via [`workflow.md § 4.4 Step 3 — Surface`](../workflow.md) format but does not formally gate handoff on Pavel approval.
- Langfuse self-host observability — deferred to `add-langfuse-self-host` per `D-MAEST-OBS`.
- Linear webhook trigger (auto-invoke from issue events) — deferred to `add-maestro-linear-webhook`.
- Lessons-learned writeback — deferred to `add-maestro-lessons-writeback`.
- `_audit/` directory layout — deferred to `add-knowledge-layout` (Layer 2).
- Phase B agents (Atlas / Echo / Pulse) — `agent_status.agent_id` enum reserves slots but the agents are not yet implemented.

The implementation landed across eight PRs over 2026-05-20:

| Phase | PR | Scope |
|---|---|---|
| Scaffold | #1530 | OpenSpec change triplet |
| P0 — Reconcile | #1534 | Triplet amended to RAP-185 schema reality |
| P5 — Risk register | #1535 | 12 R-N entries published |
| P4 — `cli-core/orchestra` | #1539 | Generic `insertJournalEntry` helper |
| P1+P2+P3 — MVP-flip | #1542 | `runMuseHeadlessMaestro` + path + cost cap |
| P6 — Forge emit | #1543 | `handoff_ack` + `build_complete` |
| P7 — Architect emit | #1546 | `spec_promoted` |
| P8 — Smoke script | #1548 | Roundtrip verifier |

## FS-mirror path superseded (applied 2026-05-20 from change `add-maestro-runtime-mvp`)

The row in [`## Access scope > File paths`](#file-paths) declaring `~/.maestro/journal/<YYYY-MM-DD>.md` is **superseded** by `~/.studio/maestro/journal/<YYYY-MM-DD>.md` (honours `STUDIO_HOME` env override).

Rationale: the archived `add-maestro-cli/design.md § D-2` chose `~/.studio/maestro/` for all Maestro CLI state (config, locks, cache, logs); the journal mirror moves under the same prefix to keep one root path. Single-prefix discipline simplifies operator mental model and matches the `cli-standards.md § 4` layout.

The original `~/.maestro/journal/` literal in line 92 is preserved as historical anchor per the openspec append-at-end convention; the FS writer implementation at `packages/muse/src/modes/maestro/journal.ts` resolves the new path as its default.
