maestro-flow 0.3.12 → 0.3.13

package/dist/src/utils/state-schema.js

@@ -0,0 +1,329 @@
+/**
+ * state-schema.ts — Canonical state.json v2 types, derivation, migration, and I/O.
+ *
+ * Single source of truth for the `.workflow/state.json` schema.
+ * All hooks, tools, and workflows should import from here.
+ */
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Cross-platform atomic rename with retry for Windows EPERM/EBUSY.
+ * Attempts unlinkSync on target before retry to handle Windows semantics.
+ */
+export function safeRename(src, dest) {
+    for (let i = 0; i < 3; i++) {
+        try {
+            renameSync(src, dest);
+            return;
+        }
+        catch (e) {
+            if (i < 2 && ['EPERM', 'EACCES', 'EBUSY'].includes(e.code)) {
+                try {
+                    unlinkSync(dest);
+                }
+                catch { }
+                continue;
+            }
+            throw e;
+        }
+    }
+}
+/** Local-time ISO 8601 string with timezone offset, e.g. "2026-04-24T14:30:00+08:00" */
+export function localISO() {
+    const d = new Date();
+    const off = -d.getTimezoneOffset();
+    const sign = off >= 0 ? '+' : '-';
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}${sign}${p(Math.floor(Math.abs(off) / 60))}:${p(Math.abs(off) % 60)}`;
+}
+// ---------------------------------------------------------------------------
+// Derivation functions — replace stored current_phase / phases_summary
+// ---------------------------------------------------------------------------
+/**
+ * Derive the "current phase" from artifact registry.
+ * Priority: phase with in_progress artifact → first phase without completed execute.
+ */
+export function deriveCurrentPhase(state) {
+    const milestone = state.milestones?.find(m => m.name === state.current_milestone || m.id === state.current_milestone);
+    if (!milestone?.phases?.length)
+        return null;
+    // Phase with in_progress work → current
+    for (const p of milestone.phases) {
+        if (state.artifacts.some(a => a.phase === p
+            && a.milestone === state.current_milestone
+            && a.status === 'in_progress'))
+            return p;
+    }
+    // First phase without completed execute
+    for (const p of milestone.phases) {
+        if (!state.artifacts.some(a => a.type === 'execute'
+            && a.phase === p
+            && a.milestone === state.current_milestone
+            && a.status === 'completed'))
+            return p;
+    }
+    return null; // all phases done
+}
+/**
+ * Derive phases_summary from artifact registry.
+ */
+export function derivePhasesSummary(state) {
+    const milestone = state.milestones?.find(m => m.name === state.current_milestone || m.id === state.current_milestone);
+    if (!milestone?.phases?.length) {
+        return { total: 0, completed: 0, in_progress: 0, pending: 0 };
+    }
+    const total = milestone.phases.length;
+    let completed = 0;
+    let in_progress = 0;
+    for (const p of milestone.phases) {
+        const arts = state.artifacts.filter(a => a.phase === p && a.milestone === state.current_milestone);
+        if (arts.some(a => a.type === 'execute' && a.status === 'completed')) {
+            completed++;
+        }
+        else if (arts.length > 0) {
+            in_progress++;
+        }
+    }
+    return { total, completed, in_progress, pending: total - completed - in_progress };
+}
+// ---------------------------------------------------------------------------
+// Artifact ID generation
+// ---------------------------------------------------------------------------
+const TYPE_PREFIX = {
+    analyze: 'ANL',
+    plan: 'PLN',
+    execute: 'EXC',
+    verify: 'VRF',
+    brainstorm: 'BST',
+    spec: 'SPC',
+    review: 'REV',
+    debug: 'DBG',
+    test: 'TST',
+};
+export function nextArtifactId(artifacts, type) {
+    const prefix = TYPE_PREFIX[type];
+    let max = 0;
+    for (const a of artifacts) {
+        if (!a.id.startsWith(prefix + '-'))
+            continue;
+        const n = parseInt(a.id.slice(prefix.length + 1), 10);
+        if (n > max)
+            max = n;
+    }
+    return `${prefix}-${String(max + 1).padStart(3, '0')}`;
+}
+/**
+ * Build artifact entries from legacy phases/ directory structure.
+ * Scans .workflow/phases/{NN}-{slug}/ for analysis.md, plan.json, .summaries/, verification.json.
+ */
+function harvestLegacyPhaseArtifacts(workflowRoot, currentMilestone) {
+    const phasesDir = join(workflowRoot, 'phases');
+    if (!existsSync(phasesDir))
+        return [];
+    const entries = [];
+    let idCounters = { ANL: 0, PLN: 0, EXC: 0, VRF: 0 };
+    const now = localISO();
+    let dirs;
+    try {
+        dirs = readdirSync(phasesDir);
+    }
+    catch {
+        return [];
+    }
+    for (const d of dirs) {
+        const match = d.match(/^(\d+)-(.+)$/);
+        if (!match)
+            continue;
+        const phaseNum = parseInt(match[1], 10);
+        const slug = match[2];
+        const phaseDir = join(phasesDir, d);
+        // Check what artifacts exist in this phase dir
+        const hasAnalysis = existsSync(join(phaseDir, 'analysis.md'));
+        const hasPlan = existsSync(join(phaseDir, 'plan.json'));
+        const hasSummaries = existsSync(join(phaseDir, '.summaries'));
+        const hasVerification = existsSync(join(phaseDir, 'verification.json'));
+        // Legacy paths are relative to .workflow/
+        const legacyPath = `phases/${d}`;
+        if (hasAnalysis) {
+            idCounters.ANL++;
+            const anlId = `ANL-${String(idCounters.ANL).padStart(3, '0')}`;
+            entries.push({
+                id: anlId,
+                type: 'analyze',
+                milestone: currentMilestone,
+                phase: phaseNum,
+                scope: 'phase',
+                path: legacyPath,
+                status: 'completed',
+                depends_on: null,
+                harvested: true,
+                created_at: now,
+                completed_at: now,
+            });
+        }
+        if (hasPlan) {
+            idCounters.PLN++;
+            const plnId = `PLN-${String(idCounters.PLN).padStart(3, '0')}`;
+            const anlId = idCounters.ANL > 0 ? `ANL-${String(idCounters.ANL).padStart(3, '0')}` : null;
+            entries.push({
+                id: plnId,
+                type: 'plan',
+                milestone: currentMilestone,
+                phase: phaseNum,
+                scope: 'phase',
+                path: legacyPath,
+                status: 'completed',
+                depends_on: anlId,
+                harvested: hasSummaries,
+                created_at: now,
+                completed_at: now,
+            });
+        }
+        if (hasSummaries) {
+            idCounters.EXC++;
+            const excId = `EXC-${String(idCounters.EXC).padStart(3, '0')}`;
+            const plnId = idCounters.PLN > 0 ? `PLN-${String(idCounters.PLN).padStart(3, '0')}` : null;
+            entries.push({
+                id: excId,
+                type: 'execute',
+                milestone: currentMilestone,
+                phase: phaseNum,
+                scope: 'phase',
+                path: legacyPath,
+                status: 'completed',
+                depends_on: plnId,
+                harvested: true,
+                created_at: now,
+                completed_at: now,
+            });
+        }
+        if (hasVerification) {
+            idCounters.VRF++;
+            const vrfId = `VRF-${String(idCounters.VRF).padStart(3, '0')}`;
+            const excId = idCounters.EXC > 0 ? `EXC-${String(idCounters.EXC).padStart(3, '0')}` : null;
+            entries.push({
+                id: vrfId,
+                type: 'verify',
+                milestone: currentMilestone,
+                phase: phaseNum,
+                scope: 'phase',
+                path: legacyPath,
+                status: 'completed',
+                depends_on: excId ? [excId] : null,
+                harvested: true,
+                created_at: now,
+                completed_at: now,
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * Normalize v1 status string to v2 enum.
+ */
+function normalizeStatus(old) {
+    if (!old)
+        return 'idle';
+    if (old === 'idle')
+        return 'idle';
+    if (old.includes('executing'))
+        return 'executing';
+    if (old === 'completed')
+        return 'completed';
+    if (old === 'active')
+        return 'active';
+    // "phase_N_pending", "verifying", etc → active
+    return 'active';
+}
+/**
+ * Migrate v1 state.json to v2. Optionally harvests legacy phases/ artifacts.
+ */
+export function migrateV1toV2(raw, workflowRoot) {
+    const currentMilestone = raw.current_milestone ?? null;
+    // Enrich milestones with id + status
+    const milestones = (raw.milestones ?? []).map((m, i) => ({
+        id: m.id ?? `M${i + 1}`,
+        name: m.name,
+        title: m.title ?? m.name,
+        status: m.status
+            ?? (m.name === currentMilestone ? 'active' : 'pending'),
+        phases: m.phases ?? [],
+    }));
+    // Start with any existing artifacts from state.json
+    let artifacts = Array.isArray(raw.artifacts) ? [...raw.artifacts] : [];
+    // Harvest from legacy phases/ if workflowRoot provided and no artifacts exist yet
+    if (artifacts.length === 0 && workflowRoot) {
+        artifacts = harvestLegacyPhaseArtifacts(workflowRoot, currentMilestone);
+    }
+    return {
+        version: '2.0',
+        project_name: raw.project_name ?? null,
+        status: normalizeStatus(raw.status),
+        current_milestone: currentMilestone,
+        current_task_id: raw.current_task_id ?? null,
+        milestones,
+        artifacts,
+        accumulated_context: raw.accumulated_context ?? {
+            key_decisions: [],
+            blockers: [],
+            deferred: [],
+        },
+        transition_history: (raw.transition_history ?? []),
+        milestone_history: (raw.milestone_history ?? []),
+        last_updated: raw.last_updated ?? localISO(),
+    };
+}
+// ---------------------------------------------------------------------------
+// I/O helpers — atomic read/write
+// ---------------------------------------------------------------------------
+/**
+ * Read state.json from a workspace. Auto-migrates v1 to v2 in memory (does not write back).
+ * Returns null if file doesn't exist.
+ */
+export function readStateJson(workflowRoot) {
+    const statePath = join(workflowRoot, '.workflow', 'state.json');
+    if (!existsSync(statePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(statePath, 'utf8'));
+        if (raw.version === '2.0')
+            return raw;
+        // Auto-migrate v1
+        return migrateV1toV2(raw, join(workflowRoot, '.workflow'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write state.json atomically (write-tmp + rename).
+ */
+export function writeStateJson(workflowRoot, state) {
+    const statePath = join(workflowRoot, '.workflow', 'state.json');
+    const tmpPath = statePath + '.tmp';
+    state.last_updated = localISO();
+    writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+    safeRename(tmpPath, statePath);
+}
+/**
+ * Read, migrate if needed, and write back v2 state.json.
+ * Returns the migrated state. Use this for one-shot migration.
+ */
+export function migrateStateFile(workflowRoot) {
+    const statePath = join(workflowRoot, '.workflow', 'state.json');
+    if (!existsSync(statePath))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(statePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (raw.version === '2.0')
+        return raw;
+    const v2 = migrateV1toV2(raw, join(workflowRoot, '.workflow'));
+    writeStateJson(workflowRoot, v2);
+    return v2;
+}
+//# sourceMappingURL=state-schema.js.map

package/dist/src/utils/state-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-schema.js","sourceRoot":"","sources":["../../../src/utils/state-schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/templates/state.json

@@ -1,39 +1,17 @@
-{
-  "version": "1.0",
-  "project_name": "{{PROJECT_NAME}}",
-  "current_milestone": "{{MILESTONE_NAME}}",
-  "current_phase": 1,
-  "status": "idle",
-  "phases_summary": {
-    "total": 0,
-    "completed": 0,
-    "in_progress": 0,
-    "pending": 0
-  },
-  "last_updated": "{{TIMESTAMP}}",
-  "accumulated_context": {
-    "key_decisions": [],
-    "blockers": [],
-    "deferred": [
-      {
-        "id": "{{DEFERRED_ID}}",
-        "severity": "{{critical|high|medium|low}}",
-        "fix_direction": "{{FIX_DIRECTION}}",
-        "description": "{{DESCRIPTION}}"
-      }
-    ]
-  },
-  "transition_history": [],
-  "milestone_history": [
-    {
-      "name": "{{MILESTONE_NAME}}",
-      "slug": "{{MILESTONE_SLUG}}",
-      "status": "{{pending|in_progress|completed}}",
-      "completed_at": null,
-      "phases": [],
-      "audit_verdict": null,
-      "force_completed": false,
-      "archive_path": null
-    }
-  ]
-}
+{
+  "version": "2.0",
+  "project_name": "{{PROJECT_NAME}}",
+  "status": "idle",
+  "current_milestone": null,
+  "current_task_id": null,
+  "milestones": [],
+  "artifacts": [],
+  "last_updated": "{{TIMESTAMP}}",
+  "accumulated_context": {
+    "key_decisions": [],
+    "blockers": [],
+    "deferred": []
+  },
+  "transition_history": [],
+  "milestone_history": []
+}

package/workflows/brainstorm.md

@@ -130,11 +130,11 @@ Parse $ARGUMENTS to determine execution mode:
   ```
   Read .workflow/state.json → state
   artifacts = state.artifacts ?? []
