<!-- source: openspec/current/workflow.md -->

---
title: Workflow
status: stable
owner: pavel
audience: [pavel, ai, engineer]
tldr: The eleven-stage operating timeline for all work at the studio — every change moves from raw idea to live release along this timeline.
---
# Workflow

> The eleven-stage operating timeline for all work at Rapoport Studio. Every piece of work — internal infrastructure, client deliverable, AI research — follows this directed timeline from raw idea to live release. Maestro mode (within Muse) is the workflow controller; Forge executes stages 4–7; specialists and the principal participate at defined delegation levels.
>
> **Consumers:** Maestro AI controller, Forge CLI (stages 4–7), Pavel (principal), Specialist network.
> **Amendment pattern:** `change-workflow-<aspect>` for timeline-shape amendments; `add-workflow-stage-<name>` for new stages. See § 7 Evolution policy.

---

## 1. Vision

### What the workflow is and why it exists

Rapoport Studio runs on a single operating thesis: **specs precede code**. Every meaningful change — a new capability, a revised design, a client deliverable — passes through a declared proposal before a line of code is written. This is Spec-Driven Development (SDD): the discipline that makes an AI-first studio legible to its principal, its specialist network, and to itself.

The workflow described in this document is the **operational form** of that thesis. It translates "specs first" into a concrete directed timeline: twelve named states, eleven advance transitions, and a well-defined owner and validation gate at every transition. The timeline answers the question that every participant in every engagement always needs to answer: *where is this piece of work right now, and what has to happen before it moves forward?*

