maestro-flow 0.3.14 → 0.3.16

package/workflows/fork.md

@@ -8,25 +8,13 @@ Worktrees operate at the **milestone level** — all phases within a milestone a
 
 ## Step 1: Parse Arguments and Flags
 
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const syncMode = $ARGUMENTS.includes('--sync')
-const baseMatch = $ARGUMENTS.match(/--base\s+(\S+)/)
-const baseBranch = baseMatch ? baseMatch[1] : 'HEAD'
-
-// Parse milestone number: -m <N> or bare <N>
-const mFlagMatch = $ARGUMENTS.match(/-m\s+(\d+)/)
-const cleaned = $ARGUMENTS
-  .replace(/--sync|--base\s+\S+|-m\s+\d+/g, '')
-  .trim()
-const bareNumMatch = cleaned.match(/^(\d+)$/)
-const milestoneNum = mFlagMatch
-  ? parseInt(mFlagMatch[1])
-  : bareNumMatch
-    ? parseInt(bareNumMatch[1])
-    : null
+```
+Timestamps use UTC+8 ISO format throughout.
+
+Parse from $ARGUMENTS:
+  --sync          → syncMode (sync existing worktree instead of forking)
+  --base <ref>    → baseBranch (default: HEAD)
+  -m <N> or bare <N> → milestoneNum (1-based)
 ```
 
 ---
@@ -34,25 +22,10 @@ const milestoneNum = mFlagMatch
 ## Step 2: Validate Prerequisites
 
 ```
-IF NOT file_exists(".workflow/state.json"):
-  ERROR E001: "Project not initialized. Run maestro-init first."
-  EXIT
-
-IF NOT file_exists(".workflow/roadmap.md"):
-  ERROR E002: "No roadmap found. Run maestro-roadmap first."
-  EXIT
-
-IF file_exists(".workflow/worktree-scope.json"):
-  ERROR E003: "Cannot fork from inside a worktree. Run from the main worktree."
-  EXIT
-
-IF milestoneNum === null:
-  ERROR E004: "Milestone number required. Usage: maestro-fork -m <number>"
-  EXIT
-
-Read .workflow/state.json → projectState
-Read .workflow/config.json → config (if exists, else use defaults)
+Require: .workflow/state.json (E001), .workflow/roadmap.md (E002), milestoneNum (E004).
+Reject: .workflow/worktree-scope.json present (E003 — cannot fork from inside a worktree).
 
+Read projectState from state.json, config from config.json (defaults if missing).
 worktreeRoot = config.worktree?.root ?? ".worktrees"
 branchPrefix = config.worktree?.branch_prefix ?? "milestone/"
 ```
@@ -62,25 +35,11 @@ branchPrefix = config.worktree?.branch_prefix ?? "milestone/"
 ## Step 3: Resolve Milestone
 
 ```
-// Lookup milestone by number from state.json.milestones[]
-IF NOT projectState.milestones || NOT Array.isArray(projectState.milestones):
-  ERROR E005: "No milestones defined in state.json."
-  EXIT
-
-// milestones[] is 0-indexed, milestoneNum is 1-based
-milestoneEntry = projectState.milestones[milestoneNum - 1]
-
-IF NOT milestoneEntry:
-  availableList = projectState.milestones
-    .map((m, i) => "  M" + (i + 1) + ": " + m.name + " (" + m.title + ")")
-    .join("\n")
-  ERROR E006: "Milestone {milestoneNum} not found.\nAvailable:\n{availableList}"
-  EXIT
-
-milestoneName = milestoneEntry.name       // e.g. "Production"
-milestoneTitle = milestoneEntry.title      // e.g. "生产就绪"
-milestonePhases = milestoneEntry.phases    // e.g. [3, 4]
-milestoneSlug = milestoneName.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+Lookup milestoneEntry from projectState.milestones[milestoneNum - 1] (1-based).
+E005 if no milestones array; E006 if index out of range (list available milestones).
+
+Extract: milestoneName (.name), milestoneTitle (.title), milestonePhases (.phases).
+milestoneSlug = kebab-case of milestoneName, max 40 chars.
 ```
 
 ---