-  IF artifacts.length > 0:
-    art = artifacts.find(a => a.phase === phaseNum)
+  art = artifacts.find(a => a.phase === phaseNum)
+  IF art:
     output_dir = ".workflow/" + art.path + "/.brainstorming/"
   ELSE:
-    output_dir = ".workflow/phases/{NN}-{slug}/.brainstorming/"
+    ERROR "Phase {phaseNum} not found in artifact registry"
   ```
 - All output: `.workflow/scratch/brainstorm-{slug}-{date}/`
 - Existing session: use existing session directory

package/workflows/codebase-rebuild.md

@@ -49,7 +49,7 @@ Scan src/ (and other source directories) for components:
 
 a. Identify source directories:
    - Check for: src/, lib/, app/, packages/
-   - Use project-tech.json source_dirs if available
+   - Read project.md Tech Stack section if available for context
 
 b. For each source directory, scan for component-forming files:
    - Directories that represent modules (contain index.ts/index.js or multiple files)
@@ -267,16 +267,7 @@ a. Update state.json:
    Set last_updated: "{ISO timestamp}"
    Write updated state.json
 
-b. Update project-tech.json (if exists):
-   Read .workflow/project-tech.json
-   Compare detected tech stack (from Step 2 scan) against existing entries:
-     - New languages, frameworks, databases, tools discovered
-     - Version changes detected (from package.json, go.mod, pyproject.toml, etc.)
-   If differences found:
-     Update project-tech.json with current detected stack
-     Display: "project-tech.json: updated with {count} changes"
-
-c. Update project.md Tech Stack (if exists):
+b. Update project.md Tech Stack (if exists):
    Read .workflow/project.md
    Compare "## Tech Stack" section against detected stack from Step 2
    If new entries or changes detected:
@@ -328,5 +319,4 @@ Suggest next:
 | `.workflow/codebase/feature-maps/_index.md` | Feature index |
 | `.workflow/codebase/feature-maps/{slug}.md` | Per-feature documentation |
 | `.workflow/state.json` | Updated: last_codebase_rebuild timestamp |
-| `.workflow/project-tech.json` | Updated: detected tech stack changes |
 | `.workflow/project.md` | Updated: Tech Stack section refreshed |

package/workflows/debug.md

@@ -14,10 +14,9 @@ When root causes found, auto-updates originating uat.md with diagnosis.
 ### Step 1: Check Active Sessions
 
 ```bash
