maestro-flow 0.3.12 → 0.3.14

package/.claude/CLAUDE.md

@@ -17,3 +17,10 @@ Available CLI endpoints are dynamically defined by the config file
 
 - **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation
 
+## Knowledge Capture
+
+- **Spec writes** → always `<spec-entry>` closed-tag format with `category`, `keywords`, `date`, `source`. Never raw Markdown. Route through `spec-add` when possible.
+- **Capture signal** → when execution surfaces non-obvious knowledge (plan deviation, retry pattern, root cause, constraint violation), ask user once whether to persist it. Match category to content: decisions→`arch`, pitfalls→`debug`/`learning`, patterns→`coding`, rules→`quality`.
+- **Promotion** → at milestone close, scan learnings for repeated keywords (≥2 entries) and offer to graduate them into formal conventions.
+- **Traceability** → every entry needs a source anchor: `file:line`, `INS-{id}`, commit, or phase path.
+

package/.claude/agents/workflow-analyzer.md

@@ -95,7 +95,6 @@ N/A -- produces markdown analysis document
 ## Output Location
 
 - **Scratch**: `.workflow/scratch/{topic-slug}/analysis.md`
-- **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
 
 The caller specifies the output path. If no path is specified, default to scratch mode using the subject as the slug.
 

package/.claude/agents/workflow-collab-planner.md

@@ -133,7 +133,6 @@ You are a collaborative planner that works within a pre-allocated task ID range.
 - **Scratch tasks**: `.workflow/scratch/{slug}/.task/TASK-{NNN}.json` (within assigned ID range only)
 - **Plan notes**: `.workflow/scratch/{slug}/plan-note.md` (append your section, do not overwrite others)
 - **Never write**: plan.json (that is the coordinating planner's responsibility)
-- **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
 
 ## Error Behavior
 - **ID range conflict** (task ID already exists): Stop and report -- do not overwrite; note conflict in plan-note.md

package/.claude/agents/workflow-debugger.md

@@ -86,7 +86,6 @@ Each line in evidence.ndjson:
 
 ## Output Location
 - **Scratch debugging**: `.workflow/scratch/debug-{slug}/understanding.md` and `.workflow/scratch/debug-{slug}/evidence.ndjson`
-- **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
 - **Code fixes**: Applied directly to project source files (not in .debug directory)
 
 ## Error Behavior

package/.claude/agents/workflow-integration-checker.md

@@ -38,11 +38,11 @@ N/A -- reads code artifacts, not task JSON.
 
 ## Input
 - Completed phase artifacts (code, configs, tests)
-- Phase/scratch definitions (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/`)
+- Phase/scratch definitions (resolved via state.json artifact registry)
 - Task summaries from `.summaries/`
 
 ## Output Location
-`.workflow/scratch/{milestone}/integration-audit.md` (legacy fallback: `.workflow/phases/{milestone}/`)
+`.workflow/scratch/{milestone}/integration-audit.md`
 
 ## Output
 Integration audit report at the output location above:

package/.claude/agents/workflow-nyquist-auditor.md

@@ -44,7 +44,6 @@ You audit test coverage by mapping requirements to test files, calculating cover
 - Test results: `.workflow/scratch/{slug}/.tests/test-results.json`
 - Coverage report: `.workflow/scratch/{slug}/.tests/coverage-report.json`
 - Generated test stubs: appropriate test directories within the project source tree
-- **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
 
 ## Output
 - `validation.json`:

package/.claude/agents/workflow-phase-researcher.md

@@ -33,7 +33,7 @@ You research the implementation approach for a specific phase of the roadmap. Yo
 - Research summary from `.workflow/research/SUMMARY.md` (if available)
 
 ## Output
-`.workflow/scratch/{slug}/research.md` (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/{NN}-{slug}/research.md`).
+`.workflow/scratch/{slug}/research.md` (resolved via state.json artifact registry).
 
 Structure:
 ```
@@ -69,7 +69,7 @@ Structure:
 N/A -- produces markdown research document
 
 ## Output Location
-`.workflow/scratch/{slug}/research.md` (legacy fallback: `.workflow/phases/{NN}-{slug}/`)
+`.workflow/scratch/{slug}/research.md`
 
 ## Error Behavior
 - If codebase analysis (`.workflow/codebase/`) is unavailable, note as limitation and proceed with external research only

package/.claude/agents/workflow-plan-checker.md

@@ -44,7 +44,7 @@ You validate the quality of execution plans before they proceed to implementatio
 - **Project specs** — `maestro spec load --category arch`: verify tasks comply with architecture constraints and module boundaries
 
 ## Output Location
-`.workflow/scratch/{slug}/plan-check.md` (legacy fallback: `.workflow/phases/{NN}-{slug}/`)
+`.workflow/scratch/{slug}/plan-check.md`
 
 ## Output
 Check report written to the output location above:

package/.claude/agents/workflow-planner.md

@@ -35,7 +35,7 @@ When invoked with `quick` flag:
 - Focus on getting to execution fast
 
 ## Input
-- `.workflow/scratch/{slug}/context.md` -- Context and decisions (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/{NN}-{slug}/`)
+- `.workflow/scratch/{slug}/context.md` -- Context and decisions (resolved via state.json artifact registry)
 - `.workflow/scratch/{slug}/research.md` -- Research (if available, resolved via artifact registry)
 - Spec references and doc-index
 - **Project specs** (MANDATORY) -- Loaded via `maestro spec load --category arch`:
@@ -167,7 +167,6 @@ When invoked with `quick` flag:
 - **Scratch planning**: `.workflow/scratch/{slug}/plan.json` and `.workflow/scratch/{slug}/.task/TASK-{NNN}.json`
 - **Plan notes** (collab mode): `.workflow/scratch/{slug}/plan-note.md`
 - **Quick mode**: Same paths, fewer task files
-- **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
 
 ## Error Behavior
 - **Missing context.md**: Stop and report -- planning requires context; do not guess

package/.claude/agents/workflow-roadmapper.md

@@ -60,7 +60,7 @@ You create a phased project roadmap from research findings and requirements. You
 
 Phase identifiers use lowercase kebab-case slug names (e.g., `auth`, `api-layer`, `ui-components`).
 
-These identifiers become scratch directory names under `.workflow/scratch/{slug}/` (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/{NN}-{slug}/`).
+These identifiers become scratch directory names under `.workflow/scratch/{slug}/` (resolved via state.json artifact registry).
 
 ## Schema Reference
 `@templates/roadmap.md` -- roadmap template

package/.claude/agents/workflow-verifier.md

@@ -107,7 +107,6 @@ You perform goal-backward verification of completed work using a three-layer che
 
 ## Output Location
 - **Scratch verification**: `.workflow/scratch/{slug}/verification.json`
-- **Legacy fallback**: `.workflow/phases/{NN}-{slug}/` paths are still recognized for backward compatibility
 - **Per-task verification**: Embedded in the `convergence_check` block within verification.json (not separate files)
 
 ## Error Behavior

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

@@ -52,7 +52,7 @@ Arguments: $ARGUMENTS
 - `.workflow/learning/lessons.jsonl` — Existing insights for dedup
 - `maestro wiki list --type spec --json` — Spec entries (decision lens)
 - `.workflow/specs/architecture-constraints.md` — Documented architectural decisions (decision lens)
-- Phase context with Locked/Free/Deferred decisions (decision lens) — resolve via `state.json.artifacts[]` scratch paths, fallback to `.workflow/phases/*/context.md`
+- Phase context with Locked/Free/Deferred decisions (decision lens) — resolve via `state.json.artifacts[]` scratch paths
 </context>
 
 <execution>
@@ -146,7 +146,7 @@ git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
 
 Also read:
 - `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry category="arch"` blocks
-- Phase context files — resolve via `state.json.artifacts[]` scratch paths (fallback: `.workflow/phases/*/context.md`) — scan for "Locked:", "Deferred:" sections
+- Phase context files — resolve via `state.json.artifacts[]` scratch paths — scan for "Locked:", "Deferred:" sections
 - `.workflow/learning/lessons.jsonl` — filter `category == "decision"`
 
 Apply scope filter (--phase, --tag, --id).

package/.claude/commands/learn-second-opinion.md

@@ -28,7 +28,7 @@ Arguments: $ARGUMENTS
 - File path → analyze that file's content
 - Wiki ID (`<type>-<slug>`) → fetch via `maestro wiki get`
 - `HEAD` or `staged` → analyze current git diff (`git diff HEAD` or `git diff --staged`)
-- Phase number (e.g., `3`) → resolve via `state.json.artifacts[]` to find plan in scratch dir; fallback to `.workflow/phases/{NN}-*/plan.json`
+- Phase number (e.g., `3`) → resolve via `state.json.artifacts[]` to find plan in scratch dir
 
 **Flags:**
 - `--mode review` — 3-persona parallel review (default)
@@ -54,7 +54,7 @@ Arguments: $ARGUMENTS
 - Wiki ID: `maestro wiki get <id>`
 - `HEAD`: `git diff HEAD` (unstaged + staged changes)
 - `staged`: `git diff --staged`
-- Phase N: Resolve via `state.json.artifacts.find(a => a.type === 'plan' && a.phase === N)` → read `.workflow/{artifact.path}/plan.json`; fallback to `.workflow/phases/{NN}-*/plan.json`
+- Phase N: Resolve via `state.json.artifacts.find(a => a.type === 'plan' && a.phase === N)` → read `.workflow/{artifact.path}/plan.json`
 - If unresolvable, AskUserQuestion for clarification
 
 ### Stage 2: Load Context

package/.claude/commands/maestro-analyze.md

@@ -53,7 +53,15 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 
 **Scope detection rule**: Text argument + `state.json.current_milestone` non-null → adhoc. Text argument + no milestone → standalone. No args + no roadmap → error (need topic or roadmap). `--gaps` → gaps scope (bypasses standard scope routing).
 
-**Output directory**: `scratch/analyze-{slug}-{date}/` (relative to `.workflow/`)
+**Output directory** (relative to `.workflow/`):
+
+| Scope | Directory format | Example |
+|-------|-----------------|---------|
+| Phase | `scratch/{YYYYMMDD}-analyze-P{N}-{slug}/` | `20260420-analyze-P1-auth` |
+| Milestone | `scratch/{YYYYMMDD}-analyze-M{N}-{slug}/` | `20260420-analyze-M1-mvp` |
+| Adhoc/Standalone | `scratch/{YYYYMMDD}-analyze-{slug}/` | `20260420-analyze-caching` |
+
+Scope prefix (`P{N}` / `M{N}`) enables directory-level identification as fallback when state.json is unavailable.
 
 **Artifact registration**: On completion, register artifact in `state.json.artifacts[]`:
 ```jsonc
@@ -63,7 +71,7 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
   "milestone": "{current_milestone or null}",
   "phase": "{phase_number or null}",
   "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/analyze-{slug}-{date}",
+  "path": "scratch/{YYYYMMDD}-analyze-P{N}-{slug}",  // P{N} for phase, M{N} for milestone, omit for adhoc/standalone
   "status": "completed",
   "depends_on": null,
   "harvested": false,

package/.claude/commands/maestro-brainstorm.md

@@ -30,7 +30,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/brainstorm-{slug}-{date}/`.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 

package/.claude/commands/maestro-execute.md

@@ -34,7 +34,7 @@ $ARGUMENTS — phase number, or no args for milestone-wide execution, with optio
 - `--auto-commit` -- Automatically commit after each task completion
 - `--method agent|cli|auto` -- Override execution method (default: from config.json)
 - `--executor <tool>` -- Default CLI tool: gemini|codex|qwen|opencode|claude
-- `--dir <path>` -- Execute specific plan directory (e.g., `scratch/plan-auth-2026-04-20`)
+- `--dir <path>` -- Execute specific plan directory (e.g., `scratch/20260420-plan-auth`)
 
 **Scope routing:**
 
@@ -55,7 +55,9 @@ $ARGUMENTS — phase number, or no args for milestone-wide execution, with optio
 
 **Output**: Task summaries written to plan's scratch dir:
 ```
-scratch/plan-{slug}-{date}/
+{YYYYMMDD}-plan-P{N}-{slug}/            # phase-scoped
+{YYYYMMDD}-plan-M{N}-{slug}/           # milestone-wide
+{YYYYMMDD}-plan-{slug}/                # adhoc/standalone
 ├── plan.json
 ├── .task/
 │   ├── TASK-001.json    # status updated to completed|blocked
@@ -65,7 +67,7 @@ scratch/plan-{slug}-{date}/
     └── TASK-002-summary.md
 ```
 
-**Incremental learning extraction**: After each plan completes, extract strategy adjustments / patterns / pitfalls from `.summaries/` and append to `specs/learnings.md`. Mark artifact `harvested: true`.
+**Incremental learning extraction**: After each plan completes, extract strategy adjustments / patterns / pitfalls from `.summaries/` and append to `specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`execute`). Mark artifact `harvested: true`.
 
 **Artifact registration**: For each plan executed, register in `state.json.artifacts[]`:
 ```jsonc
@@ -75,7 +77,7 @@ scratch/plan-{slug}-{date}/
   "milestone": "{current_milestone or null}",
   "phase": "{phase or null}",
   "scope": "{inherited from plan}",
-  "path": "{same as plan path}",
+  "path": "{same as plan path}",  // inherits plan directory name with scope prefix
   "status": "completed",
   "depends_on": "PLN-{NNN}",
   "harvested": false,
@@ -96,6 +98,21 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/execute.md' completely.
 
+### Post-task Knowledge Inquiry
+
+After each task completes, evaluate inquiry triggers:
+
+1. **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
+   → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
+
+2. **Retry success**: If task required ≥2 retries before completion:
+   → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
+
+3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
+   → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
+
 ### Issue Status Sync
 
 On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:

package/.claude/commands/maestro-milestone-complete.md

@@ -42,6 +42,20 @@ Follow '~/.maestro/workflows/milestone-complete.md' completely.
 5. Update state.json: advance to next milestone, clear artifacts[]
 6. Clean scratch dirs
 
+### Knowledge Promotion Inquiry
+
+After learning extraction (step 4), scan `learnings.md` for promotion candidates:
+
+1. **High-frequency pattern detection**: Scan all `<spec-entry category="learning">` entries for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} learning entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+
+2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
+   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+
+3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
+
+If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+
 **Next-step routing on completion:**
 - Cut a release → `/maestro-milestone-release`
 - Next milestone → `/maestro-analyze` or `/maestro-plan 1`

package/.claude/commands/maestro-plan.md

@@ -20,7 +20,7 @@ Supports three modes:
 - **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
 - **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
 
-All plan output goes to `.workflow/scratch/plan-{slug}-{date}/`. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
+All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
 </purpose>
 
 <required_reading>
@@ -60,11 +60,17 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 - Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
 - Reads `conclusions.json` if available (implementation_scope seeds task generation)
 
-**Output directory**: `scratch/plan-{slug}-{date}/` (relative to `.workflow/`)
+**Output directory** (relative to `.workflow/`):
+
+| Scope | Directory format | Example |
+|-------|-----------------|---------|
+| Phase | `scratch/{YYYYMMDD}-plan-P{N}-{slug}/` | `20260420-plan-P1-auth` |
+| Milestone | `scratch/{YYYYMMDD}-plan-M{N}-{slug}/` | `20260420-plan-M1-mvp` |
+| Adhoc/Standalone | `scratch/{YYYYMMDD}-plan-{slug}/` | `20260420-plan-caching` |
 
 **Output structure:**
 ```