@@ -91,29 +50,10 @@ If `syncMode` is true, this is a sync operation on an existing worktree, not a f
 
 ```
 IF syncMode:
-  Read .workflow/worktrees.json → registry
-  entry = registry.worktrees.find(w =>
-    w.milestone_num === milestoneNum && w.status === "active"
-  )
-
-  IF NOT entry:
-    ERROR E007: "No active worktree for milestone {milestoneNum} ({milestoneName})"
-    EXIT
-
-  // Step 4a: Pull source code
-  Bash("cd {entry.path} && git merge main")
-  IF conflict:
-    WARN "Merge conflict in worktree. Resolve in {entry.path} before continuing."
-    EXIT
-
-  // Step 4b: Re-copy shared context
-  Copy .workflow/project.md → {entry.path}/.workflow/project.md
-  Copy .workflow/roadmap.md → {entry.path}/.workflow/roadmap.md
-  Copy .workflow/config.json → {entry.path}/.workflow/config.json (if exists)
-  Copy .workflow/specs/ → {entry.path}/.workflow/specs/ (if exists)
-
-  Display "Worktree for M{milestoneNum} ({milestoneName}) synced with main."
-  EXIT (sync complete)
+  Find active worktree entry for milestoneNum in worktrees.json → E007 if not found.
+  Git merge main into worktree → warn and exit on conflict.
+  Re-copy shared context: project.md, roadmap.md, config.json (if exists), specs/ (if exists).
+  Display sync confirmation. EXIT.
 ```
 
 ---
@@ -121,41 +61,12 @@ IF syncMode:
 ## Step 5: Validate & Confirm
 
 ```
-// Load phase status from artifact registry
-phaseList = []
-artifacts = projectState.artifacts ?? []
-
-// Derive phase status from artifact registry
-for (phaseNum of milestonePhases):
-  execArtifacts = artifacts.filter(a => a.type === 'execute' && a.phase === phaseNum)
-  status = execArtifacts.some(a => a.status === 'completed') ? 'completed'
-         : execArtifacts.length > 0 ? 'in_progress'
-         : 'pending'
-  phaseList.push({ phase: phaseNum, title: "Phase " + phaseNum, status })
-
-// Validate: milestone should have at least one non-completed phase
-nonCompleted = phaseList.filter(p => p.status !== "completed")
-IF nonCompleted.length === 0:
-  Display "All phases in M{milestoneNum} ({milestoneName}) are already completed. Nothing to fork."
-  EXIT
-
-// Check for already-forked milestone
-IF file_exists(".workflow/worktrees.json"):
-  Read .workflow/worktrees.json → existingRegistry
-  alreadyForked = existingRegistry.worktrees.find(w =>
-    w.milestone_num === milestoneNum && w.status === "active"
-  )
-  IF alreadyForked:
-    ERROR E008: "M{milestoneNum} already has an active worktree at {alreadyForked.path}. Merge or cleanup first."
-    EXIT
-
-Display "Fork Milestone {milestoneNum}: {milestoneName} ({milestoneTitle})"
-Display "Phases ({phaseList.length}):"
-for (p of phaseList):
-  Display "  Phase {p.phase}: {p.title} [{p.status}]"
-
-AskUserQuestion: "Create worktree for this milestone? (y/n)"
-IF response !== 'y': EXIT
+Derive phase statuses from artifact registry (execute artifacts → completed/in_progress/pending).
+Reject if all phases completed (nothing to fork).
+Reject if milestone already has active worktree (E008).
+
+Display milestone info and phase list with statuses.
+Confirm with user → exit if declined.
 ```
 
 ---
@@ -163,87 +74,43 @@ IF response !== 'y': EXIT
 ## Step 6: Create Worktree
 
 ```
-const forkSessionId = "fork-" + getUtc8ISOString().substring(0, 19).replace(/[-:T]/g, '')
-const baseCommit = Bash("git rev-parse HEAD").trim()
-const branch = branchPrefix + milestoneSlug
-const wtPath = worktreeRoot + "/m" + milestoneNum + "-" + milestoneSlug
-
-// 6a: Clean up stale worktree/branch if exists
-IF directory_exists(wtPath):
-  Bash("git worktree remove --force {wtPath}") // ignore errors
-Bash("git branch -D {branch}") // ignore errors (may not exist)
-
-// 6b: Create worktree
-Bash("git worktree add -b {branch} {wtPath} {baseBranch}")
-
-// 6c: Create .workflow/ structure in worktree
-Bash("mkdir -p {wtPath}/.workflow/scratch")
-
-// 6d: Copy shared context (read-only)
-Copy .workflow/project.md → {wtPath}/.workflow/project.md
-Copy .workflow/roadmap.md → {wtPath}/.workflow/roadmap.md
-IF file_exists(".workflow/config.json"):
-  Copy .workflow/config.json → {wtPath}/.workflow/config.json
-IF directory_exists(".workflow/specs"):
-  Copy .workflow/specs/ → {wtPath}/.workflow/specs/
-
-// 6e: Copy milestone artifacts to worktree
-ownedPhaseNumbers = milestonePhases.slice()  // all phases in this milestone
-
-// Copy scratch dirs for this milestone's artifacts
-milestoneArtifacts = artifacts.filter(a =>
-  a.milestone === milestoneName && a.path
-)
-for (art of milestoneArtifacts):
-  IF directory_exists(".workflow/" + art.path):
-    Copy .workflow/{art.path}/ → {wtPath}/.workflow/{art.path}/
-
-// 6f: Copy dependency artifacts (phases outside this milestone)
-// Collect dependency phases from roadmap milestone entry
-// (cross-milestone dependencies are defined in milestoneEntry.depends_on or roadmap)
-depPhases = new Set()
-IF milestoneEntry.depends_on:
-  for (dep of milestoneEntry.depends_on):
-    IF NOT ownedPhaseNumbers.includes(dep):
-      depPhases.add(dep)
-// Copy dependency artifacts from main
-for (dep of depPhases):
-  depArtifacts = artifacts.filter(a => a.phase === dep && a.path)
-  for (art of depArtifacts):
-    IF directory_exists(".workflow/" + art.path):
-      Copy .workflow/{art.path}/ → {wtPath}/.workflow/{art.path}/
-
-// 6g: Build phase_dependencies map for worktree-scope
-phaseDeps = {}
-IF milestoneEntry.depends_on:
-  for (phaseNum of ownedPhaseNumbers):
-    phaseDeps[String(phaseNum)] = milestoneEntry.depends_on
-      .filter(d => !ownedPhaseNumbers.includes(d))
-
-// 6h: Write worktree-scope.json
-Write {wtPath}/.workflow/worktree-scope.json:
-  {
-    "worktree": true,
-    "milestone_num": milestoneNum,
-    "milestone": milestoneName,
-    "owned_phases": ownedPhaseNumbers,
-    "phase_dependencies": phaseDeps,
-    "main_worktree": resolve(cwd),
-    "branch": branch,
-    "base_commit": baseCommit,
-    "created_at": getUtc8ISOString()
-  }
-
-// 6i: Write scoped state.json
-Read .workflow/state.json → mainState
-firstPending = phaseList.find(p => p.status !== "completed")
-scopedState = {
-  ...mainState,
-  current_milestone: milestoneName,
-  // Carry over milestone-scoped artifacts to worktree
-  artifacts: artifacts.filter(a => a.milestone === milestoneName || ownedPhaseNumbers.includes(a.phase))
+forkSessionId = "fork-{UTC8_compact_timestamp}"
+baseCommit = git rev-parse HEAD
+branch = {branchPrefix}{milestoneSlug}
+wtPath = {worktreeRoot}/m{milestoneNum}-{milestoneSlug}
+
+6a: Clean up stale worktree/branch at wtPath if exists (ignore errors).
+6b: git worktree add -b {branch} {wtPath} {baseBranch}
+6c: mkdir -p {wtPath}/.workflow/scratch
+
+6d: Copy shared context → wtPath/.workflow/:
+    project.md, roadmap.md, config.json (if exists), specs/ (if exists)
+
+6e: Copy milestone artifacts — all artifacts matching milestoneName.
+6f: Copy dependency artifacts — phases from milestoneEntry.depends_on not in owned phases.
+
+6g: Build phase_dependencies map (external deps per owned phase).
+```
+
+Write `{wtPath}/.workflow/worktree-scope.json`:
+
+```json
+{
+  "worktree": true,
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "owned_phases": ["{ownedPhaseNumbers}"],
+  "phase_dependencies": "{phaseDeps}",
+  "main_worktree": "{resolve(cwd)}",
+  "branch": "{branch}",
+  "base_commit": "{baseCommit}",
+  "created_at": "{UTC8_ISO}"
 }
-Write {wtPath}/.workflow/state.json: scopedState
+```
+
+```
+6i: Write scoped state.json — clone mainState with current_milestone set,
+    artifacts filtered to milestone-owned phases only.
 ```
 
 ---
