maestro-flow 0.3.38 → 0.3.40

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

@@ -1,176 +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>
+---
+name: maestro-update
+description: Detect version, preview changes, apply workflow 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

@@ -1,90 +1,96 @@
----
-name: maestro-verify
-description: Goal-Backward verification with 3-layer must-have checks, anti-pattern scan, Nyquist test coverage validation, and gap-fix plan generation
-argument-hint: "[phase] [--skip-tests] [--skip-antipattern] [--dir <path>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Verify execution results through three complementary methods:
-1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved
-2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
-3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
-
-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/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
-
-Registers VRF artifact in state.json on completion.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/verify.md
-</required_reading>
-
-<deferred_reading>
-- [verification.json](~/.maestro/templates/verification.json) — read when generating output
-- [validation.json](~/.maestro/templates/validation.json) — read when generating test output
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
-
-Flags (`--skip-tests`, `--skip-antipattern`, `--dir`), scope routing, output paths, and VRF artifact registration schema are defined in workflow `verify.md`.
-</context>
-
-<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
-- Low test coverage (Nyquist gaps) → /quality-auto-test
-
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No executed plans found for verification | Run maestro-execute first |
-| E002 | error | Plan directory not found | Check --dir path |
-| E003 | error | No execution results found (missing summaries) | Run maestro-execute first |
-| W001 | warning | Test coverage below configured threshold | Review coverage gaps |
-| W002 | warning | Anti-pattern blockers found in modified files | Fix blockers before proceeding |
-</error_codes>
-
-<success_criteria>
-- [ ] Must-haves established (from convergence.criteria in tasks)
-- [ ] All truths verified with status and evidence (Layer 1)
-- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
-- [ ] All key links verified with evidence (Layer 3)
-- [ ] Anti-patterns scanned and categorized (unless skipped)
-- [ ] Nyquist test coverage assessed (unless skipped)
-- [ ] Fix plans generated for identified gaps
-- [ ] verification.json written to plan dir (single plan) or milestone verify dir
-- [ ] VRF artifact registered in state.json
-</success_criteria>
+---
+name: maestro-verify
+description: Verify goals with must-have checks and test coverage validation
+argument-hint: "[phase] [--skip-tests] [--skip-antipattern] [--dir <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Verify execution results through three complementary methods:
+1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved
+2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
+3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
+
+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/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
+
+Registers VRF artifact in state.json on completion.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/verify.md
+</required_reading>
+
+<deferred_reading>
+- [verification.json](~/.maestro/templates/verification.json) — read when generating output
+- [validation.json](~/.maestro/templates/validation.json) — read when generating test output
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
+
+Flags (`--skip-tests`, `--skip-antipattern`, `--dir`), scope routing, output paths, and VRF artifact registration schema are defined in workflow `verify.md`.
+
+### Pre-load context (before verification)
+
+1. **Codebase docs**: If `.workflow/codebase/` exists, read `ARCHITECTURE.md` for expected module wiring and `FEATURES.md` for component mapping. Use in Layer 3 (Connection) checks.
+2. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, include documented invariants as additional truth checks in Layer 1.
+3. Both are optional — proceed without if unavailable.
+</context>
+
+<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
+- Low test coverage (Nyquist gaps) → /quality-auto-test
+
+**Gap-fix closure loop:**
+Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No executed plans found for verification | Run maestro-execute first |
+| E002 | error | Plan directory not found | Check --dir path |
+| E003 | error | No execution results found (missing summaries) | Run maestro-execute first |
+| W001 | warning | Test coverage below configured threshold | Review coverage gaps |
+| W002 | warning | Anti-pattern blockers found in modified files | Fix blockers before proceeding |
+</error_codes>
+
+<success_criteria>
+- [ ] Must-haves established (from convergence.criteria in tasks)
+- [ ] All truths verified with status and evidence (Layer 1)
+- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
+- [ ] All key links verified with evidence (Layer 3)
+- [ ] Anti-patterns scanned and categorized (unless skipped)
+- [ ] Nyquist test coverage assessed (unless skipped)
+- [ ] Fix plans generated for identified gaps
+- [ ] verification.json written to plan dir (single plan) or milestone verify dir
+- [ ] VRF artifact registered in state.json
+</success_criteria>