muse-crew 0.1.0 → 0.2.0

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,17 @@ 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 || {};
+// Project this run was dispatched for — the mid-run project-change guard
+// compares the task's live project against this on every phase boundary.
+const LAUNCH_PROJECT_ID = inputs.project_id || "";
 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 +65,16 @@ 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;
+const REWORK_STEP = STEPS[BUILD_INDEX].name;
+// 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 +88,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 +97,67 @@ 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);
 
+  // ── Project-change guard ───────────────────────────────────────────
+  // A task moved to another project mid-run must not keep working in the
+  // old project's repo. Re-read the task's project at every phase
+  // boundary: if it differs from the project this run was dispatched for,
+  // abort the stale run (failed at the rework target) so the dispatcher
+  // re-launches the step with the new project's config.
+  if (LAUNCH_PROJECT_ID) {
+    const projectCheck = await agent(
+      "Read this task's current project from the dashboard.\n" +
+      "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"getstate\", args: { \"events_limit\": 1 }.\n" +
+      "Find the task with id \"" + taskId + "\" in the returned tasks array.\n" +
+      "Return exactly { \"project\": \"<the task's project field, or empty string if absent>\" } and nothing else.",
+      {
+        key: "project-check-" + step.name + (totalReworkCount > 0 ? "-r" + totalReworkCount : ""),
+        label: "Checking project before " + step.name,
+        schema: { type: "object", properties: { project: { type: "string" } }, required: ["project"] }
+      }
+    );
+    const currentProject = (projectCheck && projectCheck.project) ? projectCheck.project : LAUNCH_PROJECT_ID;
+    if (currentProject !== LAUNCH_PROJECT_ID) {
+      const abortMessage = "Task project changed mid-run from '" + LAUNCH_PROJECT_ID + "' to '" + currentProject + "' — aborting stale run. The dispatcher will re-launch from " + REWORK_STEP + " with the new project context.";
+      log(abortMessage);
+      const abortSessionPatch = (isFirstClaim && firstSessionId) ? "\"id\": \"" + firstSessionId + "\", " : "";
+      await agent(
+        "Abort the stale run and remove its worktree from the old project's repo.\n" +
+        "Call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"upsertagentsession\", args:\n" +
+        "{ \"task_id\": \"" + taskId + "\", " + abortSessionPatch + "\"identity\": \"" + step.identity + "\", \"step\": \"" + REWORK_STEP + "\", \"status\": \"failed\", " +
+        "\"notes\": " + JSON.stringify(abortMessage + " Rebuild from the Map session notes in the task's event history.") + " }.\n" +
+        "Then call artifact_invoke_action on slug \"" + DASHBOARD_SLUG + "\", action \"logevent\", args:\n" +
+        "{ \"task_id\": \"" + taskId + "\", \"type\": \"failed\", \"identity\": \"" + step.identity + "\", \"message\": " + JSON.stringify(abortMessage) + " }.\n" +
+        "Then run: CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " cleanup " + taskId + "\n" +
+        "The cleanup output should contain CLEANUP.",
+        { key: "abort-project-change", label: "Aborting stale run (project changed)", schema: { type: "object" } }
+      );
+      return { status: "failed", task_id: taskId, reason: abortMessage };
+    }
+  }
+
+  // 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 +166,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 +199,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" +
@@ -148,9 +215,12 @@ while (i < STEPS.length) {
       (mapperSpec ? "MAPPER'S SPEC (the builder was asked to implement exactly this):\n" + mapperSpec + "\n\n" : "Read the spec (from the task description or spec files under " + crewHome + "/).\n\n") +
       "Examine the code changes by running:\n" +
       "CREW_REPO=" + REPO_PATH + " " + LIFECYCLE + " inspect " + taskId + "\n\n" +
+      "The inspect output is authoritative: it prints the task branch's actual tip commit (TIP) and every commit ahead of main. Base your review ONLY on this output — do NOT run git log yourself to pick commits, and do NOT discuss commit hashes from any other source (they may come from stale rework rounds or a different repo).\n\n" +
       "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 +230,97 @@ 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" +
+        "POLICY: The live artifact is rebuilt only in this phase, from the repo. Never use artifact_edit to change the artifact directly — fixes go through the repo and the loop. A source fix is not done until the artifact is rebuilt from it here.\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 1B: Stamp publication provenance.\n" +
+        "Run: cd " + REPO_PATH + " && git rev-parse HEAD\n" +
+        "Run: basename $(readlink " + crewHome + "/current)\n" +
+        "Run: date -u +%Y-%m-%dT%H:%M:%SZ\n" +
+        "Call artifact_invoke_action on slug \"" + PUBLISH_SLUG + "\", action \"setprovenance\", args:\n" +
+        "{ \"source_commit\": \"<rev-parse output>\", \"crew_release\": \"<basename output>\", \"published_at\": \"<date output>\", \"task_id\": \"" + taskId + "\" }.\n" +
+        "Confirm the response contains ok: true. If setprovenance fails, report it in your summary but still run post-deploy to release the lock.\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" +
+        "PROVENANCE CHECK: Call artifact_invoke_action on slug \"" + PUBLISH_SLUG + "\", action \"getprovenance\", args: {}.\n" +
+        "If provenance is null, FAIL: { \"passed\": false, \"summary\": \"provenance missing — publish did not stamp source/crew release\" }.\n" +
+        "Run: cd " + REPO_PATH + " && git rev-parse HEAD\n" +
+        "Run: basename $(readlink " + crewHome + "/current)\n" +
+        "If provenance.source_commit does not equal the rev-parse output or provenance.crew_release does not equal the basename output, FAIL: { \"passed\": false, \"summary\": \"provenance mismatch: [details]\" }.\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 +328,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 +341,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 +360,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 +409,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 +417,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 +434,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++;