@@ -251,42 +118,17 @@ Write {wtPath}/.workflow/state.json: scopedState
 ## Step 7: Update Main Registry
 
 ```
-IF file_exists(".workflow/worktrees.json"):
-  Read .workflow/worktrees.json → registry
-ELSE:
-  registry = { version: "1.0", worktrees: [], fork_sessions: [] }
-
-registry.worktrees.push({
-  milestone_num: milestoneNum,
-  milestone: milestoneName,
-  slug: milestoneSlug,
-  branch: branch,
-  path: wtPath,
-  base_commit: baseCommit,
-  status: "active",
-  created_at: getUtc8ISOString(),
-  owned_phases: ownedPhaseNumbers,
-  fork_session: forkSessionId
-})
-
-registry.fork_sessions.push({
-  session_id: forkSessionId,
-  created_at: getUtc8ISOString(),
-  milestone_num: milestoneNum,
-  milestone: milestoneName,
-  base_branch: baseBranch,
-  base_commit: baseCommit
-})
-
-Write .workflow/worktrees.json: registry
-
-// Mark milestone phases as "forked"
-// In artifact registry model, worktrees.json tracks forked state.
-// No per-phase marking needed — the registry entry signals ownership.
-// (worktrees.json already updated above with owned_phases)
-
-mainState.last_updated = getUtc8ISOString()
-Write .workflow/state.json: mainState
+Load or initialize .workflow/worktrees.json (default: { version:"1.0", worktrees:[], fork_sessions:[] }).
+
+Append to worktrees[]:
+  { milestone_num, milestone, slug, branch, path:wtPath, base_commit, status:"active",
+    created_at, owned_phases, fork_session:forkSessionId }
+
+Append to fork_sessions[]:
+  { session_id:forkSessionId, created_at, milestone_num, milestone, base_branch, base_commit }
+
+Write worktrees.json. Update mainState.last_updated, write state.json.
+Note: worktrees.json owned_phases tracks forked state — no per-phase marking needed.
 ```
 
 ---

package/workflows/harvest.md

