maestro-flow 0.3.8 → 0.3.10

package/.codex/skills/maestro-execute/SKILL.md

@@ -196,17 +196,18 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**:
+1. **Plan resolution** (per scratch-milestone-architecture):
 
 | Input | Resolution |
 |-------|------------|
-| `--dir <path>` | Use path directly, set SCRATCH_MODE = true |
-| Number (e.g., `3`) | Find `.workflow/phases/{NN}-*/` matching phase number |
-| Slug (e.g., `auth`) | Find `.workflow/phases/*-{slug}/` |
+| `--dir <path>` | Use path directly (scratch plan dir) |
+| No args | Find all pending plans for current milestone from state.json.artifacts[] |
+| Number (e.g., `3`) | Find pending plans for phase N from state.json.artifacts[] |
 
-2. **Load plan**:
-   - Read `{PHASE_DIR}/plan.json` for wave structure
-   - Read `{PHASE_DIR}/index.json` for phase metadata
+   For multi-plan: execute sequentially. Each plan is a full CSV session.
+
+2. **Load plan** (per PLAN_DIR):
+   - Read `{PLAN_DIR}/plan.json` for wave structure
    - Extract `plan.waves` array with task assignments
 
 3. **Detect completed tasks (breakpoint resume)**:
@@ -307,24 +308,31 @@ If a task is blocked/failed and other tasks in later waves depend on it:
    - Update `status` to match CSV status
    - Write back to disk
 
-4. **Update index.json**:
-   ```json
-   {
-     "execution": {
-       "tasks_completed": N,
-       "tasks_total": M,
-       "current_wave": W,
-       "started_at": "<ISO>",
-       "completed_at": "<ISO or null>",
-       "commits": [{"hash": "...", "task": "...", "message": "..."}]
-     },
-     "status": "verifying" | "executing"
-   }
+3b. **Issue status sync**: For each completed/failed task that has `issue_id`:
+   - Read issue from `.workflow/issues/issues.jsonl` by `issue_id`
+   - Collect all `task_refs[]` statuses for that issue:
+     - All task_refs completed → `issue.status = "resolved"`
+     - Any task_ref failed → `issue.status = "in_progress"`
+   - Append history entry: `{ action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }`
+   - Write updated issue back to `issues.jsonl`
+
+4. **Register EXC artifact in state.json**:
+   ```
+   Read .workflow/state.json
+   plan_artifact = state.json.artifacts.find(a => a.type == "plan" && a.path == PLAN_DIR_relative)
+   next_id = max EXC-NNN + 1
+   Push artifact: { id: "EXC-{next_id}", type: "execute", milestone: plan_artifact.milestone,
+     phase: plan_artifact.phase, scope: plan_artifact.scope, path: plan_artifact.path,
+     status: "completed", depends_on: plan_artifact.id, harvested: false,
+     created_at: execution_start, completed_at: now() }
+   Write state.json (atomic)
    ```
-   - If all completed: set status = "verifying"
-   - If partial: set status = "executing" (resumable)
 
-5. **Update state.json**: Update project-level progress counters.
+5. **Extract incremental learnings**:
+   - Read all `.summaries/` from PLAN_DIR
+   - Extract strategy adjustments, patterns, pitfalls
+   - Append to `.workflow/specs/learnings.md`
+   - Mark artifact `harvested: true` in state.json
 
 6. **Generate context.md**:
 
@@ -368,11 +376,12 @@ Completed: {completed_count}/{total_count} tasks
 Blocked:   {blocked_count} tasks
 Waves:     {waves_executed}/{total_waves}
 
-Summaries: {phase_dir}/.summaries/
-Tasks:     {phase_dir}/.task/
+Summaries: {PLAN_DIR}/.summaries/
+Tasks:     {PLAN_DIR}/.task/
 
 Next steps:
-  Skill({ skill: "maestro-verify", args: "{phase}" })
+  Skill({ skill: "maestro-verify" })
+  Skill({ skill: "maestro-verify", args: "--dir {PLAN_DIR}" })
   Skill({ skill: "manage-status" })
 ```
 

package/.codex/skills/maestro-milestone-audit/SKILL.md

