muse-crew 0.10.1 → 0.11.1

package/docs/guide.md

@@ -170,9 +170,34 @@ The project must have:
 - 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).
 - Any special file structure — the crew works with whatever the repo contains.
-- Workflow files — those live in the crew home's release, not in the project.
+
+### The repo-local `.orchestration/` scaffold
+
+After registration, each project gets a repository-local `.orchestration/` directory alongside the crew-home one:
+
+```
+<repo>/.orchestration/
+  workflows/   # project-specific workflow docs (version-controlled)
+  identities/  # project-specific identity files (version-controlled)
+  phases/      # project-specific phase docs (version-controlled)
+  user/        # local-only config, ignored by Git
+```
+
+The scaffold seeds `workflows/`, `identities/`, and `phases/` from the platform defaults with no-clobber semantics — existing project files are never overwritten, so customizations survive re-runs. `user/` is for local-only config (preferences, scratch notes) and is added to `.gitignore` by the consent step below.
+
+State boundaries:
+- Version-controlled config (what the crew *should be*): `workflows/`, `identities/`, `phases/` — committed with the repo.
+- Local-only config (who is asking): `user/` — never committed.
+- Working state (what the crew *is doing*): `<repo>/.worktrees/` — ephemeral, ignored by Git.
+
+### The `.gitignore` conversation
+
+The crew asks before touching anything in your repo. When you register a project, setup shows you the exact `.gitignore` lines it wants to add — `.worktrees/` and `.orchestration/user/` — and asks for explicit consent. Say yes and the lines are appended (a missing `.gitignore` is created; existing content is never modified); say no and setup continues without them. Declining never blocks the crew — it only means worktree dirs and local config won't be ignored automatically.
+
+### The sample project
+
+If you don't have a project in mind, the crew can set up a sample: a tiny flashcard study tool that ships inside the npm package. It's extracted into a directory you choose, initialized as a fresh Git repo with an initial commit (no remote needed), and registered like any other project. Explicitly declining the sample leaves you with zero projects — a supported state; the crew idles until you register one.
 
 ### Worktrees
 

package/docs/state-boundary-spec.md

