muse-crew 0.2.0 → 0.3.0

package/API.md

@@ -33,7 +33,7 @@ Update an existing task's fields. Only `id` is required; all other fields are op
 | `description` | string (≤ 3000) | no | |
 | `state` | `todo` · `in_progress` · `parked` · `done` | no | |
 | `priority` | `high` · `normal` · `low` | no | |
-| `project` | slug | no | |
+| `project` | slug | no | **Project-move guard:** changing this to a different project throws while the task has an active run (an agent session with status `running` that started within the last hour), because the live run keeps the old project's repo context and moving it mid-phase would work on the wrong repo. Wait for the run to finish, or recover/park the task first, then move it. |
 | `workflow` | slug or null | no | |
 | `deps` | string[] | no | |
 
@@ -147,6 +147,8 @@ Register a new project.
 
 Update project fields. Only `id` is required; all others are optional patch fields. Same fields as `createproject`, except `simultaneity` minimum is 0 (for kill switch state).
 
+**Context-change guard:** changing `repo_path`, `deploy_type`, or `deploy_slug` is blocked while any task in the project has an active run (an agent session with status `running` that started within the last hour): the call throws, because live runs keep the old project config and the change would split the project context mid-run. Wait for the runs to finish, or recover/park those tasks first, then retry.
+
 ### `deleteproject`
 
 Remove a project registration.

package/docs/guide.md

@@ -213,7 +213,7 @@ Each phase has an assigned identity — a character with a defined personality:
 | Map | **Mara** | Designer |
 | Build | **Wren** | Quietest one, trusts the plan |
 | Review | **Cass** | Fair but exacting — holds the spec as the contract |
-| Integrate | **Wren** | Merges the work, pushes `main` to the repo |
+| Integrate | **Wren** | Merges the work, pushes `main` to the repo (succeeds vacuously when the task branch is empty — runtime-state deliverable) |
 | Publish | **Wren** | Ships the merged code to the publish target (skipped when none) |
 | QA | **Hazel** | Code-blind, persistent, wears persona costumes |
 | Reproduce | **Hazel** | Reproduces bugs before fixing |

package/lib/crew-release.sh

@@ -6,10 +6,13 @@
 #
 # Layout:
 #   ~/.jarvis/
-#     releases/<full-commit-hash>/   # immutable snapshot (workflows/ + lib/)
+#     releases/<full-commit-hash>/   # immutable snapshot (workflows/ + lib/ + seed/workflows/ docs)
 #     current -> releases/<hash>     # active release
 #     workflows -> current/workflows # convenience (cron/dispatcher reads this)
 #     lib -> current/lib             # convenience
+#     .orchestration/workflows/      # live workflow documents the dashboard
+#                                    # reads; re-synced from the activated
+#                                    # release on every deploy/rollback
 #
 # The Muse workflow runtime snapshots .js scripts at launch.
 # /tmp/crew-lib-* pins lifecycle scripts per run.
@@ -91,6 +94,37 @@ _validate_workflows() {
   echo "VALIDATED: workflow scripts parse"
 }
 
+# ── workflow doc sync ───────────────────────────────────────────────
+# Decision (2026-09-09): the dashboard reads the workflow documents live
+# from $CREW_HOME/.orchestration/workflows/, and `recovertask` validates
+# target_phase against them — so those documents must always reflect the
+# phases the dispatcher actually runs. Both the workflow scripts and the
+# .md docs ship in the same repo commit, so we re-sync the docs from the
+# activated release on every release activation (deploy AND rollback),
+# automatically. A manual re-sync step is exactly what drifted here: the
+# copy was seeded once by crew-init's `cp -n` and never refreshed, leaving
+# the dashboard on pre-publish-architecture phases (no Integrate, no
+# Publish) while the dispatcher ran the current phase lists.
+_sync_workflow_docs() {
+  local home="${1:?usage: _sync_workflow_docs <jarvis-home>}"
+  local src="$home/current/seed/workflows"
+  local dest="$home/.orchestration/workflows"
+  if [ ! -d "$src" ]; then
+    echo "WORKFLOW-DOCS: no seed/workflows in activated release; skipping sync" >&2
+    return 0
+  fi
+  mkdir -p "$dest"
+  local f base copied=0
+  for f in "$src"/*.md; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    [ "$base" = "AGENTS.md" ] && continue  # folder docs, not a workflow
+    cp -f "$f" "$dest/$base"
+    copied=$((copied + 1))
+  done
+  echo "WORKFLOW-DOCS: synced $copied workflow docs to $dest"
+}
+
 # ── deploy ────────────────────────────────────────────────────────────
 # Build, validate, and atomically activate a release from repo HEAD.
 # Single command — no cross-step lock needed.
@@ -124,11 +158,18 @@ cmd_deploy() {
     mkdir -p "$staging_dir"
     if [ -d .git ]; then
       # Extract from committed tree (not working directory)
-      git archive HEAD -- workflows lib | tar -xC "$staging_dir"
+      _seed=""
+      git cat-file -e "HEAD:seed/workflows" 2>/dev/null && _seed="seed/workflows" || true
+      # shellcheck disable=SC2086
+      git archive HEAD -- workflows lib $_seed | tar -xC "$staging_dir"
     else
       # Plain directory (npm install): copy directly
       [ -d workflows ] && cp -r workflows "$staging_dir/"
       [ -d lib ]       && cp -r lib "$staging_dir/"
+      if [ -d seed/workflows ]; then
+        mkdir -p "$staging_dir/seed"
+        cp -r seed/workflows "$staging_dir/seed/"
+      fi
     fi
     # Gate: refuse to install a release whose workflow scripts don't parse.
     if ! _validate_workflows "$staging_dir"; then
@@ -147,6 +188,9 @@ cmd_deploy() {
 
   echo "ACTIVATED: $hash"
 
+  # Keep the dashboard's workflow documents in sync with the release.
+  _sync_workflow_docs "$CREW_HOME"
+
   # Prune old releases — keep the 5 most recent
   _prune_releases "$home" 5
 }
@@ -172,6 +216,9 @@ cmd_rollback() {
   mv -T "$tmp_link" "$CREW_HOME/current"
 
   echo "ROLLED_BACK: $current_hash -> $prev"
+
+  # Keep the dashboard's workflow documents in sync with the release.
+  _sync_workflow_docs "$CREW_HOME"
 }
 
 # ── current ───────────────────────────────────────────────────────────

package/lib/worktree-lifecycle.sh

@@ -158,8 +158,11 @@ cmd_integrate() {
   local ahead
   ahead=$(git rev-list --count "main..task/$task_id")
   if [ "$ahead" -eq 0 ]; then
-    echo "ERROR: task/$task_id has no commits ahead of main — nothing to merge"
-    return 1
+    # 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"
+    return 0
   fi
 
   # Acquire merge lock

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Opinionated orchestration for Muse — workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,
@@ -10,7 +10,7 @@
   },
   "files": [
     "workflows/",
-    "identities/*.md",
+    "identities/",
     "personas/",
     "lib/",
     "seed/",

package/seed/workflows/AGENTS.md

@@ -1,3 +1,7 @@
 # AGENTS.md
 
 Human-readable workflow definitions — the canonical source. `crew-init` copies these to `$CREW_HOME/.orchestration/workflows/` during setup. Each file describes one workflow type: its phases, identity assignments, and progression rules.
+
+## Sync policy
+
+The workflow `.md` docs are synced from the activated release into `$CREW_HOME/.orchestration/workflows/` on every `crew-release.sh` release activation (deploy and rollback) — automatically, never as a manual step. The invariant is that the dashboard's workflow documents always reflect the phases the dispatcher actually runs: the dashboard reads those documents live from disk and `recovertask` validates target phases against them, so drift breaks recovery. Because the docs and the workflow scripts ship in the same repo commit, syncing at activation maintains the invariant by construction; the manual-step approach is what drifted (docs seeded once by `crew-init`'s `cp -n` went stale while the phases gained Integrate and Publish), so there is no manual re-sync step.

package/workflows/bugfix.js

@@ -209,6 +209,7 @@ while (i < STEPS.length) {
       "cd " + REPO_PATH + "/.worktrees/" + taskId + "\n" +
       "git add -A\n" +
       "git commit -m \"fix: " + safeTitle + "\"\n\n" +
+      "If the task's deliverable is runtime state (a cron definition, scheduler change, or dashboard/config state created outside the repo) and the repository genuinely needs no change, do NOT fabricate a commit: leave the branch with no commits ahead of main and declare `repo_diff: none` in your summary, naming the runtime-state deliverable. Otherwise commit your changes normally.\n\n" +
       (rejectionNotes ? "This is REWORK after rejection. Address these specific issues:\n" + rejectionNotes + "\n\n" : "") +
       "Your final response MUST be valid JSON and nothing else: { \"summary\": \"what you built\", \"passed\": true }. No prose, no markdown, just the JSON object.";
 
@@ -222,6 +223,7 @@ while (i < STEPS.length) {
       REPO_PATH + "/.worktrees/" + taskId + "/\n\n" +
       "Check quality, correctness, and spec compliance.\n" +
       "Check that public-affecting changes have matching public doc updates (API.md or the published API contract). If the docs are missing or inaccurate, reject with notes on what is stale.\n" +
+      "If the branch has no commits ahead of main (inspect shows an empty commit log), approve ONLY if the Build summary declares `repo_diff: none` with a plausible runtime-state deliverable (e.g. a cron created via the cron tool). Otherwise reject: 'no commits ahead of main and no repo_diff: none declaration — the builder likely forgot to commit'.\n" +
       (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry. Validate the builder's version choice: package.json must hold valid semver; if the version was bumped it must be greater than the registry version (npm view muse-crew version), the bump scope (patch/minor/major) must fit the change, and exactly one version field may change. If the version is invalid, already published, or mis-scoped, reject with notes.\n" : "") +
       "If the work passes review, your final response MUST be valid JSON and nothing else: { \"passed\": true, \"summary\": \"approval notes\" }.\n" +
       "If the work fails review, your final response MUST be valid JSON and nothing else: { \"passed\": false, \"summary\": \"rejection notes explaining what needs to change\" }.\n" +
@@ -232,6 +234,7 @@ while (i < STEPS.length) {
       "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " integrate " + taskId + " \"merge: fix: " + safeTitle + "\"\n\n" +
       "Read the output:\n" +
       "- If it contains MERGED, integration succeeded. Report the merged commit hash.\n" +
+      "- If it contains MERGED_EMPTY, the branch had no commits ahead of main (a runtime-state deliverable, declared by Build as repo_diff: none). Integration succeeded vacuously: the merge lock was NOT taken and there is no new commit. Set passed to true with summary 'merged empty: no repo changes — deliverable was runtime state'. SKIP STEP 2 (push): there is no new commit to push.\n" +
       "- If it contains LOCK_HELD, another task holds the merge lock (mid Integrate/Publish). Set passed to false.\n" +
       "- If it contains CONFLICT, a merge conflict occurred. Set passed to false with details.\n" +
       "- If it contains ERROR, something else failed. Set passed to false.\n\n" +

package/workflows/chore.js

@@ -191,6 +191,7 @@ while (i < STEPS.length) {
       "cd " + REPO_PATH + "/.worktrees/" + taskId + "\n" +
       "git add -A\n" +
       "git commit -m \"chore: " + safeTitle + "\"\n\n" +
+      "If the task's deliverable is runtime state (a cron definition, scheduler change, or dashboard/config state created outside the repo) and the repository genuinely needs no change, do NOT fabricate a commit: leave the branch with no commits ahead of main and declare `repo_diff: none` in your summary, naming the runtime-state deliverable. Otherwise commit your changes normally.\n\n" +
       (rejectionNotes ? "REWORK after rejection. Address:\n" + rejectionNotes + "\n\n" : "") +
       "Your final response MUST be valid JSON and nothing else: { \"summary\": \"what you built\", \"passed\": true }. No prose, no markdown, just the JSON object.";
 
@@ -204,6 +205,7 @@ while (i < STEPS.length) {
       REPO_PATH + "/.worktrees/" + taskId + "/\n\n" +
       "Check quality, correctness, spec compliance.\n" +
       "Check that public-affecting changes have matching public doc updates (API.md or the published API contract). If the docs are missing or inaccurate, reject with notes on what is stale.\n" +
+      "If the branch has no commits ahead of main (inspect shows an empty commit log), approve ONLY if the Build summary declares `repo_diff: none` with a plausible runtime-state deliverable (e.g. a cron created via the cron tool). Otherwise reject: 'no commits ahead of main and no repo_diff: none declaration — the builder likely forgot to commit'.\n" +
       (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry. Validate the builder's version choice: package.json must hold valid semver; if the version was bumped it must be greater than the registry version (npm view muse-crew version), the bump scope (patch/minor/major) must fit the change, and exactly one version field may change. If the version is invalid, already published, or mis-scoped, reject with notes.\n" : "") +
       "If it passes, your final response MUST be valid JSON and nothing else: { \"passed\": true, \"summary\": \"approval notes\" }.\n" +
       "If it fails, your final response MUST be valid JSON and nothing else: { \"passed\": false, \"summary\": \"rejection notes\" }.\n" +
@@ -214,6 +216,7 @@ while (i < STEPS.length) {
       "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " integrate " + taskId + " \"merge: chore: " + safeTitle + "\"\n\n" +
       "Read the output:\n" +
       "- If it contains MERGED, integration succeeded. Report the merged commit hash.\n" +
+      "- If it contains MERGED_EMPTY, the branch had no commits ahead of main (a runtime-state deliverable, declared by Build as repo_diff: none). Integration succeeded vacuously: the merge lock was NOT taken and there is no new commit. Set passed to true with summary 'merged empty: no repo changes — deliverable was runtime state'. SKIP STEP 2 (push): there is no new commit to push.\n" +
       "- If it contains LOCK_HELD, another task holds the merge lock (mid Integrate/Publish). Set passed to false.\n" +
       "- If it contains CONFLICT, a merge conflict occurred. Set passed to false with details.\n" +
       "- If it contains ERROR, something else failed. Set passed to false.\n\n" +

package/workflows/standard.js

@@ -207,6 +207,7 @@ while (i < STEPS.length) {
       "cd " + REPO_PATH + "/.worktrees/" + taskId + "\n" +
       "git add -A\n" +
       "git commit -m \"" + safeTitle + "\"\n\n" +
+      "If the task's deliverable is runtime state (a cron definition, scheduler change, or dashboard/config state created outside the repo) and the repository genuinely needs no change, do NOT fabricate a commit: leave the branch with no commits ahead of main and declare `repo_diff: none` in your summary, naming the runtime-state deliverable. Otherwise commit your changes normally.\n\n" +
       (rejectionNotes ? "This is REWORK after rejection. Address these specific issues:\n" + rejectionNotes + "\n\n" : "") +
       "Your final response MUST be valid JSON and nothing else: { \"summary\": \"what you built\", \"passed\": true }. No prose, no markdown, just the JSON object.";
 
@@ -220,6 +221,7 @@ while (i < STEPS.length) {
       REPO_PATH + "/.worktrees/" + taskId + "/\n\n" +
       "Check quality, correctness, and spec compliance.\n" +
       "Check that public-affecting changes have matching public doc updates (API.md or the published API contract). If the docs are missing or inaccurate, reject with notes on what is stale.\n" +
+      "If the branch has no commits ahead of main (inspect shows an empty commit log), approve ONLY if the Build summary declares `repo_diff: none` with a plausible runtime-state deliverable (e.g. a cron created via the cron tool). Otherwise reject: 'no commits ahead of main and no repo_diff: none declaration — the builder likely forgot to commit'.\n" +
       (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry. Validate the builder's version choice: package.json must hold valid semver; if the version was bumped it must be greater than the registry version (npm view muse-crew version), the bump scope (patch/minor/major) must fit the change, and exactly one version field may change. If the version is invalid, already published, or mis-scoped, reject with notes.\n" : "") +
       "If the work passes review, your final response MUST be valid JSON and nothing else: { \"passed\": true, \"summary\": \"approval notes\" }.\n" +
       "If the work fails review, your final response MUST be valid JSON and nothing else: { \"passed\": false, \"summary\": \"rejection notes explaining what needs to change\" }.\n" +
@@ -230,6 +232,7 @@ while (i < STEPS.length) {
       "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " integrate " + taskId + " \"merge: " + safeTitle + "\"\n\n" +
       "Read the output:\n" +
       "- If it contains MERGED, integration succeeded. Report the merged commit hash.\n" +
+      "- If it contains MERGED_EMPTY, the branch had no commits ahead of main (a runtime-state deliverable, declared by Build as repo_diff: none). Integration succeeded vacuously: the merge lock was NOT taken and there is no new commit. Set passed to true with summary 'merged empty: no repo changes — deliverable was runtime state'. SKIP STEP 2 (push): there is no new commit to push.\n" +
       "- If it contains LOCK_HELD, another task holds the merge lock (mid Integrate/Publish). Set passed to false with summary 'merge lock held'.\n" +
       "- If it contains CONFLICT, a merge conflict occurred. Set passed to false with the conflict details.\n" +
       "- If it contains ERROR, something else failed. Set passed to false with the error.\n\n" +