-scratch/plan-{slug}-{date}/
+{YYYYMMDD}-plan-P{N}-{slug}/
 ├── plan.json            # summary, task_ids[], waves[] with phase labels
 └── .task/
     ├── TASK-001.json    # { phase: 1, phase_slug: "auth", ... }
@@ -82,7 +88,7 @@ scratch/plan-{slug}-{date}/
   "milestone": "{current_milestone or null}",
   "phase": "{phase_number or null}",
   "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/plan-{slug}-{date}",
+  "path": "scratch/{YYYYMMDD}-plan-P{N}-{slug}",  // P{N} for phase, M{N} for milestone, omit for adhoc/standalone
   "status": "completed",
   "depends_on": "{ANL-NNN or null}",
   "harvested": false,
@@ -143,8 +149,8 @@ Tasks: {task_count} tasks in {wave_count} waves
 Check: {checker_status} (iteration {check_count}/{max_checks})
 Collision: {collision_status}
 
-Plan: {scratch_dir}/plan.json
-Tasks: {scratch_dir}/.task/TASK-*.json
+Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
+Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
 
 Next steps:
   /maestro-execute              -- Execute the plan

package/.claude/commands/maestro-roadmap.md

@@ -152,7 +152,7 @@ Read-only health assessment of the current roadmap.
    - **Risk assessment**: Identify phases at risk (blocked, scope creep, dependency failures)
 
 3. **Produce review report**
-   - Write to `.workflow/scratch/roadmap-review-{date}.md`
+   - Write to `.workflow/scratch/{YYYYMMDD}-roadmap-review.md`
    - Format:
      ```
      === ROADMAP REVIEW ===

package/.claude/commands/maestro-ui-design.md

@@ -49,7 +49,7 @@ $ARGUMENTS — phase number for phase mode, topic text for scratch mode, with op
 - Flags `--layouts N` and `--refine` are only effective with `ui-design.md` (full pipeline)
 
 **Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
-**Scratch mode** (text): creates `.workflow/scratch/ui-design-{slug}-{date}/` for standalone exploration.
+**Scratch mode** (text): creates `.workflow/scratch/{YYYYMMDD}-ui-design-{slug}/` for standalone exploration.
 
 **Output artifacts (in phase or scratch directory):**
 | Artifact | Description |
@@ -101,12 +101,12 @@ Stack:   {stack}
 Matrix:  {S x L x T} = {total} prototypes
 
 Design System:
-  MASTER.md:        {phase_dir}/design-ref/MASTER.md
-  Tokens:           {phase_dir}/design-ref/design-tokens.json
-  Animation:        {phase_dir}/design-ref/animation-tokens.json
-  Layout Templates: {phase_dir}/design-ref/layout-templates/
-  Prototypes:       {phase_dir}/design-ref/prototypes/
-  Compare:          {phase_dir}/design-ref/prototypes/compare.html
+  MASTER.md:        {scratch_dir}/design-ref/MASTER.md
+  Tokens:           {scratch_dir}/design-ref/design-tokens.json
+  Animation:        {scratch_dir}/design-ref/animation-tokens.json
+  Layout Templates: {scratch_dir}/design-ref/layout-templates/
+  Prototypes:       {scratch_dir}/design-ref/prototypes/
+  Compare:          {scratch_dir}/design-ref/prototypes/compare.html
 
 Next steps:
   /maestro-plan {phase}              -- Plan with design reference

package/.claude/commands/maestro-update.md

@@ -0,0 +1,176 @@
+---
+name: maestro-update
+description: Interactive workflow migration — detect version, preview changes, apply upgrades
+argument-hint: "[--dry-run] [--force]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Detect the current `.workflow/` schema version, show available migrations, and interactively apply them step-by-step. Uses a migration registry that supports incremental version upgrades (e.g., 1.0 → 2.0 → 3.0).
+
+Each migration step is previewed before execution. The user confirms each step in a loop.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--dry-run` -- Preview migration plan without executing
+- `--force` -- Skip confirmation prompts (apply all pending migrations)
+
+**Migration registry:** `src/migrations/`
+- Each migration is a standalone file (e.g., `v1-to-v2.ts`) exporting a `MigrationDef`
+- All migrations are registered via `src/migrations/index.ts`
+- Registry auto-chains: detects current version → walks chain → applies in order
+- To add a new migration: create `src/migrations/v{N}-to-v{N+1}.ts`, register in `index.ts`
+
+**CLI runner:** `src/migrations/run.ts`
+- Executable entrypoint: `npx tsx src/migrations/run.ts [root] [--dry-run] [--force] [--json]`
+- Outputs JSON (with `--json`) or human-readable text
+
+**State version source:** `.workflow/state.json` → `version` field
+</context>
+
+<execution>
+
+### Step 1: Detect Current State
+
+```
+1. Read .workflow/state.json
+2. Extract version field (default "1.0" if missing)
+3. Display:
+
+   === Maestro Workflow Update ===
+   Project:  {project_name}
+   Version:  {version}
+   Location: {.workflow/ path}
+```
+
+### Step 2: Dry-Run Preview
+
+Run the migration CLI in dry-run + JSON mode to get the full plan:
+
+```bash
+npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+```
+
+Parse the JSON output. If status is `up-to-date`:
+```
+Already up to date (v{version})
+```
+→ EXIT
+
+Otherwise display the migration plan:
+```
+Pending Migrations ({N} step(s)):
+
+  1. [v{from} → v{to}] {name}
+     {description}
+
+  2. [v{from} → v{to}] {name}
+     {description}
+```
+
+If `--dry-run` flag was passed by user → display plan and EXIT.
+
+### Step 3: Interactive Confirmation Loop
+
+For each migration step (unless `--force`):
+
+```
+LOOP for step_index = 1 to N:
+
+  Display:
+    --- Step {step_index}/{N}: {name} ---
+    Version: v{from} → v{to}
+
+    Changes:
+      {description, indented}
+
+  IF NOT --force:
+    AskUserQuestion: "Apply this migration?"
+    Options: [yes / skip / abort]
+
+    - "yes"   → proceed to Step 4 (execute)
+    - "skip"  → WARN "Skipping may break the migration chain"
+                 continue to next step
+    - "abort" → display summary of what was applied so far → EXIT
+
+  IF --force:
+    → proceed to Step 4 (execute)
+```
+
+### Step 4: Execute Single Migration
+
+```
+1. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{from}-{timestamp}
+
+2. Run migration:
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   
+   NOTE: The runner executes ALL pending migrations. For step-by-step control,
+   read state.json, call the migration function directly, or use the runner
+   which stops on first failure.
+
+3. Parse result JSON and display:
+
+   {status_icon} Step {N} completed: {name}
+   Summary: {summary}
+   Changes:
+     - {change_1}
+     - {change_2}
+     - ...
+
+4. If failed:
+   Display: "Migration failed: {summary}"
+   Display: "Backup available at: {backup_path}"
+   Display: "Restore with: cp {backup_path} .workflow/state.json"
+   → EXIT
+
+5. Continue loop to next step
+```
+
+### Step 5: Summary
+
+After all steps completed (or user aborted):
+
+```
+=== Migration Complete ===
+Applied: {applied_count} / {total_count} migration(s)
+Skipped: {skipped_count}
+Version: v{original} → v{final}
+Backup:  .workflow/state.json.backup-v{original}-{timestamp}
+
+Next steps:
+  /manage-status  -- Verify project state
+  /maestro        -- Continue workflow
+```
+
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/state.json not found | Run /maestro-init first |
+| E002 | error | state.json parse error | Check file for corruption |
+| E003 | error | Migration function failed | Restore from backup |
+| W001 | warning | Skipped migration may break version chain | Re-run /maestro-update later |
+| W002 | warning | tsx not available | Install tsx: npm i -D tsx |
+</error_codes>
+
+<success_criteria>
+- [ ] Current version detected from state.json
+- [ ] Dry-run preview shows full migration plan without execution
+- [ ] Each step confirmed interactively (unless --force)
+- [ ] Backup created before each migration
+- [ ] Migration executed and result displayed with change list
+- [ ] Abort stops cleanly with partial summary
+- [ ] Summary shows applied/skipped counts and version change
+</success_criteria>

