muse-crew 0.17.1 → 0.17.3

package/lib/bugfix/phases/integrate.js

@@ -0,0 +1,165 @@
+// lib/bugfix/phases/integrate.js — Bugfix Integrate phase (worker layer).
+//
+// Wren merges the task branch onto the integration target. Derived from
+// workflows/bugfix.js (the Bugfix Integrate step).
+//
+// Contract:
+//   - Read: task branch (mechanical git facts); staged publish base
+//     (provenance); task title (for the merge message).
+//   - Wren merges in the current checkout via the lifecycle integrate
+//     command: `merge: fix: <safeTitle>`.
+//   - verify-merge is a direct lifecycle invocation (worker-layer
+//     equivalent of the source's agent ferry). Not VERIFIED →
+//     `integrate_verify: FAILED` appended, status failed (operational).
+//   - Optional QA deploy (versioned artifact builds only): failed deploy →
+//     `deploy: FAILED` appended, status failed (operational, never a park).
+//   - FAIL → status "failed" (operational, retried by the dispatcher at
+//     Integrate), NOT "rejected" (no rework routing).
+//   - PASS → ADVANCE to Publish.
+//
+// Phase I/O contract (Phase D):
+//   read:  task branch, provenance (staged publish base), task title
+//   write: session (completed | failed), event (completed | failed)
+//   out:   ADVANCE → Publish | FAILED (dispatcher retry) |
+//          NEED_SPAWN / STANDBY (boundary)
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  ensureClaimed, log, lifecycle, lifecycleEnvPrefix, runCmd,
+  parseDeployResult, crewCmdString,
+} from "../../workflow-lib.js";
+
+export const PHASE = { name: "Integrate", identity: "wren" };
+
+// buildInstructions — verbatim from workflows/bugfix.js (variable
+// references remapped; logic and prose unchanged).
+// ctx: { env, safeTitle, lockHolder }.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var instructions = "Merge the approved task branch into the integration target and push the result.\n" +
+      "The integration target is the repo's current checkout — a branch name, or the literal word HEAD when detached (no branch name exists when detached). Print the exact token with: "+ lifecycleEnvPrefix(env) + env.lifecycle + " integration-target\n" +
+      "NEVER run git checkout — the lifecycle merges into the current checkout; moving it abandons the line Publish verifies.\n\n" +
+      "Read the staged publish base (return its stdout verbatim):\n" + crewCmdString(env, "get-provenance", { project_id: env.projectId }) + "\n" +
+      "Then run: "+ lifecycleEnvPrefix(env) + "WORKFLOW_RUN_ID=" + ctx.lockHolder + " CREW_STAGED_BASE=<provenance.source_commit, empty when null> integrate " + env.taskId + " \"merge: fix: " + ctx.safeTitle + "\\\"\\n" +
+      "The script merges, reconciles, records, and pushes under the merge lock. Informational only: RECONCILED, NO_REMOTE, NO_REMOTE_RECONCILE. Read the output:\n" +
+      "- STAGED_BASE_MISMATCH: the line left the staged base (stray checkout). VERDICT: FAIL.\n" +
+      "- MERGED_EMPTY — check FIRST (it contains the word MERGED): either a runtime-state deliverable or a task-attributed merge the workflow verified from the task's own merge records. No lock taken, no new commit. Report 'merged empty: no repo changes'. VERDICT: PASS.\n" +
+      "- MERGED: the merge landed; the script pushed inline. Read the push line: PUSHED — report the hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; NO_REMOTE_PUSH — no remote configured, VERDICT: PASS; ERROR after MERGED — a retry recovers the push; report it, VERDICT: FAIL.\n" +
+      "- STALE_MERGE: the recorded merge no longer matches the task branch (rework moved it after the merge) — the script refused to push stale state. Report the STALE_MERGE line, VERDICT: FAIL.\n" +
+      "- LOCK_HELD: 10-minute backoff exhausted. VERDICT: FAIL.\n" +
+      "- CONFLICT: the plain merge failed — aborted, the target is clean, and your task still holds the merge lock. Do NOT fail yet. Resolve it:\n" +
+      "RESOLUTION:\n" +
+      "R1. Refresh the merge lock FIRST (a long resolution must not silently lose the lock to the orphan sweep): "+ lifecycleEnvPrefix(env) + " refresh-lock " + env.taskId + ". Create a scratch worktree WITH A NEW BRANCH (the integration target is checked out in the repo, so create the scratch worktree from HEAD — never check out another branch in the repo checkout): cd " + env.repoPath + " && git worktree add -b resolve/" + env.taskId + " /tmp/crew-resolve-" + env.taskId + " HEAD. Reproduce the conflict in the scratch worktree: cd /tmp/crew-resolve-" + env.taskId + " && git merge " + env.taskBranch + ". This reproduces the exact conflict (the integration target has not moved — the lock was held throughout). The task branch " + env.taskBranch + " is never modified.\n" +
+      "R2. For each conflicted file, read the three sides: git show :1:<file> (base), git show :2:<file> (ours = the integration target), git show :3:<file> (theirs = task branch). Resolve each hunk by keeping both sides' changes when they do not semantically overlap. Version-only hunks resolve to the higher semver (safety net). Never invent new behavior. Leave no markers.\n" +
+      "R3. Verify in the scratch worktree, in this order: (a) git diff --check is clean; (b) git grep -n '^<<<<<<<' -- . returns nothing; (c) node --check every changed .js file (conflicted files plus everything listed by git diff --name-only). If any check fails, refresh the merge lock ("+ lifecycleEnvPrefix(env) + " refresh-lock " + env.taskId + "), then retry using the failure output as context — max 3 attempts total.\n" +
+      "R4. Commit the resolution on resolve/" + env.taskId + ": git add -A && git commit -m \"resolve conflicts: " + env.taskId + "\".\n" +
+      "R5. Back in " + env.repoPath + ": git merge --ff-only resolve/" + env.taskId + " — merges the resolution into the current checkout (the integration target; no git checkout anywhere). It fast-forwards — the target has not moved under the lock. Report the merged hash.\n" +
+      "R6. Clean up: cd " + env.repoPath + " && git worktree remove --force /tmp/crew-resolve-" + env.taskId + " && git branch -D resolve/" + env.taskId + ".\n" +
+      "ESCALATE — 'conflict needs human resolution', VERDICT: FAIL — when: 3 attempts are exhausted; the conflict touches generated files, migrations, or public API contracts; or 'looks right + checks pass' is not sufficient for any other reason. On escalation, RELEASE THE LOCK so the task can be reworked later: run CREW_HOME=" + env.crewHome + " CREW_REPO=" + env.repoPath + " " + env.mergeLock + " release " + env.taskId + " (release is keyed on task id; no PID needed). Do NOT run post-deploy on escalation — it would delete the untouched task branch the human still needs.\n" +
+      "- ERROR: report it. VERDICT: FAIL.\n\n" +
+      "R5-PUSH (manual R5 resolution only — the normal path pushed inline). Run: " + lifecycleEnvPrefix(env) + env.lifecycle + " push-target " + env.taskId + "\n" +
+      "PUSHED — report the merged hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; PUSH_SKIPPED — no push attempted (no record + no lock); NO_REMOTE_PUSH — no remote; VERDICT: PASS; ERROR or CONFLICT — report it, VERDICT: FAIL.\n" +
+      "NEVER force-push.\n\n" +
+      "Report what happened at each step, ending with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
+
+
+  return instructions;
+}
+
+// safeTitle — exact source transformation of the task title for the merge
+// message.
+function safeTitleOf(title) {
+  return String(title || "").replace(/"/g, "").replace(/\n/g, " ").slice(0, 72);
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  ctx.safeTitle = safeTitleOf(env.taskTitle);
+  // lockHolder: taskId alone cannot distinguish two runs of the same task;
+  // the session id disambiguates (source: lockHolder = taskId/session).
+  ctx.lockHolder = env.taskId + "/" + state.activeSessionId;
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name,
+    identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true,
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+  var workerText = boundary.workerText;
+
+  // The agent cannot verify integrate mechanically; the workflow checks
+  // the diff (docs/decisions/publish-path.md#integrate-verify).
+  var passed = boundary.verdictPassed !== false;
+  var summary = workerText;
+  if (passed) {
+    var integrateVerifyOut = "";
+    try {
+      var vr = await lifecycle(env, "verify-merge", [env.taskId]);
+      integrateVerifyOut = String((vr.stdout || "") + "\n" + (vr.stderr || "")).trim();
+    } catch (e) {
+      integrateVerifyOut = "";
+    }
+    if (/^VERIFIED:/m.test(integrateVerifyOut)) {
+      log("Integrate verified for task " + env.taskId + ": task branch tip is an ancestor of the integration target");
+      // QA deploy: after verified merge, ensure QA env serves a bundle from
+      // merged source. Failed deploy = operational failure, never a park.
+      if (env.versionedBuild === true && env.surfaceArtifact) {
+        var deployOut = "";
+        try {
+          var dr = await runCmd(["node", env.runLib + "/qa-deploy.mjs",
+            "--repo", env.repoPath,
+            "--qa-dir", env.crewHome + "/qa-envs/" + env.projectId,
+            "--task", env.taskId,
+            "--crew-home", env.crewHome,
+            "--crew-api", env.crewApiPinned,
+            "--serve-artifact", env.crewHome + "/current/lib/serve-artifact.js",
+          ]);
+          deployOut = String(dr.stdout || "").trim();
+        } catch (e) {
+          deployOut = "";
+        }
+        var deployParsed = parseDeployResult(deployOut);
+        if (deployParsed.ok) {
+          log("QA deploy ok for task " + env.taskId + ": bundle " + deployParsed.hash);
+          summary = (summary || "") + "\ndeploy: ok " + deployParsed.hash;
+        } else {
+          log("QA deploy failed for task " + env.taskId + ": " + deployParsed.reason + " — marking failed for retry");
+          summary = (summary || "") + "\ndeploy: FAILED — " + deployParsed.reason;
+          passed = false;
+        }
+      }
+    } else {
+      var integrateVerifyReason = integrateVerifyOut
+        ? integrateVerifyOut.split("\n")[0].slice(0, 200)
+        : "verify-merge produced no usable output";
+      log("Integrate verification failed for task " + env.taskId + ": " + integrateVerifyReason + " — marking failed for retry");
+      summary = (summary || "") + "\nintegrate_verify: FAILED — " + integrateVerifyReason;
+      passed = false;
+    }
+  }
+
+  // Integrate work that did not finish is operational — "failed",
+  // retryable under the dispatcher's consecutive-failure cap (never
+  // "rejected": no rework routing).
+  var status = passed ? "completed" : "failed";
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: {
+      id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+      step: PHASE.name, status: status, notes: summarizeReport(summary),
+    },
+    event: {
+      task_id: env.taskId, type: status, identity: PHASE.identity,
+      message: "Integrate " + status + " by " + PHASE.identity,
+    },
+  });
+
+  if (!passed) return { type: "FAILED" };
+  return { type: "ADVANCE", next: "Publish" };
+}

