pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/merge.md

@@ -0,0 +1,122 @@
+# Workflow: merge
+
+---
+
+## Step 1: Parse Arguments and Flags
+
+```
+Timestamps use UTC+8 ISO format throughout.
+
+Parse from $ARGUMENTS:
+  --force       → force (skip incomplete-phase confirmation)
+  --dry-run     → dryRun (preview only)
+  --no-cleanup  → noCleanup (keep worktree after merge)
+  --continue    → continueMode (resume after conflict resolution)
+  -m <N> or bare <N> → milestoneNum (1-based)
+```
+
+---
+
+## Step 2: Validate Context
+
+```
+Reject: .workflow/worktree-scope.json present (E001 — must run from main worktree).
+Require: .workflow/worktrees.json (E002 — nothing to merge without registry).
+Read registry from worktrees.json.
+```
+
+---
+
+## Step 3: Registry Health Check
+
+```
+Detect worktree entries whose directories no longer exist.
+If stale entries found → warn (W001), remove from registry, rewrite worktrees.json.
+```
+
+---
+
+## Step 4: Resolve Merge Target
+
+```
+--continue → load target from .workflow/.merge-state.json (E003 if missing), skip to Step 7.
+Otherwise → find active worktree for milestoneNum in registry (E004 if no milestone specified).
+If no matching target → display active worktrees and exit.
+```
+
+---
+
+## Step 5: Validate Readiness
+
+```
+Check phase completeness via worktree artifact registry (execute artifacts → completed or incomplete).
+If incomplete phases and not --force → warn (W002), confirm with user.
+If --dry-run → display merge preview (branch, milestone, completed/incomplete phases) and exit.
+```
+
+---
+
+## Step 6: Phase 1 — Git Merge
+
+```
+6a: Pull main into worktree branch (cd {target.path} && git merge main --no-edit).
+    On conflict → warn (W003), instruct to resolve in worktree, exit.
+
+6b: Merge worktree branch into main (git merge {target.branch} --no-ff).
+    On conflict → save .workflow/.merge-state.json {target, phase:"git_merge_conflict"},
+    instruct: resolve, git merge --continue, then /maestro-merge --continue. Exit.
+
+Display "Git merge successful."
+```
+
+---
+
+## Step 7: Phase 2 — Artifact Sync
+
+```
+Step_7:
+
+7a: Copy milestone artifact directories from worktree → main .workflow/.
+    Filter: artifacts matching target.milestone or target.owned_phases.
+
+7b: Merge artifact registries — update existing by ID, append new entries.
+
+7c: Record in mainState.transition_history:
+    { milestone_num, milestone, action:"worktree_merge", completed_at, branch, phases }
+
+7d: Merge accumulated_context — deduplicate key_decisions, append deferred items.
+
+Update mainState.last_updated, write .workflow/state.json.
+
+7e: Mark completed phases in .workflow/roadmap.md with completion indicator.
+```
+
+---
+
+## Step 8: Cleanup
+
+```
+Unless --no-cleanup: remove git worktree and delete branch.
+Remove target entry from worktrees.json registry.
+Clean up .workflow/.merge-state.json if present.
+```
+
+---
+
+## Step 9: Summary
+
+```
+Display:
+  === MERGE COMPLETE ===
+  Milestone:  M{target.milestone_num} — {target.milestone}
+  Branch:     {target.branch}
+  Phases:     {target.owned_phases.join(', ')}
+  Completed:  {completedPhases.length}/{target.owned_phases.length}
+
+  State:   .workflow/state.json updated
+  Roadmap: .workflow/roadmap.md updated
+
+  Next steps:
+    Skill({ skill: "manage-status" })          -- View dashboard
+    Skill({ skill: "maestro-milestone-audit" }) -- Audit merged milestone
+```

package/workflows/milestone-audit.md

