Merge remote-tracking branch 'origin/main' into feat/generation-queue-management

# Conflicts:
#	src/services/generationPipeline.ts

Author: ChuxiJ

.claude/agents/do-todo.md

@@ -30,22 +30,31 @@ You are a TDD-driven developer agent. Your job is to pick up ONE task and comple
 2. **Ensure you're on the correct branch**:
    - If working on a GitHub Issue: branch should be `feat/issue-NUMBER` or `fix/issue-NUMBER`
    - If branch doesn't exist, create it from main
-3. **Understand** the task — read relevant source files
-4. **Write a failing test first** (Red phase):
+3. **Check for spec context** (spec-aware TDD):
+   - Check if the issue has a `spec:` label: `gh issue view NUMBER --json labels`
+   - If a `spec:<change-name>` label is present, read the actual spec files:
+     - First check `openspec/changes/<change-name>/specs/` (active change)
+     - Fallback: `openspec/specs/` (archived specs)
+     - Use the issue body as supplementary context only (it may drift from source)
+   - Each Given/When/Then scenario becomes at least one test case
+   - MUST/SHALL keywords are mandatory — every MUST must be asserted in the test suite
+4. **Understand** the task — read relevant source files
+5. **Write a failing test first** (Red phase):
    - For store/utility tasks: create a Vitest test in `src/**/__tests__/`
    - For UI/workflow tasks: create a Playwright test in `tests/e2e/`
-5. **Run the test** to confirm it fails: `npm test` or `npx playwright test`
-6. **Implement** the minimum code to make the test pass (Green phase)
-7. **Run all tests** to ensure nothing else broke: `npm test`
-8. **Refactor** if needed while keeping tests green
-9. **Run quality gates**:
-   - `npx tsc --noEmit` — must be 0 errors
-   - `npm test` — all pass
-   - `npm run build` — succeeds
-10. **Mark progress**:
+   - If spec scenarios exist: each Given/When/Then scenario becomes a test case
+6. **Run the test** to confirm it fails: `npm test` or `npx playwright test`
+7. **Implement** the minimum code to make the test pass (Green phase)
+8. **Run all tests** to ensure nothing else broke: `npm test`
+9. **Refactor** if needed while keeping tests green
+10. **Run quality gates**:
+    - `npx tsc --noEmit` — must be 0 errors
+    - `npm test` — all pass
+    - `npm run build` — succeeds
+11. **Mark progress**:
     - If from `.llm/todo.md`: change `- [ ]` to `- [x]`
     - If from GitHub Issue: note the issue number in your commit
-11. **Commit** with a conventional commit message:
+12. **Commit** with a conventional commit message:
     ```
     git add -A
     # Use an appropriate conventional commit type: feat, fix, refactor, test, docs, etc.

.claude/agents/product-manager.md

@@ -18,11 +18,13 @@ You are the product manager for ACE-Step DAW. Your job is to translate research
 - Design guides in `docs/design/`
 - User feedback (provided in your task prompt)
 - Current state of `docs/design/UX_IMPROVEMENT_CHECKLIST.md`
+- Existing OpenSpec specs in `openspec/specs/` (living behavior contracts)
 
 ## Outputs
-1. File prioritized tasks as GitHub Issues with priority labels (`priority: P0`/`P1`/`P2`/`P3`)
-2. Update `docs/design/UX_IMPROVEMENT_CHECKLIST.md` with status changes
-3. Write feature specs as GitHub Issue bodies (detailed acceptance criteria)
+1. For features touching 3+ files: recommend running `/opsx:propose` in a main session to create formal specs with Given/When/Then scenarios BEFORE filing issues (note: this agent cannot run slash commands directly — flag the recommendation in the issue body)
+2. File prioritized tasks as GitHub Issues with priority labels (`priority: P0`/`P1`/`P2`/`P3`)
+3. Update `docs/design/UX_IMPROVEMENT_CHECKLIST.md` with status changes
+4. Write feature specs as GitHub Issue bodies (detailed acceptance criteria, referencing OpenSpec if available)
 
 ## Prioritization Rules
 - P0: Blocks users from basic usage (crash, data loss, no audio)

.claude/agents/tester.md

@@ -22,17 +22,25 @@ You are a QA agent. Your job is to run the full test suite, analyze results, and
    npm test 2>&1
    npm run build 2>&1
    ```
-2. **Analyze results**:
+2. **Spec validation** (if given a change name or spec-labeled issues exist):
+   - If a change name is provided: read specs from `openspec/changes/<name>/specs/` or `openspec/specs/`
+   - Otherwise: find active spec labels via `gh issue list --repo ace-step/ACE-Step-DAW --json labels --jq '[.[].labels[].name | select(startswith("spec:"))] | unique'`
+   - For each spec change, read the actual spec files (source of truth, not issue bodies)
+   - Extract MUST/SHALL requirements from spec files
+   - Search test files for corresponding test cases covering those requirements
+   - Report any uncovered MUST/SHALL as a spec gap
+   - Scope: only validate specs relevant to the current task/PR, not entire repo history
+3. **Analyze results**:
    - Collect all errors, warnings, and test failures
    - For each failure, identify the root cause (read the failing test + source)
-   - Categorize: type error | test failure | build error | runtime error
-3. **Create fix tasks** — file as GitHub Issues with label `bug` and `priority: P1` if tools are available.
+   - Categorize: type error | test failure | build error | runtime error | spec gap
+4. **Create fix tasks** — file as GitHub Issues with label `bug` and `priority: P1` if tools are available.
    Fallback: append to `.llm/todo.md` under appropriate priority:
    - Type errors -> Priority 1 (blocks everything)
    - Test failures -> Priority 1
    - Build errors -> Priority 1
    - Code quality issues -> Priority 3
-4. **Generate report** to `.llm/reports/test-report-<date>.md`:
+5. **Generate report** to `.llm/reports/test-report-<date>.md`:
    ```markdown
    ## Test Report — <date>
 
@@ -44,6 +52,10 @@ You are a QA agent. Your job is to run the full test suite, analyze results, and
    | Test | Error | Root Cause | Fix Task |
    |------|-------|------------|----------|
 
+   ### Spec Coverage (if applicable)
+   | Spec Change | MUST/SHALL | Covered | Gap |
+   |-------------|-----------|---------|-----|
+
    ### Coverage Summary
    - Statements: X%
    - Branches: X%

.claude/commands/opsx/apply.md

@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:propose <name>` to complete missing artifacts
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly