maestro-flow 0.3.15 → 0.3.17

package/.claude/commands/manage-knowhow-capture.md

@@ -0,0 +1,193 @@
+---
+name: manage-knowhow-capture
+description: Capture reusable knowledge into .workflow/knowhow/ — session compact, template, recipe, reference, decision, or tip
+argument-hint: "[type] [description] [--lang <lang>] [--source <url>] [--tag tag1,tag2]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
+Six content types, each optimized for a different reuse pattern. All entries are automatically
+indexed by WikiIndexer (type=knowhow) and searchable via `maestro knowhow search`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Types:**
+
+| Type | Prefix | Use Case | Key Fields |
+|------|--------|----------|------------|
+| `compact` | KNW- | Session state recovery | objective, files, decisions, plan, pending |
+| `template` | TPL- | Code/config templates | language, code block, usage context |
+| `recipe` | RCP- | Step-by-step how-to | prerequisites, steps, expected outcome |
+| `reference` | REF- | External doc / API quick-ref | source URL, key points, scenarios |
+| `decision` | DCS- | Design decision record | context, alternatives, rationale, consequences |
+| `tip` | TIP- | Quick note / reminder | content, tags |
+
+No arguments: auto-detect type or ask user via AskUserQuestion.
+
+**Flags:**
+- `--lang <lang>` — Language for templates (typescript, python, bash, yaml, etc.)
+- `--source <url>` — Source URL for references
+- `--tag tag1,tag2` — Categorization tags
+- `--title <title>` — Explicit title (auto-generated if omitted)
+</context>
+
+<execution>
+
+### Step 1: Detect Type
+
+Parse first token as type. If ambiguous, AskUserQuestion with options:
+
+| Token Match | Type |
+|-------------|------|
+| `compact`, `session`, `压缩`, `保存` | compact |
+| `template`, `tpl`, `模板` | template |
+| `recipe`, `rcp`, `配方`, `步骤` | recipe |
+| `reference`, `ref`, `参考`, `引用` | reference |
+| `decision`, `dcs`, `决策`, `adr` | decision |
+| `tip`, `note`, `记录`, `快速` | tip |
+| No match, short text, `--tag` present | tip |
+| No arguments | AskUserQuestion (6 options) |
+
+### Step 2: Generate Content by Type
+
+#### compact (KNW-{YYYYMMDD}-{HHMM}.md)
+
+Extract from conversation history:
+- **Session ID** — WFS-* if workflow session active, else `manual-{date}`
+- **Project Root** — Absolute path
+- **Objective** — High-level goal
+- **Execution Plan** — Source + complete verbatim content (never summarize)
+- **Working Files** — Modified files with roles (absolute paths, 3-8 files)
+- **Reference Files** — Read-only context files
+- **Last Action** — Final action + result
+- **Decisions** — Table: decision | reasoning
+- **Constraints** — User-specified limitations
+- **Dependencies** — Added/changed packages
+- **Known Issues** — Deferred bugs
+- **Changes Made** — Completed modifications
+- **Pending** — Next steps
+- **Notes** — Unstructured thoughts
+
+Plan detection priority: workflow session IMPL_PLAN.md > TodoWrite items > user-stated > inferred.
+
+#### template (TPL-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Language / Tech** — `--lang` flag or inferred from context
+- **Usage** — When/how to use this template
+- **Code** — The template content (ask user to provide or select from conversation)
+- **Parameters** — Placeholders to replace (e.g. `{{name}}`, `{{port}}`)
+- **Dependencies** — Required packages/config
+- **Tags** — From `--tag` flag
+
+If code not provided explicitly, prompt user: "Paste the template code:"
+
+#### recipe (RCP-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Goal** — What this recipe accomplishes
+- **Prerequisites** — Tools, access, config needed
+- **Steps** — Numbered step-by-step instructions
+- **Expected Outcome** — What success looks like
+- **Common Pitfalls** — Known issues / gotchas
+- **Related** — Links to templates, references, decisions used
+- **Tags** — From `--tag` flag
+
+If steps not clear, prompt user: "Describe the steps (numbered list):"
+
+#### reference (REF-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Source** — `--source` flag (URL, doc title, API endpoint)
+- **Key Points** — Bullet list of essential info
+- **Applicable Scenarios** — When to consult this reference
+- **Quick Examples** — Copy-paste ready code snippets
+- **Last Verified** — Date (today)
+- **Tags** — From `--tag` flag
+
+If `--source` provided, offer to fetch and summarize via WebFetch.
+
+#### decision (DCS-{YYYYMMDD}-{HHMM}.md)
+
+Ask for or extract:
+- **Context** — Background and problem statement
+- **Decision** — What was decided
+- **Alternatives Considered** — Table: alternative | pros | cons | rejected because
+- **Rationale** — Why this choice over alternatives
+- **Consequences** — Positive and negative impact
+- **Related** — Links to affected specs, recipes, templates
+- **Date** — Decision date
+- **Status** — proposed | accepted | superseded
+
+#### tip (TIP-{YYYYMMDD}-{HHMM}.md)
+
+Simple note:
+- **Content** — Everything after type token (or full $ARGUMENTS)
+- **Context** — Auto-detected from recent conversation files
+- **Tags** — From `--tag` flag
+- **Timestamp** — ISO format
+
+### Step 3: Write File
+
+Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter:
+
+```yaml
+---
+title: {auto or --title}
+type: {type}
+category: {type}
+created: {ISO timestamp}
+tags: [{tags}]
+source: {url if reference}
+lang: {language if template}
+status: {status if decision}
+---
+{markdown body}
+```
+
+### Step 4: Confirm
+
+```
+=== KNOWHOW CAPTURED ===
+Type: {type}
+ID:   knowhow-{slug}
+File: .workflow/knowhow/{filename}
+
+{type-specific summary line}
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | error | Template: no code provided after prompt | template |
+| E003 | error | Recipe: no steps provided after prompt | recipe |
+| W001 | warning | No active workflow session — compact captures conversation only | compact |
+| W002 | warning | Plan detection found no explicit plan — using inferred plan | compact |
+| W003 | warning | `--source` URL could not be fetched — proceeding with manual entry | reference |
+</error_codes>
+
+<success_criteria>
+- [ ] Type correctly detected or selected
+- [ ] All type-specific fields populated (not empty)
+- [ ] YAML frontmatter written with correct fields
+- [ ] Markdown body follows type structure
+- [ ] File written to `.workflow/knowhow/` with correct prefix
+- [ ] Auto-indexed by WikiIndexer (type=knowhow)
+- [ ] Confirmation displayed with ID, type, file path
+- [ ] Next step hint appropriate to type shown
+</success_criteria>

package/.claude/commands/{manage-memory.md → manage-knowhow.md}

@@ -1,88 +1,77 @@
----
-name: manage-memory
-description: Manage memory entries — workflow memory (.workflow/memory/) and system memory (~/.claude/projects/*/memory/)
-argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type compact|tip]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Unified memory management across two stores:
-1. **Workflow memory** (`.workflow/memory/`) — Session compacts and tips with JSON index, created by `manage-memory-capture`
-2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
-
-Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/memory.md
-</required_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Stores:**
-
-| Store | Path | Format | Index |
-|-------|------|--------|-------|
-| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` (legacy only — new tips go to `manage-learn tip`) | `.workflow/wiki-index.json` (unified) |
-| `system` | `~/.claude/projects/{project}/memory/` | `MEMORY.md` + topic `.md` files | None (flat files) |
-
-**System memory path detection:**
-```bash
-# Derive from project root — replace path separators with '--', prefix drive letter
-# e.g., D:\maestro2 → ~/.claude/projects/D--maestro2/memory/
-```
-
-**Subcommands:**
-- `list` — List entries from both stores (default if no arguments)
-- `search <query>` — Full-text search across both stores
-- `view <id|file>` — Display a workflow entry by ID or system file by name
-- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
-- `delete <id|file>` — Remove an entry/file (with confirmation)
-- `prune` — Bulk cleanup by criteria
-
-**Flags:**
-- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
-- `--tag <tag>` — Filter by tag (workflow store)
-- `--type <compact|tip>` — Filter by entry type (workflow store)
-- `--before <YYYY-MM-DD>` — Entries before date
-- `--after <YYYY-MM-DD>` — Entries after date
-- `--dry-run` — Preview destructive ops without executing
-- `--confirm` — Skip confirmation prompt
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/memory.md' Part A (Memory Management) completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | No memory stores found — run `/manage-memory-capture` or create MEMORY.md | resolve_paths |
-| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
-| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
-| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
-| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
-| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
-| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
-</error_codes>
-
-<success_criteria>
-- [ ] Both store paths correctly resolved
-- [ ] Subcommand correctly detected from arguments
-- [ ] Store auto-detected from argument format (MEM-*/TIP-* vs filename)
-- [ ] List: both stores displayed with appropriate formatting
-- [ ] Search: results from both stores, ranked by relevance
-- [ ] View: correct store selected, full content displayed
-- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
-- [ ] Delete: MEMORY.md protected, confirmation required, references checked
-- [ ] Prune: workflow-only, filters validated, index updated
-- [ ] Integrity check catches orphans and broken links
-- [ ] Next step: `/manage-memory-capture compact` to save new memory, or `/manage-status` to continue workflow
-</success_criteria>
+---
+name: manage-knowhow
+description: Manage memory entries — workflow memory (.workflow/knowhow/) and system memory (~/.claude/projects/*/memory/)
+argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type compact|tip]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified memory management across two stores:
+1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts and tips with JSON index, created by `manage-knowhow-capture`
+2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
+
+Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
+
+**Subcommands:**
+- `list` — List entries from both stores (default if no arguments)
+- `search <query>` — Full-text search across both stores
+- `view <id|file>` — Display a workflow entry by ID or system file by name
+- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
+- `delete <id|file>` — Remove an entry/file (with confirmation)
+- `prune` — Bulk cleanup by criteria
+
+**Flags:**
+- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
+- `--tag <tag>` — Filter by tag (workflow store)
+- `--type <compact|tip>` — Filter by entry type (workflow store)
+- `--before <YYYY-MM-DD>` — Entries before date
+- `--after <YYYY-MM-DD>` — Entries after date
+- `--dry-run` — Preview destructive ops without executing
+- `--confirm` — Skip confirmation prompt
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | No memory stores found — run `/manage-knowhow-capture` or create MEMORY.md | resolve_paths |
+| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
+| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
+| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
+| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
+| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
+</error_codes>
+
+<success_criteria>
+- [ ] Both store paths correctly resolved
+- [ ] Subcommand correctly detected from arguments
+- [ ] Store auto-detected from argument format (KNW-*/TIP-* vs filename)
+- [ ] List: both stores displayed with appropriate formatting
+- [ ] Search: results from both stores, ranked by relevance
+- [ ] View: correct store selected, full content displayed
+- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
+- [ ] Delete: MEMORY.md protected, confirmation required, references checked
+- [ ] Prune: workflow-only, filters validated, index updated
+- [ ] Integrity check catches orphans and broken links
+- [ ] Next step: `/manage-knowhow-capture compact` to save new knowhow, or `/manage-status` to continue workflow
+</success_criteria>

package/.claude/commands/manage-learn.md

@@ -14,7 +14,7 @@ allowed-tools:
 <purpose>
 Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
 - **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
-- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-memory-capture tip`)
+- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
 
 Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
 </purpose>
@@ -34,36 +34,11 @@ Arguments: $ARGUMENTS
 - `show <INS-id>` → full detail with phase context
 - empty → AskUserQuestion to prompt for text
 
-**Capture flags (both insight and tip modes):**
-- `--category <name>` — pattern | antipattern | decision | tool | gotcha | technique | tip. Default: inferred from text via keyword heuristics. Tip mode defaults to `tip`.
-- `--tag t1,t2` — comma-separated tags. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`.
-- `--phase <N>` — override auto-detected current phase. Use `--phase 0` to force "no phase".
-- `--confidence <level>` — high | medium | low. Default: medium (insight), low (tip).
-
-**List/search flags:**
-- `--tag t1,t2` — filter by tag
-- `--category <name>` — filter by category
-- `--phase <N>` — filter by phase
-- `--lens <name>` — filter by retrospective lens (technical | process | quality | decision | git). Note: `git` matches `source: "retro-git"` from learn-retro; others match `lens` field from quality-retrospective.
-- `--limit <N>` — list mode row limit (default 20)
-
-**Storage:**
-- `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with `quality-retrospective` output)
-- `.workflow/learning/learning-index.json` — searchable index
-
-**Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
+Flags, storage paths, and shared store rationale defined in workflow learn.md.
 </context>
 
 <execution>
-Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
-
-1. **No agent or CLI calls** — this is a pure file operation: parse → infer → append → confirm. Category inference is keyword-based, not LLM-based.
-2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and derive phase context from artifact registry (`state.json.artifacts[]`). `--phase 0` forces no link.
-3. **Index schema** — `learning-index.json` entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, confidence, routed_to, routed_id.
-4. **Stable INS ids** — `INS-{8 lowercase hex}` from `hash(insight_text + category + phase)`. Deterministic: same content in same context always produces the same ID.
-5. **Append-only lessons.jsonl** — never rewrite existing rows; duplicate detection is the user's job at search time.
-6. **Bootstrap on demand** — create `.workflow/learning/`, `lessons.jsonl`, `learning-index.json` on first use; do not require them to exist upfront.
-7. **Tip mode** — when first token is `tip`, set `source: "tip"`, `category: "tip"`, `confidence: "low"`, and implicitly add `tip` tag. Everything else follows the same pipeline as insight capture. This replaces the former `manage-memory-capture tip` mode.
+Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 </execution>
 
 <error_codes>

package/.claude/commands/manage-status.md

@@ -30,26 +30,7 @@ $ARGUMENTS (no arguments required)
 <execution>
 Follow '~/.maestro/workflows/status.md' completely.
 
-**Next-step decision table:**
-| Current state | Suggested command | Reason |
-|---------------|-------------------|--------|
-| No phases planned | `/maestro-brainstorm 1` or `/maestro-plan 1` | Explore ideas or start planning first phase |
-| Phase pending, needs analysis | `/maestro-analyze <N>` | Evaluate feasibility before planning |
-| Phase pending, needs decisions | `/maestro-analyze <N> -q` | Quick decision extraction |
-| Phase planned, not executed | `/maestro-execute <N>` | Execute the planned phase |
-| Phase executing, tasks blocked | `/quality-debug <N>` | Unblock stuck tasks |
-| Phase executed, not verified | `/maestro-verify <N>` | Verify execution results |
-| Phase verified with gaps | `/maestro-plan <N> --gaps` | Plan gap fixes |
-| Phase verified, not reviewed | `/quality-review <N>` | Code quality review before UAT |
-| Phase reviewed, verdict BLOCK | `/maestro-plan <N> --gaps` | Fix critical review findings first |
-| Phase reviewed, verdict PASS/WARN | `/quality-test <N>` | Proceed to UAT testing |
-| Phase verified, low test coverage | `/quality-test-gen <N>` | Generate missing automated tests |
-| UAT passed, all phases done | `/maestro-milestone-audit` | Cross-phase integration check |
-| UAT has failures | `/quality-debug --from-uat <N>` | Debug UAT gaps with parallel agents |
-| Need integration test cycle | `/quality-integration-test <N>` | Self-iterating integration tests |
-| All phases in milestone complete | `/maestro-milestone-audit` | Cross-phase integration check |
-| Milestone audit passed | `/maestro-milestone-complete` | Archive milestone, advance |
-| Ad-hoc small task | `/maestro-quick <task>` | Quick execute without full pipeline |
+Next-step decision table defined in workflow status.md Step 5.
 </execution>
 
 <error_codes>

package/.claude/commands/manage-wiki.md

@@ -34,7 +34,7 @@ $ARGUMENTS — subcommand and optional flags.
 | No args | Same as `health` |
 
 **Flags:**
-- `--type <type>` — Filter by wiki type: spec, memory, note, lesson, issue
+- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
 - `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
 - `--json` — Output in JSON format
 </context>