@@ -43,20 +43,11 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 ## Stage 1: parse_input
 
 ```
-1. Verify .workflow/ exists; else error E001.
-2. Tokenize $ARGUMENTS:
-   - First non-flag token: session ID, path, or empty (scan mode)
-   - Flags: --to, --source, --recent, --dry-run, -y, --min-confidence
-3. Build:
-     mode = "scan" | "session" | "path"
-     target_filter = "auto" | "wiki" | "spec" | "issue"
-     source_filter = "all" | specific source type
-     recent_days = 30 (or --recent value)
-     dry_run = false
-     auto_yes = false
-     min_confidence = 0.5
-4. Validate --to value. Unknown target → error E002.
-5. Validate --source value. Unknown source → error E003.
+Verify .workflow/ exists (else E001). Parse flags and first non-flag token:
+  mode: "scan" (no target) | "session" (ID match) | "path" (explicit path)
+  Defaults: target_filter=auto, source_filter=all, recent_days=30,
+            dry_run=false, auto_yes=false, min_confidence=0.5
+Invalid --to → E002. Invalid --source → E003.
 ```
 
 ---
@@ -78,22 +69,7 @@ Scan `.workflow/` for harvestable artifacts. Each source type has a known struct
 | `session` | `.workflow/active/WFS-*/` | `workflow-session.json` | `WFS-*` |
 | `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md`, `*.md` | filename |
 
-```
-candidates = []
-FOR each source_type in source_registry:
-  IF source_filter != "all" AND source_filter != source_type: SKIP
-  Glob for directories/files matching scan_path
-  FOR each match:
-    stat = file modification time
-    IF stat.mtime < (now - recent_days): SKIP
-    Read key files, extract:
-      - session_id or directory name
-      - title (from JSON title field or markdown H1)
-      - created_at / updated_at
-      - summary (first paragraph or JSON summary field)
-      - file_count (number of artifact files)
-    candidates.push({ source_type, id, path, title, updated_at, summary, file_count })
-```
+Scan each source type (filtered by `--source`). For each matching directory/file within `--recent` window, extract: `source_type`, `id`, `path`, `title` (from JSON or H1), `updated_at`, `summary`, `file_count`.
 
 ### Display candidates
 