@@ -1,209 +1,103 @@
----
-name: maestro-milestone-audit
-description: Audit current milestone for cross-phase integration gaps and produce verdict report
-argument-hint: "[milestone, e.g., 'v1.0']"
-allowed-tools: Read, Write, Bash, Glob, Grep, Agent
----
-
-# Maestro Milestone Audit (Single Agent)
-
-## Usage
-
-```bash
-$maestro-milestone-audit ""
-$maestro-milestone-audit "v1.0"
-$maestro-milestone-audit "MVP"
-```
-
-**Flags**:
-- `[milestone]`: Milestone identifier (defaults to current_milestone from state.json)
-
-**Output**: Audit report with cross-phase integration analysis, gap list, and PASS/FAIL verdict
-
----
-
-## Overview
-
-Sequential audit of a milestone's cross-phase integration health. Identifies all phases belonging to the milestone, reads their index.json and verification results, checks for integration gaps across phase boundaries, and produces a structured audit report with a clear verdict.
-
----
-
-## Implementation
-
-### Step 1: Parse Arguments
-
-Extract milestone identifier from arguments.
-If empty: read `current_milestone` from `.workflow/state.json`.
-If still empty: error E001.
-
-### Step 2: Load Milestone Context
-
-```bash
-cat .workflow/state.json
-cat .workflow/roadmap.md
-```
-
-Parse roadmap.md to find all phases belonging to this milestone.
-If milestone not found in roadmap: error E002.
-
-### Step 3: Collect Phase Data
-
-For each phase in the milestone:
-
-```bash
-cat .workflow/phases/{NN}-{slug}/index.json
-cat .workflow/phases/{NN}-{slug}/verification.json 2>/dev/null
-cat .workflow/phases/{NN}-{slug}/review.json 2>/dev/null
-```
-
-Collect:
-- Phase status (complete/active/pending)
-- Task completion counts
-- Verification verdicts
-- Review verdicts
-- Unresolved gaps
-
-Flag phases without `completed_at` as W001.
-If any phase is not complete/verifying: warning E003.
-
-### Step 4: Cross-Phase Integration Analysis
-
-Analyze integration points across phase boundaries:
-
-1. **Shared interfaces**: Grep for types/interfaces defined in one phase and used in another
-   ```bash
-   grep -r "export.*interface\|export.*type" .workflow/phases/*/
-   ```
-
-2. **Data contracts**: Check that data schemas are consistent across phases
-   ```bash
-   grep -r "schema\|contract\|interface" .workflow/phases/*/
-   ```
-
-3. **Dependency chains**: Verify that phase N's outputs satisfy phase N+1's inputs
-   - Read each phase's index.json for declared dependencies
-   - Check convergence criteria cross-references
-
-4. **API surface consistency**: Look for breaking changes between phases
-   ```bash
-   grep -r "breaking\|deprecated\|removed" .workflow/phases/*/verification.json
-   ```
-
-5. **Test coverage gaps**: Identify integration test blind spots
-   - Check if cross-phase interactions have test coverage
-   - Flag untested boundaries
-
-### Step 5: Spawn Integration Checker (if complex)
-
-For milestones with 3+ phases, spawn a workflow-integration-checker agent:
-
-```
-Agent({
-  subagent_type: "workflow-integration-checker",
-  prompt: "Check cross-phase integration for milestone {milestone}. Phases: {phase_list}. Focus on: shared interfaces, data contracts, dependency chains.",
-  run_in_background: false
-})
-```
-
-Merge agent findings with Step 4 analysis.
-
-### Step 6: Categorize Findings
-
-Classify each finding:
-- **Critical**: Breaking integration gap (blocks milestone completion)
-- **High**: Missing integration test coverage
-- **Medium**: Inconsistent naming/conventions across phases
-- **Low**: Documentation gaps, minor style inconsistencies
-
-### Step 7: Determine Verdict
-
-- **PASS**: No critical or high findings
-- **CONDITIONAL**: High findings exist but have clear fix paths
-- **FAIL**: Critical findings that block milestone completion
-
-### Step 8: Write Audit Report
-
-Write to `.workflow/milestone-audit-{milestone}.md`:
-
-```markdown
-# Milestone Audit: {milestone}
-**Date**: {ISO date}
-**Verdict**: {PASS|CONDITIONAL|FAIL}
-
-## Phases Audited
-
-| Phase | Status | Verification | Review | Tasks |
-|-------|--------|-------------|--------|-------|
-| {NN}-{slug} | {status} | {verdict} | {verdict} | {done}/{total} |
-
-## Integration Analysis
-
-### Critical Issues
-{list or "None"}
-
-### High Issues
-{list or "None"}
-
-### Medium Issues
-{list or "None"}
-
-### Low Issues
-{list or "None"}
-
-## Cross-Phase Dependencies
-
-{dependency matrix or diagram}
-
-## Recommendations
-
-{prioritized fix suggestions}
-
-## Next Steps
-
-{if PASS}
-  Ready for: $maestro-milestone-complete "{milestone}"
-{elif CONDITIONAL}
-  Fix high issues, then re-audit: $maestro-milestone-audit "{milestone}"
-{else}
-  Fix critical issues first. See recommendations above.
-{endif}
-```
-
-### Step 9: Completion Report
-
-```
-=== MILESTONE AUDIT: {milestone} ===
-Verdict: {PASS|CONDITIONAL|FAIL}
-
-Phases: {count} audited
-Findings: {critical} critical, {high} high, {medium} medium, {low} low
-
-Report: .workflow/milestone-audit-{milestone}.md
-
-{if PASS}
-Ready for milestone completion: $maestro-milestone-complete "{milestone}"
-{else}
-Fix {critical+high} blocking issues before completing milestone.
-{endif}
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | Milestone identifier required | Specify milestone or set current_milestone in state.json |
-| E002 | error | Milestone not found in roadmap | Check roadmap.md for valid milestones |
-| E003 | error | Phases incomplete for this milestone | Complete phases first, or audit partial |
-| W001 | warning | Phase lacks completed_at | May not have been formally transitioned |
-
----
-
-## Core Rules
-
-1. **Read everything before judging** — collect all phase data before analyzing gaps
-2. **Cross-phase focus** — single-phase issues are not this skill's concern; focus on boundaries
-3. **Actionable findings** — every finding must include a specific fix suggestion
-4. **Clear verdict** — PASS/CONDITIONAL/FAIL with unambiguous criteria
-5. **Agent only when needed** — spawn integration-checker only for 3+ phase milestones
+---
+name: maestro-milestone-audit
+description: Audit current milestone using artifact registry for cross-phase integration gaps and produce verdict report
+argument-hint: "[milestone, e.g., 'M1']"
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent
+---
+
+# Maestro Milestone Audit (Single Agent)
+
+## Usage
+
+```bash
+$maestro-milestone-audit ""
+$maestro-milestone-audit "M1"
+```
+
+**Output**: Audit report with artifact chain verification, integration analysis, and PASS/FAIL verdict
+
+---
+
+## Overview
+
+Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL→PLN→EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration.
+
+---
+
+## Implementation
+
+### Step 1: Parse Arguments
+
+Extract milestone identifier from arguments.
+If empty: read `current_milestone` from `.workflow/state.json`.
+If still empty: error E001.
+
+### Step 2: Load Artifact Registry
+
+```bash
+cat .workflow/state.json
+cat .workflow/roadmap.md
+```
+
+- Parse `state.json.artifacts[]` filtered by milestone
+- Parse `roadmap.md` for phase list in this milestone
+- Group artifacts by type and phase
+
+### Step 3: Phase Coverage Check
+
+For each phase in roadmap:
+- Check for completed analyze artifact (optional but noted)
+- Check for completed plan artifact (required)
+- Check for completed execute artifact (required)
+
+Report coverage matrix.
+
+### Step 4: Ad-hoc & Execution Completeness
+
+- Check all adhoc-scoped artifacts are completed
+- For each execute artifact, verify tasks in plan dir are all completed
+
+### Step 5: Integration Check
+
+Spawn Agent for cross-phase integration validation:
+- Shared interfaces compatibility
+- Dependency chain satisfaction
+- Data contract consistency
+- API endpoint consistency
+
+Write report to `.workflow/milestones/{milestone}/audit-report.md`
+
+### Step 6: Verdict
+
+```
+PASS if:
+  - All phases have EXC artifacts (completed)
+  - No critical integration gaps
+  - All adhoc artifacts completed
+
+FAIL if:
+  - Missing EXC artifacts for any phase
+  - Critical integration gaps found
+```
+
+Display structured audit report with next-step routing.
+
+---
+
+## Error Handling
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | Milestone identifier required | Specify milestone or ensure current_milestone is set |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found | Run maestro-execute first |
+| W001 | warning | Some phases lack analyze artifacts | Note: analysis optional but recommended |
+
+---
+
+## Core Rules
+
+1. **Artifact registry is source of truth** — don't scan directories, read state.json
+2. **Non-blocking warnings** — missing analyze is warning, missing execute is error
+3. **Integration check is required** — always spawn checker agent
+4. **Clear verdict** — PASS or FAIL with specific reasons