package/.claude/commands/quality-business-test.md

@@ -70,7 +70,7 @@ Context files:
 Follow '~/.maestro/workflows/business-test.md' completely.
 
 **Next-step routing on completion:**
-- All requirements verified → `/maestro-phase-transition {phase}`
+- All requirements verified → `/maestro-milestone-audit`
 - Failures found → `/quality-debug --from-business-test {phase}`
 - Re-run all pass → `/maestro-verify {phase}`
 - Low coverage → `/quality-test-gen {phase}`

package/.claude/commands/quality-debug.md

@@ -13,19 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Debug issues using scientific method with subagent isolation and persistent debug state. Supports three entry modes:
-
-1. **Standalone**: User describes an issue, gather symptoms interactively
-2. **From UAT**: `--from-uat` reads uat.md gaps as pre-filled symptoms (skip gathering)
-3. **Parallel**: `--parallel` spawns one debug agent per gap cluster concurrently
-
-When root causes are found, updates the originating uat.md with diagnosis artifacts (root_cause, fix_direction, affected_files) so the UAT -> debug -> fix pipeline stays connected.
-
-Key mechanisms from GSD diagnose-issues:
-- **Pre-filled symptoms from UAT**: Skip 5-question gathering when gaps already documented
-- **Parallel debug agents**: One agent per gap cluster for concurrent investigation
-- **Structured root cause collection**: Standardized output format across all agents
-- **UAT feedback loop**: Auto-update uat.md gaps with diagnosis results
+Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
 </purpose>
 
 <required_reading>