@@ -0,0 +1,184 @@
+# State-Boundary Spec: Repository-local `.orchestration/`
+
+**Status:** Approved by Eric 2026-09-17 ("Yes spec it and build it. Publish it.")
+**Scope:** 8 gaps from the 0.10.x gitignore work
+
+## 1. Repository-local `.orchestration/`
+
+When a project is registered with a repo path (dashboard mode init, or
+`create-project` via CLI/dashboard), scaffold `$REPO/.orchestration/`:
+
+```
+$REPO/.orchestration/
+  workflows/    # version-controlled — project workflow docs, seeded from platform defaults
+  identities/  # version-controlled — project crew identities, seeded from platform defaults
+  phases/       # version-controlled — project phase definitions, seeded from platform defaults
+  user/         # IGNORED — personal/local configuration, never committed
+```
+
+This is distinct from `$CREW_HOME/.orchestration/` (the crew instance's own
+config, already scaffolded by crew-init Phase 2).
+
+**Seeding:** Copy from the crew repo's canonical sources with `--no-clobber`
+semantics (never overwrite existing project customizations):
+- `workflows/` ← `$CREW_REPO/seed/workflows/*.md`
+- `identities/` ← `$CREW_REPO/identities/*.md` (and portraits)
+- `phases/` ← `$CREW_REPO/seed/phases/*.md` (if exists; else skip)
+
+**Idempotency:** Re-running scaffold on an existing `$REPO/.orchestration/`
+must not modify existing files.
+
+## 2. `.orchestration/user/`
+
+- Created by the scaffold (empty, with a `.gitkeep` or README explaining
+  it's for local config).
+- MUST be listed in the repo's `.gitignore` as `.orchestration/user/`.
+- The crew never commits this directory. User preferences/configuration
+  live here, never in version control.
+
+## 3. Deterministic `.gitignore` management
+
+Replace the current agent-driven `.gitignore` mutation (crew-init.js lines
+344-379, which prompts an agent to edit the file) with deterministic JS.
+
+**Function:** `ensureGitignoreEntries(repoPath, entries)` in a new
+`lib/gitignore.js` (pure, testable, no agent calls).
+
+**Contract:**
+- `entries`: array of gitignore patterns, e.g. `[".worktrees/", ".orchestration/user/"]`
+- If `$REPO/.gitignore` does not exist: create it containing the entries,
+  one per line, trailing newline. Return `{ created: true, appended: entries, skipped: [] }`.
+- If it exists: read lines, append each missing entry (exact line match;
+  no duplicates). Preserve existing content byte-for-byte (including
+  trailing newline handling). Return `{ created: false, appended: [...], skipped: [...] }`.
+- Idempotent: second call with same entries returns `appended: []`.
+- Never removes or reorders existing lines.
+
+**Crew-owned entries** (the complete set):
+- `.worktrees/`
+- `.orchestration/user/`
+
+## 4. Consent flow
+
+The `.gitignore` modification requires explicit user approval. This is the
+ONLY user-owned file outside `.orchestration/` that the crew touches.
+
+**Setup conversation (before crew-init launches):**
+1. Explain WHY: "The crew needs to ignore its working directories
+   (`.worktrees/` for isolated task workspaces, `.orchestration/user/`
+   for your local config) so they don't pollute your git status."
+2. Show the EXACT diff: what lines will be added to which file.
+   - New file: show full proposed content.
+   - Existing file: show the lines to be appended.
+3. Offer two choices:
+   - Approve (Enter / "yes") → pass `gitignoreConsent: true`
+   - "I'll handle it" (decline) → pass `gitignoreConsent: false`;
+     setup continues; the user is told exactly what to add manually.
+
+**Rules:**
+- Declining MUST NOT block setup.
+- Non-interactive (no TTY / `--non-interactive`): default to `false`
+  (fail closed — never modify a user's file without consent).
+- The consent decision is recorded in the init summary output.
+
+**Dashboard path:** The dashboard onboarding flow must present the same
+consent UI before launching crew-init.
+
+**CLI path:** The CLI setup conversation (or `crew-init` wrapper) must
+present the same consent prompt. `create-project` on an existing repo
+must also offer the `.orchestration/` scaffold + gitignore consent.
+
+## 5. Sample-project setup
+
+Optional; never forced.
+
+**Flow:**
+1. Setup asks: "Do you have a git project in mind? [yes/no]"
+2. If no → offer: "Want me to set up the sample flashcards project so
+   you can try the crew? [yes/no]"
+3. If yes to sample:
+   a. Extract `seed/sample-project.tar.gz` from the installed package
+      to the chosen location (default: `~/workspace/<name>/`).
+   b. `git init`, initial commit.
+   c. Register via the existing `create-project` action (no new endpoint).
+4. If no to sample: setup completes with zero projects. This is a
+   supported state. The user is told how to add a project later
+   (`create-project` via CLI or dashboard).
+
+**Rules:**
+- No sample-specific API endpoint. Compose existing actions.
+- No remote required. Workflows must not treat a missing remote as a defect.
+- The sample's `.gitignore` (ships in the tarball) is preserved; the
+  crew appends its entries per the consent flow.
+
+## 6. Behavioral tests
+
+New `tests/gitignore.test.js` and `tests/repo-orchestration.test.js`:
+
+**gitignore:**
+- Missing file → created with entries
+- Existing file, missing entries → appended, no duplicates
+- Existing file, entries present → no-op (idempotent)
+- Existing file with entries in different order → no-op
+- Entries that are substrings of existing lines are still added
+  (exact line match, not substring)
+- Trailing newline preserved/added correctly
+
+**consent:**
+- Decline → setup completes, `.gitignore` untouched
+- Non-interactive → defaults to decline, `.gitignore` untouched
+- Accept → entries added
+
+**repo-orchestration:**
+- Scaffold creates all four subdirs
+- `user/` is created
+- Re-run does not overwrite customizations
+- Seed sources are copied correctly
+
+## 7. What this does NOT do
+
+- Does not move `.worktrees/` (still repo-local; relocation deferred,
+  no approval to change).
+- Does not add new API endpoints.
+- Does not change Room #12 or any existing crew's behavior.
+
+## 8. Setup commits its scaffold (0.11.1)
+
+**Defect (room #13, 2026-09-17):** 0.11.0's setup wrote `.orchestration/`
+(and the consented `.gitignore` update) but never committed them. The
+first task's Integrate then refused to merge onto the dirty main — twice,
+deterministically. An uncommitted scaffold deterministically breaks the
+first task after setup.
+
+**Contract:** setup leaves the repo's main checkout clean. After the
+scaffold + `.gitignore` steps, `lib/commit-scaffold.js` commits exactly
+the crew's paths (`.orchestration/`, plus `.gitignore` when the setup step
+changed it under consent). The commit message names what was staged,
+computed from the index.
+
+**Rules:**
+- Only the crew's paths are ever staged. The user's unrelated changes
+  (tracked modifications, untracked files) are never swept in.
+- Idempotent: nothing new staged → no commit, `{ committed: false,
+  reason: "nothing-to-commit" }`. Never an empty commit.
+- Missing `.orchestration/` → throw (the scaffold step did not run).
+- Commit failures (e.g. no git identity) throw loudly with git's stderr.
+  No identity is ever invented — the commit belongs to the user; the
+  caller configures identity and re-runs.
+- With `--consent`, `.gitignore` must be clean before setup touches it:
+  a pre-existing dirty `.gitignore` fails setup loudly (refuse — never
+  sweep the user's edits into the setup commit). `.orchestration/` is
+  crew-owned: pre-existing uncommitted content there is committed, not
+  refused (this also repairs 0.11.0 rooms).
+- `lib/setup-project-repo.js` (the composer) runs all three steps and
+  exits non-zero on any failure. crew-init's dashboard mode calls the
+  composer (one agent call, replacing the old two-call shape); a failed
+  commit is logged loudly and surfaced as `repoSetupWarning` in the init
+  summary, since the first task will fail Integrate until the scaffold
+  is committed.
+
+**Tests:** `tests/commit-scaffold.test.js` (behavioral: clean tree after
+setup, accurate message, idempotency, non-repo no-op, missing scaffold
+throws, missing identity throws, composer refusal on dirty `.gitignore`,
+declined consent leaves `.gitignore` untouched; structural: crew-init
+calls the composer).

package/lib/AGENTS.md

@@ -27,3 +27,8 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `build-readback-request.js` — builds the LLM-inspector read-back `verbatim_request` from the merge commit's diff (2026-09-14): carries the merged diff as the expected change and asks for an independent read of the artifact's actual source. Retained as the manual fallback; the deterministic `readback-disk.js` is the primary sensor.
 - `verify-publish.js` — mechanical publish verification judge (2026-09-14/16): certifies the read-back findings block against `git diff` (strict `FILE:`/`ADDED:`/`REMOVED:`/`END_FILE` parsing, every added line PRESENT / every removed line ABSENT, HEAD==commit supersession check) and only then stamps provenance. Binary files, mode-only changes, and fully-colliding added hunks fail closed as `unverifiable-content` (2026-09-16, critic findings 1/5) — they can never vacuously stamp. Content-mismatch, unreadable-result, superseded, and stamp failures exit 1 with `publish: verification-failed` and no stamp. Collision exemption (2026-09-15): a removed line occurring in the old tree strictly more times than the diff removes is exempt from ABSENT (zero discriminating power); computed from `git show <base>:<path>`, never the working tree.
 - `update-watch.js` — deterministic automatic update watcher (2026-09-16, zero deps): `node update-watch.js --crew-home <path>` (missing arg → usage, exit 2; every other path exits 0). Watches the public npm registry (`npm view muse-crew version` pinned to `https://registry.npmjs.org/`) vs `crew-release.sh current` and files a `workflow: "upgrade"` task with `source: npm@<version>` when policy (`auto_update_crew`, `update_channel`) and channel gating allow; watches `git ls-remote origin HEAD` on the first `deploy_type=artifact` project vs `$CREW_HOME/.update-watch.json` and files a `workflow: "chore"` task carrying the mechanical dashboard-upgrade journey. Reads the `.crew-version` compatibility anchor at the new ref via `git fetch` + `git show <sha>:.crew-version` (never the working tree) and orders dashboard-led: a declared newer crew files the crew upgrade task FIRST and the dashboard task notes it follows the crew upgrade (declaration bypasses `update_channel`, not the `auto_update_crew=false` opt-out); a declared older crew skips the dashboard leg entirely as a human decision; a missing/invalid/unfetchable anchor fails open to the dashboard leg as today. Idempotency via the same state file (records at file time); check failures log to `$CREW_HOME/update-watch.log` and are never thrown. Safety: only files tasks — never deploys, never touches the artifact/config/scheduler. Run by the daily `crew-update-watch` cron through the `current` symlink (latest release); deliberately NOT in the lib-pinning `PIN_BASENAMES`.
+- `gitignore.js` — deterministic .gitignore management for crew-owned paths (2026-09-17): the crew touches exactly one user-owned file outside `.orchestration/` — the repo's `.gitignore`. `ensureGitignoreEntries(repoPath, entries)` creates the file when missing, appends missing entries (exact line match, no duplicates), preserves existing content byte-for-byte, and is idempotent. `describeGitignoreChange(repoPath, entries)` renders the exact diff for the setup consent conversation. Crew-owned entries: `.worktrees/`, `.orchestration/user/`. CLI: `--repo <path> [--dry-run]`.
+- `repo-orchestration.js` — repository-local `.orchestration/` scaffold (2026-09-17): `scaffoldRepoOrchestration(repoPath, crewRepoPath)` creates `$REPO/.orchestration/{workflows,identities,phases,user}/`, seeds workflows/identities/phases from the crew repo's platform defaults with no-clobber semantics (existing project customizations never overwritten), and writes a README in `user/` explaining it's for local config. Idempotent. CLI: `--repo <path> --crew-repo <path>`.
+- `setup-project-repo.js` — repo-local setup composer for a registered project (2026-09-17, setup-commit 2026-09-18): runs the `.orchestration/` scaffold plus the `.gitignore` update (only with explicit `--consent`), then COMMITS both via `commit-scaffold.js` so the repo's main checkout is clean when setup finishes (room #13: an uncommitted scaffold deterministically broke the first task's Integrate). Refuses loudly when `.gitignore` has pre-existing uncommitted changes (never sweeps the user's edits into the setup commit); `.orchestration/` is crew-owned so pre-existing content there is committed, not refused. The CLI-path equivalent of crew-init's dashboard-mode repo setup; the dashboard calls the same script. No new API endpoint — composition of existing deterministic modules. CLI: `--repo <path> --crew-repo <path> [--consent]`; prints `{ orchestration, gitignore, commit }`, exits non-zero on any failure.
+- `commit-scaffold.js` — deterministic setup-scaffold commit (2026-09-18): stages only `.orchestration/` (+ `.gitignore` with `--gitignore`) and commits with a message naming exactly what was staged. Idempotent (`nothing-to-commit`, never an empty commit); not-a-git-repo is a clean no-op; missing `.orchestration/` and commit failures (e.g. no git identity) throw loudly — the commit belongs to the user, so no identity is ever invented here. Exports `isPathDirty` (porcelain check for one path) for the composer's pre-mutation guard. CLI: `--repo <path> [--gitignore]`.
+- `sample-project.js` — optional sample-project setup (2026-09-17): extracts `seed/sample-project.tar.gz` (stripping the `sample-project/` prefix), `git init`, initial commit. No remote required. Registration happens via the existing `create-project` action — no sample-specific endpoint. CLI: `--tarball <path> --dest <dir> --name <project-name>`.

package/lib/commit-scaffold.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// lib/commit-scaffold.js — commit the crew's setup scaffold files.
+//
+// After project setup writes $REPO/.orchestration/ (and, with the user's
+// consent, updates .gitignore), this module commits exactly those paths so
+// the repo's main checkout is clean when setup finishes.
+//
+// Why this exists (room #13, 2026-09-17): 0.11.0's setup wrote the scaffold
+// but never committed it. The first task's Integrate then refused to merge
+// onto the dirty main — twice in a row, deterministically. An uncommitted
+// scaffold deterministically breaks the first task after setup. Setup must
+// leave main clean; this is the mechanical half of that contract.
+//
+// Contract:
+//   - Only ever stages `.orchestration/` and (with --gitignore) `.gitignore`.
+//     The user's unrelated changes are never swept into the setup commit.
+//   - Idempotent: nothing new staged → { committed: false, reason:
+//     "nothing-to-commit" }; never creates an empty commit.
+//   - Not a git repo → { committed: false, reason: "not-a-git-repo" }.
+//     There is no main to keep clean, so there is nothing to do.
+//   - Missing `.orchestration/` → throws. The scaffold step did not run;
+//     fail loudly, never silently skip.
+//   - Commit failures (e.g. no git identity configured) throw with git's
+//     stderr. The caller configures identity and re-runs; never invent an
+//     identity here — the commit belongs to the user, not the crew.
+//   - The commit message names exactly what was staged (computed from the
+//     index, not from flags).
+//
+// Usage:
+//   node lib/commit-scaffold.js --repo <path> [--gitignore]
+//     --gitignore: the setup step modified .gitignore (consent was given);
+//                  include it in the commit.
+// Prints JSON: { committed, sha, reason }
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+function git(repoPath, args, env) {
+  try {
+    // No .trim(): callers that parse fixed-width output (porcelain) need
+    // the raw lines; scalar callers trim themselves.
+    return execFileSync("git", args, {
+      cwd: repoPath,
+      encoding: "utf8",
+      env: env || process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+    const stderr = e.stderr ? String(e.stderr).trim() : "";
+    throw new Error("git " + args.join(" ") + " failed: " + (stderr || e.message));
+  }
+}
+
+// Porcelain status lines touching exactly relPath (e.g. ".gitignore").
+// Used by the composer as a pre-mutation guard; exported for tests.
+function isPathDirty(repoPath, relPath) {
+  const out = git(repoPath, ["status", "--porcelain", "--", relPath]);
+  return out.split("\n").some(function (line) {
+    if (line.length < 4) return false;
+    const p = line.slice(3).replace(/^"|"$/g, "");
+    return p === relPath;
+  });
+}
+
+function commitScaffold(repoPath, opts) {
+  opts = opts || {};
+  const includeGitignore = opts.includeGitignore === true;
+
+  if (!fs.existsSync(path.join(repoPath, ".git"))) {
+    return { committed: false, sha: null, reason: "not-a-git-repo" };
+  }
+  if (!fs.existsSync(path.join(repoPath, ".orchestration"))) {
+    throw new Error(
+      "no .orchestration/ scaffold found in " + repoPath + " — run the scaffold step before committing"
+    );
+  }
+
+  const paths = [".orchestration"];
+  if (includeGitignore) paths.push(".gitignore");
+  git(repoPath, ["add", "--"].concat(paths));
+
+  const staged = git(repoPath, ["diff", "--cached", "--name-only"]).trim();
+  if (!staged) {
+    return { committed: false, sha: null, reason: "nothing-to-commit" };
+  }
+
+  const stagedFiles = staged.split("\n");
+  const subject = stagedFiles.indexOf(".gitignore") !== -1
+    ? "Muse Crew setup: commit .orchestration scaffold and crew .gitignore entries"
+    : "Muse Crew setup: commit .orchestration scaffold";
+  const body =
+    "Setup leaves the repo's main checkout clean: these are the crew-owned\n" +
+    "files written during project setup. Integrate refuses to merge onto a\n" +
+    "dirty main, so they are committed here instead of left uncommitted.";
+  git(repoPath, ["commit", "-m", subject, "-m", body, "--quiet"]);
+  const sha = git(repoPath, ["rev-parse", "HEAD"]).trim();
+
+  return { committed: true, sha: sha, reason: null };
+}
+
+module.exports = { commitScaffold, isPathDirty };
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const get = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : null;
+  };
+  const repoPath = get("--repo");
+  if (!repoPath) {
+    console.error("Usage: node lib/commit-scaffold.js --repo <path> [--gitignore]");
+    process.exit(2);
+  }
+  try {
+    console.log(JSON.stringify(commitScaffold(repoPath, { includeGitignore: argv.includes("--gitignore") })));
+  } catch (e) {
+    console.error("commit-scaffold failed: " + (e.message || e));
+    process.exit(1);
+  }
+}

package/lib/gitignore.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// lib/gitignore.js — deterministic .gitignore management for crew-owned paths.
+//
+// The crew touches exactly one user-owned file outside .orchestration/:
+// the repo's .gitignore. This module does it deterministically — no agent
+// judgment, no prose parsing. Pure functions, fully testable.
+//
+// Crew-owned entries:
+//   .worktrees/            — isolated task workspaces
+//   .orchestration/user/   — personal/local configuration, never committed
+//
+// Contract of ensureGitignoreEntries(repoPath, entries):
+//   - Missing .gitignore → create it with entries, one per line.
+//   - Existing .gitignore → append each missing entry (exact line match).
+//   - Idempotent: second call with same entries is a no-op.
+//   - Never removes, reorders, or reformats existing content.
+//   - Returns { created, appended[], skipped[] }.
+
+const fs = require("fs");
+const path = require("path");
+
+const CREW_GITIGNORE_ENTRIES = [".worktrees/", ".orchestration/user/"];
+
+function gitignorePath(repoPath) {
+  return path.join(repoPath, ".gitignore");
+}
+
+// Normalize a line for comparison: trim trailing whitespace and \r.
+// Leading whitespace is significant in gitignore (it isn't, actually —
+// gitignore strips leading/trailing whitespace unless escaped — but we
+// treat lines literally to avoid merging distinct user intent).
+function normLine(line) {
+  return line.replace(/\r$/, "").replace(/[ \t]+$/, "");
+}
+
+function ensureGitignoreEntries(repoPath, entries) {
+  const file = gitignorePath(repoPath);
+  const wanted = entries || CREW_GITIGNORE_ENTRIES;
+
+  let existing = null;
+  try {
+    existing = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+
+  // Missing file → create.
+  if (existing === null) {
+    const content = wanted.join("\n") + "\n";
+    fs.writeFileSync(file, content, "utf8");
+    return { created: true, appended: wanted.slice(), skipped: [] };
+  }
+
+  // Existing file → append missing entries only.
+  const lines = existing.split("\n").map(normLine);
+  // Drop the phantom last element from a trailing newline so it doesn't
+  // count as content, but remember whether the file ended with one.
+  const endsWithNewline = existing.endsWith("\n");
+  const contentLines = endsWithNewline ? lines.slice(0, -1) : lines;
+  const present = new Set(contentLines);
+
+  const appended = [];
+  const skipped = [];
+  for (const entry of wanted) {
+    if (present.has(entry)) {
+      skipped.push(entry);
+    } else {
+      appended.push(entry);
+      present.add(entry); // dedupe within `wanted` itself
+    }
+  }
+
+  if (appended.length === 0) {
+    return { created: false, appended: [], skipped };
+  }
+
+  // Preserve existing bytes; ensure exactly one newline before appending.
+  let out = existing;
+  if (!out.endsWith("\n")) out += "\n";
+  out += appended.join("\n") + "\n";
+  fs.writeFileSync(file, out, "utf8");
+  return { created: false, appended, skipped };
+}
+
+// Render the exact diff the setup conversation shows the user for consent.
+// Returns a human-readable description of what would change.
+function describeGitignoreChange(repoPath, entries) {
+  const file = gitignorePath(repoPath);
+  const wanted = entries || CREW_GITIGNORE_ENTRIES;
+
+  let existing = null;
+  try {
+    existing = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+
+  if (existing === null) {
+    return {
+      file,
+      mode: "create",
+      diff: wanted.map((e) => "+ " + e).join("\n"),
+      lines: wanted.slice(),
+    };
+  }
+
+  const lines = existing.split("\n").map(normLine);
+  const endsWithNewline = existing.endsWith("\n");
+  const contentLines = endsWithNewline ? lines.slice(0, -1) : lines;
+  const present = new Set(contentLines);
+  const missing = wanted.filter((e) => !present.has(e));
+
+  return {
+    file,
+    mode: missing.length === 0 ? "noop" : "append",
+    diff: missing.map((e) => "+ " + e).join("\n"),
+    lines: missing,
+  };
+}
+
+module.exports = {
+  CREW_GITIGNORE_ENTRIES,
+  ensureGitignoreEntries,
+  describeGitignoreChange,
+};
+
+// CLI: node lib/gitignore.js --repo <path> [--dry-run]
+// Used by crew-init and by tests. --dry-run prints the diff without writing.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const repoIdx = argv.indexOf("--repo");
+  const repoPath = repoIdx >= 0 ? argv[repoIdx + 1] : null;
+  const dryRun = argv.includes("--dry-run");
+  if (!repoPath) {
+    console.error("Usage: node lib/gitignore.js --repo <path> [--dry-run]");
+    process.exit(2);
+  }
+  if (dryRun) {
+    const d = describeGitignoreChange(repoPath);
+    console.log("File: " + d.file);
+    console.log("Mode: " + d.mode);
+    if (d.diff) console.log(d.diff);
+  } else {
+    const r = ensureGitignoreEntries(repoPath);
+    console.log(JSON.stringify(r));
+  }
+}

package/lib/repo-orchestration.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// lib/repo-orchestration.js — scaffold repository-local .orchestration/ state.
+//
+// When a project is registered with a repo path, the crew scaffolds
+// $REPO/.orchestration/ with version-controlled project configuration
+// and an ignored user/ directory for personal/local config:
+//
+//   $REPO/.orchestration/
+//     workflows/    # version-controlled — seeded from $CREW_REPO/seed/workflows/
+//     identities/   # version-controlled — seeded from $CREW_REPO/identities/
+//     phases/       # version-controlled — seeded from $CREW_REPO/seed/phases/ (if exists)
+//     user/         # IGNORED — local config, must be in .gitignore
+//
+// Seeding uses no-clobber semantics: existing project customizations are
+// never overwritten. Idempotent: re-running is a no-op.
+
+const fs = require("fs");
+const path = require("path");
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+    return true;
+  }
+  return false;
+}
+
+// Copy files from srcDir to destDir, skipping existing files (no-clobber).
+// Returns { created: [relative paths], skipped: [relative paths] }.
+function seedDir(srcDir, destDir, patterns) {
+  const created = [];
+  const skipped = [];
+  if (!fs.existsSync(srcDir)) return { created, skipped };
+
+  ensureDir(destDir);
+  const files = fs.readdirSync(srcDir);
+  for (const file of files) {
+    if (patterns && !patterns.some((p) => file.endsWith(p))) continue;
+    const src = path.join(srcDir, file);
+    const dest = path.join(destDir, file);
+    if (fs.statSync(src).isDirectory()) continue;
+    if (fs.existsSync(dest)) {
+      skipped.push(file);
+    } else {
+      fs.copyFileSync(src, dest);
+      created.push(file);
+    }
+  }
+  return { created, skipped };
+}
+
+function scaffoldRepoOrchestration(repoPath, crewRepoPath) {
+  const orchDir = path.join(repoPath, ".orchestration");
+  const result = {
+    orchDir,
+    dirsCreated: [],
+    workflows: { created: [], skipped: [] },
+    identities: { created: [], skipped: [] },
+    phases: { created: [], skipped: [] },
+    userDir: false,
+  };
+
+  // Create the four subdirectories.
+  for (const sub of ["workflows", "identities", "phases", "user"]) {
+    if (ensureDir(path.join(orchDir, sub))) {
+      result.dirsCreated.push(sub);
+    }
+  }
+  result.userDir = true;
+
+  // Seed workflows from platform defaults (markdown docs, not JS).
+  result.workflows = seedDir(
+    path.join(crewRepoPath, "seed", "workflows"),
+    path.join(orchDir, "workflows"),
+    [".md"]
+  );
+
+  // Seed identities (markdown + portraits).
+  result.identities = seedDir(
+    path.join(crewRepoPath, "identities"),
+    path.join(orchDir, "identities"),
+    [".md", ".png"]
+  );
+
+  // Seed phases (if the crew repo has them).
+  result.phases = seedDir(
+    path.join(crewRepoPath, "seed", "phases"),
+    path.join(orchDir, "phases"),
+    [".md"]
+  );
+
+  // Ensure user/ has a README explaining it's for local config.
+  const userReadme = path.join(orchDir, "user", "README.md");
+  if (!fs.existsSync(userReadme)) {
+    fs.writeFileSync(
+      userReadme,
+      "# .orchestration/user/\n\n" +
+        "Personal and local configuration for this project. " +
+        "This directory is ignored by git (see .gitignore) and never committed.\n\n" +
+        "Put your local overrides, preferences, and machine-specific settings here.\n",
+      "utf8"
+    );
+    result.userDir = "created-with-readme";
+  }
+
+  return result;
+}
+
+module.exports = {
+  scaffoldRepoOrchestration,
+};
+
+// CLI: node lib/repo-orchestration.js --repo <path> --crew-repo <path>
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const repoIdx = argv.indexOf("--repo");
+  const crewRepoIdx = argv.indexOf("--crew-repo");
+  const repoPath = repoIdx >= 0 ? argv[repoIdx + 1] : null;
+  const crewRepoPath = crewRepoIdx >= 0 ? argv[crewRepoIdx + 1] : null;
+  if (!repoPath || !crewRepoPath) {
+    console.error("Usage: node lib/repo-orchestration.js --repo <path> --crew-repo <path>");
+    process.exit(2);
+  }
+  const r = scaffoldRepoOrchestration(repoPath, crewRepoPath);
+  console.log(JSON.stringify(r, null, 2));
+}

package/lib/sample-project.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// lib/sample-project.js — optional sample-project setup.
+//
+// Extracts the bundled flashcards sample (seed/sample-project.tar.gz),
+// git-inits it, and creates the initial commit. Registration happens via
+// the existing create-project action (no sample-specific endpoint).
+//
+// The sample is OPTIONAL — the caller (setup conversation) asks the user
+// first. This script is the mechanical half: extract + git init + commit.
+// Zero projects after an explicit decline is a supported state.
+//
+// Usage: node lib/sample-project.js --tarball <path> --dest <dir> --name <project-name>
+//   --tarball: path to sample-project.tar.gz (from the installed package)
+//   --dest:    parent directory for the new project (project goes to <dest>/<name>)
+//   --name:    directory/project name (e.g. "flashcards")
+// Prints JSON: { path, committed, commitSha }
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+function run(cmd, args, cwd) {
+  return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function setupSampleProject(tarballPath, destParent, name) {
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error("sample tarball not found: " + tarballPath);
+  }
+  const destDir = path.join(destParent, name);
+  if (fs.existsSync(destDir)) {
+    throw new Error("destination already exists: " + destDir + " — refusing to overwrite");
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+
+  // Extract. The tarball wraps files in a sample-project/ prefix —
+  // strip it so the project lands directly in destDir.
+  run("tar", ["-xzf", tarballPath, "-C", destDir, "--strip-components=1"]);
+
+  // Git init + initial commit. No remote required — workflows must not
+  // treat a missing remote as a defect.
+  run("git", ["init"], destDir);
+  run("git", ["add", "-A"], destDir);
+  // Use deterministic identity for the seed commit; the user's identity
+  // takes over for their own commits.
+  const env = Object.assign({}, process.env, {
+    GIT_AUTHOR_NAME: "Muse Crew",
+    GIT_AUTHOR_EMAIL: "crew@localhost",
+    GIT_COMMITTER_NAME: "Muse Crew",
+    GIT_COMMITTER_EMAIL: "crew@localhost",
+  });
+  execFileSync("git", ["commit", "-m", "Initial commit: flashcards sample project", "--quiet"], {
+    cwd: destDir,
+    env,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const sha = run("git", ["rev-parse", "HEAD"], destDir);
+
+  return { path: destDir, committed: true, commitSha: sha };
+}
+
+module.exports = { setupSampleProject };
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const get = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : null;
+  };
+  const tarball = get("--tarball");
+  const dest = get("--dest");
+  const name = get("--name");
+  if (!tarball || !dest || !name) {
+    console.error("Usage: node lib/sample-project.js --tarball <path> --dest <dir> --name <project-name>");
+    process.exit(2);
+  }
+  try {
+    console.log(JSON.stringify(setupSampleProject(tarball, dest, name)));
+  } catch (e) {
+    console.error("sample-project setup failed: " + (e.message || e));
+    process.exit(1);
+  }
+}

package/lib/setup-project-repo.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// lib/setup-project-repo.js — repo-local setup for a registered project.
+//
+// Composes the deterministic building blocks after create-project:
+//   1. Scaffold $REPO/.orchestration/ (workflows/identities/phases versioned, user/ ignored)
+//   2. Optionally update .gitignore (only with explicit --consent)
+//   3. Commit the scaffold (and the .gitignore update when consented) so
+//      the repo's main checkout is clean when setup finishes.
+//
+// Step 3 is the 2026-09-18 fix for the room #13 defect: 0.11.0 wrote the
+// scaffold but never committed it, and the first task's Integrate then
+// refused to merge onto the dirty main — twice, deterministically. Setup
+// must leave main clean; the commit is mechanical, not agent judgment.
+//
+// This is the CLI path equivalent of what crew-init's dashboard mode does.
+// The dashboard calls the same script. No new API endpoint — composition.
+//
+// Guards:
+//   - With --consent, .gitignore must be clean before we touch it. The
+//     commit only ever stages .orchestration/ (+ .gitignore when we changed
+//     it), but a pre-existing dirty .gitignore would be swept into our
+//     commit by `git add` — so refuse loudly instead. Commit or stash it,
+//     then re-run.
+//   - .orchestration/ is crew-owned: pre-existing uncommitted content there
+//     (e.g. left dirty by 0.11.0) is committed, not refused.
+//
+// Usage:
+//   node lib/setup-project-repo.js --repo <path> --crew-repo <path> [--consent]
+//     --consent: user approved the .gitignore change (from the setup conversation)
+// Prints JSON: { orchestration: {...}, gitignore: {...} | { declined: true }, commit: {...} }
+// Exits non-zero on any failure (fail closed, loud).
+
+const fs = require("fs");
+const path = require("path");
+const { scaffoldRepoOrchestration } = require("./repo-orchestration");
+const { ensureGitignoreEntries, describeGitignoreChange } = require("./gitignore");
+const { commitScaffold, isPathDirty } = require("./commit-scaffold");
+
+function main() {
+  const argv = process.argv.slice(2);
+  const get = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : null;
+  };
+  const repoPath = get("--repo");
+  const crewRepoPath = get("--crew-repo");
+  const consent = argv.includes("--consent");
+
+  if (!repoPath || !crewRepoPath) {
+    console.error("Usage: node lib/setup-project-repo.js --repo <path> --crew-repo <path> [--consent]");
+    process.exit(2);
+  }
+
+  try {
+    // Guard: never sweep the user's own .gitignore edits into our commit.
+    if (consent && fs.existsSync(path.join(repoPath, ".git")) && isPathDirty(repoPath, ".gitignore")) {
+      throw new Error(
+        "setup refused: .gitignore has uncommitted changes not made by setup — " +
+          "commit or stash them, then re-run setup"
+      );
+    }
+
+    const orchestration = scaffoldRepoOrchestration(repoPath, crewRepoPath);
+
+    let gitignore;
+    if (consent) {
+      gitignore = ensureGitignoreEntries(repoPath);
+    } else {
+      // Declined (or non-interactive default): report what WOULD change.
+      const preview = describeGitignoreChange(repoPath);
+      gitignore = { declined: true, wouldChange: preview };
+    }
+
+    let commit;
+    try {
+      commit = commitScaffold(repoPath, { includeGitignore: consent });
+    } catch (commitErr) {
+      throw new Error(
+        "commit failed: " +
+          commitErr.message +
+          " — the repo has uncommitted crew files; configure git identity and run: " +
+          "node lib/commit-scaffold.js --repo <path>" +
+          (consent ? " --gitignore" : "")
+      );
+    }
+
+    console.log(JSON.stringify({ orchestration, gitignore, commit }, null, 2));
+  } catch (e) {
+    console.error("setup-project-repo failed: " + (e.message || e));
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { main };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Opinionated orchestration for Muse \u2014 workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,
@@ -29,4 +29,4 @@
   "dependencies": {
     "playwright-core": "1.63.0"
   }
-}
+}

package/workflows/crew-init.js

@@ -337,50 +337,6 @@ 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
@@ -458,6 +414,84 @@ try {
 log("Project: " + dashboardSlug + " " + projectResult.action + " (repo_path=" + gateFacts.dashboardRepoExpanded + ")");
 } // end dashboard-mode project registration
 
+// ── Project repo setup (2026-09-18) ─────────────────────────────────
+// One deterministic composer — lib/setup-project-repo.js — scaffolds
+// $REPO/.orchestration/, applies the consented .gitignore update, and COMMITS
+// both so the repo's main checkout is clean when setup finishes.
+// Room #13 (2026-09-17): the old two-call shape wrote the scaffold but never
+// committed it, and the first task's Integrate then refused to merge onto the
+// dirty main — twice, deterministically. This replaces both calls; the agent
+// still runs one fixed command and all logic stays in the tested lib modules.
+// Best-effort as before (a failed setup never blocks init), but a failed
+// COMMIT is logged loudly: the repo is dirty and the first task will fail
+// Integrate until the scaffold is committed.
+var setupRepoWarning = null;
+var setupRepoResult = null;
+if (dashboardRepoPath) {
+  try {
+    setupRepoResult = await agent(
+      "Run the deterministic project-repo setup composer. Do not decide anything — just run the command and return its JSON output.\n\n" +
+      "Command:\n" +
+      "node " + crewHome + "/current/lib/setup-project-repo.js --repo \"" + gateFacts.dashboardRepoExpanded + "\" --crew-repo \"" + crewRepoPath + "\"" + (gitignoreConsent ? " --consent" : "") + "\n\n" +
+      "The script prints one JSON object: { orchestration, gitignore, commit }.\n" +
+      "orchestration carries orchDir, dirsCreated, and per-area created/skipped arrays;\n" +
+      "gitignore carries created/appended/skipped (or declined:true with a wouldChange preview);\n" +
+      "commit carries { committed, sha, reason }.\n" +
+      "Return that JSON verbatim.",
+      {
+        key: "scaffold-repo-setup",
+        label: "Set up project repo (scaffold + gitignore + commit)",
+        schema: {
+          type: "object",
+          properties: {
+            orchestration: {
+              type: "object",
+              properties: {
+                orchDir: { type: "string" },
+                dirsCreated: { type: "array", items: { type: "string" } }
+              },
+              required: ["orchDir", "dirsCreated"]
+            },
+            gitignore: { type: "object" },
+            commit: {
+              type: "object",
+              properties: {
+                committed: { type: "boolean" },
+                sha: { type: ["string", "null"] },
+                reason: { type: ["string", "null"] }
+              },
+              required: ["committed"]
+            }
+          },
+          required: ["orchestration", "gitignore", "commit"]
+        }
+      }
+    );
+    var orchDirs = (setupRepoResult.orchestration.dirsCreated || []).join(", ");
+    var commitMsg = setupRepoResult.commit.committed
+      ? "committed " + setupRepoResult.commit.sha
+      : "not committed (" + setupRepoResult.commit.reason + ")";
+    log("Repo setup: scaffolded " + setupRepoResult.orchestration.orchDir +
+        " (dirs: [" + orchDirs + "]); gitignore " +
+        (gitignoreConsent ? "update consented" : "declined by user — add '.worktrees/' and '.orchestration/user/' manually") +
+        "; scaffold " + commitMsg);
+    if (!setupRepoResult.commit.committed && setupRepoResult.commit.reason !== "nothing-to-commit") {
+      setupRepoWarning = "Project repo setup left the scaffold uncommitted (" +
+        setupRepoResult.commit.reason + ") — the first task's Integrate will refuse to merge until it is committed.";
+      log("WARNING: " + setupRepoWarning);
+    }
+  } catch (e) {
+    var setupErr = String(e.message || e);
+    setupRepoWarning = "Project repo setup failed: " + setupErr + " — continuing without the repo scaffold.";
+    if (/commit failed/i.test(setupErr)) {
+      setupRepoWarning += " The repo has uncommitted crew files; the first task's Integrate will refuse to merge until they are committed.";
+    }
+    log(setupRepoWarning + " (non-fatal)");
+  }
+} else {
+  log("Repo setup: no repo (CLI-only mode) — skipping.");
+}
+
 // ── Scheduler identity (2026-09-16) ──────────────────────────────────
 // The crew's scheduler identity is dashboard-independent and chosen once.
 // First init uses the crew-home basename; a re-run keeps the instanceId
@@ -716,6 +750,7 @@ return {
   releaseHash: releaseResult.hash,
   scaffold: { created: scaffoldCreated, skipped: scaffoldSkipped },
   project: projectResult.action,
+  repoSetupWarning: setupRepoWarning,
   crons: cronsResult.summary.crons,
   registry: cronsResult.summary.registry,
   autoUpdate: {