@@ -0,0 +1,155 @@
+# Workflow: milestone-audit
+
+Cross-phase integration audit for milestone completion. Based on artifact registry.
+
+---
+
+## Step 1: Load Milestone Context
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - If no milestone: ERROR E001
+   - Get `artifacts[]` array
+   - Resolve milestone object from `milestones[]` by id
+   - Determine milestone type: `milestone_obj.type` (default `"standard"` if field missing)
+
+2. **Standard milestone** (`type != "adhoc"`):
+   - Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
+
+3. **Adhoc milestone** (`type == "adhoc"`):
+   - Skip roadmap.md parsing (roadmap may not exist)
+   - Phases are defined by `milestone_obj.phases[]` (typically `[1]` with slug `"standalone"`)
+
+4. Group milestone artifacts by type → `analyze_artifacts`, `plan_artifacts`, `execute_artifacts`, `verify_artifacts`
+
+---
+
+## Step 2: Phase Coverage Check
+
+**Standard milestone**: Parse roadmap.md phases for this milestone. For each phase, verify completed artifacts exist for analyze, plan, and execute types. WARN if any phase is missing its execute artifact: "Phase {number} ({title}) missing execute artifact"
+
+**Adhoc milestone**: Skip phase-level coverage check (no roadmap phases to validate). Instead, verify that at least one complete artifact chain exists: plan artifact (PLN) + execute artifact (EXC) with matching milestone ID. WARN if no execute artifact found.
+
+---
+
+## Step 3: Ad-hoc Completeness Check
+
+Check all ad-hoc artifacts (`scope == "adhoc"`) for this milestone are completed. WARN if any incomplete (list ids).
+
+---
+
+## Step 4: Execution Completeness Check
+
+For each execute artifact, read `{path}/.task/TASK-*.json` and verify all tasks are completed or skipped. WARN if any tasks remain incomplete: "Plan {plan_dir}: {N} tasks not completed"
+
+---
+
+## Step 5: Integration Check
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-integration-checker` agent:
+
+```
+Agent({
+  subagent_type: "workflow-integration-checker",
+  prompt: "
+    Audit cross-phase integration for milestone {milestone}.
+
+    Artifacts to audit:
+    {for each execute artifact: path, phase, scope}
+
+    Check:
+    1. SHARED INTERFACES -- Do artifacts that share interfaces have compatible types/contracts?
+    2. DEPENDENCY CHAINS -- Are all cross-phase dependencies satisfied?
+    3. DATA CONTRACTS -- Do data models used across phases match?
+    4. API CONSISTENCY -- Are API endpoints/interfaces consistent?
+    5. CONFIGURATION -- Are shared configs compatible?
+    6. ERROR HANDLING -- Do error flows work across boundaries?
+
+    For each check, report:
+    - Status: passed | gap_found
+    - If gap: description, affected phases, severity, fix suggestion
+
+    Ensure directory exists: mkdir -p .workflow/milestones/{milestone}/
+    Write audit report to .workflow/milestones/{milestone}/audit-report.md
+    Return: summary with gap count and severity breakdown.
+  ",
+  run_in_background: false
+})
+```
+
+---
+
+## Step 5.5: CLI Supplementary Integration Scan (optional)
+
+**Purpose:** Use external CLI tool for broad cross-phase dependency and API consistency checks that complement the agent-based integration checker.
+
+**Skip if** no enabled CLI tools or milestone has only 1 phase.
+
+```
+IF no CLI tools enabled OR phases.length <= 1: skip to Step 6
+
+# Collect all modified files across execute artifacts
+all_execute_paths = execute_artifacts.map(a => a.path)
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Cross-phase integration scan for milestone completion
+TASK: Check for import/export consistency across phase boundaries | Detect shared type/interface mismatches | Identify configuration key conflicts between phases
+MODE: analysis
+CONTEXT: @${all_execute_paths as glob patterns}
+EXPECTED: JSON { import_issues: [{ file, import_path, issue }], type_mismatches: [{ type_name, definitions: [{ file, shape }] }], config_conflicts: [{ key, values: [{ file, value }] }] }
+CONSTRAINTS: Only check cross-phase boundaries | Ignore intra-phase issues
+" --role analyze --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:** Parse result, append to integration checker findings. Critical items surface in Step 6 verdict.
+
+---
+
+## Step 5.9: Artifact & Evidence Verification
+
+Before proceeding to verdict:
+- Verify `audit-report.md` exists at `.workflow/milestones/{milestone}/audit-report.md`. If missing: re-run Step 5.
+- Every audit check result MUST cite what was examined and what was found (e.g., "Phase 1 chain complete: ANL-001 → PLN-001 → EXC-001" or "Phase 2 missing EXC artifact"). Do NOT mark checks as PASS without verifying the actual artifact exists.
+
+---
+
+## Step 6: Audit Report & Verdict
+
+1. Read the audit report generated by the integration checker
+
+2. Determine verdict:
+   - PASS: all phases have complete artifact chains + no critical integration gaps
+   - FAIL: missing execute artifacts OR critical integration gaps
+
+3. Display structured report:
+
+```
+====================================================
+  MILESTONE AUDIT: {milestone} ({milestone_name})
+  ARTIFACTS: {total_count}
+====================================================
+
+PHASE COVERAGE:
+  Phase 1 ({slug}):    ANL-001 → PLN-001 → EXC-001 ✓
+  Phase 2 ({slug}):    ANL-002 → PLN-002 → EXC-002 ✓
+
+AD-HOC TASKS:
+  {topic}: ANL-003 → PLN-003 → EXC-003 ✓
+
+VERIFICATION:
+  VRF-001: milestone-level verify ✓ (or "not yet run")
+
+INTEGRATION:
+  Shared Interfaces:   {passed|N gaps}
+  Dependency Chains:   {passed|N gaps}
+  Data Contracts:      {passed|N gaps}
+
+VERDICT: PASS | FAIL
+====================================================
+```
+
+4. Route next step:
+   - PASS → suggest `/maestro-milestone-complete`
+   - FAIL → suggest specific fix actions

