muse-crew 0.10.1 → 0.11.0

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,143 @@
+# 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.

package/lib/AGENTS.md

@@ -27,3 +27,7 @@ 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): runs the `.orchestration/` scaffold plus the `.gitignore` update (only with explicit `--consent`). 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]`.
+- `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/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,50 @@
+#!/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)
+//
+// 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.
+//
+// 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 } }
+
+const { scaffoldRepoOrchestration } = require("./repo-orchestration");
+const { ensureGitignoreEntries, describeGitignoreChange } = require("./gitignore");
+
+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);
+  }
+
+  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 };
+  }
+
+  console.log(JSON.stringify({ orchestration, gitignore }, null, 2));
+}
+
+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.0",
   "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

@@ -339,22 +339,19 @@ 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.
+// and we have a repo (dashboard mode), append crew-owned paths to .gitignore
+// via the deterministic lib/gitignore.js (no agent judgment — the agent
+// just runs the fixed command; all merge logic is in the tested JS module).
 // 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 }.",
+      "Run the deterministic gitignore updater. Do not decide anything — just run the command and return its JSON output.\n\n" +
+      "Command:\n" +
+      "node " + crewHome + "/current/lib/gitignore.js --repo \"" + gateFacts.dashboardRepoExpanded + "\"\n\n" +
+      "The script prints one JSON line: { created, appended[], skipped[] }.\n" +
+      "Return that JSON verbatim.",
       {
         key: "scaffold-gitignore",
         label: "Update .gitignore for crew paths",
@@ -376,7 +373,7 @@ if (gitignoreConsent && dashboardRepoPath) {
     log("Gitignore update failed (non-fatal): " + String(e.message || e));
   }
 } else if (dashboardRepoPath) {
-  log("Gitignore: user declined — add '.worktrees/' to " + dashboardRepoPath + "/.gitignore manually.");
+  log("Gitignore: user declined — add '.worktrees/' and '.orchestration/user/' to " + dashboardRepoPath + "/.gitignore manually.");
 } else {
   log("Gitignore: no repo (CLI-only mode) — skipping.");
 }
@@ -458,6 +455,39 @@ try {
 log("Project: " + dashboardSlug + " " + projectResult.action + " (repo_path=" + gateFacts.dashboardRepoExpanded + ")");
 } // end dashboard-mode project registration
 
+// ── Repo-local .orchestration/ scaffold ─────────────────────────────
+// Scaffold $REPO/.orchestration/ in the dashboard repo (version-controlled
+// workflows/identities/phases + ignored user/). Deterministic — the agent
+// runs the fixed command; all logic is in the tested lib module.
+if (dashboardRepoPath) {
+  var repoOrchResult;
+  try {
+    repoOrchResult = await agent(
+      "Scaffold the repository-local .orchestration/ directory. Do not decide anything — just run the command and return its JSON output.\n\n" +
+      "Command:\n" +
+      "node " + crewHome + "/current/lib/repo-orchestration.js --repo \"" + gateFacts.dashboardRepoExpanded + "\" --crew-repo \"" + crewRepoPath + "\"\n\n" +
+      "The script prints JSON with dirsCreated, workflows, identities, phases.\n" +
+      "Return that JSON verbatim.",
+      {
+        key: "scaffold-repo-orch",
+        label: "Scaffold repo-local .orchestration",
+        schema: {
+          type: "object",
+          properties: {
+            orchDir: { type: "string" },
+            dirsCreated: { type: "array", items: { type: "string" } }
+          },
+          required: ["orchDir", "dirsCreated"]
+        }
+      }
+    );
+    log("Repo-orchestration: scaffolded " + repoOrchResult.orchDir +
+        " (dirs: [" + (repoOrchResult.dirsCreated || []).join(", ") + "])");
+  } catch (e) {
+    log("Repo-orchestration scaffold failed (non-fatal): " + String(e.message || e));
+  }
+}
+
 // ── 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