muse-crew 0.4.3 → 0.4.4

package/lib/test-worktree-backend.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# test-worktree-backend.sh — regression tests for lib/worktree-lifecycle.sh
+# (git worktree backend).
+#
+# Lifecycle on a scratch repo:
+#   validate → prepare (CREATED) → prepare (REUSED) → inspect → status →
+#   cleanup → cleanup (idempotent) → dirty-main preflight (exit 4)
+set -u
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+LIFECYCLE="$REPO_DIR/lib/worktree-lifecycle.sh"
+
+fail() { echo "FAIL: $1"; exit 1; }
+
+T=/tmp/crew-git-backend-test
+rm -rf "$T"
+mkdir -p "$T"
+cd "$T"
+git init -q -b main .
+git config user.email test@test.t
+git config user.name test
+echo x > f.txt
+git add -A
+git commit -qm init
+
+export CREW_REPO="$T"
+tid="backendtest1"
+
+# validate: good id passes, bad id is rejected
+bash "$LIFECYCLE" validate "$tid" >/dev/null || fail "validate rejected a good id"
+bash "$LIFECYCLE" validate "bad id!" >/dev/null 2>&1 && fail "validate accepted a bad id"
+
+# prepare: creates worktree + branch + registry entry
+out=$(bash "$LIFECYCLE" prepare "$tid") || fail "prepare exited non-zero: $out"
+echo "$out" | grep -q '^CREATED' || fail "prepare: expected CREATED, got: $out"
+echo "$out" | grep -q '^BASE: ' || fail "prepare: no BASE: line"
+[ -d "$T/.worktrees/$tid" ] || fail "prepare: .worktrees/$tid missing"
+git -C "$T" rev-parse --verify "task/$tid" >/dev/null 2>&1 || fail "prepare: branch task/$tid missing"
+[ -f "$T/.worktrees/.registry/$tid" ] || fail "prepare: registry entry missing"
+grep -q '^branch=task/backendtest1$' "$T/.worktrees/.registry/$tid" || fail "prepare: registry branch wrong"
+grep -q "^path=$T/.worktrees/$tid\$" "$T/.worktrees/.registry/$tid" || fail "prepare: registry path wrong"
+
+# prepare again: reuses the existing worktree
+out=$(bash "$LIFECYCLE" prepare "$tid") || fail "prepare (reuse) exited non-zero"
+echo "$out" | grep -q '^REUSED' || fail "prepare: expected REUSED on second run: $out"
+
+# inspect: diffs the task branch against main
+echo change >> "$T/.worktrees/$tid/f.txt"
+(cd "$T/.worktrees/$tid" && git commit -qam work)
+out=$(bash "$LIFECYCLE" inspect "$tid") || fail "inspect exited non-zero"
+echo "$out" | grep -q "=== Branch: task/$tid ===" || fail "inspect: wrong branch header"
+echo "$out" | grep -q "change" || fail "inspect: diff missing the worktree change"
+
+# status: reports registry, worktree, branch
+out=$(bash "$LIFECYCLE" status "$tid") || fail "status exited non-zero"
+echo "$out" | grep -q "=== Worktree: $tid ===" || fail "status: missing header"
+echo "$out" | grep -q "task/$tid" || fail "status: missing branch info"
+
+# cleanup: removes worktree + branch + registry entry
+out=$(bash "$LIFECYCLE" cleanup "$tid") || fail "cleanup exited non-zero"
+[ -d "$T/.worktrees/$tid" ] && fail "cleanup: worktree still exists"
+git -C "$T" rev-parse --verify "task/$tid" >/dev/null 2>&1 && fail "cleanup: branch still exists"
+[ -f "$T/.worktrees/.registry/$tid" ] && fail "cleanup: registry entry still exists"
+
+# cleanup again: idempotent
+out=$(bash "$LIFECYCLE" cleanup "$tid") || fail "cleanup (idempotent) exited non-zero"
+echo "$out" | grep -q "already clean" || fail "cleanup: expected already-clean on second run"
+
+# prepare fails closed when main is dirty (exit 4)
+echo dirty >> "$T/f.txt"
+if bash "$LIFECYCLE" prepare "backendtest2" >/dev/null 2>&1; then
+  fail "prepare succeeded with dirty main"
+else
+  [ "$?" -eq 4 ] || fail "prepare with dirty main: expected exit 4"
+fi
+git -C "$T" checkout -q -- f.txt
+
+rm -rf "$T"
+echo "worktree-backend: OK"

package/lib/worktree-lifecycle.sh

@@ -1,5 +1,14 @@
 #!/usr/bin/env bash
-# worktree-lifecycle.sh — git worktree lifecycle manager for Muse Crew
+# worktree-lifecycle.sh — worktree lifecycle manager for Muse Crew
+#
+# Git backend: task worktrees live in $REPO/.worktrees/<task_id>, on
+# branches named task/<task_id>. This script is the single seam where the
+# worktree strategy lives — workflows and agents never run raw git worktree
+# commands; they call these lifecycle commands instead.
+#
+# The crew's registry ($REPO/.worktrees/.registry/<task_id>) is the source
+# of truth for task→branch/path. Never reconstruct the mapping from git
+# state alone.
 #
 # Commands:
 #   validate  <task_id>                  — check task ID is safe for branches/paths
@@ -30,6 +39,28 @@ ORPHAN_SWEEP="$LIB_DIR/orphan-sweep.sh"
 
 # --- helpers ---
 
+# Task branch name: task/<id>. The registry wins when the task was
+# prepared before.
+resolve_branch() {
+  local task_id="$1" b
+  if [ -f "$REGISTRY_DIR/$task_id" ]; then
+    b=$(grep '^branch=' "$REGISTRY_DIR/$task_id" | cut -d= -f2-)
+    if [ -n "$b" ]; then printf '%s' "$b"; return 0; fi
+  fi
+  printf 'task/%s' "$task_id"
+}
+
+# Worktree path: $REPO/.worktrees/<id>. The registry wins when the task
+# was prepared before.
+resolve_path() {
+  local task_id="$1" p
+  if [ -f "$REGISTRY_DIR/$task_id" ]; then
+    p=$(grep '^path=' "$REGISTRY_DIR/$task_id" | cut -d= -f2-)
+    if [ -n "$p" ]; then printf '%s' "$p"; return 0; fi
+  fi
+  printf '%s/%s' "$WORKTREE_DIR" "$task_id"
+}
+
 validate_task_id() {
   local id="$1"
   if [[ ! "$id" =~ ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ ]]; then
@@ -57,12 +88,12 @@ require_clean_main() {
 }
 
 register() {
-  local task_id="$1" base_commit="$2"
+  local task_id="$1" base_commit="$2" branch="$3" wt_path="$4"
   mkdir -p "$REGISTRY_DIR"
   cat > "$REGISTRY_DIR/$task_id" <<EOF
 task_id=$task_id
-branch=task/$task_id
-path=$WORKTREE_DIR/$task_id
+branch=$branch
+path=$wt_path
 base_commit=$base_commit
 created=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 EOF
@@ -96,7 +127,7 @@ cmd_prepare() {
     return 0
   fi
 
-  # Preflight: main must be clean
+  # Preflight: main must be clean — prepare fails closed.
   require_clean_main || exit 4
 
   local base_commit
@@ -107,7 +138,7 @@ cmd_prepare() {
   mkdir -p "$WORKTREE_DIR"
   git worktree add "$WORKTREE_DIR/$task_id" -b "task/$task_id"
 
-  register "$task_id" "$base_commit"
+  register "$task_id" "$base_commit" "task/$task_id" "$WORKTREE_DIR/$task_id"
 
   echo "CREATED: .worktrees/$task_id on branch task/$task_id"
   echo "BASE: $base_commit"
@@ -117,26 +148,29 @@ cmd_inspect() {
   local task_id="$1"
   validate_task_id "$task_id"
 
+  local branch
+  branch=$(resolve_branch "$task_id")
+
   cd "$REPO"
 
   # Verify the branch exists
-  if ! git rev-parse --verify "task/$task_id" >/dev/null 2>&1; then
-    echo "ERROR: branch task/$task_id does not exist"
+  if ! git rev-parse --verify "$branch" >/dev/null 2>&1; then
+    echo "ERROR: branch $branch does not exist"
     return 1
   fi
 
-  echo "=== Branch: task/$task_id ==="
+  echo "=== Branch: $branch ==="
   local tip
-  tip=$(git rev-parse "task/$task_id")
+  tip=$(git rev-parse "$branch")
   echo "TIP: $tip"
   echo ""
   echo "=== Commits ahead of main ==="
-  git log --oneline "main..task/$task_id"
+  git log --oneline "main..$branch"
   echo ""
-  echo "=== Diff: main...task/$task_id ==="
-  git diff --stat "main...task/$task_id"
+  echo "=== Diff: main...$branch ==="
+  git diff --stat "main...$branch"
   echo ""
-  git diff "main...task/$task_id"
+  git diff "main...$branch"
 }
 
 cmd_integrate() {
@@ -144,24 +178,27 @@ cmd_integrate() {
   local commit_msg="${2:-merge: $task_id}"
   validate_task_id "$task_id"
 
+  local branch
+  branch=$(resolve_branch "$task_id")
+
   cd "$REPO"
 
   # Preflight: main must be clean
   require_clean_main || exit 4
 
   # Verify task branch exists and has commits ahead of main
-  if ! git rev-parse --verify "task/$task_id" >/dev/null 2>&1; then
-    echo "ERROR: branch task/$task_id does not exist"
+  if ! git rev-parse --verify "$branch" >/dev/null 2>&1; then
+    echo "ERROR: branch $branch does not exist"
     return 1
   fi
 
   local ahead
-  ahead=$(git rev-list --count "main..task/$task_id")
+  ahead=$(git rev-list --count "main..$branch")
   if [ "$ahead" -eq 0 ]; then
     # Approved empty diff: the deliverable was runtime state (cron,
     # scheduler, dashboard config), not a repo change. Nothing to merge,
     # nothing to serialize — the merge lock is intentionally not taken.
-    echo "MERGED_EMPTY: task/$task_id has no commits ahead of main — runtime-state deliverable, nothing to merge"
+    echo "MERGED_EMPTY: $branch has no commits ahead of main — runtime-state deliverable, nothing to merge"
     return 0
   fi
 
@@ -174,7 +211,7 @@ cmd_integrate() {
   echo "$lock_result"
 
   # Merge
-  if ! git merge --no-ff "task/$task_id" -m "$commit_msg" 2>&1; then
+  if ! git merge --no-ff "$branch" -m "$commit_msg" 2>&1; then
     echo "CONFLICT: merge failed — aborting"
     git merge --abort 2>/dev/null || true
     exit 3
@@ -248,6 +285,10 @@ cmd_status() {
   local task_id="$1"
   validate_task_id "$task_id"
 
+  local branch wt_path
+  branch=$(resolve_branch "$task_id")
+  wt_path=$(resolve_path "$task_id")
+
   cd "$REPO"
 
   echo "=== Worktree: $task_id ==="
@@ -261,11 +302,11 @@ cmd_status() {
   fi
 
   # Worktree existence
-  if [ -d "$WORKTREE_DIR/$task_id" ]; then
-    echo "Worktree: exists at .worktrees/$task_id"
+  if [ -n "$wt_path" ] && [ -d "$wt_path" ]; then
+    echo "Worktree: exists at $wt_path"
     local head dirty
-    head=$(cd "$WORKTREE_DIR/$task_id" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
-    dirty=$(cd "$WORKTREE_DIR/$task_id" && git status --porcelain 2>/dev/null | wc -l)
+    head=$(cd "$wt_path" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+    dirty=$(cd "$wt_path" && git status --porcelain 2>/dev/null | wc -l)
     echo "HEAD: $head"
     [ "$dirty" -gt 0 ] && echo "Dirty: $dirty uncommitted changes" || echo "Dirty: clean"
   else
@@ -273,13 +314,13 @@ cmd_status() {
   fi
 
   # Branch existence and merge status
-  if git rev-parse --verify "task/$task_id" >/dev/null 2>&1; then
+  if git rev-parse --verify "$branch" >/dev/null 2>&1; then
     local ahead behind
-    ahead=$(git rev-list --count "main..task/$task_id" 2>/dev/null || echo "?")
-    behind=$(git rev-list --count "task/$task_id..main" 2>/dev/null || echo "?")
-    echo "Branch: task/$task_id (${ahead} ahead, ${behind} behind main)"
+    ahead=$(git rev-list --count "main..$branch" 2>/dev/null || echo "?")
+    behind=$(git rev-list --count "$branch..main" 2>/dev/null || echo "?")
+    echo "Branch: $branch (${ahead} ahead, ${behind} behind main)"
     local merged
-    merged=$(git branch --merged main 2>/dev/null | sed 's/^[* +]*//' | grep -Fx "task/$task_id" || true)
+    merged=$(git branch --merged main 2>/dev/null | sed 's/^[* +]*//' | grep -Fx "$branch" || true)
     [ -n "$merged" ] && echo "Merged: yes" || echo "Merged: no"
   else
     echo "Branch: not found"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Opinionated orchestration for Muse \u2014 workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,

package/seed/cron-body-template.md

@@ -6,15 +6,17 @@ You are the dispatch trigger for Muse Crew. Run the authoritative dispatcher wor
 
 1. **Load tools:** Call tool_search_load_tool_namespace with paths ["workflow_launch"].
 
-2. **Run the dispatcher:** Call workflow_launch with scriptPath "{crewHome}/workflows/crew-dispatch.js" and args {"dashboardSlug": "{dashboardSlug}", "crewHome": "{crewHome}"}.
+2. **Load the workflow registry:** Read the file "{crewHome}/workflows/registry.json" with the read tool and parse it as JSON. If the file does not exist (the live release predates the registry), proceed without it — omit the `registry` arg and the dispatcher will load the registry the slow way and log a warning.
+
+3. **Run the dispatcher:** Call workflow_launch with scriptPath "{crewHome}/workflows/crew-dispatch.js" and args {"dashboardSlug": "{dashboardSlug}", "crewHome": "{crewHome}", "registry": <parsed registry JSON, or omit the key when the file was missing>}.
 
    Wait for it to complete. It reads the board, determines eligibility, claims tasks, acknowledges the poll, and returns structured results.
 
-3. **Report claims:** Extract the `claims` array from the dispatcher result. For each claim, emit one line:
+4. **Report claims:** Extract the `claims` array from the dispatcher result. For each claim, emit one line:
    LAUNCH: script={claim.scriptPath} args={JSON.stringify(claim.args)}
 
    If the dispatcher returned no claims or the claims array is empty, report: NO_DISPATCH
 
    Do NOT call workflow_launch_async for any task workflow. The main chat agent does that.
 
-4. Exit silently.
+5. Exit silently.

package/seed/workflows/bugfix.md

@@ -6,7 +6,11 @@ The full software engineering workflow. Use for bug reports where reproduction m
 
 ### Triage
 **Identity:** Sage
-Validate, prioritize, connect dependencies, assign this workflow. If the task needs decomposition, break it into subtasks first.
+Validate, prioritize, connect dependencies, assign this workflow. If the task needs decomposition, break it into subtasks first. Flags the task experiential when it changes anything rendered and visible in the artifact.
+
+### Capture
+**Identity:** Hazel
+Baseline evidence for experiential tasks only — skipped otherwise. The capture itself is parent-driven; the workflow records a baseline request and parks for the parent protocol (`docs/visual-verdict.md`). After two requests the task continues with `baseline: none`.
 
 ### Reproduce
 **Identity:** Hazel
@@ -15,7 +19,7 @@ Validate, prioritize, connect dependencies, assign this workflow. If the task ne
 
 ### Map
 **Identity:** Mara
-Update the task with a solution-oriented spec. Research options, pick the shortest path, write it clearly enough that the builder doesn't need to ask questions.
+Update the task with a solution-oriented spec. Research options, pick the shortest path, write it clearly enough that the builder doesn't need to ask questions. For experiential tasks, the spec cannot be written without baseline evidence (or an explicit `baseline: none`) — without it Map bounces back to Capture.
 
 ### Build
 **Identity:** Wren
@@ -40,3 +44,4 @@ Optional. Ships the merged code to the project's publish target (`deploy_type` o
 **Personas:** Yes — Hazel wears a persona costume to test from that perspective.
 **Constraint:** No code context. Same tools and process as reproduction. Pass or fail. File follow-up tasks for related issues found during testing.
 Fail if public-affecting changes lack public docs. Public docs are not code — Hazel reads them as a user would.
+**Visual verdict:** for experiential artifact tasks, the QA agent covers the mechanical checks only — the visual verdict is owned by the parent after the rendered post-change inspection results arrive (`docs/visual-verdict.md`). No experiential task completes without a recorded visual PASS.

package/seed/workflows/chore.md

@@ -1,16 +1,20 @@
 # Chore
 
-For routine maintenance and simple tasks. Like Standard but without QA — the change is low-risk enough to ship after review.
+For routine maintenance and simple tasks. Like Standard but without QA — the change is low-risk enough to ship after review. Capture keeps its baseline pass for experiential tasks, but there is no visual verdict and no QA gate here.
 
 ## Steps
 
 ### Triage
 **Identity:** Sage
-Validate, prioritize, connect dependencies, assign this workflow.
+Validate, prioritize, connect dependencies, assign this workflow. Flags the task experiential when it changes anything rendered and visible in the artifact.
+
+### Capture
+**Identity:** Hazel
+Baseline evidence for experiential tasks only — skipped otherwise. The capture itself is parent-driven; the workflow records a baseline request and parks for the parent protocol (`docs/visual-verdict.md`). After two requests the task continues with `baseline: none`.
 
 ### Map
 **Identity:** Mara
-Research options, pick the path, write the spec.
+Research options, pick the path, write the spec. For experiential tasks, the spec cannot be written without baseline evidence (or an explicit `baseline: none`) — without it Map bounces back to Capture.
 
 ### Build
 **Identity:** Wren

package/seed/workflows/standard.md

@@ -6,11 +6,15 @@ The default workflow for feature work and improvements. Like Bugfix but without
 
 ### Triage
 **Identity:** Sage
-Validate, prioritize, connect dependencies, assign this workflow.
+Validate, prioritize, connect dependencies, assign this workflow. Flags the task experiential when it changes anything rendered and visible in the artifact.
+
+### Capture
+**Identity:** Hazel
+Baseline evidence for experiential tasks only — skipped otherwise. The capture itself is parent-driven; the workflow records a baseline request and parks for the parent protocol (`docs/visual-verdict.md`). After two requests the task continues with `baseline: none` and final QA judges on the rubric alone.
 
 ### Map
 **Identity:** Mara
-Research options, pick the path, write the spec.
+Research options, pick the path, write the spec. For experiential tasks, the spec cannot be written without baseline evidence (or an explicit `baseline: none`) — without it Map bounces back to Capture.
 
 ### Build
 **Identity:** Wren
@@ -35,3 +39,4 @@ Optional. Ships the merged code to the project's publish target (`deploy_type` o
 **Personas:** Yes — Hazel wears a persona costume to test from that perspective.
 **Constraint:** No code context. Pass or fail. File follow-up tasks for related issues found during testing.
 Fail if public-affecting changes lack public docs. Public docs are not code — Hazel reads them as a user would.
+**Visual verdict:** for experiential artifact tasks, the QA agent covers the mechanical checks only — the visual verdict is owned by the parent after the rendered post-change inspection results arrive (`docs/visual-verdict.md`). No experiential task completes without a recorded visual PASS.

package/workflows/AGENTS.md

@@ -2,11 +2,11 @@
 
 Executable Muse workflow scripts (JavaScript). These are what the workflow runtime actually runs.
 
-- `crew-dispatch.js` — reads the board, claims eligible tasks, returns structured launch records
+- `crew-dispatch.js` — reads the board, recommends eligible tasks, returns structured launch records (the launched workflow self-claims; the dispatcher never writes claims)
 - `crew-init.js` — sets up a new crew instance: orchestration folders, dashboard, cron, sample project
-- `standard.js` — default task workflow: Triage → Map → Build → Review → Integrate → Publish → QA
-- `bugfix.js` — adds Reproduce after Triage
-- `chore.js` — drops QA (low-risk)
+- `standard.js` — default task workflow: Triage → Capture → Map → Build → Review → Integrate → Publish → QA
+- `bugfix.js` — adds Capture after Triage, then Reproduce
+- `chore.js` — adds Capture after Triage, drops QA (low-risk)
 - `docs.js` — Tate writes, Cass reviews
 
 The `.js` scripts here are distinct from the `.md` definitions in `seed/workflows/` and `.orchestration/workflows/`. The `.md` files describe phases and prompts; these `.js` files execute them.