Without a declared timeline, AI-augmented development develops characteristic failure patterns: work regresses silently (a spec is rewritten after the code contradicts it), decisions get laundered (an agent makes a scope call that should have been the principal's), and bottlenecks become invisible until they become crises. The eleven-stage timeline is the instrument that makes these failure modes detectable before they compound.

This document is a **capability spec**, not a methodology guide. It is consumed by code: the Forge conductor implements against stages 4–7, the Maestro mode runtime implements against all eleven, and the future `/control/workflow` studio UI renders against the metrics defined in § 3. Changes to this document go through dedicated change proposals (slug pattern `change-workflow-*`) per the amendment policy in § 7.

### The SDD thesis

The four invariants of Spec-Driven Development as practiced at Rapoport Studio:

1. **Proposal first.** Every change has `proposal.md` + `design.md` + `tasks.md` before any implementation artifact is created. The proposal answers *why* and *what changes*; the design answers *how*; the tasks define the executable unit. This triple is the minimum viable specification.

2. **Stage gates are blocking conditions, not suggestions.** Work does not advance from Stage N to Stage N+1 unless the validation gate at Stage N has passed. A gate is not a metric — it is a precondition for advance. Gates block; metrics observe. The distinction is not cosmetic; conflating them produces "metrics that block work," which makes observability frameworks toxic.

3. **Owner semantics are explicit.** Every stage declares who executes it and at what delegation level (§ 2 table). The delegation taxonomy (Author / Editor / Director / Orchestrator, per the Microsoft Worklab 2026 four-pattern model) answers whether a human must be in the loop on every action, on outcome only, or not at all. Ambiguous ownership is the primary cause of laundered decisions.

4. **The timeline is engagement-mode invariant.** Whether work is internal-studio, a Hybrid engagement, or a Full deliverables-only engagement (per `rapoport-studio-engagement.md § 4`), the twelve stage names and eleven transitions are the same. What varies is the **owner** column, not the stage list. The full per-engagement-mode owner table appears in § 5.

### The eleven stages as a directed timeline

Work enters at Stage 0 (Capture) and exits at Stage 11 (Release). The twelve states cluster into four phase-groupings — mnemonic labels that help readers orient, not runtime routing logic:

| Phase grouping | Stages | Character |
|---|---|---|
| **Discovery** | 0 Capture → 1 Frame → 2 Spec | Unstructured idea → approved problem statement |
| **Spec** | 3 Stage → 4 Plan | Linear work-items → execution plan cached by Forge |
| **Build** | 5 Build → 6 Verify → 7 Finalize → 8 Review | Code produced, gates run, PR created, human approved |
| **Ship** | 9 Merge → 10 Archive → 11 Release | PR merged, change folder archived, production updated |

Every transition has a named entry criterion and a named validation gate. A piece of work is in exactly one stage at any moment. Stages do not repeat in the forward direction (regression is re-entry at the last valid stage, not a backward step).

Per-stage detail — definition, entry, artifact, owner, delegation level, validation gate, failure modes, and recovery — is specified in § 2 below.

### Maestro as workflow controller

Maestro mode (within Muse) is the **timeline controller**: the agent that reads workflow state across all in-flight pieces of work, identifies candidates for advance or attention, surfaces decisions to Pavel, and records outcomes in the append-only orchestra journal.

Maestro runs a four-step loop (detailed in § 4):

1. **Read** — journal, agent status, Forge state, Canvas state, OpenSpec.
2. **Identify** — three candidate types in priority order: decision candidates (ambiguous routing, must surface to Pavel), drift candidates (stuck-stage signal fired, must flag), advance candidates (gate passed, ready to route).
3. **Surface** — decision candidates go to Pavel via HitL gate; drift candidates post journal entry tagged `drift`; advance candidates route to the next stage's owner.
4. **Record** — every outcome written to orchestra_journal (append-only) and filesystem audit log.

Maestro does not write code, does not merge PRs, and does not approve its own routing decisions when the target is ambiguous. It reads; it identifies; it surfaces; it records.

### Who this document is for

- **Maestro AI** — this spec is the contract your routing function implements against. Every advance decision cites a stage as the work-item key. Every drift signal maps to a stage entry in the § 2 table.
- **Forge CLI** — you are the executor for stages 4–7. `forge plan`, `forge build`, `forge build` post-steps (Verify + Finalize), and `forge review` map one-to-one to stages 4, 5, 6+7, and 8 respectively.
- **Pavel** — you are the principal. Author-level delegation stages (0-entry, 2-approval, 9-merge) require your decision. Director-level stages (4-plan-approval, 8-human-approval) require your sign-off on outcomes. You can override any Maestro routing decision.
- **Specialist network** — you participate at stages declared for your role in § 5. Your entry point is always a Linear sub-issue with a task-slug and a link to the change folder.

---

## 2. The eleven stages

### Overview table

| # | Stage | Phase | Primary artifact | Owner | Delegation level |
|---|---|---|---|---|---|
| 0 | Capture | Discovery | Draft Linear issue or raw note | Pavel | Orchestrator |
| 1 | Frame | Discovery | `proposal.md` + `design.md` + `tasks.md` (draft) | Muse Architect | Director |
| 2 | Spec | Discovery | Finalized change triple (reviewed) | Pavel | Author |
| 3 | Stage | Spec | Linear epic + sub-issues | Pavel + Muse | Editor |
| 4 | Plan | Spec | `~/.forge/plans/<key>.md` | Forge architect | Director |
| 5 | Build | Build | Worktree + branch | Forge builder | Director |
| 6 | Verify | Build | Gate run report + `BuildOutcome` | Forge orchestrator | Orchestrator |
| 7 | Finalize | Build | GitHub PR + commit on branch | Forge orchestrator | Orchestrator |
| 8 | Review | Build | PR review decision (human-approved) | AI reviewer + Pavel | Editor |
| 9 | Merge | Ship | Commit on `main` + branch deleted | Pavel | Author |
| 10 | Archive | Ship | `openspec/archive/<date>-<slug>/` + amended `current/*.md` | Pavel + Forge | Director |
| 11 | Release | Ship | Live deployment or published package version | GitHub Actions / Pavel | Orchestrator / Author |

---

### Stage 0 — Capture

**Definition.** Raw idea deposit. An observation, user request, bug report, or opportunity enters the system before any structure is applied. The stage does not filter; any idea may be captured. A captured idea is not a commitment.

**Entry.** Any channel: wizard intake form, voice memo, Telegram message from Pavel, Linear Inbox ticket from a client, `forge propose <slug>` invocation, or a note file added manually to `openspec/changes/<slug>/`. No prior approval required.

**Artifact.** An unstructured source artifact: either a draft Linear issue in Inbox state, or a raw note file in `openspec/changes/<slug>/` that has not yet been shaped into proposal/design/tasks form.

**Owner.** Pavel (primary decision-maker on what gets captured). Muse Architect mode assists on wizard-assisted intakes. See `muse.md § Architect mode` for the wizard-intake protocol.

**Delegation level.** Orchestrator — Pavel decides what enters; Muse assists intake but does not filter or discard ideas without Pavel's direction.

**Validation gate.** None. There is no gate on capture. An idea is captured the moment it is recorded in any of the input channels above.

**Failure modes.** (a) Idea arrives in a private channel (e.g., direct Telegram message) and is never recorded → invisible to Maestro's routing. (b) Duplicate captures of the same idea → artificial inflation of Stage 0 WIP count.

**Recovery.** (a) Post a journal entry tagging the source artifact retroactively; create the Linear issue or note file within 24h. (b) Mark duplicates as `duplicate` in Linear; link to the canonical capture; deduplicate at Stage 1 (Frame).

---

### Stage 1 — Frame

**Definition.** Structured dialogue with Muse Architect mode that transforms a raw capture into a proposal/design/tasks triple. The Architect runs the studio's wizard-intake protocol, emitting the three change files as structured output. See `muse.md § Architect mode` for the prompt contract and output schema.

**Entry.** A Stage 0 capture exists. Pavel explicitly assigns the idea to Muse Architect for framing (via `muse frame <slug>` or wizard session), or Maestro identifies a Stage 0 item as an advance candidate and routes it to Architect.

**Artifact.** `openspec/changes/<slug>/proposal.md` (draft), `openspec/changes/<slug>/design.md` (draft), `openspec/changes/<slug>/tasks.md` (draft). The three files together constitute the minimum viable specification; partial output does not exit Stage 1.

**Owner.** Muse Architect mode (executor). Pavel (decision authority on scope, problem framing, and which options to consider). The Architect produces draft artifacts autonomously; Pavel corrects scope before Stage 2 review.

**Delegation level.** Director — Pavel approves the framing topic and scope before Architect begins; Architect produces the three-file draft autonomously within that scope.

**Validation gate.** All three files present and non-empty. `proposal.md` contains the required sections (Problem / Solution / Out of scope / Risks / Decisions captured). No section is a stub placeholder. The proposal does not contradict an existing `current/*.md` capability spec without declaring the contradiction explicitly.

**Failure modes.** (a) Architect produces a proposal that contradicts an existing spec without declaring the conflict → held at Stage 1 pending resolution. (b) Scope is insufficiently constrained → Architect loops without emitting a complete triple. (c) `design.md` architectural decisions conflict with a parallel in-flight change → collision discovered only at Stage 2 review.

**Recovery.** (a) Pavel narrows the problem scope; Architect re-emits with a constrained problem statement and explicit contradiction declaration. (b) Constrain scope in a second wizard session. (c) Coordinate with the parallel change at Stage 2; defer or split if the collision is fundamental.

---

### Stage 2 — Spec

**Definition.** Human review and approval of the Frame output. Pavel (or a designated specialist) reads the three-file draft, requests revisions, and ultimately signals approval. The change proposal becomes the canonical problem statement for this piece of work and the source of truth for all subsequent stages.

**Entry.** Stage 1 validation gate passed (all three files present and complete). Pavel is assigned as reviewer in Linear (sub-issue transitions to `In Review`).

**Artifact.** `openspec/changes/<slug>/proposal.md` + `design.md` + `tasks.md` — finalized, reviewed, and approved. The files are immutable after Stage 2 exit except through a new change proposal that amends them.

**Owner.** Pavel (reviewer and approver). Muse Architect mode (revision executor). Stage 2 is Pavel-gated; no amount of Architect confidence bypasses operator approval.

**Delegation level.** Author — final approval is operator-only. No autonomous advance. This is the last stage at which the problem statement can be changed without creating a new change proposal.

**Validation gate.** *Updated 2026-06-02 by change `add-openspec-audit-pass` — adds the OpenSpec audit panel as a blocking gate between Stage 2 and Stage 3.*

Pavel signals approval (Linear sub-issue transitions from `In Review` to `Done`, or Pavel explicitly marks the change approved). The proposal must not contradict an existing `current/*.md` spec, or the contradiction must be explicitly scoped and declared for resolution within the same change or a companion change.

**Audit-panel gate (added 2026-06-02).** All four artefact files (`proposal.md`, `design.md`, `tasks.md`, `verification.md`) present, glossary terms resolved, cross-references live — AND — `forge audit openspec-change <slug>` verdict is `PASS` or `PASS-WITH-FIXES`. `BLOCK` verdict prevents Stage 2 → Stage 3 transition until findings close. See `forge/commands.md § Command surface` for the `openspec-change` module and `add-openspec-audit-pass/design.md § 3.3` for the composite-verdict rule. The audit pass closes the solo-founder confirmation-bias gap named in `add-inquiry-workflow-gates § 3.4`.

**Failure modes.** (a) Contradiction with existing spec is discovered at review but scope of resolution is unclear → stuck indefinitely at Stage 2. (b) `tasks.md` scope expands during review without bounding → tasks list grows unbounded, making Stage 3 unpredictable. (c) Spec approved but key architectural decision is deferred → Stage 4 Plan generation hits an unresolved fork.

**Recovery.** (a) Pavel scopes the contradiction into a separate change folder; approves the original proposal without that scope. (b) Bound the task list explicitly before approval; defer excess scope to a follow-up change. (c) Return to Frame (Stage 1) for a targeted architectural session on the deferred decision before re-entering Stage 2.

---

### Stage 3 — Stage (Linear epic + sub-issues)

**Definition.** Translate the approved change proposal into a Linear epic + sub-issues, populating the metadata the Forge conductor needs to operate: labels, `auto-build` field, task-slug, `openspec_change` link per the conductor issue-body schema. See `muse.md § Linear write tools` and `openspec/archive/2026-05-12-add-forge-epic-conductor/design.md § Issue-body schema` for the required field contract.

**Entry.** Stage 2 complete (proposal finalized and approved). Pavel triggers `muse stage <slug>` or manually creates Linear artifacts referencing the change folder.

**Artifact.** A Linear epic linked to `openspec/changes/<slug>/`, plus one sub-issue per task declared in `tasks.md`. Each sub-issue carries: task-slug, `auto-build: true/false` label, `openspec_change` link, and priority. The Forge conductor can enumerate the epic's issues and knows which to dispatch autonomously.

**Owner.** Pavel + Muse (linear_write_tools). Studio UI (`/issues/new` with OpenSpec import wizard) when available. Pavel reviews and sets priority.

**Delegation level.** Editor — Muse creates the Linear structure from the tasks.md; Pavel reviews, adjusts priority, and confirms `auto-build` settings.

**Validation gate.** Every task in `tasks.md` has a corresponding Linear sub-issue. Epic is linked to the change folder. Sub-issues have task-slug populated. Conductor can enumerate the epic's issues without error.

**Failure modes.** (a) `tasks.md` is amended after Linear issues are created → Linear and spec diverge. (b) Issue body schema missing required fields → conductor skips the issue silently. (c) Epic not linked to change folder → Maestro routing loses the spec context for that epic.

**Recovery.** (a) Run `muse stage --sync <slug>` (when implemented) to reconcile Linear with the updated `tasks.md`; manually until then. (b) Edit issue bodies to match the conductor schema. (c) Add the `openspec_change` field to the epic body; re-run Maestro routing for that epic.

---

### Stage 4 — Plan

**Definition.** Forge architect role generates a structured execution plan for a single Linear sub-issue. The plan is cached to `~/.forge/plans/<key>.md` and includes ordered steps, verification gates, and artifact declarations. The plan is the contract that stages 5–7 execute against. See `forge.md § Builder mode › Plan generation` for the plan file schema.

**Entry.** Sub-issue in Stage 3 with `auto-build: true`, OR `forge plan <key>` manual invocation. The change folder and task-slug are resolvable from the issue body.

**Artifact.** `~/.forge/plans/<key>.md` containing `Plan.verificationGates[]`, ordered step list, and artifact list. The plan references specific files, packages, and boundaries it will touch.

**Owner.** Forge architect role (plan-generation sub-process). Pavel reviews the plan before `forge build` dispatches when the plan includes steps that cross package boundaries or modify `current/*.md` files.

**Delegation level.** Director — Forge architect generates the plan autonomously; operator reviews before build dispatch for risky steps.

**Validation gate.** Plan file present and parseable. `Plan.verificationGates[]` is non-empty and includes at minimum typecheck and lint. No step references a package boundary violation per `CLAUDE.md § Package boundaries`.

**Failure modes.** (a) Plan references a dependency not in the lockfile → build will fail at Stage 5. (b) Verification gates omit a required check (e.g., `pnpm test` for a package with a test suite) → silent quality regression passes Stage 6. (c) Plan steps are underspecified → builder agent produces speculative code outside task scope.

**Recovery.** (a) `forge plan --regen <key>` with an amended spec context that names the dependency explicitly. (b) Manually add the missing gate to the plan file before dispatching build. (c) Return plan to architect with a narrowed task description; re-generate.

---

### Stage 5 — Build

**Definition.** Builder agent generates code in an isolated worktree against the approved plan. The builder executes each plan step in sequence, pausing at checkpoints and reporting progress. See `forge.md § Builder mode › Checkpoint model` for checkpoint semantics and the `BuildOutcome` type.

**Entry.** Plan approved (Stage 4 exit). `forge build <key>` invocation, or conductor advances automatically when `auto-build: true` and Stage 4 exit is recorded.

**Artifact.** Worktree at `~/.forge/worktrees/<key>` with branch `forge/<change>/<task>`. Files written per the plan step sequence.

**Owner.** Forge orchestrator + Anthropic Agent SDK subprocess (Builder mode prompt).

**Delegation level.** Director — operator approves plan once; builder executes autonomously through all checkpoints.

**Validation gate.** All `Plan.verificationGates[]` pass (evaluated at Stage 6 — Verify). Build step sequence completes without a fatal error. `BuildOutcome` is not `failed-builder` or `failed-push`.

**Failure modes.** (a) Hung at a checkpoint (no progress > 10 min) → deadlock or token budget ceiling. (b) Verification gate fails → `BuildOutcome: failed-builder`. (c) Build-lock contention (another forge process holds the worktree) → blocked start. (d) Agent produces speculative changes outside plan scope → gate catches the diff; manual review needed.

**Recovery.** (a) `forge cancel <key>` + inspect `.forge/errors/<key>-error.md`; re-dispatch from the same checkpoint. (b) Read gate failure; amend spec or code; re-dispatch. (c) Wait for lock release or `forge cancel <other-key>` if the other process is stale. (d) Prune the out-of-scope changes; re-run gates.

---

### Stage 6 — Verify

**Definition.** Verification gates declared in `Plan.verificationGates[]` run to completion against the worktree output. Passing all gates is the signal that the code is correct-by-contract. Gates are blocking conditions, not metrics — a failing gate means the work does not advance. See `forge.md § Builder mode › Checkpoint model`.

**Entry.** Build step sequence completes (Stage 5 exit). Gates are triggered automatically by Forge orchestrator post-steps.

**Artifact.** Gate run report (stdout/stderr from `pnpm typecheck` / `pnpm lint` / `pnpm test`). `BuildOutcome` field written to `.forge/state/<key>.json`.

**Owner.** Forge orchestrator (runs gates automatically). No human involvement unless gates fail.

**Delegation level.** Orchestrator — fully autonomous gate execution. Human is only re-engaged on gate failure.

**Validation gate.** Every gate in `Plan.verificationGates[]` exits with code 0.

**Failure modes.** (a) Flaky test produces intermittent failure → retry loop stuck. (b) Typecheck error introduced by a build step → `BuildOutcome: failed-builder`; Stage 5 re-entry required. (c) Gate declared in plan but not applicable to this package (no test suite) → false negative passes silently.

**Recovery.** (a) Re-run gate once; if still failing, classify as `failed-builder` and surface the flake as a separate issue. (b) Re-enter Stage 5 with the typecheck error as a constraint in the plan amendment. (c) Remove inapplicable gate from plan; add applicable gates (or document why no test suite exists).

---

### Stage 7 — Finalize

**Definition.** Forge post-build steps: openspec bundle regeneration (if `openspec/` was touched), commit with canonical message, push branch, create GitHub pull request. Transitions the worktree output into a reviewable PR. See `forge.md § Build orchestrator post-steps`.

**Entry.** Stage 6 gate pass (all verification gates green).

**Artifact.** GitHub PR (`forge/<change>/<task>` → `main`) with title referencing the Linear issue. Commit with message `forge(<change>): <task title>`. `BuildOutcome: completed-with-pr` written to `.forge/state/<key>.json`.

**Owner.** Forge orchestrator (automated post-steps).

**Delegation level.** Orchestrator — fully automated unless PR creation fails, at which point Forge surfaces the error and halts.

**Validation gate.** GitHub PR exists and links to the Linear sub-issue. `BuildOutcome: completed-with-pr` written. If `openspec/` files were touched, bundle regenerated and within size budget (< 5.5 MB gzipped per CI tripwire).

**Failure modes.** (a) `git push` rejected (branch protection rule, force-push blocked) → `BuildOutcome: failed-push`. (b) `gh pr create` fails (rate limit, auth expiry) → `BuildOutcome: failed-pr`. (c) Bundle regen produces a delta outside expected budget → operator warning; bundle not committed.

**Recovery.** (a) Check branch protection rules; ensure Forge token has write access; `forge finalize <key>` re-runs from last successful post-step. (b) Rotate GitHub token; re-run `forge finalize <key>`. (c) Investigate bundle delta; if legitimate, update budget estimate; if unexpected, trace the source file.

---

### Stage 8 — Review

**Definition.** Pull request receives AI-assisted review (structured findings in PR comment) and then human approval. Stage is not complete until a human approves. The AI reviewer surfaces `critical`, `warning`, and `suggestion` findings; `critical` findings are blocking. See `forge.md § Review orchestration`.

**Entry.** PR exists (Stage 7 exit). Linear sub-issue transitions to `In Review`. PR appears in studio sidebar review queue.

**Artifact.** GitHub PR review decision: `approved` or `changes-requested`. AI reviewer output posted as a PR comment. No `critical` finding unresolved.

**Owner.** AI reviewer (initial pass, automated). Pavel or a designated specialist (human approval gate, required).

**Delegation level.** Editor — AI produces structured review; human makes the final approval decision. The AI reviewer does not approve its own output.

**Validation gate.** PR has at least one human approval (Pavel or designated reviewer). No unresolved `critical` AI reviewer finding. CI passes on PR head at time of approval.

**Failure modes.** (a) No reviewer assigned → PR stalls; Stage 8 WIP accumulates. (b) Unresolved `critical` finding → PR cannot advance; Stage 5 re-entry required to address finding. (c) Reviewer approves without reading AI findings → quality bypass; findings are recorded but not acted on.

**Recovery.** (a) Maestro identifies Stage 8 WIP exceeding the 95th-percentile time-in-stage threshold and surfaces as a drift candidate; Pavel assigns a reviewer. (b) Address the `critical` finding in a new build (Stage 5 re-entry); link the new PR to the issue. (c) PR history retains the unread findings for retro analysis; encourage reviewer to acknowledge AI findings before approving.

---

### Stage 9 — Merge

**Definition.** Approved PR merges into `main`. Branch is deleted. Linear sub-issue transitions to `Done` via webhook. If auto-merge is configured for this issue, Forge conductor triggers the merge automatically after Stage 8 exit; otherwise Pavel merges manually. See the `add-forge-epic-auto-close` proposal for the auto-merge contract.

**Entry.** Human approval on PR (Stage 8 exit). No unresolved merge conflicts. CI passing on PR head.

**Artifact.** Squash commit on `main`. Branch deleted. Linear sub-issue status → `Done`.

**Owner.** Pavel (squash merge button) OR Forge conductor auto-merge when `auto-build: true` and auto-merge is enabled per issue.

**Delegation level.** Author — merge is operator-only unless auto-merge is explicitly enabled for this sub-issue.

**Validation gate.** CI passes on PR head at merge time. No unresolved merge conflicts. Linear sub-issue transitions to `Done` within 5 minutes of merge (webhook delivery).

**Failure modes.** (a) Merge conflict after long Stage 8 dwell → manual rebase required before merge. (b) CI regresses on merge commit (edge case: race with a concurrent merge) → revert required. (c) Linear webhook delivery fails → sub-issue stays `In Review` despite merge; Maestro routing reads stale state.

**Recovery.** (a) Rebase the PR branch onto `main`; force-push (after confirming branch protection allows it); re-request review if significant conflicts. (b) Revert the merge commit; diagnose regression; re-enter Stage 5. (c) Manually transition Linear sub-issue to `Done`; file a webhook reliability issue.

---

### Stage 10 — Archive

**Definition.** The change folder (`openspec/changes/<slug>/`) is renamed to `openspec/archive/<YYYY-MM-DD>-<slug>/`. Cross-reference amendments to `current/*.md` are applied (one paragraph per affected spec, per `openspec/AGENTS.md § What gets amended where, and when`). The Linear epic transitions to `Done`. The change is closed. See also `openspec/archive/2026-05-12-add-forge-epic-conductor/design.md § Archive (close-out)`.

**Entry.** All sub-issues for this change are `Done` (Stage 9 complete for every task). Pavel or Maestro identifies the epic as an archive candidate.

**Artifact.** `openspec/archive/<YYYY-MM-DD>-<slug>/` (renamed folder). Amended `current/*.md` files with cross-references. Linear epic status → `Done`. Bundle regenerated.

**Owner.** Pavel + Forge (archive post-step automation). Muse Architect mode (cross-reference amendment generation, when `auto-build: true` on the archive task).

**Delegation level.** Director — Forge generates and applies amendments; Pavel reviews and merges the archive PR.

**Validation gate.** All sub-issues `Done`. `openspec/changes/<slug>/` no longer exists. All declared `current/*.md` amendments applied (per `proposal.md § What changes`). Bundle regenerated and within size budget.

**Failure modes.** (a) One sub-issue remains open (missed or cancelled without record) → archive blocked. (b) Cross-reference amendment conflicts with an in-flight change editing the same `current/*.md` file → merge conflict on archive PR. (c) Bundle regen fails due to a malformed new `current/*.md` file → archive PR cannot merge.

**Recovery.** (a) Close or cancel the missed sub-issue with a documented rationale; link cancellation journal entry to the epic. (b) Coordinate the amendment merge with the in-flight change; sequence archive PR after the conflicting PR. (c) Fix the malformed spec file; re-run `pnpm openspec:bundle`; amend archive PR.

---

### Stage 11 — Release

**Definition.** Work lands in production. For `apps/web` and `apps/studio`: Cloudflare Workers deploy triggers automatically on merge to `main` via `opennextjs-cloudflare` in GitHub Actions. For packages: manual version bump + npm publish (or GitHub Release tag) until publish automation lands. See `forge.md § Distribution › Publish workflow` and the `apps/web` Cloudflare Workers deploy pipeline.

**Entry.** Merge to `main` (Stage 9 exit). For apps: CI deploy pipeline triggers automatically. For packages: Pavel manually tags and publishes when the epic is archived.

**Artifact.** Live deployment at `rapoport.studio` / `app.rapoport.studio` (apps), OR new package version on the npm registry (packages).

**Owner.** GitHub Actions (automated for apps). Pavel (manual for packages until publish automation lands).

**Delegation level.** Orchestrator (apps, fully automated). Author (packages, manual decision on when to publish).

**Validation gate.** Deployment health check passes (`/healthz` or equivalent). No Sentry error spike within 15 minutes of deploy. For packages: install smoke test in a clean environment (or `pnpm pack` + local install) before publish.

**Failure modes.** (a) Cloudflare Workers deploy strips secrets → runtime auth failures post-deploy. (b) Package publish fails due to npm auth token expiry → version stuck in registry at previous tag. (c) Deploy succeeds but Cloudflare edge cache is not invalidated → stale HTML/CSS served.

**Recovery.** (a) Run `wrangler secret put` for each stripped secret immediately after deploy per the known gotcha in `CLAUDE.md`. (b) Rotate npm token; `npm publish --access public` manual re-run. (c) Purge cache via Cloudflare dashboard zone purge; or wait for TTL expiry.

---

## 3. Metrics framework

Metrics are the **observability layer** over the eleven-stage timeline — distinct from gates, cost-guards, and validators. The framework declares three metric kinds that Maestro reads for routing and that the studio control room dashboards aggregate.

> **Key distinction (from § 1 Vision).** Metrics observe transitions. Gates block transitions. A metric that blocks work is a gate that laundered its identity. The four layers are strictly separate:
> - **Metrics** — observe stage transitions (this section).
> - **Gates** — block advance (`Plan.verificationGates[]`, AI reviewer `critical` finding).
> - **Cost-guards** — enforce budgets (`CANVAS_BUDGET_CENTS`, per-role caps).
> - **Validators** — enforce contracts (Zod schemas, tool call allowlists).

### 3.1 Three metric kinds

| Kind | What it measures | Example | Consumed by |
|---|---|---|---|
| **State** | Where each piece of work currently is, and how long it has been there | "RAP-407 is at Stage 8 (Review), entered 2 h ago" | Maestro routing decisions, `/tasks/[key]` UI, drift detection |
| **Throughput** | Rate at which work advances through transitions | "Stage 5→6 median wall-clock = 12 min over last 30 days" | Retro analysis, capacity planning, conductor pacing |
| **Quality** | Whether an advance was clean — exit-state distribution and gate-pass rates | "% of Stage 7 exits with `BuildOutcome: completed-with-pr`" | Retro analysis, regression detection, Forge productivity report |

The three kinds are exhaustive for this framework. A proposed metric that does not fit any of the three kinds is either a gate (blocking condition), a cost-guard (budget enforcement), or a validator (contract enforcement) — not a metric.

### 3.2 Per-stage metric assignments

Each stage carries at minimum one **state** metric. Throughput and quality metrics are assigned where a useful signal exists; early Discovery stages intentionally carry fewer metrics than Build/Ship stages because the work at those stages is less automatable.

| # | Stage | State metric | Throughput metric | Quality metric |
|---|---|---|---|---|
| 0 | Capture | `stage_entered_at` (ISO-8601) | — | — |
| 1 | Frame | `stage_entered_at`; `stage_exited_at` | `time_in_stage` (wall-clock) | All three files non-empty on first exit (yes/no) |
| 2 | Spec | `stage_entered_at`; `stage_exited_at` | `time_in_stage` | Revisions-before-approval count |
| 3 | Stage | `stage_entered_at`; `stage_exited_at` | `time_in_stage` | Linear-issues-created vs tasks-declared (coverage ratio) |
| 4 | Plan | `stage_entered_at`; `stage_exited_at` | `time_in_stage` | Plan-regen count (0 = first-pass success) |
| 5 | Build | `stage_entered_at`; `stage_exited_at`; `BuildOutcome` | `time_in_stage` | `BuildOutcome: completed-with-pr` rate |
| 6 | Verify | `stage_entered_at`; `stage_exited_at`; gate-pass bitmask | `time_in_stage` | Gate-pass-on-first-try rate per gate type |
| 7 | Finalize | `stage_entered_at`; `stage_exited_at`; `BuildOutcome` | `time_in_stage` | `BuildOutcome: completed-with-pr` rate (distinct from Stage 5) |
| 8 | Review | `stage_entered_at`; `stage_exited_at` | `time_in_stage` | AI-`critical`-findings-per-PR; human-approval cycle count |
| 9 | Merge | `stage_entered_at`; `stage_exited_at` | `time_in_stage` | Rebase-required rate |
| 10 | Archive | `stage_entered_at`; `stage_exited_at` | `time_in_stage` | Amendment-conflicts-at-archive rate |
| 11 | Release | `stage_entered_at`; `stage_exited_at` | `time_in_stage` (for packages: manual; for apps: deploy pipeline latency) | Post-deploy error-spike rate (Sentry, 15-min window) |

**Recording convention.** `stage_entered_at` is written by the agent that takes ownership of the stage (Maestro records it in `orchestra_journal` as an `advance` entry). `stage_exited_at` is written by the agent that satisfies the validation gate. Until `orchestra_journal` is migrated from `.forge/state/<key>.json`, state metrics for stages 4–7 are read from Forge's per-issue state file.

### 3.3 What is not a metric

Per design.md § 3.3, the following are explicitly **not** metrics in this framework:

- `pnpm typecheck` / `pnpm lint` / `pnpm test` exit codes — these are **validation gates** (blocking conditions).
- `CANVAS_BUDGET_CENTS` cap, per-role budget caps — these are **cost-guards** (enforcement primitives).
- Zod schemas on tool call outputs, allowlists — these are **runtime validators** (contracts).

Treating these as metrics creates "metrics that block work" — the standard anti-pattern that makes observability frameworks toxic to the teams that adopt them.

### 3.4 Aggregate metrics

Three aggregate signals surface across all stages. These are what `/control/workflow` (future change) renders at the dashboard level.

| Metric | Definition | Why it matters |
|---|---|---|
| **WIP per stage** | Count of work items currently dwelling in stage X | Capacity signal — Stage 8 (Review) WIP > 5 means the PR queue is bottlenecked; Stage 5 (Build) WIP > 3 means Forge concurrency is saturated |
| **End-to-end cycle time** | Median wall-clock from Stage 0 `stage_entered_at` to Stage 11 `stage_exited_at` | Lead-time-for-changes proxy (DORA Deployment Frequency / Lead Time pair); tracked per quarter |
| **Stuck-stage signal** | Per-stage 95th-percentile `time_in_stage` (rolling 30-day) | Drift indicator — when a stage's 95p doubles week-over-week, Maestro triggers a retro entry; see § 4.2 for how Maestro identifies drift candidates |

Aggregates are updated continuously as `orchestra_journal` receives new entries. They are read-only from the perspective of any individual agent.

### 3.5 Anti-vanity rules and Goodhart's law mitigation

**Anti-vanity rules.** A metric is "vain" when it can be improved by optimizing for the metric rather than the underlying quality. Three rules prevent this:

1. **No standalone composite scores.** Individual metric components are always reported alongside any composite. A "studio health score" that hides its M1–M9 inputs is not permitted. (See `openspec/archive/2026-05-11-add-forge-productivity-measurement/draft-amendments/forge-productivity-measurement.md § Goodhart's law strategy` for the concrete mitigations applied to the Forge Productivity Index, which implements this rule for the Build phase.)
2. **Quality budget on throughput improvements.** A throughput improvement that coincides with a quality regression (e.g., shorter Stage 5 wall-clock + higher `BuildOutcome: failed-builder` rate) is flagged as a "trade-off," not an improvement. Throughput wins must not come at a quality cost.
3. **Coverage denominators are visible.** Rates (e.g., gate-pass-on-first-try) always display the denominator (total gate runs) alongside the rate. A 100% pass rate on 1 run is not the same signal as 100% on 50 runs.

**Goodhart's law mitigation.** Per the strategy documented in `openspec/archive/2026-05-11-add-forge-productivity-measurement/draft-amendments/forge-productivity-measurement.md § Goodhart's law strategy`: no single metric is a target. Metrics are **inputs to retro analysis** (§ 7 Evolution policy), not optimization objectives. Maestro does not route based on aggregate scores — it routes based on stage state and gate outcomes. Aggregate metrics inform the human retro; they do not drive automated decisions.

### 3.6 DORA / SPACE / DevEx cross-reference

Readers arriving from industry framework mental models will recognize the three metric kinds as a projection of the standard frameworks onto this studio's operating context. The mapping is provided here for orientation; the three kinds (state / throughput / quality) are the canonical framework for this spec and for Maestro's routing function.

The proposal-layer four-layer decomposition maps onto the three kinds as follows:

| 4-layer (proposal / industry) | Metric kind | Notes |
|---|---|---|
| **Delivery** (DORA-shaped: deployment frequency, lead time, restore time) | Throughput + Quality | Lead time = end-to-end cycle time (§ 3.4). Deployment frequency = Stage 11 exit rate. Restore time = Stage 5 re-entry cycle time when `BuildOutcome: failed-builder` |
| **Quality** (SDD-shaped: gate-pass rates, `critical`-finding frequency) | Quality | Directly mapped to per-stage quality metrics (§ 3.2, columns 5) |
| **Cost / Effort** (denominated in $: Anthropic API spend, operator hours) | Throughput | Throughput expressed in cost units, not just time — `time_in_stage` × cost-per-hour is the denominator in the Forge Productivity Index (see forge-productivity-measurement.md) |
| **Friction / Health** (SPACE / DevEx: flow state, tool interruptions, toil) | State | WIP per stage and stuck-stage signal (§ 3.4) are the friction proxies — high Stage 8 dwell is high friction for the reviewer; high Stage 2 revision count is high friction in the approval loop |

**DORA four metrics directly:**
- *Deployment frequency* → Stage 11 exit rate (count of work items exiting Stage 11 per week).
- *Lead time for changes* → end-to-end cycle time (Stage 0 entry → Stage 11 exit, median).
- *Change failure rate* → post-deploy error-spike rate (Stage 11 quality metric, § 3.2).
- *Mean time to restore* → Stage 5 re-entry cycle time on `BuildOutcome: failed-builder` (throughput metric, Stage 5).

**SPACE framework (Satisfaction / Performance / Activity / Communication / Efficiency):** maps most directly to Quality (Performance), Throughput (Activity + Efficiency), and State (Satisfaction proxied by drift frequency).

**DevEx framework (feedback loops / cognitive load / flow state):** maps to the stuck-stage signal (State) and the review cycle count (Quality, Stage 8). A stuck-stage signal firing at Stage 8 is a feedback-loop failure; a high revision count at Stage 2 is a cognitive-load signal.

These cross-references are informational. The studio does not maintain separate DORA / SPACE / DevEx dashboards; the three-kind framework produces the underlying data from which any of these industry views can be derived.

---

## 4. Maestro control loop

Maestro mode (within Muse) is the **timeline controller**: the agent that continuously reads workflow state across all in-flight pieces of work, identifies what needs attention or advance, surfaces decisions to Pavel, and records every outcome in the append-only orchestra journal. This section specifies the controller's four-step loop as a contract — the runtime implementation is a separate code change per design.md Decision D-6.

Cross-link: `agents/maestro.md § Cross-cutting defenses` specifies the HitL gate, idempotency invariant, and risk mitigations that this loop relies on. This section describes the loop's timeline-controller subset; maestro.md carries the full agent specification.

### 4.1 The four-step loop

```
                ┌──────────────────────────────────────────────┐
                │                                              │
                ▼                                              │
   1. READ      journal + agent_status + forge state     ──────┘
                │           + canvas state + openspec/
                ▼
   2. IDENTIFY  candidates                           (§ 4.2)
                │   ├─ decision candidates    (priority 1)
                │   ├─ drift candidates       (priority 2)
                │   └─ advance candidates     (priority 3)
                ▼
   3. SURFACE   decisions to Pavel via HitL gate    (maestro.md § Cross-cutting defenses)
                │
                ▼
   4. RECORD    outcomes in orchestra_journal       (append-only)
                │           + filesystem rationale mirror
                └──────────────────────────────────────────────┐
                                                               │
                             (loop repeats on next invocation) │
```

The loop is **not continuous polling** — it is invoked on a schedule or event trigger (the trigger mechanism is part of the Maestro runtime code change). Each invocation processes the complete snapshot of current state and terminates. The loop does not hold state between invocations; state is fully reconstructed from the journal on each read.

### 4.2 Step 1 — Read

Maestro reads (and ONLY reads — per `agents/maestro.md § Access scope`):

| Input | Source | What Maestro reads from it |
|---|---|---|
| `orchestra_journal` | Supabase table (schema lands with `add-knowledge-layout`) | Append-only event stream from every agent; the complete audit trail of stage transitions, drift entries, and decision records |
| `agent_status` | Supabase table | Current work item per active agent; identifies which agents are mid-stage and which are idle |
| Forge state | `~/.forge/state/<key>.json` (transitional) + `forge_runs` / `forge_steps` / `forge_outputs` (Supabase) | Per-issue stage state, `BuildOutcome`, checkpoint progress; transitional until journal migration completes |
| Canvas state | `canvas_sessions` (Supabase) | Canvas lifecycle stage scores (from `lifecycle.yaml`); used for Stage 0–2 routing |
| OpenSpec | `openspec/current/**`, `openspec/changes/**`, `openspec/_methodology/**` | Spec context for routing rationale — Maestro cites the spec when recording advance decisions |

Maestro does **not** write to any of these sources during the Read step. It constructs an in-memory snapshot of current stage state for all in-flight work items.

### 4.3 Step 2 — Identify candidates

From the snapshot, Maestro identifies three candidate types and orders them by priority:

| Priority | Type | Trigger condition | What Maestro does |
|---|---|---|---|
| **1 — Decision** | Decision candidate | Ambiguous routing target: no clear next-stage owner; two agents have claimed or disclaimed the same work item; or the routing requires a scope call beyond Maestro's authority | Surface to Pavel via HitL gate (Step 3); **halt advance** for this item until Pavel responds |
| **2 — Drift** | Drift candidate | Stuck-stage signal fires: `time_in_stage` exceeds the per-stage 95th-percentile threshold (§ 3.4) | Post `drift` journal entry; **do not auto-advance**; flag for retro at end-of-quarter (§ 7) |
| **3 — Advance** | Advance candidate | Validation gate passed; next-stage owner is unambiguous and available | Route work to next stage's owner; record `advance` journal entry (Step 4) |

Priority ordering is strict. If the same work item qualifies as both a drift candidate and an advance candidate (gate has since passed but the item was also stuck), it is processed as a drift candidate first. The drift entry is recorded; then the advance is processed in the same loop iteration.

**Decision-laundering mitigation.** Every journal entry carries `originating_agent_id` — the agent that produced the underlying state that triggered the routing decision. This means a routing outcome traces back to its source, not just to Maestro. Decision laundering (an agent making a scope call that should have been Pavel's) is detectable in the journal history per `agents/maestro.md § Risk matrix`.

### 4.4 Step 3 — Surface

After identifying candidates, Maestro surfaces decision candidates to Pavel. Non-decision candidates (drift, advance) do not require a Pavel response before the loop proceeds.

**HitL gate for decision candidates.** Maestro posts the decision candidate to Pavel via the HitL gate mechanism specified in `agents/maestro.md § Cross-cutting defenses`. The format is:

```
Work item:    <Linear key> — <issue title>
Current stage: <stage #> (<stage name>)
Decision needed: <one sentence describing the ambiguity>
Options:
  A. <option A> — <consequence>
  B. <option B> — <consequence>
Maestro recommendation: <A or B> — <rationale citing spec section>
```

Maestro **always provides a recommendation** with a spec citation. The recommendation is not binding — Pavel can override. The recommendation makes the loop auditable: if Maestro's recommendation is systematically wrong, the pattern surfaces in journal history.

**Advance candidates.** Maestro routes them to the next stage's owner without a Pavel confirmation step. The advance is recorded in Step 4. Pavel can inspect any advance in the journal; the journal is not hidden.

**Drift candidates.** Maestro posts a `drift` journal entry and does not advance the item. Drift items accumulate for retro analysis (§ 7 Evolution policy). Maestro does not automatically reassign, re-dispatch, or modify the stuck work item.

### 4.5 Step 4 — Record

Every outcome from Step 3 is written to two output sinks:

| Sink | Format | Properties |
|---|---|---|
| `orchestra_journal` (canonical) | Append-only Supabase row: `{event_type, work_item_key, stage_from, stage_to, agent_id, originating_agent_id, rationale, timestamp}` | Immutable after write; the audit trail; source of truth for all aggregate metrics (§ 3.4) |
| `~/.maestro/journal/<YYYY-MM-DD>.md` (filesystem mirror) | Human-readable Markdown audit log | One file per calendar day; append-only; read by Pavel during manual retro review; not a canonical source |

The filesystem mirror exists for human readability only. If the mirror and the Supabase journal diverge (e.g., after a crash mid-write), the Supabase journal is authoritative.

**Journal entry schema (per event type):**

| Event type | `stage_from` | `stage_to` | Mandatory fields |
|---|---|---|---|
| `advance` | Stage # exited | Stage # entered | `originating_agent_id`, `rationale` (spec citation) |
| `drift` | Current stage # | same | `time_in_stage_seconds`, `threshold_p95_seconds`, `drift_note` |
| `decision` | Current stage # | `null` (pending) | `decision_text`, `options`, `recommendation`, `recommendation_rationale` |
| `decision_resolved` | `null` | Stage # entered or `blocked` | `resolution`, `resolved_by` (always Pavel's agent ID for decision candidates) |

### 4.6 Idempotency

The routing function is **pure**: `route(journal_snapshot, request) → decision`. Re-running the loop with the same journal snapshot and the same set of in-flight work items produces the same set of candidates and the same routing decisions. This means:

- Maestro restart mid-iteration is safe — the journal snapshot on restart reflects any entries written before the crash, producing a consistent state.
- Duplicate invocations (e.g., scheduler fires twice before first invocation completes) are safe — the second invocation sees the same snapshot plus any entries the first wrote, which de-duplicates candidates.
- Advance entries are idempotent: if an `advance` entry for `(key, stage_from, stage_to)` already exists in the journal, Maestro does not write a duplicate.

Idempotency is guaranteed by the append-only property of `orchestra_journal` combined with a pre-write check: before writing any entry, Maestro queries for an existing entry with the same `(work_item_key, event_type, stage_from, stage_to, timestamp_day)` composite. If found, the write is skipped and the existing entry is returned as the output. Per `agents/maestro.md § Cross-cutting defenses`.

---

## 5. Roles

Roles describe *who* does the work at each stage. The eleven stages are engagement-mode invariant (the list does not fork per engagement type — per design.md Decision D-7), but **ownership varies by engagement mode**. This section declares both the full role roster and how ownership shifts across the four engagement modes defined in `openspec/_methodology/rapoport-studio-engagement.md § 4`, which is the source of truth for engagement mode definitions.

### 5.1 Role roster

| Role | Type | Description |
|---|---|---|
| **Pavel** | Human principal | Studio founder; final authority on all Author-delegated stages; can override any Maestro routing decision |
| **Maestro** | AI agent (Muse mode) | Timeline controller; runs the four-step control loop (§ 4); does not execute stages — routes and records |
| **Muse Architect** | AI agent (Muse mode) | Discovery executor; runs wizard intake (Stage 1), generates proposal/design/tasks triple, authors cross-reference amendments at Stage 10 |
| **Muse Builder** | AI agent (Muse mode) | Deferred. Intended for narrative and content deliverables; not yet active in stages |
| **Forge** | CLI toolchain | Build executor; owns stages 4–7 (Plan / Build / Verify / Finalize); also participates in Stage 10 archive post-steps |
| **Specialist network** | Human contractor | Domain expert engaged per project need; entry point is always a Linear sub-issue with a task-slug and change-folder link; see `openspec/_methodology/specialist-network.md` |
| **Client** | Human stakeholder | External party in Full or Hybrid engagements; owns or co-owns stages 4–11 depending on engagement mode; see `rapoport-studio-engagement.md § 4` |

### 5.2 Role × Stage matrix

The matrix below shows the **primary owner** and **support roles** for each stage in the default Internal-studio engagement mode. "Owner" means the role that must satisfy the stage's validation gate. "Support" means the role assists but is not accountable for gate passage.

| # | Stage | Owner | Support | Delegation level |
|---|---|---|---|---|
| 0 | Capture | Pavel | Muse Architect (wizard assist) | Orchestrator |
| 1 | Frame | Muse Architect | Pavel (scope direction) | Director |
| 2 | Spec | Pavel | Muse Architect (revision executor) | Author |
| 3 | Stage | Pavel + Muse | — | Editor |
| 4 | Plan | Forge architect role | Pavel (risky-step review) | Director |
| 5 | Build | Forge builder role | — | Director |
| 6 | Verify | Forge orchestrator | — | Orchestrator |
| 7 | Finalize | Forge orchestrator | — | Orchestrator |
| 8 | Review | AI reviewer + Pavel | Specialist (when assigned) | Editor |
| 9 | Merge | Pavel | Forge conductor (auto-merge when enabled) | Author |
| 10 | Archive | Pavel + Forge | Muse Architect (amendment generation) | Director |
| 11 | Release | GitHub Actions | Pavel (packages) | Orchestrator / Author |

**Delegation level taxonomy** (Microsoft Worklab 2026 four-pattern model, cited in § 1 Vision):

| Level | Human involvement | When to use |
|---|---|---|
| **Author** | Human produces or approves every output | High-stakes gates where operator accountability is non-negotiable (spec approval, merge, publish) |
| **Editor** | Human reviews and corrects AI/tool output | AI generates; human validates before advance |
| **Director** | Human sets scope once; agent executes autonomously within that scope | Forge Plan generation, Build execution, Finalize post-steps |
| **Orchestrator** | Human monitors outcomes; agent executes without per-action approval | Fully automated stages (Verify, Release for apps, Maestro routing) |

Ambiguous delegation (where the boundary is unclear in practice) is a **decision candidate** for Maestro: it surfaces the ambiguity to Pavel rather than resolving it autonomously. See § 4.3.

### 5.3 Engagement-mode owner variation

The four engagement modes from `openspec/_methodology/rapoport-studio-engagement.md § 4` alter ownership for stages 3–11. Discovery stages (0–2) are always studio-owned regardless of mode. The table below shows who owns each stage per mode; cells in **bold** differ from the Internal-studio baseline.

| Stage | Internal-studio | Deliverables-only | Hybrid | Full |
|---|---|---|---|---|
| 0 Capture | Pavel + Muse | Pavel + Muse + Specialist | Pavel + Muse + Specialist | Pavel + Muse + Specialist |
| 1 Frame | Muse Architect | Muse Architect | Muse Architect | Muse Architect |
| 2 Spec | Pavel | Pavel | Pavel | Pavel |
| 3 Stage | Pavel + Muse | **Studio** | **Studio** | **Studio** |
| 4 Plan | Forge architect | **Client team** | **Client team OR Forge** | Forge architect |
| 5 Build | Forge builder | **Client team** | **Client team** | Forge builder |
| 6 Verify | Forge orchestrator | **Client team** | **Client team** | Forge orchestrator |
| 7 Finalize | Forge orchestrator | **Client team** | **Studio fork-PR** | Forge orchestrator |
| 8 Review | AI reviewer + Pavel | **Client team** | **Client team** | AI reviewer + Client team |
| 9 Merge | Pavel | **Client team** | **Client team** | **Client team** |
| 10 Archive | Pavel + Forge | **Client team** | **Client team** | **Client team OR Studio** |
| 11 Release | GitHub Actions / Pavel | **Client team** | **Client team** | **Client team** |

**Reading the table:**

- **Internal-studio** — all eleven stages owned by the studio (Pavel + agents + Forge). Default for all internal infrastructure, spec authoring, and AI research work.
- **Deliverables-only** — studio owns Discovery (0–2) and high-level staging (3); client team owns execution (4–11). Studio participates in 0–3 and provides tooling; client team drives all build and ship stages.
- **Hybrid** — discovery and staging owned by studio; build execution split (client team for Stages 4–6; studio provides a fork-PR integration layer at Stage 7; review shared at Stage 8). Common for embedded-sprint engagements.
- **Full** — studio owns the full Build phase (4–7); client team co-owns Review (8) and owns all Ship stages (9–11). Common for contracted builds where the client takes over post-merge operations.

The stage list does not fork across modes — it is always twelve states and eleven transitions. Engagement-mode variation is tracked as metadata on the Linear epic (`engagement_mode` field); Maestro reads this metadata when identifying the owner for the next stage. Per design.md Decision D-7.

**Source of truth for engagement mode definitions:** `openspec/_methodology/rapoport-studio-engagement.md § 4`. When engagement modes change, both `rapoport-studio-engagement.md` and this table are amended in lockstep through the same change folder.

### 5.4 Specialist network participation

Specialist network members (see `openspec/_methodology/specialist-network.md`) participate where indicated in the Stage matrix and engagement-mode table. Their entry protocol is invariant across engagement modes:

1. Maestro (or Pavel manually) creates a Linear sub-issue with the specialist's name/handle as assignee.
2. The sub-issue body includes: task-slug, `openspec_change` link, scope description, and expected artifact.
3. The specialist delivers the artifact; Pavel (or the client team in Deliverables-only / Hybrid) reviews against the Stage 2-approved scope.
4. If the specialist's artifact is a code contribution: it enters at Stage 4 (Plan) in the specialist's own worktree, or at Stage 8 (Review) if the specialist opens a PR directly.

Specialists do not have write access to `openspec/current/` and do not own any stage's validation gate without explicit delegation from Pavel.

---

## 6. Drift signals taxonomy

A **drift signal** is a named stuck pattern that Maestro's control loop (§ 4) detects and classifies. Drift signals are not errors — they are signals that a piece of work has stopped advancing and needs attention. They feed into the `drift` journal entries described in § 4.3 and into the quarterly retro analysis described in § 7 (Evolution policy).

This section is the canonical taxonomy of known stuck patterns. Each entry declares:
- **Name** — a kebab-case slug used in `orchestra_journal` `drift_note` fields and in retro reports.
- **Detection rule** — the observable condition that fires the signal.
- **Severity** — `low` (informational; surface at retro), `medium` (surface to Pavel within 24h), `high` (surface to Pavel immediately; halt related advances).
- **Expected response** — the default action when the signal fires.

Maestro uses this taxonomy when writing `drift` journal entries: the `drift_note` field must reference one of these named patterns (or declare a new unnamed pattern for retro classification). Unnamed patterns accumulate and are reviewed at the quarterly retro for potential addition to this taxonomy.

### 6.1 Drift signal table

| Signal name | Detection rule | Severity | Expected response |
|---|---|---|---|
| `verification-gate-flaky` | A gate in `Plan.verificationGates[]` fails, is retried automatically, passes on retry — and this pattern repeats ≥ 2 times within one Stage 6 run | **medium** | Surface to Pavel; create a separate Linear issue for the flake; do not count the flaky pass as a clean gate result in quality metrics |
| `plan-stale` | The plan file `~/.forge/plans/<key>.md` was last modified > 24h before `forge build <key>` is invoked | **medium** | Block build dispatch; prompt Pavel to review the plan for staleness; re-generate if the change folder has changed since the plan was written |
| `epic-conflict` | A merge conflict is detected on a downstream wave PR (a PR whose branch diverged from `main` while upstream PRs were merging) at Stage 9 | **medium** | Do not merge until conflict is resolved; Maestro surfaces the conflicting files to Pavel; priority: unblock the upstream PR first, then rebase the downstream |
| `pr-merge-stalled` | A PR at Stage 9 (Merge) has been open and approved (Stage 8 exit recorded) for > 4h without merging, and auto-merge is not enabled | **medium** | Maestro surfaces to Pavel; expected action is merge or explicit deferral with a recorded rationale in the journal |
| `archive-pending` | A change folder in `openspec/changes/` has all tasks ticked in `tasks.md` (every checkbox is `[x]`) but no archive PR exists and > 24h have elapsed since the last task was ticked | **low** | Maestro surfaces at next scheduled loop run; expected action is `git mv openspec/changes/<slug> openspec/archive/<YYYY-MM-DD>-<slug>` per Stage 10 protocol |
| `stage-wip-ceiling` | WIP count for any single stage exceeds the per-stage ceiling (Stage 5 Build > 3 concurrent; Stage 8 Review > 5 concurrent; any other stage > 8) | **high** | Halt new advances into the saturated stage; Maestro surfaces WIP table to Pavel; expected action is to process existing items before dispatching new ones |
| `decision-unresolved` | A `decision` journal entry (§ 4.5) has been posted but no `decision_resolved` entry exists after > 2h | **high** | Re-surface the decision to Pavel immediately; halt advance on the affected work item; do not re-dispatch until Pavel responds |
| `spec-drift` | A `current/*.md` file referenced in an in-flight change's `proposal.md` has been amended by a separate merged PR since the change's Stage 2 approval | **medium** | Surface to Pavel; expected action is a quick review to confirm the amendment does not invalidate assumptions in the in-flight change; record resolution in journal |
| `journal-gap` | No `orchestra_journal` entries have been written for any work item for > 12h during active business hours (08:00–22:00 UTC+3) | **medium** | Maestro self-diagnoses: checks whether journal writes are failing (Supabase connectivity); surfaces the gap to Pavel; if journal is healthy, flags the quiescence as a capacity signal |

### 6.2 Signal-to-spec cross-reference

Each signal maps to one or more existing specs or change proposals that define the underlying mechanism. The cross-reference is provided for traceability; when a linked spec evolves, the signal detection rule may need updating.

| Signal name | Linked spec / change | What the spec defines |
|---|---|---|
| `verification-gate-flaky` | `openspec/current/workflow.md § 2` (Stage 6, failure mode a); `openspec/current/forge/verifier.md § Checkpoint model` | Gate-pass semantics; `BuildOutcome` type; retry behavior |
| `plan-stale` | `openspec/current/workflow.md § 2` (Stage 4, failure mode a); `openspec/archive/2026-05-12-add-forge-epic-conductor/design.md` (RAP-392 B4 plan staleness) | Plan file schema; plan-regen protocol |
| `epic-conflict` | `openspec/current/workflow.md § 2` (Stage 9, failure mode a); `openspec/archive/2026-05-12-add-forge-epic-conductor/design.md` (RAP-407 Phase 4 trivial-conflict handling) | Merge conflict recovery; conductor wave ordering |
| `pr-merge-stalled` | `openspec/current/workflow.md § 2` (Stage 9, failure mode —); `openspec/archive/2026-05-12-add-forge-epic-auto-close/proposal.md` (RAP-408 wait-for-merge) | Auto-merge contract; merge timeout handling |
| `archive-pending` | `openspec/current/workflow.md § 2` (Stage 10); `openspec/AGENTS.md § What gets amended where, and when` | Archive protocol; change-folder naming; amendment sequencing |
| `stage-wip-ceiling` | `openspec/current/workflow.md § 3.4` (WIP per stage aggregate metric); `openspec/current/agents/maestro.md § Function` | WIP ceiling definition; Maestro routing scope |
| `decision-unresolved` | `openspec/current/agents/maestro.md § Cross-cutting defenses`; `openspec/current/workflow.md § 4.3` (Step 3 — Surface) | HitL gate protocol; decision entry schema |
| `spec-drift` | `openspec/AGENTS.md § What gets amended where, and when`; `openspec/current/workflow.md § 2` (Stage 10, failure mode b) | Amendment sequencing; archive-conflict resolution |
| `journal-gap` | `openspec/current/agents/maestro.md § Access scope`; `openspec/current/workflow.md § 4.5` (Step 4 — Record) | Journal write protocol; Supabase connectivity assumptions |

### 6.3 Severity response protocol

Severity levels determine how Maestro surfaces the signal and when Pavel must respond:

| Severity | Surface channel | Pavel response window | Auto-action if no response |
|---|---|---|---|
| **low** | Added to retro queue; surfaced in next scheduled Maestro report | Next quarterly retro | None — accumulates for retro analysis |
| **medium** | Posted to `orchestra_journal` as `drift` entry; summary surfaced to Pavel in next HitL cycle (≤ 24h) | 24h from surface | Maestro re-surfaces at next cycle; if no response after 48h, escalates to `high` |
| **high** | Immediate HitL gate post (same format as decision candidates in § 4.3); work item advance halted | 2h from surface | Maestro blocks all advances on the affected work item until Pavel responds; no auto-resolution |

All drift signals — regardless of severity — are written to `orchestra_journal` as `drift` entries. The `drift_note` field names the signal slug from § 6.1. Low-severity signals that accumulate (e.g., `archive-pending` for multiple change folders) are batched into a single retro report entry rather than generating individual HitL posts.

### 6.4 Adding new drift signals

New stuck patterns discovered during retro analysis (§ 7) are added to this taxonomy through a dedicated change proposal (slug pattern `change-workflow-drift-signals`). The bar for addition:

1. The pattern has been observed in `orchestra_journal` at least twice (two distinct work items, two distinct time periods).
2. The detection rule is automatable — Maestro can detect it from the inputs defined in § 4.2 without requiring Pavel's judgment.
3. The expected response is deterministic enough to specify without case-by-case branching.

Patterns that do not meet the bar are tracked as retro notes in `~/.maestro/journal/` until they do. Maestro marks unnamed drift entries with `drift_note: "unnamed — retro-classify"` to surface them for human classification at the next retro.

---

## 7. Evolution policy

The workflow spec is a **living contract**. It evolves through explicit change proposals — never through direct edits to `openspec/current/workflow.md` outside of a change folder and archive step. This section declares the amendment slug patterns, the retro cadence, and the retro format and outputs.

### 7.1 Amendment slug patterns

All amendments to this spec go through the standard OpenSpec change proposal process (per `CLAUDE.md § Hard rule 7` and `openspec/AGENTS.md § What gets amended where, and when`). Two slug-pattern families are reserved:

| Amendment type | Slug pattern | When to use |
|---|---|---|
| **Timeline-shape amendments** | `change-workflow-<aspect>` | Any change to stage definitions, transition rules, delegation levels, metrics framework, control loop protocol, drift taxonomy, or audience table. Examples: `change-workflow-drift-signals`, `change-workflow-metrics-quality`, `change-workflow-delegation-levels` |
| **New stages** | `add-workflow-stage-<name>` | Adding a net-new stage to the eleven-stage list — rare; requires justification per § 2.3 (why not split/merge instead). Example: `add-workflow-stage-triage` if a triage gate is inserted between Capture and Frame |

No other slug pattern is reserved. Amendments that touch this spec incidentally (e.g., a change that amends `forge/spec.md` and adds one cross-reference sentence to `workflow.md`) use the originating change's slug.

**Amendment bar for new stages.** The decision to add a stage must clear the § 2.3 criteria: the new stage has a distinct artifact, a distinct owner, and a distinct validation gate that cannot be expressed as a sub-step of an existing stage. Proposals that add stages must explicitly document why the existing eleven stages cannot accommodate the new behavior.

### 7.2 Quarterly retro cadence

The workflow retro runs on a **soft quarterly cadence** — it is a ritual, not a gate. Out-of-band amendments (e.g., a drift signal added mid-quarter because a new stuck pattern appeared in production) are first-class and do not wait for the retro. The retro is the venue for *systematic* review of accumulated signals; urgent single-signal amendments go through their own change proposal immediately.

**Cadence:** end of each calendar quarter (Q1 = March, Q2 = June, Q3 = September, Q4 = December). The retro produces a set of outputs (§ 7.4); outputs that require a change proposal are queued for the next quarter's work, not blocked on retro completion.

**Who runs the retro:** Pavel (principal) + Maestro (prepares the input report from journal data). Maestro reads the retro inputs (§ 7.3), formats the five questions (§ 7.3), and posts the pre-populated report to Pavel before the retro session. Pavel responds; Maestro records the outputs (§ 7.4) in the journal.

### 7.3 Retro inputs and format

**Inputs.** The retro draws on four data sources, all readable by Maestro without additional tooling:

| Input | Source | What it contributes |
|---|---|---|
| **Previous-quarter aggregate metrics** | `orchestra_journal` aggregate queries (§ 3.4): WIP per stage, end-to-end cycle time, stuck-stage signal 95p per stage | Objective baseline — which stages were fastest / slowest / most stuck in absolute terms |
| **Drift entries** | `orchestra_journal` rows with `event_type: drift`, filtered to the quarter | Named stuck patterns (§ 6.1) that fired; unnamed patterns (`drift_note: "unnamed — retro-classify"`) that need classification |
| **Closed Linear epics** | Linear API: epics closed in the quarter, with their sub-issue cycle times and `BuildOutcome` distributions | Qualitative data — which types of work advanced cleanly vs needed multiple Stage 5 re-entries |
| **Drift-cleanup items** | `ROADMAP.md § 6` (drift-cleanup backlog section) | Known small fixes that have accumulated since the last retro; candidate inputs for the retro's cleanup outputs |

**Retro format — five questions.** Maestro prepopulates answers from the input data; Pavel amends and finalizes:

1. **What advanced fastest?** — Identify the stages and work types with the lowest median `time_in_stage` and the cleanest `BuildOutcome` distributions. What made these fast? Is the pattern repeatable?

2. **What stuck most?** — Identify the stages with the highest 95p `time_in_stage` or the highest `drift` entry count. What drift signals fired most often? Were they expected or surprising?

3. **Which gates fired falsely?** — Review `verification-gate-flaky` entries and any `plan-stale` patterns where the plan regen was unnecessary. Which gates are over-triggering relative to the quality signal they provide?

4. **Which decisions got laundered?** — Review `decision_resolved` entries where `resolved_by` was an agent (not Pavel). Were those resolutions within Maestro's authority per § 4.3, or were scope calls made that should have been Author-level? Any patterns in which agent is most often the `originating_agent_id` on contested advance decisions?

5. **What would change the timeline?** — If one thing changed in the eleven-stage structure, the metrics framework, or the control loop, what would have the most leverage on end-to-end cycle time or quality? Candidates: removing a stage (too granular), splitting a stage (too coarse), changing a delegation level, adding a drift signal, modifying a gate.

### 7.4 Retro outputs

The retro produces three categories of output. Each category has a different handling path:

| Output category | What it is | Handling |
|---|---|---|
| **Drift-cleanup items** | Small fixes: a drift signal name correction, a cross-reference that has gone stale, a gate definition that needs tightening by one sentence | Regular PRs against `openspec/current/workflow.md` via a `change-workflow-cleanup-<YYYY-QN>` change folder; archived immediately after merge |
| **Change folders** | Large structural changes: a stage split or merge, a delegation-level revision, a new metric kind, a control-loop protocol amendment | Full `change-workflow-<aspect>` change proposals; queued and sequenced per the standard OpenSpec process |
| **`change-workflow-*` proposals for timeline shape** | Proposals that alter the stage count, advance transition rules, or phase-grouping mnemonics | Require design.md rationale equivalent to § 2.3 of this spec (why eleven, not ten, not twelve); Pavel's Author-level approval before the change folder opens |

Retro outputs are recorded in `orchestra_journal` as a `retro` event type (a superset of `drift` entries). The journal entry references the quarter, the five-question answers, and the list of output change folders and cleanup PRs proposed.

**Retro is not a gate.** Work does not halt waiting for the retro. The retro is a scheduled signal-review ritual. In-flight work continues through the eleven stages; the retro informs the next quarter's structure but does not pause the current quarter's execution.

---

## 8. Audiences and glossary

### 8.1 Multi-audience entry points

This document is consumed by multiple audiences with different reading contexts. Each audience has a recommended starting point and a "where to go next" pointer. The full document repays a linear reading, but these entry points orient skimming.

**Pavel (principal)**

You are the authority at every Author-delegated stage (0-entry, 2-approval, 9-merge, publish decisions). Start with § 1 Vision to confirm the SDD thesis and delegation model match your operating intent. Then read § 5 Roles to verify the engagement-mode ownership tables reflect how you want to run each engagement type. During active work, your primary touch points are: § 4.3 (Step 2 — Identify candidates) to understand what Maestro will surface to you; § 5.3 (Engagement-mode owner variation) when onboarding a new client; and § 7 (Evolution policy) when a retro quarter arrives. You can override any Maestro routing decision — the HitL gate format in § 4.4 is designed to give you a recommendation with a spec citation, not a fait accompli.

*Where to go next:* `openspec/current/agents/maestro.md` (Maestro's full capability spec, including risk matrix and access scope); `openspec/_methodology/rapoport-studio-engagement.md § 4` (engagement mode source of truth).

**Specialist**

You are a contractor engaged for a specific task within a change. Your work enters the timeline at Stage 4 (Plan) if you are executing a build task, or at Stage 8 (Review) if you are opening a PR directly. You do not own any stage's validation gate without explicit delegation from Pavel. Your entry artifact is always a Linear sub-issue with a task-slug and a link to the change folder. Read § 5.4 (Specialist network participation) for the exact entry protocol. Read § 2 (The eleven stages) at the stage you are entering to understand the validation gate you must satisfy.

*Where to go next:* `openspec/_methodology/specialist-network.md` (specialist engagement contract and onboarding checklist); your assigned Linear sub-issue (carries the task-slug, change-folder link, and expected artifact).

**Client**

You are an external stakeholder in a Hybrid or Full engagement. The eleven stages apply to your work too — what changes is the ownership column (§ 5.3). In a Full engagement, the studio owns Discovery (stages 0–2) and the Build phase (stages 4–7); you co-own Review (stage 8) and own all Ship stages (9–11). In a Deliverables-only or Hybrid engagement, your team owns more of the execution. Read § 5.3 (Engagement-mode owner variation) to see exactly which stages you own in your engagement mode. The stage your work is currently in is always visible in Linear; Maestro tracks it in the journal.

*Where to go next:* `openspec/_methodology/rapoport-studio-engagement.md` (your engagement charter and mode definition); your engagement's Linear epic (the source of truth for which sub-issues are assigned to you).

**AI agent (Maestro, Forge, Muse)**

You are a consumer of this spec as a runtime contract. The sections you implement against are: § 2 (The eleven stages) — the state machine your routing function reads; § 3 (Metrics framework) — the observability layer you write to; § 4 (Maestro control loop) — the four-step loop you execute; § 6 (Drift signals taxonomy) — the pattern library for `drift_note` field values. Every advance decision you record must cite the stage number as the work-item key. Every drift entry must reference a named signal from § 6.1 or declare `drift_note: "unnamed — retro-classify"`. You do not modify `openspec/current/workflow.md` directly — see § 7 (Evolution policy) for the amendment path.

*Where to go next:* `openspec/current/agents-overview.md` (orchestra roster and routing scope); `openspec/current/agents/maestro.md` (Maestro's full capability spec, access scope, and cross-cutting defenses); § 4 of this document (four-step control loop contract).

### 8.2 Glossary

Key terms used throughout this document. Definitions are scoped to this spec's usage; see cross-references for the authoritative source where a term is defined elsewhere.

**Stage.** One of twelve named states in the directed timeline (Capture through Release). A piece of work is in exactly one stage at any moment. Stages do not repeat in the forward direction; regression is re-entry at the last valid stage. The twelve states and eleven advance transitions are listed in § 2.

**Phase grouping.** A mnemonic label that clusters stages into four groups: Discovery (0–2), Spec (3–4), Build (5–8), Ship (9–11). Phase groupings are for human orientation only; they do not appear in routing logic, metrics queries, or journal entries.

**Advance transition.** A validated move from stage N to stage N+1. An advance transition occurs when the validation gate at stage N passes and the next-stage owner is available. Maestro records it as an `advance` journal entry. There are eleven advance transitions (Capture → Frame, Frame → Spec, …, Archive → Release); the twelfth move (Release → done) is terminal.

**Advance candidate.** A work item that has passed its current stage's validation gate and whose next-stage owner is unambiguous and available. Advance candidates are priority-3 in Maestro's candidate identification step (§ 4.3). An advance candidate becomes a decision candidate if the next-stage owner is ambiguous.

**Drift candidate.** A work item whose `time_in_stage` has exceeded the per-stage 95th-percentile threshold (the stuck-stage signal from § 3.4). Maestro records it as a `drift` journal entry and does not auto-advance it. Drift candidates accumulate for retro analysis (§ 7); high-severity signals trigger immediate HitL surface per § 6.3.

**Decision candidate.** A work item whose routing requires a scope call beyond Maestro's authority: the next-stage owner is ambiguous, two agents have claimed or disclaimed the item, or the routing implies a scope change that Pavel must authorize. Decision candidates are priority-1 (§ 4.3); Maestro halts advance and posts the HitL gate format from § 4.4 before proceeding.

**Validation gate.** A blocking condition that must be satisfied before a work item advances from stage N to stage N+1. Gates are correctness preconditions, not metrics. Examples: all `Plan.verificationGates[]` passing (stages 6→7), Pavel's approval on a PR (stage 8→9), all sub-issues `Done` (stage 10 entry). Conflating gates with metrics produces the "metrics that block work" anti-pattern (§ 3 preamble).

**Gate (disambiguation).** The term "gate" is used in two related but distinct senses in this spec: (1) **validation gate** — the stage-advance precondition described above; (2) **HitL gate** — the human-in-the-loop surface mechanism Maestro uses to post decision candidates to Pavel (§ 4.4, `agents/maestro.md § Cross-cutting defenses`). Context disambiguates; "validation gate" is always the stage-advance meaning.

**Delegation level.** One of four levels from the Microsoft Worklab 2026 four-pattern model that declares how much human involvement a stage requires: **Author** (human produces or approves every output), **Editor** (human reviews AI/tool output before advance), **Director** (human sets scope once; agent executes autonomously), **Orchestrator** (human monitors outcomes; agent executes without per-action approval). Full taxonomy in § 5.2.

**Checkpoint.** Within Stage 5 (Build), a checkpoint is a pause point in the build step sequence where Forge reports progress and waits for a signal before continuing. Checkpoints are sub-stage events; they do not appear in the stage-state metrics but do appear in `forge_steps` (Supabase). Defined in `openspec/current/forge/spec.md § Builder mode › Checkpoint model`.

**Orchestra journal (`orchestra_journal`).** The append-only Supabase table that is the canonical record of all stage transitions, drift signals, and decision records across all in-flight work. The journal is the source of truth for all aggregate metrics (§ 3.4) and the retro input (§ 7.3). Schema lands with the `add-knowledge-layout` change. No agent may delete or modify an existing journal row.

**BuildOutcome.** The exit-state enum written by Forge to `.forge/state/<key>.json` (and eventually to `forge_runs`) when a build run terminates. Values include `completed-with-pr` (clean exit), `failed-builder` (gate failure), `failed-push` (push rejected), `failed-pr` (PR creation failed). Used as the quality metric for stages 5 and 7. Defined in `openspec/current/forge/entities.md § BuildOutcome`.

**Wave.** A set of Linear sub-issues dispatched in the same build batch by the Forge conductor (RAP-407). Issues within a wave may be dispatched in parallel (if they touch non-overlapping files) or sequenced (if one is upstream of another). The `epic-conflict` drift signal (§ 6.1) fires when a wave PR has a merge conflict with an upstream wave PR's merge. Defined in `openspec/archive/2026-05-12-add-forge-epic-conductor/design.md`.

**Engagement mode.** One of four operating configurations from `openspec/_methodology/rapoport-studio-engagement.md § 4` that determine ownership across stages 3–11: Internal-studio, Deliverables-only, Hybrid, Full. The stage list is engagement-mode invariant; what changes is the owner column (§ 5.3, design.md Decision D-7).

**Stuck-stage signal.** The per-stage 95th-percentile `time_in_stage` rolling 30-day threshold, used by Maestro to detect drift candidates. When a stage's 95p doubles week-over-week, the signal fires and Maestro generates a `drift` journal entry. One of the three aggregate metrics in § 3.4.

**WIP per stage.** Count of work items currently dwelling in stage X at a given moment. One of the three aggregate metrics (§ 3.4). Used as a capacity signal: Stage 8 (Review) WIP > 5 means the PR queue is bottlenecked; Stage 5 (Build) WIP > 3 means Forge concurrency is saturated. Triggers the `stage-wip-ceiling` drift signal (§ 6.1) when per-stage ceilings are exceeded.

**End-to-end cycle time.** Median wall-clock from Stage 0 `stage_entered_at` to Stage 11 `stage_exited_at`. Lead-time-for-changes proxy (DORA D2). Tracked per quarter; one of the three aggregate metrics (§ 3.4). The retro question "what would change the timeline?" (§ 7.3 Q5) targets this metric.

**Time-in-stage.** Wall-clock duration from `stage_entered_at` to `stage_exited_at` for a specific work item at a specific stage. The primary throughput metric for all stages. Aggregated as median (for capacity planning) and 95th percentile (for drift detection). See § 3.2 for per-stage assignments.

**Metrics vs. gates vs. cost-guards vs. validators.** Four distinct layers that are frequently conflated: **metrics** observe stage transitions (§ 3); **gates** block advance (validation gates, § 2 per-stage prose); **cost-guards** enforce budgets (`CANVAS_BUDGET_CENTS`, per-role caps — enforced by runtime, not by this spec); **validators** enforce contracts (Zod schemas on tool call outputs — enforced by runtime). A metric that blocks work is a gate laundering its identity. See § 3 preamble and § 3.3.

### 8.3 Cross-reference index

Related specs, changes, and methodology documents that this spec cites or is cited by. Every link below was verified at the time this section was authored; links marked `(deferred)` point to documents planned but not yet created.

**Capability specs (`openspec/current/`):**

| Document | Relationship to this spec |
|---|---|
| [`agents/maestro.md`](agents/maestro.md) | Maestro's full capability spec. This spec declares the timeline-controller subset of Maestro's function; `maestro.md` carries the complete routing scope, risk matrix, HitL gate protocol, and access scope. |
| [`agents-overview.md`](agents-overview.md) | Orchestra roster. Declares the six-agent architecture; this spec assigns timeline roles to each agent at specific stages. |
| [`forge/spec.md`](forge/spec.md) | Forge CLI capability spec. Stages 4–7 of this spec map to `forge plan`, `forge build`, Verify/Finalize post-steps, and `forge review` respectively. `BuildOutcome` type and `Plan.verificationGates[]` are defined there. |
| [`muse.md`](muse.md) | Muse capability spec. Architect mode owns stages 1–2; Maestro mode is the timeline controller declared in § 4 of this spec. |
| [`platform.md`](platform.md) | Studio platform overview. Workflow timeline is the operating model layer over the platform; `platform.md § Operating model` will reference this spec after Phase 5 archive. |

**Methodology documents (`openspec/_methodology/`):**

| Document | Relationship to this spec |
|---|---|
| [`rapoport-studio-engagement.md`](_methodology/rapoport-studio-engagement.md) | Source of truth for engagement mode definitions. § 5.3 of this spec cites it as the authority for Internal-studio / Deliverables-only / Hybrid / Full mode definitions. When engagement modes change, both files amend in lockstep. |
| [`specialist-network.md`](_methodology/specialist-network.md) | Specialist engagement contract. § 5.4 of this spec cites it for the specialist entry protocol. |
| [`studio-charter.md`](_methodology/studio-charter.md) | Studio operating charter. Declares the SDD operating thesis that § 1 Vision of this spec implements. |
| [`research/loop-protocol.md`](_methodology/research/loop-protocol.md) | Micro-loop primer. Informs the § 3 metrics aggregates design. |

**In-flight and active change proposals (`openspec/changes/`):**

| Document | Relationship to this spec |
|---|---|
| [`add-forge-epic-conductor/design.md`](../archive/2026-05-12-add-forge-epic-conductor/design.md) | RAP-407. Forge conductor operates within stages 4–7; its wave model and issue-body schema are referenced in § 2 (stages 3–7) and the `epic-conflict` drift signal in § 6.1. |
| [`add-forge-epic-auto-close/proposal.md`](../archive/2026-05-12-add-forge-epic-auto-close/proposal.md) | RAP-408. Auto-merge contract referenced in Stage 9 (§ 2) and the `pr-merge-stalled` drift signal (§ 6.1). |

**Archive (`openspec/archive/`):**

| Document | Relationship to this spec |
|---|---|
| [`2026-05-11-add-forge-productivity-measurement/draft-amendments/forge-productivity-measurement.md`](../archive/2026-05-11-add-forge-productivity-measurement/draft-amendments/forge-productivity-measurement.md) | Forge Productivity Index. Cited in § 3.5 (Goodhart's law mitigation) and § 3.6 (DORA / SPACE / DevEx cross-reference) as the concrete implementation of the anti-vanity rules for the Build phase. |

**Other references:**

| Reference | Cited in |
|---|---|
| `openspec/AGENTS.md § What gets amended where, and when` | § 6.1 (`archive-pending` drift signal), § 7 (evolution policy amendment path), § 10 archive protocol |
| `CLAUDE.md § Hard rule 7` | § 7 (amendment path — `current/` is read-only outside archive steps) |
| Microsoft Worklab 2026 four-pattern model (Author / Editor / Director / Orchestrator) | § 1 Vision, § 5.2 (delegation level taxonomy) |
| DORA metrics framework (Deployment Frequency, Lead Time, Change Failure Rate, MTTR) | § 3.6 (industry framework cross-reference) |
| SPACE framework (Satisfaction, Performance, Activity, Communication, Efficiency) | § 3.6 |
| DevEx framework (feedback loops, cognitive load, flow state) | § 3.6 |