package/lib/bugfix/phases/map.js

@@ -0,0 +1,129 @@
+// lib/bugfix/phases/map.js — Bugfix Map phase (worker layer).
+//
+// Mara researches the bug and writes a solution-oriented spec for Build.
+// Derived from workflows/bugfix.js (the Bugfix Map step).
+//
+// Contract:
+//   - Read: Reproduce evidence (the completed Reproduce session notes are
+//     the handoff — Map does NOT inherit Standard's exact spec.md gate);
+//     task row (title, description); project surface and description.
+//   - Baseline gate (experiential + classified surface only — must match
+//     Capture's run condition): when no baseline evidence exists, record a
+//     "failed" session/event and REWIND to Capture (Map gate bounce). The
+//     driver's gateBounceCount gives Capture fresh spawn keys on the
+//     re-visit.
+//   - Instructions carry the baseline paragraph when baseline refs exist
+//     (or baseline:none was recorded), plus surface-specific spec guidance.
+//   - Closeout: standard session/event record; on PASS the truncated
+//     summary becomes Build's mapper spec (re-derived by Build from the
+//     durable Map session notes).
+//   - Map never rejects: a completed spec advances to Build.
+//
+// Phase I/O contract (Phase D):
+//   read:  Reproduce session notes, task title/description, project
+//          surface/description, experiential flag, baseline status
+//   write: session (completed | failed [gate bounce]), event (completed |
+//          failed [gate bounce])
+//   out:   ADVANCE → Build | REWIND → Capture (gate bounce) |
+//          NEED_SPAWN / STANDBY / FAILED (boundary)
+
+import {
+  runWorkBoundary, recordPhase, buildEventPreamble, summarizeReport,
+  ensureClaimed, log, resolveExperiential, baselineStatus,
+} from "../../workflow-lib.js";
+
+export const PHASE = { name: "Map", identity: "mara" };
+
+// buildInstructions — verbatim from workflows/bugfix.js (variable
+// references remapped to ctx.env; logic and prose unchanged).
+// ctx: { env, state, mapBaselineRefs, mapBaselineNone }.
+export function buildInstructions(ctx) {
+  var env = ctx.env;
+  var mapBaselineRefs = ctx.mapBaselineRefs || "";
+  var mapBaselineNone = !!ctx.mapBaselineNone;
+  var mapGatePara = "";
+  if (mapBaselineRefs || mapBaselineNone) {
+    mapGatePara = "\nBASELINE GATE (experiential task): " +
+      (mapBaselineNone
+        ? "no baseline was capturable (baseline: none recorded) — write the spec without baseline comparison and note it."
+        : "pre-change baseline evidence: " + mapBaselineRefs + " — consult it when writing the spec.") +
+      " If the baseline evidence is missing with no baseline:none recorded, do not write the spec — report 'baseline evidence missing — Map gate bounce required' and stop.\n" +
+      (env.surfaceTerminal
+        ? "Declare the CLI surface to exercise: end your report with a line `terminal_targets: <comma-separated CLI commands/flags>` (machine-read; optional — falls back to the task description)."
+        : "Declare capture targets for the post-change visual capture: end your report with a line `capture_targets: <comma-separated views/controls this change affects>` (optional; falls back to the task description).");
+  }
+  return "Update the task with a solution-oriented spec. Research options, pick the shortest path.\n" +
+    (env.surfaceTerminal ? "TERMINAL SPEC: this project's surface is a CLI. Specify the exact commands, their expected stdout/stderr, exit codes, --help text, and error messages — Hazel judges the build against this spec and the shared bar at " + env.uxDoctrinePath + ".\n" : "") +
+    (env.surfaceArtifact ? "ARTIFACT SPEC: this project's surface is a rendered artifact. Specify the exact screens, flows, and visual states the change affects — Hazel judges the build against this spec and the shared bar at " + env.uxDoctrinePath + ".\n" : "") +
+    "The builder will edit source files in a git worktree.\nProject: " + env.projectDesc + "\nWrite it clearly enough that the builder does not need to ask questions.\nReport back in plain prose — what you specified." + mapGatePara;
+}
+
+export async function runPhase(ctx) {
+  var env = ctx.env, state = ctx.state;
+
+  // Claim first: the baseline gate below records a "failed" session on the
+  // gate bounce, and that record needs the claimed session id (source
+  // parity: the source claims before instruction-building, which is where
+  // the gate lives).
+  var claimed = await ensureClaimed(env, state, PHASE);
+  if (claimed.type !== "CLAIMED") return claimed;
+
+  // Baseline gate — must match Capture's run condition (experiential +
+  // classified surface): when Capture skips, no baseline notes exist, so
+  // the gate must not apply.
+  var mapBaselineRefs = "";
+  var mapBaselineNone = false;
+  if ((await resolveExperiential(env, state)) === "yes" && (env.surfaceArtifact || env.surfaceTerminal)) {
+    var gateStatus = await baselineStatus(env);
+    if (!gateStatus.baseline_found) {
+      log("Map gate: no baseline evidence for experiential task " + env.taskId + " — bouncing to Capture");
+      await recordPhase(env, {
+        task_id: env.taskId,
+        session: {
+          id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+          step: PHASE.name, status: "failed",
+          notes: "Map gate bounce: no baseline evidence recorded for this experiential task — no spec was written. Baseline evidence must be captured before the spec.",
+        },
+        event: {
+          task_id: env.taskId, type: "failed", identity: PHASE.identity,
+          message: "Map gate bounce — baseline evidence missing, returning to Capture",
+        },
+      });
+      // The driver's gateBounceCount increments on REWIND, giving Capture
+      // fresh spawn keys on the re-visit (worker-layer equivalent of the
+      // source's -g<N> bounce suffix).
+      return { type: "REWIND", next: "Capture" };
+    }
+    mapBaselineRefs = (gateStatus.baseline_refs || []).join(", ");
+    mapBaselineNone = (gateStatus.baseline_kind === "none");
+  }
+  ctx.mapBaselineRefs = mapBaselineRefs;
+  ctx.mapBaselineNone = mapBaselineNone;
+
+  var boundary = await runWorkBoundary(env, state, {
+    phase: PHASE.name,
+    identity: PHASE.identity,
+    instructions: buildInstructions(ctx),
+    eventPreamble: buildEventPreamble(env, PHASE.name),
+    crewApiLine: true,
+    visitSuffix: (state.gateBounceCount > 0) ? "-g" + state.gateBounceCount : "",
+  });
+  if (boundary.type !== "BOUNDARY_DONE") return boundary;
+
+  // Closeout: the truncated summary becomes Build's mapper spec. It is
+  // re-derived by Build from these durable session notes (the worker-layer
+  // equivalent of the source's in-memory mapperSpec).
+  var summary = summarizeReport(boundary.workerText);
+  await recordPhase(env, {
+    task_id: env.taskId,
+    session: {
+      id: state.activeSessionId, task_id: env.taskId, identity: PHASE.identity,
+      step: PHASE.name, status: "completed", notes: summary,
+    },
+    event: {
+      task_id: env.taskId, type: "completed", identity: PHASE.identity,
+      message: "Map completed by " + PHASE.identity,
+    },
+  });
+  return { type: "ADVANCE", next: "Build" };
+}