@@ -219,20 +195,11 @@ For each fragment, determine the best routing target (unless `--to` forces a spe
 
 ### Override with `--to`
 
-If `--to wiki`: all fragments → wiki entries
-If `--to spec`: all fragments → spec entries
-If `--to issue`: all fragments → issue entries
-If `--to auto`: use classification rules above
+`--to wiki|spec|issue` forces all fragments to that target. `--to auto` (default) uses classification rules above.
 
 ### Build routing plan
 
-```
-routing_plan = {
-  wiki: [{ fragment, wiki_type, slug, title, tags, body }],
-  spec: [{ fragment, spec_type, content }],
-  issue: [{ fragment, title, severity, description }]
-}
-```
+Group fragments into three buckets: `wiki` (fragment, wiki_type, slug, title, tags, body), `spec` (fragment, spec_type, content), `issue` (fragment, title, severity, description).
 
 ---
 
@@ -262,11 +229,7 @@ Fragments extracted: 8 (filtered from 12 by confidence ≥ 0.5)
   Total: 3 wiki + 2 spec + 3 issue = 8 routed items
 ```
 
-If `--dry-run`: display and exit.
-If NOT `--dry-run` AND NOT `-y`:
-  AskUserQuestion: "Apply this routing plan? (yes/edit/skip)" with options.
-  - `edit`: re-display with per-item accept/reject
-  - `skip`: exit without writing
+`--dry-run` → display and exit. Otherwise (unless `-y`), AskUserQuestion: "yes" (apply), "edit" (per-item accept/reject), "skip" (abort).
 
 ---
 
@@ -276,32 +239,11 @@ Execute the routing plan. Each target uses existing infrastructure:
 
 ### 6a. Wiki routing
 
-For each wiki item:
-```bash
-maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id> \
-  --title "<title>" --tags "<tags>" --body "<body>"
-```
-
-Wiki types mapping:
-- `note` → `--type note`
-- `lesson` → `--type lesson`
-- `spec` → `--type spec`
-
-If `maestro wiki create` fails, fall back to writing `.workflow/harvest/wiki-pending-{id}.md` with frontmatter.
+Create via `maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id> --title --tags --body`. Types: note/lesson/spec. Fallback on failure: write `.workflow/harvest/wiki-pending-{id}.md` with frontmatter.
 
 ### 6b. Spec routing
 
-For each spec item, use the same mechanism as `quality-retrospective` Stage 6:
-
-```
-Skill({ skill: "spec-add", args: "<spec_type> <content>" })
-```
-
-Where `spec_type` maps from fragment category:
-- `pattern` → `pattern`
-- `decision` → `decision`
-- `bug` → `bug`
-- `lesson` → `rule` (if it prescribes a rule)
+Route via `Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Category mapping: pattern→pattern, decision→decision, bug→bug, lesson→rule.
 
 ### 6c. Issue routing
 
@@ -345,16 +287,7 @@ This log prevents duplicate harvesting in future runs.
 
 ## Stage 7: dedup_check
 
-Before writing any item in Stage 6, check for duplicates:
-
-1. **harvest-log.jsonl**: Has this fragment_id already been routed?
-2. **Wiki**: `maestro wiki search "<title>"` — does a similar entry exist?
-3. **Issues**: Search `issues.jsonl` for matching title/description
-4. **Specs**: Search `learnings.md` for similar content
-
-If duplicate found:
-- Skip with `[SKIP-DUP]` marker
-- Log to harvest report
+Before writing any item in Stage 6, check for duplicates across `harvest-log.jsonl` (by fragment_id), wiki (by title search), `issues.jsonl` (by title/description), and `learnings.md` (by content). Duplicates are skipped with `[SKIP-DUP]` marker and logged to harvest report.
 
 ---
 

package/workflows/init.md

@@ -7,10 +7,7 @@ Project initialization with automatic state detection. Creates project infrastru
 ## Worktree Guard
 
 ```
-# Block in worktree
-IF file_exists(".workflow/worktree-scope.json"):
-  ERROR "Cannot run maestro-init inside a worktree. Run from the main worktree."
-  EXIT
+If .workflow/worktree-scope.json exists: error "Cannot run maestro-init inside a worktree." and exit.
 ```
 
 ## Step 1: State Detection
@@ -18,11 +15,7 @@ IF file_exists(".workflow/worktree-scope.json"):
 Detect current project state to determine initialization path.
 
 ```
-CHECK .workflow/state.json exists?
-  YES → Path C (existing project)
-  NO  → CHECK if directory has source code files (*.ts, *.js, *.py, *.java, *.go, etc.)
-    YES → Path B (brownfield)
-    NO  → Path A (greenfield)
+state.json exists → Path C (existing) | source files exist → Path B (brownfield) | else → Path A (greenfield)
 ```
 
 ### Path A: Empty/Greenfield Project
@@ -73,14 +66,7 @@ CHECK .workflow/state.json exists?
    Write `.workflow/config.json` from template + user selections.
    If `--auto`: use defaults (standard, parallel, commit, all agents on).
 
-3. **Research** (optional, based on config.workflow.research) -- Spawn 4 parallel `workflow-project-researcher` agents:
-   ```
-   Agent 1: Stack      → .workflow/research/STACK.md (standard tech stack for domain)
-   Agent 2: Features   → .workflow/research/FEATURES.md (table stakes vs differentiators)
-   Agent 3: Arch       → .workflow/research/ARCHITECTURE.md (component boundaries, data flow)
-   Agent 4: Pitfalls   → .workflow/research/PITFALLS.md (common mistakes, prevention)
-   ```
-   Each agent writes directly to `.workflow/research/` -- orchestrator receives confirmation only.
+3. **Research** (optional, based on config.workflow.research) -- Spawn 4 parallel `workflow-project-researcher` agents writing to `.workflow/research/`: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.
 
 4. **Synthesize** -- Spawn `workflow-research-synthesizer` agent:
    - Input: all `.workflow/research/` documents