-# Check both scratch (artifact registry) and legacy phases for debug sessions
+# Check scratch dirs (resolved via artifact registry) for debug sessions
 find .workflow/scratch -path "*/.debug/*" -name "understanding.md" 2>/dev/null | head -5
 find .workflow/scratch -type d -name "debug-*" 2>/dev/null | head -5
-find .workflow/phases -path "*/.debug/*" -name "understanding.md" 2>/dev/null | head -5
 ```
 
 **If active sessions exist AND no $ARGUMENTS:**
@@ -30,7 +29,7 @@ Display:
 
 | # | Location | Status | Current Hypothesis |
 |---|----------|--------|--------------------|
-| 1 | phases/03-auth/.debug/jwt-expiry/ | investigating | Token not refreshed on 401 |
+| 1 | scratch/plan-auth-2026-04-20/.debug/jwt-expiry/ | investigating | Token not refreshed on 401 |
 | 2 | scratch/debug-nav-crash-2026-03-14/ | checkpoint | Awaiting user input |
 
 Reply with a number to resume, or describe a new issue.
@@ -65,7 +64,7 @@ Pass to debug agents as prior knowledge (known issues, root causes, workarounds)
 
 Skip if --from-uat is not set. Go to Step 3 instead.
 
-Read `{phase_dir}/uat.md` Gaps section. For each gap:
+Read `{artifact_dir}/uat.md` Gaps section (artifact_dir resolved from artifact registry). For each gap:
 ```yaml
 - test: T-003
   truth: "User can reply to comments"
