muse-crew 0.1.0 → 0.1.1

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`
 

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).
@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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

package/workflows/bugfix.js

@@ -1,7 +1,7 @@
 export const meta = {
   name: "crew-bugfix",
-  description: "Bugfix workflow: Triage → Reproduce → Map → Build → Review → Integrate → Deploy → QA",
-  phases: ["Triage", "Reproduce", "Map", "Build", "Review", "Integrate", "Deploy", "QA"],
+  description: "Bugfix workflow: Triage → Reproduce → Map → Build → Review → Integrate → Publish → QA",
+  phases: ["Triage", "Reproduce", "Map", "Build", "Review", "Integrate", "Publish", "QA"],
   steps: [
     { name: "Triage", identity: "sage" },
     { name: "Reproduce", identity: "hazel" },
@@ -9,7 +9,7 @@ export const meta = {
     { name: "Build", identity: "wren" },
     { name: "Review", identity: "cass" },
     { name: "Integrate", identity: "wren" },
-    { name: "Deploy", identity: "wren" },
+    { name: "Publish", identity: "wren" },
     { name: "QA", identity: "hazel" }
   ],
   reworkTarget: "Build"
@@ -32,12 +32,14 @@ const MERGE_LOCK_SRC = crewHome + "/lib/merge-lock.sh";
 const RUN_LIB = "/tmp/crew-lib-" + taskId;
 const LIFECYCLE = RUN_LIB + "/worktree-lifecycle.sh";
 const MERGE_LOCK = RUN_LIB + "/merge-lock.sh";
+const ORPHAN_SWEEP_SRC = crewHome + "/lib/orphan-sweep.sh";
+const ORPHAN_SWEEP = RUN_LIB + "/orphan-sweep.sh";
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
 const REPO_PATH = projectConfig.repo_path || "~/workspace/ts-spaces/orchestra-dashboard";
-const DEPLOY_TYPE = projectConfig.deploy_type || "artifact";
-const DEPLOY_SLUG = projectConfig.deploy_slug || DASHBOARD_SLUG;
+const PUBLISH_TYPE = projectConfig.deploy_type || "";
+const PUBLISH_SLUG = projectConfig.deploy_slug || DASHBOARD_SLUG;
 const PROJECT_DESC = projectConfig.description || "React + TypeScript web dashboard (client/src/, server/src/, drizzle/)";
 const RELEASE_SCRIPT = crewHome + "/crew-release.sh";
 
@@ -61,13 +63,15 @@ const STEPS = [
   { name: "Build", identity: "wren" },
   { name: "Review", identity: "cass" },
   { name: "Integrate", identity: "wren" },
-  { name: "Deploy", identity: "wren" },
+  { name: "Publish", identity: "wren" },
   { name: "QA", identity: "hazel" }
 ];
 const BUILD_INDEX = STEPS.findIndex(s => s.name === 'Build');
 if (BUILD_INDEX < 0) throw new Error("STEPS missing 'Build' step");
-const MAX_REWORK = 2;
-let reworkCount = 0;
+// Shared rework budget: Review and QA rejections draw from the SAME pool of 2.
+// E.g. 2 Review bounces + 1 QA bounce = 3 total > budget -> task blocks.
+const MAX_TOTAL_REWORK = 2;
+let totalReworkCount = 0;
 let rejectionNotes = inputs.rejection_notes || "";
 let mapperSpec = "";
 let i = startStepIndex;
@@ -75,17 +79,35 @@ let i = startStepIndex;
 // Pin lifecycle scripts
 await agent(
   "Snapshot lifecycle scripts for version pinning.\n" +
-  "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK,
+  "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + ORPHAN_SWEEP,
   { key: "pin-lifecycle", label: "Pinning lifecycle scripts", schema: { type: "object" } }
 );
 
 while (i < STEPS.length) {
   const step = STEPS[i];
-  const isFirstClaim = (i === startStepIndex && reworkCount === 0);
+  const isFirstClaim = (i === startStepIndex && totalReworkCount === 0);
 
   phase(step.name);
   log(step.name + " step (" + step.identity + ") for task " + taskId);
 
+  // Publish is optional and target-based. Empty target = prototyping project: skip the phase.
+  // Unknown target (incl. legacy "repo") = config error: block.
+  if (step.name === "Publish" && !PUBLISH_TYPE) {
+    log("Publish skipped for task " + taskId + " — no publish target configured (deploy_type empty)");
+    await agent(
+      "Release the merge lock and clean up without publishing.\n" +
+      "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
+      "If the output contains DEPLOYED, the lock is released and the worktree is cleaned up.",
+      { key: "publish-skip-cleanup", label: "Skipping Publish (no target)", schema: { type: "object" } }
+    );
+    i++;
+    continue;
+  }
+  if (step.name === "Publish" && PUBLISH_TYPE !== "npm" && PUBLISH_TYPE !== "artifact" && PUBLISH_TYPE !== "vercel") {
+    log("Unknown publish target for task " + taskId + ": " + PUBLISH_TYPE);
+    return { status: "blocked", task_id: taskId, reason: "Unknown publish target '" + PUBLISH_TYPE + "' — expected 'npm', 'artifact', 'vercel', or empty (skip publish)." };
+  }
+
   // Claim session
   let activeSessionId;
   if (isFirstClaim && firstSessionId) {
@@ -94,10 +116,10 @@ while (i < STEPS.length) {
     const claimResult = await agent(
       "Claim a session for this task step.\n" +
       "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"claimtask\", args:\n" +
-      "{ \"task_id\": \"" + taskId + "\", \"identity\": \"" + step.identity + "\", \"step\": \"" + step.name + "\", \"notes\": \"" + step.name + " step started" + (reworkCount > 0 ? " (rework #" + reworkCount + ")" : "") + "\" }.\n" +
+      "{ \"task_id\": \"" + taskId + "\", \"identity\": \"" + step.identity + "\", \"step\": \"" + step.name + "\", \"notes\": \"" + step.name + " step started" + (totalReworkCount > 0 ? " (rework #" + totalReworkCount + ")" : "") + "\" }.\n" +
       "Return the session_id from the response.",
       {
-        key: "claim-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
+        key: "claim-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
         label: "Claiming " + step.name,
         schema: {
           type: "object",
@@ -137,8 +159,10 @@ while (i < STEPS.length) {
       (mapperSpec ? "MAPPER'S SPEC (implement exactly this):\n" + mapperSpec + "\n\n" : "") +
       "Your working directory: " + REPO_PATH + "/.worktrees/" + taskId + "/\n" +
       "This is the project source: " + PROJECT_DESC + "\n" +
-      "Edit the TypeScript source files directly. Do NOT use artifact_edit — that happens in the Deploy phase.\n" +
-      "Do not add unrequested features. Build exactly what the spec calls for.\n\n" +
+      "Edit the TypeScript source files directly. Do NOT use artifact_edit — that happens in the Publish phase.\n" +
+      "Do not add unrequested features. Build exactly what the spec calls for.\n" +
+      "PUBLIC DOCS: If your change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), update the public docs in the same commit — API.md for API changes. Documentation and implementation ship together.\n\n" +
+      (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry, so you choose the package version. If this change warrants a published release (anything a consumer can observe: workflow behavior, phase lists, identities, published docs, API), bump the version in package.json with semver (patch for fixes, minor for new behavior, major for breaking changes) and state the chosen version and why in your summary. If the change is internal-only, leave the version unchanged and say so. Check the registry first — npm view muse-crew version — and never re-publish an existing version.\n\n" : "") +
       "STEP 3: Commit your changes.\n" +
       "cd " + REPO_PATH + "/.worktrees/" + taskId + "\n" +
       "git add -A\n" +
@@ -154,6 +178,8 @@ while (i < STEPS.length) {
       "You can also read specific files in the worktree at:\n" +
       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" +
+      (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" +
       "No prose, no markdown, just the JSON object.";
@@ -163,45 +189,75 @@ 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 LOCK_HELD, another task is deploying. Set passed to false.\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" +
+      "\n" +
+      "STEP 2: Push the merged main to the remote repository.\n" +
+      "Run: cd " + REPO_PATH + " && git push origin main\n" +
+      "- If the push succeeds, report the merged commit hash.\n" +
+      "- If the push is rejected as non-fast-forward (the remote has commits not present locally),\n" +
+      "  NEVER force-push. Do not run any --force variant. Set passed to false with summary:\n" +
+      "  'git push origin main rejected as non-fast-forward — remote main has diverged; manual resolution required'.
+\n\n" +
       "Your final response MUST be valid JSON and nothing else: { \"summary\": \"result\", \"passed\": true/false }. No prose, no markdown, just the JSON object.";
 
-  } else if (step.name === "Deploy") {
-    if (DEPLOY_TYPE === "repo") {
-      // Repo projects: install immutable release and atomically activate
-      instructions = "Deploy repo changes via the immutable release system.\n\n" +
-        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during deploy.\n" +
+  } else if (step.name === "Publish") {
+    if (PUBLISH_TYPE === "npm") {
+      // npm packages: immutable release + pack + publish to the registry (push is universal in Integrate)
+      instructions = "Publish the npm package to the registry.\n\n" +
+        "The repo push already happened in Integrate — do NOT push to git in this phase, and NEVER force-push.\n" +
+        "Version discipline: publish ships the exact version merged in Integrate (Build applied it, Review validated it). Do not bump the version here.\n\n" +
+        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during publish.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " refresh-lock " + taskId + "\n\n" +
-        "STEP 1: Install and activate the new release.\n" +
+        "STEP 1: Install and activate the immutable release.\n" +
         "Run: " + RELEASE_SCRIPT + " deploy " + REPO_PATH + "\n" +
         "Verify the output contains INSTALLED and ACTIVATED (or EXISTS and ACTIVATED if unchanged).\n\n" +
-        "STEP 2: Finalize.\n" +
+        "STEP 2: Check whether the package version needs publishing.\n" +
+        "Read the version from: cd " + REPO_PATH + " && node -p \"require('./package.json').version\"\n" +
+        "Check the registry: npm view muse-crew version 2>/dev/null || echo NOT_FOUND\n" +
+        "If the local version matches the registry version, the version is already live — skip to STEP 5.\n\n" +
+        "STEP 3: Pack and publish.\n" +
+        "Run: cd " + REPO_PATH + " && npm pack\n" +
+        "Then publish: python3 ~/workspace/skills/npm/bin/npm-publish.py " + REPO_PATH + "/muse-crew-$(node -p \"require('" + REPO_PATH + "/package.json').version\").tgz\n" +
+        "If publish fails with 'You cannot publish over the previously published versions', the version is already live — continue to STEP 4.\n\n" +
+        "STEP 4: Verify.\n" +
+        "Run: npm view muse-crew version\n" +
+        "Confirm it matches the local package.json version.\n\n" +
+        "STEP 5: Finalize.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
         "If the output contains DEPLOYED, finalization is complete.\n\n" +
-        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"release activated and finalized\", \"passed\": true }.\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"result\", \"passed\": true }.\n" +
         "No prose, no markdown, just the JSON object.";
-    } else {
-      instructions = "Deploy the merged code to the live artifact.\n\n" +
-        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during deploy.\n" +
+    } else if (PUBLISH_TYPE === "artifact") {
+      // Artifact projects: rebuild the live artifact via artifact_edit, then finalize
+      instructions = "Publish the merged code to the live artifact.\n\n" +
+        "The repo push already happened in Integrate — do NOT push to git in this phase.\n\n" +
+        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during publish.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " refresh-lock " + taskId + "\n\n" +
-        "STEP 1: Deploy to the live artifact.\n" +
+        "STEP 1: Publish to the live artifact.\n" +
         "Get the change summary: cd " + REPO_PATH + " && git log -1 --stat\n" +
-        "Then call artifact_edit with slug \"" + DEPLOY_SLUG + "\" and verbatim_request:\n" +
+        "Then call artifact_edit with slug \"" + PUBLISH_SLUG + "\" and verbatim_request:\n" +
         "'Rebuild the application from current source. Do not modify any source files — just rebuild and deploy what is on disk.'\n" +
         "Wait for the build to complete by polling artifact_status until it is no longer running.\n\n" +
         "STEP 2: Finalize.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
-        "If the output contains DEPLOYED, deployment is complete.\n\n" +
+        "If the output contains DEPLOYED, publishing is complete.\n\n" +
         "If artifact_edit failed, still run post-deploy to release the merge lock and clean up.\n" +
-        "Report the failure: { \"passed\": false, \"summary\": \"artifact deployment failed: [details]\" }.\n\n" +
-        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"deployed changes\", \"passed\": true }.\n" +
+        "Report the failure: { \"passed\": false, \"summary\": \"artifact publish failed: [details]\" }.\n\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"published changes\", \"passed\": true }.\n" +
+        "No prose, no markdown, just the JSON object.";
+    } else if (PUBLISH_TYPE === "vercel") {
+      // vercel publish is not yet implemented — block without inventing behavior
+      instructions = "The project's publish target is \"vercel\", which is not yet implemented.\n" +
+        "Do NOT invent publish behavior — do not guess CLI commands, APIs, or deployment steps.\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"passed\": false, \"summary\": \"vercel publish not yet implemented\" }.\n" +
         "No prose, no markdown, just the JSON object.";
     }
-
   } else if (step.name === "QA") {
     instructions = "Final QA testing. You are CODE-BLIND — do NOT read source code.\n" +
+      "Public docs (API.md, README, published action schemas) are NOT source code — read them freely, exactly as a user would.\n" +
+      "DOCS GATE: If the fix is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), verify the public docs describe it. If public docs are missing or stale, FAIL with { \"passed\": false, \"summary\": \"public docs missing/stale for [the change]\" }. QA always fails when public-affecting changes lack public docs. Guide/tutorial gaps are lower priority — file a follow-up task for those instead of failing.\n" +
       "To test, use artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\" with action \"getstate\" (args {}) to read current sessions, events, and tasks.\n" +
       "Verify the fix by checking that session notes in the returned data now handle newlines correctly.\n" +
       "You can also check specific data with the getevents action.\n" +
@@ -216,8 +272,8 @@ while (i < STEPS.length) {
   var eventPreamble = "";
   if (step.name !== "Review") {
     eventPreamble = "CONTEXT: First, fetch this task's event history for background.\n" +
-      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getevents\", args: { \"limit\": 100 }.\n" +
-      "Look through returned events for entries matching task_id \"" + taskId + "\". They contain notes and decisions from prior phases.\n\n";
+      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getevents\", args: { \"task_id\": \"" + taskId + "\" }.\n" +
+      "The returned events are filtered to this task. They contain notes and decisions from prior phases.\n\n";
   }
 
   var stepResult;
@@ -234,7 +290,7 @@ while (i < STEPS.length) {
     "CONSTRAINT: Do NOT call logevent or upsertagentsession — the workflow handles all phase tracking after your step completes.\n\n" +
     "Stay in character. Do the work thoroughly.",
     {
-      key: "work-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
+      key: "work-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
       label: step.identity + ": " + step.name + " on \"" + taskTitle + "\"",
       timeoutMs: 3600000,
       schema: WORK_SCHEMA
@@ -282,7 +338,7 @@ while (i < STEPS.length) {
     "Then call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"logevent\", args:\n" +
     "{ \"task_id\": \"" + taskId + "\", \"type\": \"" + status + "\", \"identity\": \"" + step.identity + "\", \"message\": \"" + step.name + " " + status + " by " + step.identity + "\" }.",
     {
-      key: "record-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
+      key: "record-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
       label: "Recording " + step.name + " result",
       schema: { type: "object" }
     }
@@ -302,14 +358,14 @@ while (i < STEPS.length) {
 
   // Review/QA rejection bounces to Build
   if (!passed && (step.name === "Review" || step.name === "QA")) {
-    reworkCount++;
-    if (reworkCount > MAX_REWORK) {
-      log("Max rework attempts reached for task " + taskId + " — worktree preserved at .worktrees/" + taskId + " for manual inspection");
-      return { status: "blocked", task_id: taskId, reason: "Exceeded " + MAX_REWORK + " rework attempts after " + step.name + " rejection. Worktree preserved." };
+    totalReworkCount++;
+    if (totalReworkCount > MAX_TOTAL_REWORK) {
+      log("Shared rework budget exhausted for task " + taskId + " — worktree preserved at .worktrees/" + taskId + " for manual inspection");
+      return { status: "blocked", task_id: taskId, reason: "Exceeded shared rework budget (" + MAX_TOTAL_REWORK + " total rework attempts across Review and QA) after " + step.name + " rejection. Worktree preserved." };
     }
     rejectionNotes = summary;
     i = BUILD_INDEX;
-    log(step.name + " rejected — bouncing to Build (rework #" + reworkCount + ")");
+    log(step.name + " rejected — bouncing to Build (rework #" + totalReworkCount + " of " + MAX_TOTAL_REWORK + ")");
     continue;
   }
 
@@ -319,10 +375,10 @@ while (i < STEPS.length) {
     return { status: "blocked", task_id: taskId, reason: "Integration failed: " + summary };
   }
 
-  // Deploy failure blocks the task
-  if (!passed && step.name === "Deploy") {
-    log("Deploy failed for task " + taskId + ": " + summary);
-    return { status: "blocked", task_id: taskId, reason: "Deploy failed: " + summary };
+  // Publish failure blocks the task
+  if (!passed && step.name === "Publish") {
+    log("Publish failed for task " + taskId + ": " + summary);
+    return { status: "blocked", task_id: taskId, reason: "Publish failed: " + summary };
   }
 
   i++;

package/workflows/chore.js

@@ -1,14 +1,14 @@
 export const meta = {
   name: "crew-chore",
-  description: "Chore workflow: Triage → Map → Build → Review → Integrate → Deploy",
-  phases: ["Triage", "Map", "Build", "Review", "Integrate", "Deploy"],
+  description: "Chore workflow: Triage → Map → Build → Review → Integrate → Publish",
+  phases: ["Triage", "Map", "Build", "Review", "Integrate", "Publish"],
   steps: [
     { name: "Triage", identity: "sage" },
     { name: "Map", identity: "mara" },
     { name: "Build", identity: "wren" },
     { name: "Review", identity: "cass" },
     { name: "Integrate", identity: "wren" },
-    { name: "Deploy", identity: "wren" }
+    { name: "Publish", identity: "wren" }
   ],
   reworkTarget: "Build"
 };
@@ -30,12 +30,14 @@ const MERGE_LOCK_SRC = crewHome + "/lib/merge-lock.sh";
 const RUN_LIB = "/tmp/crew-lib-" + taskId;
 const LIFECYCLE = RUN_LIB + "/worktree-lifecycle.sh";
 const MERGE_LOCK = RUN_LIB + "/merge-lock.sh";
+const ORPHAN_SWEEP_SRC = crewHome + "/lib/orphan-sweep.sh";
+const ORPHAN_SWEEP = RUN_LIB + "/orphan-sweep.sh";
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
 const REPO_PATH = projectConfig.repo_path || "~/workspace/ts-spaces/orchestra-dashboard";
-const DEPLOY_TYPE = projectConfig.deploy_type || "artifact";
-const DEPLOY_SLUG = projectConfig.deploy_slug || DASHBOARD_SLUG;
+const PUBLISH_TYPE = projectConfig.deploy_type || "";
+const PUBLISH_SLUG = projectConfig.deploy_slug || DASHBOARD_SLUG;
 const PROJECT_DESC = projectConfig.description || "React + TypeScript web dashboard (client/src/, server/src/, drizzle/)";
 const RELEASE_SCRIPT = crewHome + "/crew-release.sh";
 
@@ -58,7 +60,7 @@ const STEPS = [
   { name: "Build", identity: "wren" },
   { name: "Review", identity: "cass" },
   { name: "Integrate", identity: "wren" },
-  { name: "Deploy", identity: "wren" }
+  { name: "Publish", identity: "wren" }
 ];
 const BUILD_INDEX = STEPS.findIndex(s => s.name === 'Build');
 if (BUILD_INDEX < 0) throw new Error("STEPS missing 'Build' step");
@@ -71,7 +73,7 @@ let i = startStepIndex;
 // Pin lifecycle scripts
 await agent(
   "Snapshot lifecycle scripts for version pinning.\n" +
-  "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK,
+  "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + ORPHAN_SWEEP,
   { key: "pin-lifecycle", label: "Pinning lifecycle scripts", schema: { type: "object" } }
 );
 
@@ -82,6 +84,24 @@ while (i < STEPS.length) {
   phase(step.name);
   log(step.name + " step (" + step.identity + ") for task " + taskId);
 
+  // Publish is optional and target-based. Empty target = prototyping project: skip the phase.
+  // Unknown target (incl. legacy "repo") = config error: block.
+  if (step.name === "Publish" && !PUBLISH_TYPE) {
+    log("Publish skipped for task " + taskId + " — no publish target configured (deploy_type empty)");
+    await agent(
+      "Release the merge lock and clean up without publishing.\n" +
+      "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
+      "If the output contains DEPLOYED, the lock is released and the worktree is cleaned up.",
+      { key: "publish-skip-cleanup", label: "Skipping Publish (no target)", schema: { type: "object" } }
+    );
+    i++;
+    continue;
+  }
+  if (step.name === "Publish" && PUBLISH_TYPE !== "npm" && PUBLISH_TYPE !== "artifact" && PUBLISH_TYPE !== "vercel") {
+    log("Unknown publish target for task " + taskId + ": " + PUBLISH_TYPE);
+    return { status: "blocked", task_id: taskId, reason: "Unknown publish target '" + PUBLISH_TYPE + "' — expected 'npm', 'artifact', 'vercel', or empty (skip publish)." };
+  }
+
   let activeSessionId;
   if (isFirstClaim && firstSessionId) {
     activeSessionId = firstSessionId;
@@ -121,8 +141,10 @@ while (i < STEPS.length) {
       (mapperSpec ? "MAPPER'S SPEC (implement exactly this):\n" + mapperSpec + "\n\n" : "") +
       "Your working directory: " + REPO_PATH + "/.worktrees/" + taskId + "/\n" +
       "This is the project source: " + PROJECT_DESC + "\n" +
-      "Edit the TypeScript source files directly. Do NOT use artifact_edit — that happens in the Deploy phase.\n" +
-      "Do not add unrequested features.\n\n" +
+      "Edit the TypeScript source files directly. Do NOT use artifact_edit — that happens in the Publish phase.\n" +
+      "Do not add unrequested features.\n" +
+      "PUBLIC DOCS: If your change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), update the public docs in the same commit — API.md for API changes. Documentation and implementation ship together.\n\n" +
+      (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry, so you choose the package version. If this change warrants a published release (anything a consumer can observe: workflow behavior, phase lists, identities, published docs, API), bump the version in package.json with semver (patch for fixes, minor for new behavior, major for breaking changes) and state the chosen version and why in your summary. If the change is internal-only, leave the version unchanged and say so. Check the registry first — npm view muse-crew version — and never re-publish an existing version.\n\n" : "") +
       "STEP 3: Commit your changes.\n" +
       "cd " + REPO_PATH + "/.worktrees/" + taskId + "\n" +
       "git add -A\n" +
@@ -138,6 +160,8 @@ while (i < STEPS.length) {
       "You can also read specific files in the worktree at:\n" +
       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" +
+      (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" +
       "No prose, no markdown, just the JSON object.";
@@ -147,40 +171,69 @@ 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 LOCK_HELD, another task is deploying. Set passed to false.\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" +
+      "\n" +
+      "STEP 2: Push the merged main to the remote repository.\n" +
+      "Run: cd " + REPO_PATH + " && git push origin main\n" +
+      "- If the push succeeds, report the merged commit hash.\n" +
+      "- If the push is rejected as non-fast-forward (the remote has commits not present locally),\n" +
+      "  NEVER force-push. Do not run any --force variant. Set passed to false with summary:\n" +
+      "  'git push origin main rejected as non-fast-forward — remote main has diverged; manual resolution required'.
+\n\n" +
       "Your final response MUST be valid JSON and nothing else: { \"summary\": \"result\", \"passed\": true/false }. No prose, no markdown, just the JSON object.";
 
-  } else if (step.name === "Deploy") {
-    if (DEPLOY_TYPE === "repo") {
-      // Repo projects: install immutable release and atomically activate
-      instructions = "Deploy repo changes via the immutable release system.\n\n" +
-        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during deploy.\n" +
+  } else if (step.name === "Publish") {
+    if (PUBLISH_TYPE === "npm") {
+      // npm packages: immutable release + pack + publish to the registry (push is universal in Integrate)
+      instructions = "Publish the npm package to the registry.\n\n" +
+        "The repo push already happened in Integrate — do NOT push to git in this phase, and NEVER force-push.\n" +
+        "Version discipline: publish ships the exact version merged in Integrate (Build applied it, Review validated it). Do not bump the version here.\n\n" +
+        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during publish.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " refresh-lock " + taskId + "\n\n" +
-        "STEP 1: Install and activate the new release.\n" +
+        "STEP 1: Install and activate the immutable release.\n" +
         "Run: " + RELEASE_SCRIPT + " deploy " + REPO_PATH + "\n" +
         "Verify the output contains INSTALLED and ACTIVATED (or EXISTS and ACTIVATED if unchanged).\n\n" +
-        "STEP 2: Finalize.\n" +
+        "STEP 2: Check whether the package version needs publishing.\n" +
+        "Read the version from: cd " + REPO_PATH + " && node -p \"require('./package.json').version\"\n" +
+        "Check the registry: npm view muse-crew version 2>/dev/null || echo NOT_FOUND\n" +
+        "If the local version matches the registry version, the version is already live — skip to STEP 5.\n\n" +
+        "STEP 3: Pack and publish.\n" +
+        "Run: cd " + REPO_PATH + " && npm pack\n" +
+        "Then publish: python3 ~/workspace/skills/npm/bin/npm-publish.py " + REPO_PATH + "/muse-crew-$(node -p \"require('" + REPO_PATH + "/package.json').version\").tgz\n" +
+        "If publish fails with 'You cannot publish over the previously published versions', the version is already live — continue to STEP 4.\n\n" +
+        "STEP 4: Verify.\n" +
+        "Run: npm view muse-crew version\n" +
+        "Confirm it matches the local package.json version.\n\n" +
+        "STEP 5: Finalize.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
         "If the output contains DEPLOYED, finalization is complete.\n\n" +
-        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"release activated and finalized\", \"passed\": true }.\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"result\", \"passed\": true }.\n" +
         "No prose, no markdown, just the JSON object.";
-    } else {
-      instructions = "Deploy the merged code to the live artifact.\n\n" +
-        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during deploy.\n" +
+    } else if (PUBLISH_TYPE === "artifact") {
+      // Artifact projects: rebuild the live artifact via artifact_edit, then finalize
+      instructions = "Publish the merged code to the live artifact.\n\n" +
+        "The repo push already happened in Integrate — do NOT push to git in this phase.\n\n" +
+        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during publish.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " refresh-lock " + taskId + "\n\n" +
-        "STEP 1: Deploy to the live artifact.\n" +
+        "STEP 1: Publish to the live artifact.\n" +
         "Get the change summary: cd " + REPO_PATH + " && git log -1 --stat\n" +
-        "Then call artifact_edit with slug \"" + DEPLOY_SLUG + "\" and verbatim_request:\n" +
+        "Then call artifact_edit with slug \"" + PUBLISH_SLUG + "\" and verbatim_request:\n" +
         "'Rebuild the application from current source. Do not modify any source files — just rebuild and deploy what is on disk.'\n" +
         "Wait for the build to complete by polling artifact_status until it is no longer running.\n\n" +
         "STEP 2: Finalize.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
-        "If the output contains DEPLOYED, deployment is complete.\n\n" +
+        "If the output contains DEPLOYED, publishing is complete.\n\n" +
         "If artifact_edit failed, still run post-deploy to release the merge lock and clean up.\n" +
-        "Report the failure: { \"passed\": false, \"summary\": \"artifact deployment failed: [details]\" }.\n\n" +
-        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"deployed changes\", \"passed\": true }.\n" +
+        "Report the failure: { \"passed\": false, \"summary\": \"artifact publish failed: [details]\" }.\n\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"published changes\", \"passed\": true }.\n" +
+        "No prose, no markdown, just the JSON object.";
+    } else if (PUBLISH_TYPE === "vercel") {
+      // vercel publish is not yet implemented — block without inventing behavior
+      instructions = "The project's publish target is \"vercel\", which is not yet implemented.\n" +
+        "Do NOT invent publish behavior — do not guess CLI commands, APIs, or deployment steps.\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"passed\": false, \"summary\": \"vercel publish not yet implemented\" }.\n" +
         "No prose, no markdown, just the JSON object.";
     }
   }
@@ -189,8 +242,8 @@ while (i < STEPS.length) {
   var eventPreamble = "";
   if (step.name !== "Review") {
     eventPreamble = "CONTEXT: First, fetch this task's event history for background.\n" +
-      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getevents\", args: { \"limit\": 100 }.\n" +
-      "Look through returned events for entries matching task_id \"" + taskId + "\". They contain notes and decisions from prior phases.\n\n";
+      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getevents\", args: { \"task_id\": \"" + taskId + "\" }.\n" +
+      "The returned events are filtered to this task. They contain notes and decisions from prior phases.\n\n";
   }
 
   var stepResult;
@@ -273,9 +326,9 @@ while (i < STEPS.length) {
     return { status: "blocked", task_id: taskId, reason: "Integration failed: " + summary };
   }
 
-  if (!passed && step.name === "Deploy") {
-    log("Deploy failed for task " + taskId + ": " + summary);
-    return { status: "blocked", task_id: taskId, reason: "Deploy failed: " + summary };
+  if (!passed && step.name === "Publish") {
+    log("Publish failed for task " + taskId + ": " + summary);
+    return { status: "blocked", task_id: taskId, reason: "Publish failed: " + summary };
   }
 
   i++;

package/workflows/crew-dispatch.js

@@ -250,8 +250,9 @@ for (var p = 0; p < toProcess.length; p++) {
     "Claim the task for the " + nextStepName + " step.\n" +
     "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"claimtask\", args:\n" +
     "{ \"task_id\": \"" + itask.id + "\", \"identity\": \"" + identity + "\", \"step\": \"" + nextStepName + "\", \"notes\": \"" + nextStepName + " step started\" }.\n" +
-    "Check the response. If the task was successfully claimed (a new session was created), return { claimed: true, session_id: \"<the new session id>\" }.\n" +
-    "If the task was already claimed by another tick (already has a running session), return { claimed: false, session_id: \"\" }.",
+    "Do not interpret the response. It already contains an explicit \"claimed\" field — copy it verbatim.\n" +
+    "Return { claimed: <the response's claimed field exactly>, session_id: \"<the response's session_id field>\" }.\n" +
+    "If claimed is false there is no session_id; return { claimed: false, session_id: \"\" }.",
     {
       key: "claim-" + itask.id,
       label: "Claiming " + nextStepName + " for: " + itask.title,

package/workflows/crew-init.js

@@ -172,7 +172,7 @@ try {
     "      - mode: 'task'\n" +
     "      - schedule: { kind: 'interval', every: '3m' }\n" +
     "      - owner: 'space:" + dashboardSlug + "'\n" +
-    "      - timeout_secs: 180\n" +
+    "      - timeout_secs: 120\n" +
     "      - body: the processed template text\n" +
     "   d. Return { existed: false }\n\n" +
     "Return JSON with existed (boolean).",

package/workflows/docs.js

@@ -22,6 +22,11 @@ const DASHBOARD_SLUG = inputs.dashboardSlug || "orchestra-dashboard";
 const crewHome = inputs.crewHome || "~/workspace/.jarvis";
 const ORCH_PATH = crewHome + "/.orchestration";
 
+// Project repo — the docs workflow edits the project's own docs, not the crew home.
+// Falls back to crew home only for manual launches without a project config.
+const projectConfig = inputs.project_config || {};
+const REPO_PATH = projectConfig.repo_path || crewHome;
+
 if (!taskId) {
   throw new Error("task_id is required in args");
 }
@@ -72,7 +77,7 @@ while (i < STEPS.length) {
   if (step.name === "Triage") {
     instructions = "Validate the task, check clarity, confirm the docs workflow assignment.\nYour final response MUST be valid JSON and nothing else: { \"summary\": \"your assessment\", \"passed\": true }. No prose, no markdown, just the JSON object.";
   } else if (step.name === "Write") {
-    instructions = "Write or revise the documentation the task asks for.\nFollow Tate's voice — clear, conversational, no jargon unless it earns its place.\nAll doc files go under " + crewHome + "/." +
+    instructions = "Write or revise the documentation the task asks for.\nFollow Tate's voice — clear, conversational, no jargon unless it earns its place.\nDo your work in the project repository at " + REPO_PATH + " — all doc files go there, not under the crew home." +
       (rejectionNotes ? "\n\nREWORK after review rejection. Address:\n" + rejectionNotes : "") +
       "\nYour final response MUST be valid JSON and nothing else: { \"summary\": \"what you wrote and where\", \"passed\": true }. No prose, no markdown, just the JSON object.";
   } else if (step.name === "Review") {
@@ -83,7 +88,7 @@ while (i < STEPS.length) {
     "Read the identity file at " + ORCH_PATH + "/identities/" + step.identity + ".md using the read tool, and embody that character fully.\n\n" +
     "## Your Assignment\n\n" +
     "Task: " + taskTitle + "\nTask ID: " + taskId + "\nDescription: " + taskDescription + "\nStep: " + step.name + "\nDashboard slug: " + DASHBOARD_SLUG + "\n\n" +
-    "## Instructions\n\n" + instructions + "\n\nCONSTRAINT: Do NOT call logevent or upsertagentsession — the workflow handles all phase tracking after your step completes.\n\nStay in character. All file work under " + crewHome + "/.",
+    "## Instructions\n\n" + instructions + "\n\nCONSTRAINT: Do NOT call logevent or upsertagentsession — the workflow handles all phase tracking after your step completes.\n\nStay in character. All file work under " + REPO_PATH + "/.",
     {
       key: "work-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
       label: step.identity + ": " + step.name + " on \"" + taskTitle + "\"",

package/workflows/standard.js

@@ -1,14 +1,14 @@
 export const meta = {
   name: "crew-standard",
-  description: "Standard workflow: Triage → Map → Build → Review → Integrate → Deploy → QA",
-  phases: ["Triage", "Map", "Build", "Review", "Integrate", "Deploy", "QA"],
+  description: "Standard workflow: Triage → Map → Build → Review → Integrate → Publish → QA",
+  phases: ["Triage", "Map", "Build", "Review", "Integrate", "Publish", "QA"],
   steps: [
     { name: "Triage", identity: "sage" },
     { name: "Map", identity: "mara" },
     { name: "Build", identity: "wren" },
     { name: "Review", identity: "cass" },
     { name: "Integrate", identity: "wren" },
-    { name: "Deploy", identity: "wren" },
+    { name: "Publish", identity: "wren" },
     { name: "QA", identity: "hazel" }
   ],
   reworkTarget: "Build"
@@ -32,12 +32,14 @@ const MERGE_LOCK_SRC = crewHome + "/lib/merge-lock.sh";
 const RUN_LIB = "/tmp/crew-lib-" + taskId;
 const LIFECYCLE = RUN_LIB + "/worktree-lifecycle.sh";
 const MERGE_LOCK = RUN_LIB + "/merge-lock.sh";
+const ORPHAN_SWEEP_SRC = crewHome + "/lib/orphan-sweep.sh";
+const ORPHAN_SWEEP = RUN_LIB + "/orphan-sweep.sh";
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
 const REPO_PATH = projectConfig.repo_path || "~/workspace/ts-spaces/orchestra-dashboard";
-const DEPLOY_TYPE = projectConfig.deploy_type || "artifact";
-const DEPLOY_SLUG = projectConfig.deploy_slug || DASHBOARD_SLUG;
+const PUBLISH_TYPE = projectConfig.deploy_type || "";
+const PUBLISH_SLUG = projectConfig.deploy_slug || DASHBOARD_SLUG;
 const PROJECT_DESC = projectConfig.description || "React + TypeScript web dashboard (client/src/, server/src/, drizzle/)";
 const RELEASE_SCRIPT = crewHome + "/crew-release.sh";
 
@@ -60,13 +62,15 @@ const STEPS = [
   { name: "Build", identity: "wren" },
   { name: "Review", identity: "cass" },
   { name: "Integrate", identity: "wren" },
-  { name: "Deploy", identity: "wren" },
+  { name: "Publish", identity: "wren" },
   { name: "QA", identity: "hazel" }
 ];
 const BUILD_INDEX = STEPS.findIndex(s => s.name === 'Build');
 if (BUILD_INDEX < 0) throw new Error("STEPS missing 'Build' step");
-const MAX_REWORK = 2;
-let reworkCount = 0;
+// Shared rework budget: Review and QA rejections draw from the SAME pool of 2.
+// E.g. 2 Review bounces + 1 QA bounce = 3 total > budget -> task blocks.
+const MAX_TOTAL_REWORK = 2;
+let totalReworkCount = 0;
 let rejectionNotes = inputs.rejection_notes || "";
 let mapperSpec = "";
 let i = startStepIndex;
@@ -80,7 +84,8 @@ await agent(
   "  mkdir -p " + RUN_LIB + "\n" +
   "  cp " + LIFECYCLE_SRC + " " + LIFECYCLE + "\n" +
   "  cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + "\n" +
-  "  chmod +x " + LIFECYCLE + " " + MERGE_LOCK + "\n" +
+  "  cp " + ORPHAN_SWEEP_SRC + " " + ORPHAN_SWEEP + "\n" +
+  "  chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + ORPHAN_SWEEP + "\n" +
   "Confirm the files exist by listing " + RUN_LIB + ".",
   { key: "pin-lifecycle", label: "Pinning lifecycle scripts", schema: { type: "object" } }
 );
@@ -88,11 +93,29 @@ log("Lifecycle scripts pinned to " + RUN_LIB);
 
 while (i < STEPS.length) {
   const step = STEPS[i];
-  const isFirstClaim = (i === startStepIndex && reworkCount === 0);
+  const isFirstClaim = (i === startStepIndex && totalReworkCount === 0);
 
   phase(step.name);
   log(step.name + " step (" + step.identity + ") for task " + taskId);
 
+  // Publish is optional and target-based. Empty target = prototyping project: skip the phase.
+  // Unknown target (incl. legacy "repo") = config error: block.
+  if (step.name === "Publish" && !PUBLISH_TYPE) {
+    log("Publish skipped for task " + taskId + " — no publish target configured (deploy_type empty)");
+    await agent(
+      "Release the merge lock and clean up without publishing.\n" +
+      "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
+      "If the output contains DEPLOYED, the lock is released and the worktree is cleaned up.",
+      { key: "publish-skip-cleanup", label: "Skipping Publish (no target)", schema: { type: "object" } }
+    );
+    i++;
+    continue;
+  }
+  if (step.name === "Publish" && PUBLISH_TYPE !== "npm" && PUBLISH_TYPE !== "artifact" && PUBLISH_TYPE !== "vercel") {
+    log("Unknown publish target for task " + taskId + ": " + PUBLISH_TYPE);
+    return { status: "blocked", task_id: taskId, reason: "Unknown publish target '" + PUBLISH_TYPE + "' — expected 'npm', 'artifact', 'vercel', or empty (skip publish)." };
+  }
+
   // Claim session — reuse dispatcher's session for the very first step
   let activeSessionId;
   if (isFirstClaim && firstSessionId) {
@@ -101,10 +124,10 @@ while (i < STEPS.length) {
     const claimResult = await agent(
       "Claim a session for this task step.\n" +
       "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"claimtask\", args:\n" +
-      "{ \"task_id\": \"" + taskId + "\", \"identity\": \"" + step.identity + "\", \"step\": \"" + step.name + "\", \"notes\": \"" + step.name + " step started" + (reworkCount > 0 ? " (rework #" + reworkCount + ")" : "") + "\" }.\n" +
+      "{ \"task_id\": \"" + taskId + "\", \"identity\": \"" + step.identity + "\", \"step\": \"" + step.name + "\", \"notes\": \"" + step.name + " step started" + (totalReworkCount > 0 ? " (rework #" + totalReworkCount + ")" : "") + "\" }.\n" +
       "Return the session_id from the response.",
       {
-        key: "claim-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
+        key: "claim-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
         label: "Claiming " + step.name,
         schema: {
           type: "object",
@@ -134,8 +157,10 @@ while (i < STEPS.length) {
       (mapperSpec ? "MAPPER'S SPEC (implement exactly this):\n" + mapperSpec + "\n\n" : "") +
       "Your working directory: " + REPO_PATH + "/.worktrees/" + taskId + "/\n" +
       "This is the project source: " + PROJECT_DESC + "\n" +
-      "Edit source files directly. Do NOT use artifact_edit — that happens in the Deploy phase.\n" +
-      "Do not add unrequested features. Build exactly what the spec calls for.\n\n" +
+      "Edit source files directly. Do NOT use artifact_edit — that happens in the Publish phase.\n" +
+      "Do not add unrequested features. Build exactly what the spec calls for.\n" +
+      "PUBLIC DOCS: If your change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), update the public docs in the same commit — API.md for API changes. Documentation and implementation ship together.\n\n" +
+      (PUBLISH_TYPE === "npm" ? "PACKAGE VERSION: this project publishes to the npm registry, so you choose the package version. If this change warrants a published release (anything a consumer can observe: workflow behavior, phase lists, identities, published docs, API), bump the version in package.json with semver (patch for fixes, minor for new behavior, major for breaking changes) and state the chosen version and why in your summary. If the change is internal-only, leave the version unchanged and say so. Check the registry first — npm view muse-crew version — and never re-publish an existing version.\n\n" : "") +
       "STEP 3: Commit your changes.\n" +
       "cd " + REPO_PATH + "/.worktrees/" + taskId + "\n" +
       "git add -A\n" +
@@ -151,6 +176,8 @@ while (i < STEPS.length) {
       "You can also read specific files in the worktree at:\n" +
       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" +
+      (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" +
       "No prose, no markdown, just the JSON object.";
@@ -160,56 +187,84 @@ 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 LOCK_HELD, another task is deploying. Set passed to false with summary 'merge lock held'.\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" +
+      "\n" +
+      "STEP 2: Push the merged main to the remote repository.\n" +
+      "Run: cd " + REPO_PATH + " && git push origin main\n" +
+      "- If the push succeeds, report the merged commit hash.\n" +
+      "- If the push is rejected as non-fast-forward (the remote has commits not present locally),\n" +
+      "  NEVER force-push. Do not run any --force variant. Set passed to false with summary:\n" +
+      "  'git push origin main rejected as non-fast-forward — remote main has diverged; manual resolution required'.\n\n" +
       "Your final response MUST be valid JSON and nothing else: { \"summary\": \"result\", \"passed\": true/false }. No prose, no markdown, just the JSON object.";
 
-  } else if (step.name === "Deploy") {
-    if (DEPLOY_TYPE === "repo") {
-      // Repo projects: install immutable release and atomically activate
-      instructions = "Deploy repo changes via the immutable release system.\n\n" +
-        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during deploy.\n" +
+  } else if (step.name === "Publish") {
+    if (PUBLISH_TYPE === "npm") {
+      // npm packages: immutable release + pack + publish to the registry (push is universal in Integrate)
+      instructions = "Publish the npm package to the registry.\n\n" +
+        "The repo push already happened in Integrate — do NOT push to git in this phase, and NEVER force-push.\n" +
+        "Version discipline: publish ships the exact version merged in Integrate (Build applied it, Review validated it). Do not bump the version here.\n\n" +
+        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during publish.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " refresh-lock " + taskId + "\n\n" +
-        "STEP 1: Install and activate the new release.\n" +
+        "STEP 1: Install and activate the immutable release.\n" +
         "Run: " + RELEASE_SCRIPT + " deploy " + REPO_PATH + "\n" +
         "Verify the output contains INSTALLED and ACTIVATED (or EXISTS and ACTIVATED if unchanged).\n\n" +
-        "STEP 2: Finalize.\n" +
+        "STEP 2: Check whether the package version needs publishing.\n" +
+        "Read the version from: cd " + REPO_PATH + " && node -p \"require('./package.json').version\"\n" +
+        "Check the registry: npm view muse-crew version 2>/dev/null || echo NOT_FOUND\n" +
+        "If the local version matches the registry version, the version is already live — skip to STEP 5.\n\n" +
+        "STEP 3: Pack and publish.\n" +
+        "Run: cd " + REPO_PATH + " && npm pack\n" +
+        "Then publish: python3 ~/workspace/skills/npm/bin/npm-publish.py " + REPO_PATH + "/muse-crew-$(node -p \"require('" + REPO_PATH + "/package.json').version\").tgz\n" +
+        "If publish fails with 'You cannot publish over the previously published versions', the version is already live — continue to STEP 4.\n\n" +
+        "STEP 4: Verify.\n" +
+        "Run: npm view muse-crew version\n" +
+        "Confirm it matches the local package.json version.\n\n" +
+        "STEP 5: Finalize.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
         "If the output contains DEPLOYED, finalization is complete.\n\n" +
-        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"release activated and finalized\", \"passed\": true }.\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"result\", \"passed\": true }.\n" +
         "No prose, no markdown, just the JSON object.";
-    } else {
-      // Artifact projects: deploy via artifact_edit then finalize
-      instructions = "Deploy the merged code to the live artifact.\n\n" +
-        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during deploy.\n" +
+    } else if (PUBLISH_TYPE === "artifact") {
+      // Artifact projects: rebuild the live artifact via artifact_edit, then finalize
+      instructions = "Publish the merged code to the live artifact.\n\n" +
+        "The repo push already happened in Integrate — do NOT push to git in this phase.\n\n" +
+        "STEP 0: Refresh the merge lock to prevent stale-lock breaking during publish.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " refresh-lock " + taskId + "\n\n" +
-        "STEP 1: Deploy to the live artifact.\n" +
+        "STEP 1: Publish to the live artifact.\n" +
         "Get the change summary: cd " + REPO_PATH + " && git log -1 --stat\n" +
-        "Then call artifact_edit with slug \"" + DEPLOY_SLUG + "\" and verbatim_request:\n" +
+        "Then call artifact_edit with slug \"" + PUBLISH_SLUG + "\" and verbatim_request:\n" +
         "'Rebuild the application from current source. Do not modify any source files — just rebuild and deploy what is on disk.'\n" +
         "Wait for the build to complete by polling artifact_status until it is no longer running.\n\n" +
         "STEP 2: Finalize.\n" +
         "Run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " post-deploy " + taskId + "\n" +
-        "If the output contains DEPLOYED, deployment is complete.\n\n" +
+        "If the output contains DEPLOYED, publishing is complete.\n\n" +
         "If artifact_edit failed, still run post-deploy to release the merge lock and clean up.\n" +
-        "Report the failure: { \"passed\": false, \"summary\": \"artifact deployment failed: [details]\" }.\n\n" +
-        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"deployed changes\", \"passed\": true }.\n" +
+        "Report the failure: { \"passed\": false, \"summary\": \"artifact publish failed: [details]\" }.\n\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"summary\": \"published changes\", \"passed\": true }.\n" +
+        "No prose, no markdown, just the JSON object.";
+    } else if (PUBLISH_TYPE === "vercel") {
+      // vercel publish is not yet implemented — block without inventing behavior
+      instructions = "The project's publish target is \"vercel\", which is not yet implemented.\n" +
+        "Do NOT invent publish behavior — do not guess CLI commands, APIs, or deployment steps.\n" +
+        "Your final response MUST be valid JSON and nothing else: { \"passed\": false, \"summary\": \"vercel publish not yet implemented\" }.\n" +
         "No prose, no markdown, just the JSON object.";
     }
-
   } else if (step.name === "QA") {
-    if (DEPLOY_TYPE === "artifact") {
+    if (PUBLISH_TYPE === "artifact") {
       var safeDesc = taskDescription.replace(/"/g, "'").replace(/\\/g, "\\\\").slice(0, 500);
-      instructions = "You are code-blind QA. You NEVER read source files.\n\n" +
-        "STEP 1: Trigger a visual inspection of the deployed artifact.\n" +
+      instructions = "You are code-blind QA. You NEVER read source files.\n" +
+        "Public docs (API.md, README, published action schemas) are NOT source code — read them freely, exactly as a user would.\n\n" +
+        "STEP 1: Trigger a visual inspection of the published artifact.\n" +
         "Call artifact_inspect with:\n" +
-        "  slug: \"" + DEPLOY_SLUG + "\"\n" +
+        "  slug: \"" + PUBLISH_SLUG + "\"\n" +
         "  repair_authorized: false\n" +
         "  verbatim_request: \"Verify task: " + safeTitle + ". " + safeDesc + "\"\n\n" +
         "This call is asynchronous — it fires the inspection but results arrive outside this workflow. That is expected and correct.\n\n" +
         "STEP 2: Verify data integrity via the dashboard API.\n" +
-        "Use artifact_invoke_action on slug \"" + DEPLOY_SLUG + "\" with read-only actions (e.g. gettasks, getagentsessions) to check the task's data-level effects.\n\n" +
+        "Use artifact_invoke_action on slug \"" + PUBLISH_SLUG + "\" with read-only actions (e.g. gettasks, getagentsessions) to check the task's data-level effects.\n" +
+        "DOCS GATE: If the change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), verify the public docs describe it. If public docs are missing or stale for a public-affecting change, FAIL with { \"passed\": false, \"summary\": \"public docs missing/stale for [the change]\" }. QA always fails when public-affecting changes lack public docs. Guide/tutorial gaps are lower priority — file a follow-up task for those instead of failing.\n\n" +
         "STEP 3: File follow-up tasks for any related issues you discover.\n" +
         "Use artifact_invoke_action createtask on slug \"" + DASHBOARD_SLUG + "\" for each issue.\n\n" +
         "Your final response MUST be valid JSON and nothing else:\n" +
@@ -217,7 +272,9 @@ while (i < STEPS.length) {
         "No prose, no markdown, just the JSON object.";
     } else {
       instructions = "Test from a user's perspective. You are CODE-BLIND — do NOT read source code.\n" +
+        "Public docs (API.md, README) are NOT source code — read them freely, exactly as a user would.\n" +
         "Verify the change is working as described in the task.\n" +
+        "DOCS GATE: If the change is public-affecting (it alters anything a user or consumer can observe: API actions, parameters, behavior, or errors), verify the public docs describe it. If public docs are missing or stale, FAIL with { \"passed\": false, \"summary\": \"public docs missing/stale for [the change]\" }. QA always fails when public-affecting changes lack public docs. Guide/tutorial gaps are lower priority — file a follow-up task for those instead of failing.\n" +
         "File follow-up tasks via artifact_invoke_action createtask on slug \"" + DASHBOARD_SLUG + "\" for related issues found.\n\n" +
         "Your final response MUST be valid JSON and nothing else: { \"passed\": true/false, \"summary\": \"what you tested and found\" }.\n" +
         "No prose, no markdown, just the JSON object.";
@@ -228,8 +285,8 @@ while (i < STEPS.length) {
   var eventPreamble = "";
   if (step.name !== "Review") {
     eventPreamble = "CONTEXT: First, fetch this task's event history for background.\n" +
-      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getevents\", args: { \"limit\": 100 }.\n" +
-      "Look through returned events for entries matching task_id \"" + taskId + "\". They contain notes and decisions from prior phases.\n\n";
+      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getevents\", args: { \"task_id\": \"" + taskId + "\" }.\n" +
+      "The returned events are filtered to this task. They contain notes and decisions from prior phases.\n\n";
   }
 
   // Run work agent WITH schema — runtime retries on non-JSON via structured outputs
@@ -247,7 +304,7 @@ while (i < STEPS.length) {
       "CONSTRAINT: Do NOT call logevent or upsertagentsession — the workflow handles all phase tracking after your step completes.\n\n" +
       "Stay in character. Do the work thoroughly.",
       {
-        key: "work-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
+        key: "work-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
         label: step.identity + ": " + step.name + " on \"" + taskTitle + "\"",
         timeoutMs: 3600000,
         schema: WORK_SCHEMA
@@ -296,7 +353,7 @@ while (i < STEPS.length) {
     "Then call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"logevent\", args:\n" +
     "{ \"task_id\": \"" + taskId + "\", \"type\": \"" + status + "\", \"identity\": \"" + step.identity + "\", \"message\": \"" + step.name + " " + status + " by " + step.identity + "\" }.",
     {
-      key: "record-" + step.name + (reworkCount > 0 ? "-r" + reworkCount : ""),
+      key: "record-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
       label: "Recording " + step.name + " result",
       schema: { type: "object" }
     }
@@ -304,14 +361,14 @@ while (i < STEPS.length) {
 
   // Handle rejection — bounce back to Build
   if (!passed && (step.name === "Review" || step.name === "QA")) {
-    reworkCount++;
-    if (reworkCount > MAX_REWORK) {
-      log("Max rework attempts reached for task " + taskId + " — worktree preserved at .worktrees/" + taskId + " for manual inspection");
-      return { status: "blocked", task_id: taskId, reason: "Exceeded " + MAX_REWORK + " rework attempts after " + step.name + " rejection. Worktree preserved." };
+    totalReworkCount++;
+    if (totalReworkCount > MAX_TOTAL_REWORK) {
+      log("Shared rework budget exhausted for task " + taskId + " — worktree preserved at .worktrees/" + taskId + " for manual inspection");
+      return { status: "blocked", task_id: taskId, reason: "Exceeded shared rework budget (" + MAX_TOTAL_REWORK + " total rework attempts across Review and QA) after " + step.name + " rejection. Worktree preserved." };
     }
     rejectionNotes = summary;
     i = BUILD_INDEX;
-    log(step.name + " rejected — bouncing to Build (rework #" + reworkCount + ")");
+    log(step.name + " rejected — bouncing to Build (rework #" + totalReworkCount + " of " + MAX_TOTAL_REWORK + ")");
     continue;
   }
 
@@ -321,10 +378,10 @@ while (i < STEPS.length) {
     return { status: "blocked", task_id: taskId, reason: "Integration failed: " + summary };
   }
 
-  // Deploy failure blocks the task
-  if (!passed && step.name === "Deploy") {
-    log("Deploy failed for task " + taskId + ": " + summary);
-    return { status: "blocked", task_id: taskId, reason: "Deploy failed: " + summary };
+  // Publish failure blocks the task
+  if (!passed && step.name === "Publish") {
+    log("Publish failed for task " + taskId + ": " + summary);
+    return { status: "blocked", task_id: taskId, reason: "Publish failed: " + summary };
   }
 
   i++;