muse-crew 0.9.1 → 0.10.0

package/docs/crew-state-boundaries.md

@@ -0,0 +1,124 @@
+# Spec: Crew-Owned State Boundaries
+
+**Date:** 2026-09-17  
+**Status:** Approved by Eric — build and publish  
+**Context:** Gate 1 J1/J2 canaries exposed two instances of crew-owned state leaking into user git operations (0.9.1: `.worktrees/` broke cleanliness check; 0.9.2: `.merge-lock` committed via `git add -A`). The root problem: we can't enumerate all crew-owned files, so surgical exclusions are whack-a-mole.
+
+## The Rule
+
+Crew state lives in exactly three places. Nothing crew-owned sits in the repo unclassified.
+
+| Location | Version-controlled? | Contents |
+|----------|---------------------|----------|
+| `$REPO/.orchestration/` | **Yes** | Custom workflows, identities, phases — the user's crew configuration |
+| `$REPO/.orchestration/user/` | **No** (gitignored) | Personal settings, local config, secrets — user-specific, not shared |
+| `$CREW_HOME/` | N/A (outside repo) | Worktrees, merge lock, registry, pins — transient operational state |
+
+## Directory Structure
+
+```
+$REPO/
+  .orchestration/
+    workflows/       # custom workflow definitions (versioned)
+    identities/      # custom identity definitions (versioned)
+    phases/          # custom phase definitions (versioned)
+    user/            # personal settings (GITIGNORED)
+      config.json    # example: user preferences
+      secrets/       # example: local secrets (never versioned)
+  .gitignore         # includes .orchestration/user/
+
+$CREW_HOME/
+  worktrees/         # task worktrees (moved from $REPO/.worktrees/)
+  .merge-lock        # merge lock file (moved from $REPO/.worktrees/.merge-lock)
+  .registry/         # task registry (moved from $REPO/.worktrees/.registry/)
+  .pins/             # release pins
+```
+
+## Changes
+
+### 1. Gitignore consent flow (THIS RELEASE)
+
+**What:** The crew needs to add `.worktrees/` to the repo's `.gitignore`. This is the ONLY user file outside crew-owned directories that the crew modifies.
+
+**When:** During the setup conversation (before `crew-init` is launched), as part of the "setup is a conversation" experience.
+
+**UX (in the setup conversation):**
+
+The agent (emojiman) says:
+
+```
+The crew keeps its working files in .worktrees/ (task worktrees, merge lock).
+These should never be committed to git.
+
+I'll add one line to your .gitignore:
+
+  + .worktrees/
+
+OK to apply? (yes/no)
+```
+
+**If user says yes:** Launch `crew-init` with `gitignoreConsent: true`. The scaffold phase appends the entry.
+
+**If user says no:**
+```
+Got it — I'll leave your .gitignore alone. Add this line yourself when you get a chance:
+  .worktrees/
+The crew will still work (it excludes .worktrees/ from its own git operations),
+but you'll see it as untracked until you do.
+```
+Launch `crew-init` with `gitignoreConsent: false`.
+
+**`crew-init.js` inputs:**
+- `gitignoreConsent` (boolean, default false): Whether the user approved `.gitignore` modification.
+
+**Edge cases:**
+- **No `.gitignore` exists:** Create it with the entry (if consent given).
+- **Entry already present:** Skip (idempotent).
+- **Non-interactive / not provided:** Default false (fail closed).
+
+### 2. `.orchestration/user/` structure (FUTURE)
+
+When `$REPO/.orchestration/` is implemented (project-specific custom workflows, identities, phases), it will follow this structure:
+
+```
+$REPO/.orchestration/
+  workflows/       # versioned — custom workflow definitions
+  identities/      # versioned — custom identity definitions
+  phases/          # versioned — custom phase definitions
+  user/            # GITIGNORED — personal settings, local config, secrets
+```
+
+The gitignore consent flow will be extended to include `.orchestration/user/` at that time. The standing rule (crew modifies only `.gitignore`, with consent) already covers this.
+
+### 3. Worktrees relocation (deferred)
+
+**Decision:** For this release, `.worktrees/` stays in `$REPO/.worktrees/` but is covered by the gitignore consent flow (add `.worktrees/` to `.gitignore` alongside `.orchestration/user/`).
+
+**Rationale:** Relocating to `$CREW_HOME/worktrees/` is the cleaner long-term solution (eliminates the entire class of bug), but it's a larger change affecting `worktree-lifecycle.sh`, `merge-lock.sh`, and all workflow `WORKTREE_HINT` constants. The gitignore approach solves the immediate leak with minimal risk. Relocation is tracked as future work.
+
+**Gitignore entries added (with consent):**
+```
+.orchestration/user/
+.worktrees/
+```
+
+### 4. Migration
+
+Existing setups (e.g., Room #12) have `$REPO/.worktrees/` without gitignore coverage. On the next `crew-init` re-run (or manual upgrade), the consent flow will offer to add the entries. No automatic migration — the user must consent.
+
+## Standing Rule
+
+If the crew ever needs to modify another user file outside `.orchestration/`, it goes through the same flow: heads-up, diff, Enter/skip. The `.gitignore` is currently the only such file.
+
+## Test Plan
+
+1. `crew-init` on a repo without `.gitignore` → creates file, adds entries, user confirms
+2. `crew-init` on a repo with existing `.gitignore` → appends entries, shows diff
+3. `crew-init` with entries already present → no-op, no prompt
+4. User types 'skip' → setup continues, warning logged
+5. Non-interactive → no modification, instruction logged
+6. Full suite passes
+
+## Release
+
+Version 0.9.2 (includes the `.merge-lock` exclusion fix from d3e5790).

package/lib/test-worktree-backend.sh

@@ -210,6 +210,35 @@ git -C "$T4/repo" branch -D "task/deadbeef" "task/deadbeef-1111" >/dev/null
 out=$(bash "$LIFECYCLE" resolve-branch "$fullid") || fail "prefix-test: resolve-branch failed with no branch present"
 [ "$out" = "task/$fullid" ] || fail "prefix-test: resolve-branch returned '$out', expected canonical fallback task/$fullid"
 
+# post-deploy never commits the crew's .worktrees/ state into main
+# (2026-09-17, Gate 1 J1 canary): cmd_post_deploy's `git add -A` swept up
+# a leftover .worktrees/.merge-lock into main. The add must exclude the
+# crew-owned .worktrees/ dir.
+T5=/tmp/crew-git-postdeploy-test
+rm -rf "$T5"
+mkdir -p "$T5"
+git init -q -b main "$T5"
+git -C "$T5" config user.email test@test.t
+git -C "$T5" config user.name test
+echo base > "$T5/f.txt"
+git -C "$T5" add -A
+git -C "$T5" commit -qm base
+export CREW_REPO="$T5"
+export CREW_LIB="$REPO_DIR/lib"
+out=$(bash "$LIFECYCLE" prepare "pd1") || fail "postdeploy-test: prepare failed: $out"
+# Simulate the merge-lock left behind by a real integrate flow
+printf 'task_id=pd1\nholder=test\n' > "$T5/.worktrees/.merge-lock"
+# A genuine user change the post-deploy commit should pick up
+echo userchange > "$T5/user.txt"
+out=$(bash "$LIFECYCLE" post-deploy "pd1") || fail "postdeploy-test: post-deploy failed: $out"
+# The user change must be committed...
+git -C "$T5" log --name-only --format= -1 | grep -q '^user\.txt$' || fail "postdeploy-test: user change not committed"
+# ...but the crew's merge-lock must NOT be in main's history
+if git -C "$T5" log --name-only --format= | grep -q '^\.worktrees/'; then
+  fail "postdeploy-test: .worktrees/ content committed into main"
+fi
+rm -rf "$T5"
+
 rm -rf "$T2" "$T3" "$T4"
 export CREW_REPO="$T"
 rm -rf "$T"

package/lib/worktree-lifecycle.sh

@@ -414,8 +414,11 @@ cmd_post_deploy() {
   cd "$REPO"
   git checkout main 2>/dev/null
 
-  # Commit any changes the artifact builder left behind
-  git add -A
+  # Commit any changes the artifact builder left behind.
+  # The crew's own .worktrees/ dir (merge lock, registry) is crew-owned
+  # state, never user content — exclude it so a stray lock file can never
+  # be committed into main (J1 canary: .merge-lock landed in main via add -A).
+  git add -A -- ':!.worktrees/'
   if ! git diff --cached --quiet 2>/dev/null; then
     git commit -m "rebuild: $task_id"
     echo "COMMITTED: artifact builder changes"

package/package.json

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

package/workflows/crew-init.js

@@ -20,6 +20,13 @@ const dashboardName = inputs.dashboardName || "Muse Crew";
 const crewName = inputs.crewName || null;
 const cronIds = inputs.cronIds || {};
 
+// ── Gitignore consent input ─────────────────────────────────────────
+// Set by the setup conversation before launch. If true, the scaffold phase
+// appends crew-owned paths (.orchestration/user/, .worktrees/) to the repo's
+// .gitignore. Defaults to false (fail closed) — the user must explicitly
+// approve modifying their .gitignore during the setup conversation.
+const gitignoreConsent = inputs.gitignoreConsent === true;
+
 // ── Automatic-update policy inputs ──────────────────────────────────
 // All optional. autoUpdateCrew/autoUpdateDashboard default to true (the
 // update watcher files upgrade tasks through the loop); updateChannel
@@ -330,6 +337,50 @@ var scaffoldCreated = scaffoldResult.created ? scaffoldResult.created.length : 0
 var scaffoldSkipped = scaffoldResult.skipped ? scaffoldResult.skipped.length : 0;
 log("Scaffold: " + scaffoldCreated + " created, " + scaffoldSkipped + " skipped");
 
+// ── Gitignore consent execution ─────────────────────────────────────
+// If the user approved during the setup conversation (gitignoreConsent=true)
+// and we have a repo (dashboard mode), append crew-owned paths to .gitignore.
+// This is the ONLY user file outside .orchestration/ that the crew modifies.
+if (gitignoreConsent && dashboardRepoPath) {
+  var gitignoreResult;
+  try {
+    gitignoreResult = await agent(
+      "Update the .gitignore file in the repository to exclude crew-owned paths.\n\n" +
+      "Repository: " + dashboardRepoPath + "\n\n" +
+      "Steps:\n" +
+      "1. Check if " + dashboardRepoPath + "/.gitignore exists.\n" +
+      "2. Ensure this entry is present (one per line):\n" +
+      "   .worktrees/\n" +
+      "3. If the file doesn't exist, create it with that line.\n" +
+      "4. If it exists, append the entry if missing (do not duplicate).\n" +
+      "5. Report what was done.\n\n" +
+      "Return JSON with: { created: boolean (true if file was created), appended: array of entries that were added, skipped: array of entries already present }.",
+      {
+        key: "scaffold-gitignore",
+        label: "Update .gitignore for crew paths",
+        schema: {
+          type: "object",
+          properties: {
+            created: { type: "boolean" },
+            appended: { type: "array", items: { type: "string" } },
+            skipped: { type: "array", items: { type: "string" } }
+          },
+          required: ["created", "appended", "skipped"]
+        }
+      }
+    );
+    log("Gitignore: " + (gitignoreResult.created ? "created" : "updated") +
+        " — appended [" + (gitignoreResult.appended || []).join(", ") + "]" +
+        ", already present [" + (gitignoreResult.skipped || []).join(", ") + "]");
+  } catch (e) {
+    log("Gitignore update failed (non-fatal): " + String(e.message || e));
+  }
+} else if (dashboardRepoPath) {
+  log("Gitignore: user declined — add '.worktrees/' to " + dashboardRepoPath + "/.gitignore manually.");
+} else {
+  log("Gitignore: no repo (CLI-only mode) — skipping.");
+}
+
 // ── Phase 3: Project registration ─────────────────────────────────────
 // Registers the first project in crew-state.db via the Crew API. In
 // dashboard mode, the dashboard becomes the crew's first project (so the