muse-crew 0.1.0 → 0.2.0

package/AGENTS.md

@@ -5,7 +5,7 @@ Muse Crew source repository. The repo is the product; the personal instance (`$C
 ## Structure
 
 - `API.md` — the Crew API contract: every action a task service must implement
-- `.orchestration/` — this project's crew configuration (project.json)
+- `.orchestration/` — crew configuration notes (deploy config lives in the dashboard's project record — the single source of truth)
 - `identities/` — crew member character files and portraits
 - `lib/` — shell scripts for release, merge, worktree, and cleanup
 - `personas/` — QA perspective costumes for Hazel

package/API.md

@@ -48,6 +48,13 @@ Atomically claim a task for a workflow step. Used by the dispatcher and by workf
 | `step` | string (1–120) | no | The workflow phase name |
 | `notes` | string (≤ 3000) | no | Defaults to `""` |
 
+Returns one of:
+
+- `{ "ok": true, "claimed": true, "session_id": "<uuid>", "session": {...} }`
+- `{ "ok": true, "claimed": false, "reason": "already_claimed", "existing_session_id": "<uuid>" }`
+
+`claimed` is the single field callers branch on. `reason` is present only when `claimed` is false.
+
 ### `recovertask`
 
 Send a stuck or failed task to a specific workflow phase for recovery.
@@ -102,6 +109,7 @@ Read the event timeline.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
+| `task_id` | uuid | no | Return only events for this task |
 | `limit` | integer (1–100) | no | Defaults to 50 |
 
 ---
@@ -129,12 +137,11 @@ Register a new project.
 | `id` | slug | yes | Unique project identifier |
 | `display_name` | string (1–120) | yes | |
 | `repo_path` | string (1–1000) | yes | Absolute path to the project's Git repo |
-| `deploy_type` | `artifact` · `repo` | yes | |
+| `deploy_type` | `npm` · `artifact` · `vercel` · empty string | yes | Publish target: `npm` publishes the package to the npm registry, `artifact` rebuilds the live artifact, `vercel` is not yet implemented (blocks the task), empty skips the Publish phase |
 | `deploy_slug` | slug or null | no | Required when `deploy_type` is `artifact` |
 | `description` | string (≤ 3000) | no | |
 | `simultaneity` | integer (1–100) | no | Max concurrent tasks; defaults to 2 |
 | `quiesced` | boolean | no | Start paused; defaults to false |
-| `idle_hunting` | boolean | no | Defaults to false |
 
 ### `updateproject`
 
@@ -203,6 +210,21 @@ Set a global configuration value.
 | `key` | string (1–80) | yes | |
 | `value` | string (≤ 10000) | yes | |
 
+### `setprovenance`
+
+Stamp publication provenance. Called by the crew Publish phase after rebuilding the artifact.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `source_commit` | 40-char hex | yes | Repo commit the artifact was built from |
+| `crew_release` | 40-char hex | yes | Active crew release (`$CREW_HOME/current`) at publish time |
+| `published_at` | ISO 8601 datetime (UTC) | yes | |
+| `task_id` | string | no | Publishing task, for traceability |
+
+### `getprovenance`
+
+Read the last publication provenance. Returns `{ "provenance": { "source_commit", "crew_release", "published_at" } }`, or `{ "provenance": null }` when nothing has been published yet.
+
 ---
 
 ## Not part of this API

package/README.md

@@ -14,7 +14,7 @@ Five things make it go.
 
 **Identities** are the characters who do the work — values, taste, writing style. What makes the reviewer exacting and the QA agent persistent.
 
-**Projects** connect a repository to a deploy target. Tasks belong to projects; the dispatcher routes each task through its project's configuration.
+**Projects** connect a repository to a publish target. Every task's merged work is pushed to the project's private Git repo; the optional Publish phase then ships it to the target. Tasks belong to projects; the dispatcher routes each task through its project's configuration.
 
 **Scheduling** uses [Muse's](https://muse.ai) always-on cron. The dispatcher checks the board every few minutes, claims what's ready, and puts the right agent on the right phase. Review rejects bounce back automatically. The system keeps going until the work is done or stuck.
 
@@ -26,15 +26,15 @@ The repo ships workflows and identities for a software development crew — one
 |----------|------|----------------|
 | **Sage** | Triage | Fast routing — classifies and prioritizes before anything else runs |
 | **Mara** | Designer | Makes tasks solution-oriented before building starts |
-| **Wren** | Builder | Trusts the plan, lets commits speak. Also handles integration and deployment |
+| **Wren** | Builder | Trusts the plan, lets commits speak. Also handles integration and publishing |
 | **Cass** | Reviewer | Fair but exacting — holds the spec as the contract until the work is tight |
 | **Hazel** | QA | Code-blind by design. Persistent. Wears persona costumes for multi-lens testing |
 | **Tate** | Docs | Observational, jargon-hostile |
 
 ```
-standard:  Triage → Map → Build → Review → Integrate → Deploy → QA
-bugfix:    Triage → Reproduce → Map → Build → Review → Integrate → Deploy → QA
-chore:     Triage → Map → Build → Review → Integrate → Deploy
+standard:  Triage → Map → Build → Review → Integrate → Publish → QA
+bugfix:    Triage → Reproduce → Map → Build → Review → Integrate → Publish → QA
+chore:     Triage → Map → Build → Review → Integrate → Publish
 docs:      Triage → Write → Review
 ```
 

package/docs/guide.md

@@ -5,7 +5,7 @@ This is the full setup and operations reference. If you're new, start with the [
 ## Components
 
 **In this repo:**
-- **Workflow scripts** — walk each task through its phases (Triage → Map → Build → Review → Integrate → Deploy → QA). The defaults are built for software, but you can create your own workflows for any kind of work.
+- **Workflow scripts** — walk each task through its phases (Triage → Map → Build → Review → Integrate → Publish → QA). The defaults are built for software, but you can create your own workflows for any kind of work.
 - A **dispatcher** — reads the board and puts the crew to work.
 - A **release system** — immutable releases with atomic symlink swap. Works with Git checkouts or npm installs.
 - An **`.orchestration/` scaffold** — identity files, persona files, workflow documentation, and feedback conventions.
@@ -118,20 +118,19 @@ Required fields:
 - `id` — kebab-case identifier, unique across all projects.
 - `display_name` — human-readable name.
 - `repo_path` — absolute path to the project's Git repository.
-- `deploy_type` — `"artifact"` (deploys via artifact edit) or `"repo"` (changes stay in the repo).
+- `deploy_type` — names the project's **publish target**: `"npm"` (installs the immutable release and publishes the package to the npm registry), `"artifact"` (rebuilds the live artifact from disk), `"vercel"` (not yet implemented — blocks the task), or empty (no publish target — the Publish phase is skipped, for prototyping projects). Every project pushes merged work to its private Git repo in Integrate regardless of target — never force-push; a non-fast-forward rejection blocks the task.
 
 Optional fields:
 - `deploy_slug` — the artifact slug, required when `deploy_type` is `"artifact"`.
 - `description` — free text.
 - `simultaneity` — max concurrent tasks for this project (default: 2, range: 1–100).
 - `quiesced` — start paused (default: false).
-- `idle_hunting` — not yet implemented (default: false).
 
 ### What a registered project needs
 
 The project must have:
 - A Git repository at the specified `repo_path`.
-- For artifact deploy type: an existing web artifact at the specified `deploy_slug`.
+- For the `artifact` publish target: an existing web artifact at the specified `deploy_slug`.
 
 The project does **not** need:
 - A `.orchestration/` folder (that belongs to the crew home, not the project).
@@ -191,7 +190,7 @@ Every 3 minutes, the `crew-poll` cron fires:
 
 5. **Main-chat agent launches workflows** — receives the claim records and calls `workflow_launch_async` for each one.
 
-6. **Workflow executes phases** — each phase dispatches an agent in character (the identity assigned to that phase), records the result, and advances the task.
+6. **Workflow executes phases** — each phase dispatches an agent in character (the identity assigned to that phase), records the result, and advances the task. At every phase boundary the workflow re-reads the task's project: if the task was moved to another project mid-run, the stale run aborts (its session is marked `failed` at the Build/Write step and its worktree is removed from the old repo) so the dispatcher re-launches it with the new project's repo and config.
 
 7. **Task completes** — when all phases finish, the dispatcher marks the task `done` on the next tick.
 
@@ -199,9 +198,9 @@ Every 3 minutes, the `crew-poll` cron fires:
 
 | Workflow | Phases |
 |----------|--------|
-| standard | Triage → Map → Build → Review → Integrate → Deploy → QA |
-| bugfix | Triage → Reproduce → Map → Build → Review → Integrate → Deploy → QA |
-| chore | Triage → Map → Build → Review → Integrate → Deploy |
+| standard | Triage → Map → Build → Review → Integrate → Publish → QA |
+| bugfix | Triage → Reproduce → Map → Build → Review → Integrate → Publish → QA |
+| chore | Triage → Map → Build → Review → Integrate → Publish |
 | docs | Triage → Write → Review |
 
 ## Identities
@@ -214,8 +213,8 @@ 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 |
-| Deploy | **Wren** | Ships the release |
+| Integrate | **Wren** | Merges the work, pushes `main` to the repo |
+| 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 |
 | Write | **Tate** | Docs writer, observational voice |
@@ -281,7 +280,7 @@ The full pause/resume/dispatch cycle has been proven end-to-end.
 
 Releases are immutable snapshots of the crew's runtime code.
 
-### Deploy
+### Installing a release
 
 ```bash
 crew-release.sh deploy <source-path>
@@ -294,7 +293,7 @@ crew-release.sh deploy <source-path>
 5. Atomically swaps the `current` symlink to point at the new release.
 6. Prunes old releases, keeping the 5 most recent.
 
-The `crew-release.sh` manager itself lives at `crewHome/crew-release.sh`, outside the managed releases, so it's never overwritten by a deploy.
+The `crew-release.sh` manager itself lives at `crewHome/crew-release.sh`, outside the managed releases, so it's never overwritten by a release activation.
 
 ### Rollback
 
@@ -306,7 +305,7 @@ Activates the second-newest release by modification time.
 
 ### Safety
 
-Running workflows are safe from mid-deploy changes. Muse snapshots workflow JavaScript at launch time, so a deploy that swaps the symlink does not affect workflows already in flight.
+Running workflows are safe from mid-publish changes. Muse snapshots workflow JavaScript at launch time, so a deploy that swaps the symlink does not affect workflows already in flight.
 
 ### Release identity
 
@@ -322,12 +321,10 @@ crew-release.sh current
 
 2. **Stuck sessions.** If a workflow dies mid-run, its session stays `running` indefinitely and the cron skips it every tick. Manual cleanup is currently required.
 
-3. **No idle hunting.** The `idle_hunting` field exists in the project schema but is not implemented. No proactive QA runs when the board is empty.
+3. **No streaming.** The polling loop checks every 3 minutes. There is no webhook or event-driven dispatch.
 
-4. **No streaming.** The polling loop checks every 3 minutes. There is no webhook or event-driven dispatch.
+4. **Single dispatcher.** Only one cron runs the dispatcher. Concurrent ticks are prevented by the session-claiming atomicity, but there is no explicit distributed lock.
 
-5. **Single dispatcher.** Only one cron runs the dispatcher. Concurrent ticks are prevented by the session-claiming atomicity, but there is no explicit distributed lock.
+5. **No automatic retry escalation.** Failed tasks retry the same phase on the next tick. There is no backoff, retry limit, or escalation path.
 
-6. **No automatic retry escalation.** Failed tasks retry the same phase on the next tick. There is no backoff, retry limit, or escalation path.
-
-7. **QA is code-blind.** Hazel uses `artifact_inspect` for visual/functional testing. She cannot read source code — this is by design (context isolation), but it means QA catches only what's visible or inspectable through the artifact's public interface.
+6. **QA is code-blind.** Hazel uses `artifact_inspect` for visual/functional testing. She cannot read source code — this is by design (context isolation), but it means QA catches only what's visible or inspectable through the artifact's public interface.

package/lib/crew-release.sh

@@ -59,6 +59,38 @@ cmd_init() {
   echo "CURRENT: $cur"
 }
 
+# ── workflow syntax validation ──────────────────────────────────────
+# Every workflow script must parse before a release can install.
+_validate_workflows() {
+  # The workflow runtime accepts top-level `export`, `return`, and `await`
+  # (it wraps scripts in an async function), so neither `node --check` on the
+  # raw .js (vacuous for ESM — exits 0 even on blatant syntax errors) nor a
+  # .mjs check (rejects the runtime-legal top-level `return`) is correct.
+  # Emulate the runtime instead: strip `export`, wrap the script in an async
+  # function, then node --check the result. Tokenizer errors (e.g. an
+  # unterminated string literal) still fail under the wrap.
+  local dir="$1"
+  local f tmp base
+  tmp="$(mktemp -d)"
+  for f in "$dir"/workflows/*.js; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f" .js)"
+    {
+      echo "async function __crew_workflow__(args) {"
+      sed 's/^export //' "$f"
+      echo "}"
+    } > "$tmp/$base.js"
+    if ! node --check "$tmp/$base.js" 2>"$tmp/$base.err"; then
+      cat "$tmp/$base.err" >&2
+      echo "VALIDATION FAILED: $f does not parse" >&2
+      rm -rf "$tmp"
+      return 1
+    fi
+  done
+  rm -rf "$tmp"
+  echo "VALIDATED: workflow scripts parse"
+}
+
 # ── deploy ────────────────────────────────────────────────────────────
 # Build, validate, and atomically activate a release from repo HEAD.
 # Single command — no cross-step lock needed.
@@ -98,6 +130,11 @@ cmd_deploy() {
       [ -d workflows ] && cp -r workflows "$staging_dir/"
       [ -d lib ]       && cp -r lib "$staging_dir/"
     fi
+    # Gate: refuse to install a release whose workflow scripts don't parse.
+    if ! _validate_workflows "$staging_dir"; then
+      rm -rf "$staging_dir"
+      die "release $hash rejected: workflow syntax validation failed"
+    fi
     # Atomic rename into place
     mv "$staging_dir" "$release_dir"
     echo "INSTALLED: $hash"

package/lib/orphan-sweep.sh

@@ -2,9 +2,10 @@
 # orphan-sweep.sh — find and clean orphaned worktrees + stale merge locks
 #
 # Usage:
-#   orphan-sweep.sh report  — list orphans and their state (read-only)
+#   orphan-sweep.sh report  — list orphans (read-only for worktrees);
+#                              force-releases stale locks with dead PIDs
 #   orphan-sweep.sh clean   — remove safe-to-clean orphans (merged branches only)
-#                              and break stale merge locks (>30 min)
+#                              and force-release stale merge locks (>30 min)
 #
 # "Safe to clean" means the task branch is fully merged into main.
 # Dirty or unmerged worktrees are always preserved and reported.
@@ -40,13 +41,11 @@ if [ -f "$LOCK_FILE" ]; then
       else
         echo "STALE_LOCK: held ${age_min}m by $lock_holder (pid ${lock_pid:-none} dead) — threshold ${STALE_LOCK_MIN}m"
         found=1
-        if [ "$cmd" = "clean" ]; then
-          rm -f "$LOCK_FILE"
-          if [ ! -f "$LOCK_FILE" ]; then
-            echo "  → broken"
-          else
-            echo "  → ERROR: lock file still exists after rm at $LOCK_FILE"
-          fi
+        rm -f "$LOCK_FILE"
+        if [ ! -f "$LOCK_FILE" ]; then
+          echo "  → released (dead PID)"
+        else
+          echo "  → ERROR: lock file still exists after rm at $LOCK_FILE"
         fi
       fi
     fi

package/lib/worktree-lifecycle.sh

@@ -125,6 +125,14 @@ cmd_inspect() {
     return 1
   fi
 
+  echo "=== Branch: task/$task_id ==="
+  local tip
+  tip=$(git rev-parse "task/$task_id")
+  echo "TIP: $tip"
+  echo ""
+  echo "=== Commits ahead of main ==="
+  git log --oneline "main..task/$task_id"
+  echo ""
   echo "=== Diff: main...task/$task_id ==="
   git diff --stat "main...task/$task_id"
   echo ""

package/package.json

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

package/seed/workflows/bugfix.md

@@ -19,21 +19,24 @@ Update the task with a solution-oriented spec. Research options, pick the shorte
 
 ### Build
 **Identity:** Wren
-Execute the spec. Write the code, write the tests.
+Execute the spec. Write the code, write the tests. Update public docs for public-affecting changes — docs ship with implementation.
 
 ### Review
 **Identity:** Cass
 **Constraint:** Independent context. Do not share the builder's context. Read the spec and review the changes cold.
+Verify public docs are current for public-affecting changes; reject if stale.
 
 ### Integrate
 **Identity:** Wren
 Merge changes into the target branch. Create the commit with a clear message.
+Then push `main` to the project's private remote. Never force-push: a non-fast-forward rejection blocks the task.
 
-### Deploy
+### Publish
 **Identity:** Wren
-Deploy the changes.
+Optional. Ships the merged code to the project's publish target (`deploy_type` on the project record): `npm` installs the immutable release and publishes the package to the registry; `artifact` rebuilds the live artifact from disk; `vercel` is not implemented and blocks the task; an empty target skips this phase. The repo push already happened in Integrate — Publish never touches git.
 
 ### QA
 **Identity:** Hazel
 **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.

package/seed/workflows/chore.md

@@ -14,16 +14,18 @@ Research options, pick the path, write the spec.
 
 ### Build
 **Identity:** Wren
-Execute the spec.
+Execute the spec. Update public docs for public-affecting changes — docs ship with implementation.
 
 ### Review
 **Identity:** Cass
 **Constraint:** Independent context. Review cold.
+Verify public docs are current for public-affecting changes; reject if stale.
 
 ### Integrate
 **Identity:** Wren
 Merge changes into the target branch. Create the commit with a clear message.
+Then push `main` to the project's private remote. Never force-push: a non-fast-forward rejection blocks the task.
 
-### Deploy
+### Publish
 **Identity:** Wren
-Deploy the changes.
+Optional. Ships the merged code to the project's publish target (`deploy_type` on the project record): `npm` installs the immutable release and publishes the package to the registry; `artifact` rebuilds the live artifact from disk; `vercel` is not implemented and blocks the task; an empty target skips this phase. The repo push already happened in Integrate — Publish never touches git.

package/seed/workflows/standard.md

@@ -14,21 +14,24 @@ Research options, pick the path, write the spec.
 
 ### Build
 **Identity:** Wren
-Execute the spec.
+Execute the spec. Update public docs for public-affecting changes — docs ship with implementation.
 
 ### Review
 **Identity:** Cass
 **Constraint:** Independent context. Review cold.
+Verify public docs are current for public-affecting changes; reject if stale.
 
 ### Integrate
 **Identity:** Wren
 Merge changes into the target branch. Create the commit with a clear message.
+Then push `main` to the project's private remote. Never force-push: a non-fast-forward rejection blocks the task.
 
-### Deploy
+### Publish
 **Identity:** Wren
-Deploy the changes.
+Optional. Ships the merged code to the project's publish target (`deploy_type` on the project record): `npm` installs the immutable release and publishes the package to the registry; `artifact` rebuilds the live artifact from disk; `vercel` is not implemented and blocks the task; an empty target skips this phase. The repo push already happened in Integrate — Publish never touches git.
 
 ### QA
 **Identity:** Hazel
 **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.

package/workflows/AGENTS.md

@@ -4,7 +4,7 @@ Executable Muse workflow scripts (JavaScript). These are what the workflow runti
 
 - `crew-dispatch.js` — reads the board, claims eligible tasks, returns structured launch records
 - `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 → Deploy → QA
+- `standard.js` — default task workflow: Triage → Map → Build → Review → Integrate → Publish → QA
 - `bugfix.js` — adds Reproduce after Triage
 - `chore.js` — drops QA (low-risk)
 - `docs.js` — Tate writes, Cass reviews