package/workflows/milestone-complete.md

@@ -0,0 +1,167 @@
+# Workflow: milestone-complete
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from $ARGUMENTS or current_milestone)
+   - If no milestone: ERROR E001
+   - Resolve milestone object from `milestones[]` by id
+   - Determine milestone type: `milestone_obj.type` (default `"standard"` if field missing)
+
+2. Check milestone audit status:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` if exists
+   - If no audit report:
+     - ERROR E004: "No audit report found. Audit is a required hard contract — cannot complete without it."
+     - Guidance: "Run `/maestro-milestone-audit` first, then re-run this command."
+     - Exit (skipping audit is not permitted)
+   - If verdict is FAIL: ERROR E002
+
+3. Verify all milestone artifacts have status "completed" → ERROR E003 if any incomplete (list ids and statuses)
+
+---
+
+## Step 2: Create Milestone Archive
+
+1. Create archive directory:
+   ```
+   mkdir -p .workflow/milestones/{milestone}/artifacts/
+   ```
+
+2. Snapshot roadmap:
+   - **Standard milestone**: `cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md`
+   - **Adhoc milestone**: Skip roadmap snapshot (roadmap may not exist)
+
+3. Archive scratch directories: copy each milestone artifact's `.workflow/{artifact.path}` to `.workflow/milestones/{milestone}/artifacts/{basename}/`. After each copy:
+
+   a. If the destination contains `archive.json` with `lifecycle.status == "sealed"`:
+      - Set `lifecycle.status = "archived"`
+      - Set `lifecycle.archived_at = now`
+      - Set `lifecycle.linked_milestone = {milestone}` if currently null
+
+   b. If the destination contains `context-package.json`, prune it (scheme C — non-destructive):
+      - Read full content as `orig`
+      - Compute `pruned` = {
+          `open_questions`: items without `answer` and without `resolved_in`,
+          `constraints`: items where `status == "open"`,
+          `insights`: items beyond index 20 (keep top 20 by source order),
+          `references`: items whose `path` does not exist on disk (relative to session dir)
+        }
+      - If any `pruned.*` is non-empty:
+        - Write `{session_dir}/context-package.pruned.json` containing the dropped items
+        - Rewrite `context-package.json` keeping only:
+          `open_questions` answered/resolved, `constraints` status=locked, `insights[0..20]`, `references` whose paths exist; all other top-level fields unchanged
+        - Update `archive.json.pruned = { "at": now, "counts": { open_questions, constraints, insights, references }, "ref": "context-package.pruned.json" }`
+      - Otherwise leave both files untouched and set `archive.json.pruned = { "at": now, "counts": {...zeros}, "ref": null }`
+
+   c. If the session dir lacks `archive.json` (legacy session prior to lifecycle convention), skip (a) and (b); log W0xx "legacy session not indexed"; flag archive as [LOW CONFIDENCE] (lifecycle.indexed=false, legacy session).
+
+---
+
+## Step 2.5: Load Existing Learnings
+
+```
+existing_learnings = maestro spec load --category coding
+```
+
+Check existing entries to avoid duplicates when appending in Step 3.
+
+---
+
+## Step 3: Extract Learnings
+
+1. For each execute artifact, read `.summaries/` and `reflection-log.md` if exists:
+   - Extract strategy adjustments
+   - Extract patterns discovered
+   - Extract pitfalls encountered
+
+2. Aggregate learnings and append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format. Each entry (strategy adjustment, pattern, or pitfall) follows this template:
+   ```
+   <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
+
+   ### {summary}
+
+   {content}
+   Milestone: {milestone}
+
+   </spec-entry>
+   ```
+
+   **Keyword extraction**: Extract 3-5 domain-specific terms from the content (same rules as `spec-add`).
+
+---
+
+## Step 4: Update State
+
+1. Archive artifact entries to milestone_history:
+   ```json
+   {
+     "milestone_history": [
+       {
+         "id": "{milestone}",
+         "name": "{milestone_name}",
+         "status": "completed",
+         "completed_at": "{now}",
+         "archive_path": "milestones/{milestone}/",
+         "archived_artifacts": [ ...all milestone artifacts entries... ]
+       }
+     ]
+   }
+   ```
+
+2. Clear artifacts array: remove all entries where `milestone == target_milestone`
+
+3. Advance to next milestone:
+   - **Standard milestone**: activate first pending milestone → set as `current_milestone`. If none pending → set `current_milestone = null`, `status = "completed"`
+   - **Adhoc milestone**: Do NOT search for next milestone. Set `current_milestone = null`, `status = "idle"` (adhoc milestones are self-contained, no successor)
+
+4. Write state.json (atomic)
+
+---
+
+## Step 5: Clean Scratch
+
+Remove archived scratch directories: delete `.workflow/{artifact.path}` for each archived artifact.
+
+---
+
+## Step 6: Generate Summary
+
+Write `.workflow/milestones/{milestone}/summary.md`:
+```markdown
+# Milestone: {milestone} — {name}
+
+**Completed**: {date}
+**Artifacts**: {count} (analyze: {n}, plan: {n}, execute: {n}, verify: {n})
+
+## Key Outcomes
+{extracted from audit report + learnings}
+
+## Learnings
+{top patterns and pitfalls}
+
+## Next Milestone
+{next milestone name and first phase, or "Project complete"}
+```
+
+Update `.workflow/project.md` Context section with milestone summary.
+
+---
+
+## Step 7: Report
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone} ({name})
+Artifacts: {count} archived
+Learnings: {learnings_count} extracted
+
+Archive: .workflow/milestones/{milestone}/
+Next:    {next_milestone or "Project complete" or "Ad-hoc task complete"}
+
+Next steps:
+  /maestro-milestone-release    -- Cut a release
+  /maestro-analyze              -- Start next milestone (standard only)
+  /manage-status                -- View project state
+```