@@ -136,18 +135,18 @@ Create debug session directory and proceed to Step 6.
 
 | Mode | Directory |
 |------|-----------|
-| Phase-scoped (from UAT) | `{PHASE_DIR}/.debug/{gap-slug}/` (PHASE_DIR resolved via artifact registry or legacy phases/) |
+| Phase-scoped (from UAT) | `{ARTIFACT_DIR}/.debug/{gap-slug}/` (ARTIFACT_DIR resolved from artifact registry) |
 | Standalone | `.workflow/scratch/debug-{slug}-{date}/` |
 
 ```
 IF TARGET_TYPE == "phase":
   Read .workflow/state.json → state
   artifacts = state.artifacts ?? []
-  IF artifacts.length > 0:
-    art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
+  art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
+  IF art:
     DEBUG_DIR = ".workflow/" + art.path + "/.debug/{gap-slug}/"
   ELSE:
-    DEBUG_DIR = ".workflow/phases/{NN}-{slug}/.debug/{gap-slug}/"
+    ERROR "Phase {phaseNum} not found in artifact registry"
 ELSE:
   DEBUG_DIR = ".workflow/scratch/debug-{slug}-{date}/"
 

package/workflows/execute.md

@@ -221,9 +221,6 @@ For each wave in execution_queue (sequential):
     Read .workflow/state.json
     If state.json.status != "executing":
       state.json.status = "executing"
-      # Worktree mode: skip phases_summary (reconciled on merge)
-      IF NOT file_exists(".workflow/worktree-scope.json"):
-        state.json.phases_summary.in_progress += 1
       state.json.last_updated = now()
       Write .workflow/state.json
 
@@ -565,7 +562,24 @@ Write state.json (atomic)
 // Incremental learning extraction
 Read all ${PLAN_DIR}/.summaries/TASK-*-summary.md
 Extract: strategy adjustments, patterns discovered, pitfalls encountered
-Append to .workflow/specs/learnings.md under "## Entries"
+
+// Check existing entries to avoid duplicates
+existing_learnings = maestro spec load --category learning
+
+// Append using <spec-entry> closed-tag format:
+FOR each extracted learning:
+  keywords = extract_keywords(learning.content)  // 3-5 domain-specific terms
+  IF not duplicate of existing_learnings:
+    Append to .workflow/specs/learnings.md:
+      <spec-entry category="learning" keywords="{keywords}" date="{YYYY-MM-DD}" source="execute">
+
+      ### {learning.summary}
+
+      {learning.content}
+      Phase: {phase} | Plan: {PLAN_DIR}
+
+      </spec-entry>
+
 Mark artifact.harvested = true
 Write state.json (atomic)
 ```