@@ -55,15 +43,12 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 
 Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
 
-**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone)
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/debug.md' completely.
 
-**Output writes to DEBUG_DIR** (`scratch/{YYYYMMDD}-debug-P{N}-{slug}/`):
-- understanding.md, evidence.ndjson, diagnosis-summary.json
-
 **Register artifact on completion (phase-scoped only):**
 ```
 Append to state.json.artifacts[]:
@@ -73,7 +58,7 @@ Append to state.json.artifacts[]:
   milestone: current_milestone,
   phase: target_phase,
   scope: "phase",
-  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",  // or {YYYYMMDD}-debug-{slug} for standalone
+  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",
   status: all_diagnosed ? "completed" : "failed",
   depends_on: triggering_review_id || exec_art.id,
   harvested: false,

package/.claude/commands/quality-integration-test.md

@@ -13,15 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Run a self-iterating integration test cycle that combines exploration, test design, test execution, reflection, and adaptive strategy adjustment. Unlike quality-test (UAT with user) or quality-test-gen (generate missing tests), this command runs automated integration tests in a closed loop that self-corrects until convergence.
-
-Key mechanisms from DMS3 integration-test-cycle:
-- **6-phase cycle**: Explore -> Design -> Develop -> Test -> Reflect -> Adjust
-- **Reflection-driven**: After each iteration, reflect on what worked/failed and adjust strategy
-- **Adaptive strategy engine**: Conservative (iter 1-2) -> Aggressive (>80% similar) -> Surgical (regression) -> Reflective (stuck 3+)
-- **L0-L3 progressive layers**: Static Analysis -> Unit -> Integration -> E2E
-- **Self-iterating**: Loop continues until pass rate threshold met or max iterations reached
-- **State persistence**: state.json + reflection-log.md survive context resets
+Run a self-iterating integration test cycle that combines exploration, test design, test execution, reflection, and adaptive strategy adjustment. Unlike quality-test (UAT with user) or quality-test-gen (generate missing tests), this command runs automated integration tests in a closed loop that self-corrects until convergence. Full 6-phase cycle, adaptive strategy engine, and L0-L3 progressive layers defined in workflow integration-test.md.
 </purpose>
 
 <required_reading>
@@ -35,26 +27,14 @@ Phase: $ARGUMENTS (required -- phase number)
 - `--max-iter <N>` -- Maximum iterations (default: 5)
 - `--layer <L0|L1|L2|L3>` -- Start from specific layer (default: auto-detect)
 
-**L0-L3 Progressive Test Layers:**
-
-| Layer | Name | What | Tools |
-|-------|------|------|-------|
-| L0 | Static Analysis | Type checking, lint, dead code | `tsc --noEmit`, `eslint`, `ruff` |
-| L1 | Unit Tests | Function-level isolation tests | jest, vitest, pytest |
-| L2 | Integration Tests | Cross-module, API, DB tests | supertest, pytest + fixtures |
-| L3 | E2E Tests | Full user flow tests | playwright, cypress, selenium |
-
-**State files (in `.tests/integration/`):**
-- `state.json` -- iteration state, pass rates, strategy
-- `reflection-log.md` -- per-iteration reflections
-- `test-results-iter-{N}.json` -- results per iteration
+L0-L3 layer definitions, state file formats, and strategy engine rules defined in workflow integration-test.md.
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/integration-test.md' completely.
 
 **Next-step routing on completion:**
-- Converged (pass rate met) → `/maestro-phase-transition {phase}`
+- Converged (pass rate met) → `/maestro-milestone-audit`
 - Max iterations, pass rate close → `/quality-debug {phase}` (investigate remaining failures)
 - Regressions detected → `/quality-debug {phase}`
 - Stuck 3+ iterations → `/maestro-analyze {phase} -q` (reassess approach)

package/.claude/commands/quality-retrospective.md

@@ -30,34 +30,7 @@ Post-execution multi-perspective retrospective (复盘) for completed phases. Co
 <context>
 Arguments: $ARGUMENTS
 
-**Modes (auto-detected from first non-flag token):**
-- No phase argument → `scan` mode: report unreviewed completed phases, prompt selection
-- `<N>` → `single` mode: retrospect phase N
-- `<N>..<M>` → `range` mode: retrospect phases N through M (inclusive)
-- `--all` → batch mode: re-run for every completed phase (archives existing retrospective.json)
-
-**Flags:**
-- `--lens <name>` — restrict to one lens; allowed: technical, process, quality, decision (repeatable)
-- `--no-route` — produce retrospective.{md,json} only; skip auto-creation of spec/note/issue
-- `--compare <M>` — emit a delta section vs phase M's prior retrospective
-- `--auto-yes` — accept all routing recommendations without prompting
-
-**Storage written:**
-- Retrospective output (resolve via `state.json.artifacts[]` → `.workflow/scratch/` path):
-  - retrospective.md — human-readable record
-  - retrospective.json — structured record
-- `.workflow/specs/{category-file}.md` — `<spec-entry>` entries appended to matching category files (one per spec-routed insight)
-- `.workflow/issues/issues.jsonl` — appended issue rows (`source: "retrospective"`)
-- `.workflow/learning/lessons.jsonl` — tips routed via `manage-learn tip` (formerly manage-memory-capture)
-- `.workflow/learning/lessons.jsonl` — append-only insight log
-- `.workflow/learning/learning-index.json` — searchable index
-
-**Storage read (never modified):**
-- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths):
-  - index.json, plan.json, verification.json, review.json, uat.md
-  - .task/TASK-*.json, .summaries/TASK-*-summary.md
-- `.workflow/issues/issues.jsonl`, `.workflow/issues/issue-history.jsonl`
-- `.workflow/state.json`
+Modes (scan/single/range/all), flags (--lens, --no-route, --compare, --auto-yes), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
 </context>
 
 <execution>