package/workflows/milestone-release.md

@@ -0,0 +1,82 @@
+# Workflow: milestone-release
+
+Bump version, generate changelog, and tag the current milestone for release.
+
+> **STATUS: PLACEHOLDER** — minimal skeleton referenced by `maestro-milestone-release.md`.
+> Full release pipeline is TODO. Do not invoke until contents below are fleshed out.
+
+---
+
+## Arguments
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<milestone>` | Milestone id from `.workflow/state.json` `milestones[]` | current_milestone |
+| `--bump <level>` | Semver bump: `major` \| `minor` \| `patch` | `minor` |
+| `--dry-run` | Preview changes without writing | `false` |
+
+---
+
+## Step 1: Validation
+
+1. Read `.workflow/state.json`:
+   - Determine target milestone (from `$ARGUMENTS` or `current_milestone`).
+   - If no milestone: ERROR E001.
+2. Verify milestone is **completed**:
+   - Read `.workflow/milestones/{milestone}/audit-report.md` — verdict must be `PASS`.
+   - If missing or non-PASS: ERROR E002 with guidance to run `/maestro-milestone-complete` first.
+3. Read package manifest (`package.json` / `pyproject.toml` / etc.) — locate current version. TODO: multi-manifest detection.
+
+---
+
+## Step 2: Version Bump
+
+1. Compute next version from `--bump` level (semver). TODO: prerelease/build metadata handling.
+2. Update manifest file in place. If `--dry-run`: print diff and exit.
+
+---
+
+## Step 3: Changelog Generation
+
+1. Read milestone audit report + retrospective insights (`.workflow/milestones/{milestone}/`).
+2. Render `CHANGELOG.md` entry — header `## [vX.Y.Z] - YYYY-MM-DD`, body grouped by `Added / Changed / Fixed / Removed`.
+3. TODO: integrate with `quality-retrospective` output for richer narrative.
+
+---
+
+## Step 4: Tag and Commit
+
+1. Stage updated manifest + `CHANGELOG.md`.
+2. Commit: `chore(release): vX.Y.Z — {milestone}`.
+3. Create annotated git tag `vX.Y.Z`.
+4. TODO: optionally push tag (`--push` flag).
+
+---
+
+## Outputs
+
+| Artifact | Status |
+|----------|--------|
+| Updated manifest version | written |
+| `CHANGELOG.md` entry | appended |
+| Git tag `vX.Y.Z` | created locally (not pushed) |
+
+---
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| E001 | No milestone resolvable |
+| E002 | Milestone not completed / audit not PASS |
+| E003 | Manifest file not found |
+| E004 | Git working tree dirty (uncommitted changes block tagging) |
+
+---
+
+## TODO (placeholder gaps)
+
+- Multi-package monorepo support.
+- Push tag + GitHub release integration.
+- Roll-back path on failed tag.
+- Wire to `manage-knowhow-capture` for release-note capture.