package/.claude/commands/maestro-verify.md

@@ -20,7 +20,7 @@ Verify execution results through three complementary methods:
 
 Supports dual-level verification:
 - **Single plan**: `verify --dir scratch/plan-xxx` — verifies one plan, writes `verification.json` into plan dir
-- **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/verify-{milestone}-{date}/milestone-verification.json`
+- **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 Registers VRF artifact in state.json on completion.
 </purpose>
@@ -51,7 +51,7 @@ $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 | `verify --dir scratch/plan-xxx` | Single plan: verify specific plan directory |
 
 **Single plan output**: `verification.json` appended to plan's scratch dir
-**Milestone output**: `scratch/verify-{milestone-slug}-{date}/milestone-verification.json`
+**Milestone output**: `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 **Artifact registration**: On completion, register VRF artifact:
 ```jsonc
@@ -61,7 +61,7 @@ $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
   "milestone": "{current_milestone or null}",
   "phase": null,
   "scope": "milestone",
-  "path": "scratch/verify-{milestone-slug}-{date}",
+  "path": "scratch/{YYYYMMDD}-verify-M{N}-{slug}",  // M{N} = milestone number
   "status": "completed",
   "depends_on": ["EXC-001", "EXC-002", ...],
   "harvested": false,
@@ -74,6 +74,21 @@ $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 <execution>
 Follow '~/.maestro/workflows/verify.md' completely.
 
+### Post-verify Knowledge Inquiry
+
+After verification completes, evaluate inquiry triggers:
+
+1. **Anti-pattern detection**: If anti-pattern scan found blockers (TODO/FIXME, stubs, empty returns):
+   → Ask: "Verification found {N} anti-patterns. Should `quality-rules.md` be updated to enforce these checks? (`/spec-add quality`)"
+
+2. **Constraint violation**: If Goal-Backward check found constraint_violations or missing wiring:
+   → Ask: "Verification found architecture constraint violations. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+
+3. **Test coverage gaps**: If Nyquist gaps found with recurring pattern (same module/type across tasks):
+   → Ask: "Persistent test coverage gap detected in {module}. Should it be added to `test-conventions.md` as a required test area? (`/spec-add test`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+
 **Next-step routing on completion:**
 - All checks pass, no gaps → /quality-review
 - Gaps found (must-have failures or anti-pattern blockers) → /maestro-plan --gaps

package/.claude/commands/manage-codebase-rebuild.md

@@ -70,7 +70,6 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 - [ ] doc-index.json generated and valid
 - [ ] All documentation files regenerated
 - [ ] state.json updated with rebuild timestamp
-- [ ] project-tech.json refreshed with detected tech stack
 - [ ] project.md Tech Stack section updated if changes detected
 - [ ] Next step routing: `/manage-status` or `/manage-codebase-refresh` for incremental updates later
 </success_criteria>

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

@@ -76,7 +76,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
 2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
 3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
 4. **Reuse existing routing infrastructure**:
-   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id> --created-by manage-harvest --source-ref HRV-<fragment_id> --category <fragment_category>`
    - Spec: `Skill({ skill: "spec-add", args: "<category> <content>" })`
    - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
 5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.