muse-crew 0.11.0 → 0.12.0

package/API.md

@@ -385,13 +385,15 @@ Register a new project.
 | `id` | slug | yes | Unique project identifier |
 | `display_name` | string (1–120) | yes | |
 | `repo_path` | string (1–1000) | yes | Absolute path to the project's Git repo |
-| `deploy_type` | `npm` · `artifact` · `vercel` · empty string | yes | Publish target: `npm` publishes the package to the npm registry, `artifact` rebuilds the live artifact, `vercel` is not yet implemented (blocks the task), empty skips the Publish phase |
-| `deploy_slug` | slug or null | no | Required when `deploy_type` is `artifact` |
+| `deploy_type` | `npm` · `artifact` · `vercel` · empty string | yes | Publish target: `npm` publishes the package to the npm registry, `artifact` rebuilds the live artifact, `vercel` is not yet implemented (blocks the task), empty skips the Publish phase. When omitted and the classified surface is `artifact`, defaults to `artifact` (see surface classification below). |
+| `deploy_slug` | slug or null | no | Required when `deploy_type` is `artifact`. When `deploy_type` is auto-defaulted to `artifact`, filled from the repo's `space.json` slug when present; explicitly chosen `deploy_type`/`deploy_slug` values are never overwritten. |
 | `description` | string (≤ 3000) | no | |
 | `simultaneity` | integer (1–100) | no | Max concurrent tasks; defaults to 2 |
 | `quiesced` | boolean | no | Start paused; defaults to false |
 | `visual_protocol` | boolean or null | no | Tri-state: `null` = inherit crew default (off), `true` = enable for this project, `false` = explicit off. Defaults to null. |
-| `environment_type` | `artifact` · `terminal` · null | no | User-facing surface for experiential QA routing: `artifact` = a rendered web UI (Hazel drives it with the see-act browser loop), `terminal` = a CLI (Hazel drives it herself, keeping transcripts). `null` = unclassified: no experiential QA. `deploy_type` names the deployment target, but `deploy_type: "artifact"` remains a legacy artifact-surface signal so pre-field projects keep today's experiential QA (the migration does not backfill the column); on conflicting config artifact wins. Defaults to null. |
+| `environment_type` | `artifact` · `terminal` · null | no | User-facing surface for experiential QA routing: `artifact` = a rendered web UI (Hazel drives it with the see-act browser loop), `terminal` = a CLI (Hazel drives it herself, keeping transcripts). `null` = unclassified: no experiential QA. `deploy_type` names the deployment target, but `deploy_type: "artifact"` remains a legacy artifact-surface signal so pre-field projects keep today's experiential QA (the migration does not backfill the column); on conflicting config artifact wins. Omitted means auto-classify from `repo_path` (see surface classification below); an explicit value, including explicit `null`, always wins. |
+
+**Surface classification (repo-derived defaults):** when `repo_path` is provided and `environment_type` is omitted, `create-project` mechanically classifies the repo at registration via `lib/classify-surface.js` — `space.json` present → `artifact`; else a non-empty `package.json` `bin` → `terminal`; otherwise unclassified (`null`). The classifier never throws: bad paths and malformed files classify as unclassified. Classification only fills omitted fields — an explicitly supplied `environment_type` (including explicit `null`) always wins, and deploy defaults follow the *effective* surface, so an explicit `"terminal"` never triggers artifact deploy defaults.
 
 ### `updateproject`
 

package/docs/guide.md

@@ -261,7 +261,7 @@ Every 15 minutes, the `crew-poll` cron fires:
 
 7. **Task completes** — when all phases finish, the dispatcher marks the task `done` on the next tick.
 
-Every tick also records its own release identity: right after acknowledging the poll, the dispatcher appends one line — `{"seq": <n>, "release": "<active release id>"}` — to `$CREW_HOME/.tick-releases.jsonl`. `release` is the active release (the basename of the crew home's `current` symlink, the same resolution the Crew API uses), and `seq` is the file's non-empty line count plus one; the file is append-only and never rewritten. Ordering is the proof, not timestamps — deliberately, since workflow scripts may not read the clock. For the self-upgrade proof, a tick whose line names the new release is demonstrably running the newly built code. A failed write never fails the tick: the writer swallows its own errors, carries no schema, and is wrapped in try/catch.
+Every tick also records its own release identity: right after acknowledging the poll, the dispatcher appends one line — `{"seq": <n>, "release": "<active release id>"}` — to `$CREW_HOME/.tick-releases.jsonl`. `release` is the active release (the basename of the crew home's `current` symlink, the same resolution the Crew API uses), and `seq` is the file's non-empty line count plus one; the file is append-only and never rewritten. Ordering is the proof, not timestamps — deliberately, since workflow scripts may not read the clock. For the self-upgrade proof, a tick whose line names the new release is demonstrably running the newly built code. A failed write never fails the tick: the writer swallows its own errors, carries no schema, and is wrapped in try/catch. The writer echoes the appended line to stdout (2026-09-17, rooms #12–#14): the fire-and-forget agent call carries no schema, and the platform's JSON-candidate scan throws on an empty schema-less result — so the writer speaks the same non-empty shape as every other fire-and-forget call in the dispatcher.
 
 ### Failure handling and retry
 

package/docs/publish-verification.md

@@ -106,6 +106,19 @@ request builder (`lib/build-readback-request.js`, `--base`) use the identical
 base: the previously-stamped provenance, or the empty tree for a genuine
 first publish. Request builder and verifier never disagree on the base.
 
+**Diff transport (room #14, 2026-09-17):** the diff is computed by the
+deterministic `lib/compute-publish-diff.js` (pinned per-run alongside the
+other lifecycle files), which writes the raw diff bytes to
+`$CREW_HOME/.publish-diffs/<taskId>[-rN].diff` and returns only a small JSON
+summary (`sha256`, `changed_lines` = added+removed, `has_binary`,
+`has_rename`). The LLM never carries diff bytes — an earlier shape asked an
+agent to return the raw diff as a JSON string field, and the JSON ferry
+dropped a valid 700-line diff ("Publish diff parsed to zero files"). The
+trigger agent verifies the file with `sha256sum` before any `artifact_edit`
+call and pastes the verified content into the edit. The 200 changed-line
+budget counts added+removed lines from the summary, never raw diff output
+lines (context lines inflated the old count ~2x).
+
 ## The shape: code detects, the tick ferries, code certifies
 
 A standalone verification workflow cannot work with the async inspection

package/docs/state-boundary-spec.md

@@ -141,3 +141,81 @@ New `tests/gitignore.test.js` and `tests/repo-orchestration.test.js`:
   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).
+
+## 9. Publish base advances past the setup scaffold (0.11.2)
+
+**Defect (room #14, 2026-09-17):** `create-project` stamps
+provenance `source_commit` at the pre-scaffold repo HEAD; the scaffold
+commit lands on top. The first task's publish diff then carries the whole
+scaffold (517 insertions in room #14) and blows the 200 changed-line
+diff-transport budget. The scaffold is crew-owned infrastructure the
+dashboard artifact never consumes, so the correct publish base is the
+scaffold commit itself.
+
+**Contract:** after the scaffold commit, crew-init runs
+`lib/advance-publish-base.js`, which moves `source_commit` to the scaffold
+commit only when every condition proves safety:
+
+- this init created the project (`--project-created`): the stamp is ours,
+  never a real publish's;
+- the scaffold commit's parent is exactly the stamped base: nothing (an
+  un-published task commit, a human push) slipped between the stamp and
+  the scaffold. An intermediate commit skips — the base still covers the
+  un-published work;
+- the scaffold commit touches only crew-owned paths (`.orchestration/`,
+  `.gitignore`): a foreign path skips, so user content is never dropped
+  from a publish diff;
+- no provenance + root scaffold commit → stamp fresh (the empty-repo-at-
+  create case); no provenance + non-root scaffold → skip (unverified
+  history is not claimed).
+
+Every other case skips without touching provenance. A base-pointer move is
+not a publish: `published_at` is preserved, and the result is read back
+and verified exact before returning. The call is best-effort from
+crew-init: an advance failure is logged loudly and init continues with the
+stamped base.
+
+**Tests:** `tests/advance-publish-base.test.js` (behavioral: advance,
+idempotency, all fail-closed skips, fresh stamp, usage errors; structural:
+crew-init wiring).

package/lib/AGENTS.md

@@ -14,7 +14,7 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `test-publish-skip.sh` — regression tests for the no-lock graceful publish skip (park 2026-09-11): `lock-status` returns exact `UNLOCKED`/`LOCKED by <holder> since <ts> (pid <pid>)`; a fake empty-diff integrate takes the MERGED_EMPTY branch and never takes the lock; the shipped step-5 block from publish-npm.sh (extracted by anchor) skips gracefully on UNLOCKED (no park, no `PUBLISH_COMPLETE`), follows the refresh path when a lock is held, and fails closed on a `lock-status` query failure; the gate sits inside the ALREADY_PUBLISHED=0 branch and mutation steps are gated on NO_LOCK_HELD=0
 - `publish-npm.sh` — deterministic npm publish: lock refresh, release install, version write/commit, pack, registry publish, verify, push, post-deploy. Takes TARGET_VERSION as input; idempotent on retry/resume.
 - `compose-evidence.py` — deterministic visual-evidence compositor (Pillow): pairs identical PNG stems from baseline/ and postchange/ dirs, emits `<stem>-sidebyside.png` and amplified-difference `<stem>-overlay.png` into composites/, prints `PAIR`/`SKIP` manifests. Byte-deterministic; nonzero exit on errors.
-- `compose-evidence-caption.js` — deterministic QA-evidence caption composer (2026-09-14): given `--crew-home`, `--task-id`, and the resolved `--audit-dir` name, extracts the task title/description, the QA verdict, the `publish: verified` commit (or the global provenance record when it belongs to this task), and the merge commit's subject line from the project repo — and prints the out-of-context transition Eric asked for (problem → solution → evidence handoff) to stdout. The caller appends the desktop/mobile attachment lines after this caption. Verdict source (2026-09-16): Hazel's `task-evidence/<taskId>/postchange/verdict.json` is authoritative, then the last line of the append-only `verdicts.jsonl` ledger, then the newest legacy `visual_verdict:` note (the parent visual-verdict protocol was retired 2026-09-15). Honest labels: "provenance not yet stamped" when no commit is known, "no QA verdict recorded" when none exists, and the visual-protocol-unavailable note only when no verdict evidence exists at all and the newest `baseline:` note is `baseline: none` (a `baseline: none` note means no baseline captures to compare against — it never overrules a real QA verdict). "Latest" is by event timestamp, sorted explicitly. Exits non-zero on missing input.
+- `compose-evidence-caption.js` — deterministic QA-evidence caption composer (2026-09-14): given `--crew-home`, `--task-id`, and the resolved `--audit-dir` name, extracts the task title/description, the QA verdict, the `publish: verified` commit (or the global provenance record when it belongs to this task), and the merge commit's subject line from the project repo — and prints the out-of-context transition Eric asked for (problem → solution → evidence handoff) to stdout. The caller appends the desktop/mobile attachment lines after this caption. Verdict source (2026-09-16): Hazel's `task-evidence/<taskId>/postchange/verdict.json` is authoritative, then the last line of the append-only `verdicts.jsonl` ledger, then the newest legacy `visual_verdict:` note (the parent visual-verdict protocol was retired 2026-09-15). Honest labels: "provenance not yet stamped" when no commit is known, "no QA verdict recorded" when none exists, and the visual-protocol-unavailable note only when no verdict evidence exists at all, the newest `baseline:` note is `baseline: none`, AND captures exist (a `baseline: none` note means no baseline captures to compare against — it never overrules a real QA verdict; the note's premise is the post-deploy capture, so without captures it would fabricate evidence again). Capture guard (2026-09-17, room #14): the composer resolves the audit dir itself (`<home>/workspace/ts-spaces/<deploy_slug>/audits/<auditDir>/`, the same root crew-api.js and readback-disk.js resolve) and verifies `screenshot.png` + `screenshot-mobile.png` are files before claiming "desktop + mobile captures below" — a bare `--audit-dir` name is never trusted. Missing deploy_slug, missing dir, or missing PNGs gets the honest no-captures opener and Evidence line (terminal surfaces named explicitly: "terminal surface — QA judges the CLI, not pixels"); the caller only appends attachment lines when its own freshness check passes. "Latest" is by event timestamp, sorted explicitly. Exits non-zero on missing input.
 - `edit-image.py` — deterministic pixel-level evidence editing (2026-09-15, Pillow): `crop --region x,y,w,h` (pixel-exact, rejects out-of-bounds), `zoom --factor <f> [--center x,y]` (nearest-neighbor, returns to source frame size), `label --text <caption>` (caption bar), `nup --cols <n> --in <a.png> --in <b.png> [--labels "a|b"]` (side-by-side grid). Byte-deterministic PNG output; no network, no time, no randomness. Derivatives supplement raw frames — the source frame stays archived.
 - `render-html.js` — deterministic HTML evidence composition (2026-09-15, headless Chromium): renders a local HTML layout to PNG (fixed viewport width, device scale 1, full-page screenshot). Hermetic: remote HTTP(S) assets are blocked and fail the render loudly; relative image paths resolve against the HTML file; local/system fonts only. Exit 3 reports NOT POSSIBLE when Chromium is unavailable. The composition layer above edit-image.py's pixel layer.
 - `see-act.js` — single-step browser driver for experiential QA (2026-09-14): one browser action per invocation (`aria`, `shot`, `click`, `scroll`, `type`), one JSON line on stdout, exit 0/2/3 (3 = NOT POSSIBLE: missing playwright-core or Chromium). Spawns its own loopback forward proxy on an ephemeral port (Chromium blocks direct loopback). The QA work agent closes the OODA loop: run a step, read the screenshot/aria, decide the next. Determinism: no wall-clock reads, no randomness. `SEE_ACT_ARCHIVE_DIR=<phase-dir>` (2026-09-14): every screenshot is archived automatically as `001-shot-desktop.png`, `002-click-mobile.png`, ... (counter in `<dir>/.seq`); `--out` becomes optional; JSON carries `screenshot` + `archived`; explicit `--out` + archive copies into the archive; unusable dir is NOT POSSIBLE exit 3.
@@ -29,5 +29,9 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `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]`.
+- `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>`.
+- `compute-publish-diff.js` — deterministic publish-diff computer (2026-09-18, room #14): replaces the agent-ferried `git diff` JSON string field (the JSON ferry dropped a valid 700-line diff — "Publish diff parsed to zero files"). Runs `git diff <base> <HEAD>` via argv (no shell), writes the raw diff bytes to `--out`, and prints only a small JSON summary (`commit`, `base`, `diff_file`, `sha256`, `bytes`, `file_count`, `changed_lines` = added+removed, never raw diff output lines, `files`, `has_binary`, `has_rename`). Empty-tree base is the first-publish ancestor (hardcoded, never `merge-base` on the empty tree); non-ancestor is semantic JSON (`ok:false, error:"not-ancestor"`, exit 0); usage errors exit 2 with nothing on stdout. Pinned per-run alongside the other lifecycle files (`COMPUTE_DIFF` in `PIN_BASENAMES`) so a mid-run release swap cannot change it under the workflow.
+- `classify-surface.js` — deterministic project-surface classifier (2026-09-18, room #14 defect): a pure, never-throwing scan of the registered repo — `space.json` present → `artifact` surface (deploy_slug suggestion = `space.json`'s valid slug, verbatim — presence alone still means "web app"), `package.json` with a non-empty `bin` → `terminal` surface, otherwise null (unclassified); artifact wins conflicts (the deployed artifact is what users see, same rule as workflows/standard.js). CLI `--repo-path` prints one JSON object (`{surface, deploy_slug, signals}`), always exit 0 (classification failure is a null result, exit 2 only for usage). `create-project` fills omitted `environment_type`/`deploy_type`/`deploy_slug` from the classification; explicit values (including explicit null) always win and drive the effective surface.
+- `advance-publish-base.js` — publish-base advance past the setup scaffold (2026-09-18, room #14): `create-project` stamps provenance at the pre-scaffold repo HEAD, then crew-init commits `.orchestration/` (+ the consented `.gitignore`) on top — the first task's publish diff would carry the whole scaffold (517 insertions) and blow the 200-line diff-transport budget. The script moves `source_commit` to the scaffold commit only when `--project-created` (the stamp is this init's, never a real publish's), the scaffold commit's parent is exactly the stamped base, and the scaffold touches only crew-owned paths (`.orchestration/`, `.gitignore`); no provenance + root scaffold commit stamps fresh. Every other case skips without touching provenance; `published_at` is preserved on advance. Called from crew-init.js (best-effort, non-fatal). CLI: `--crew-home <path> --repo <path> --scaffold-sha <sha> [--project-created]`.

package/lib/advance-publish-base.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// Advance the publish base past crew-init's scaffold commit (2026-09-18).
+//
+// Room #14 (2026-09-17): create-project stamps provenance.source_commit at the
+// pre-scaffold repo HEAD; crew-init then commits the .orchestration/ scaffold
+// on top. The first task's publish diff then carries the whole scaffold (517
+// insertions in room #14) and blows the 200-line diff-transport budget. The
+// scaffold is crew-owned infrastructure the dashboard artifact never consumes,
+// so the correct publish base is the scaffold commit itself.
+//
+// This script moves provenance.source_commit to the scaffold commit only when
+// every fail-closed condition holds:
+//   1. --project-created: this init created the project, so the existing stamp
+//      is this run's initial stamp — never a real publish's.
+//   2. The scaffold commit's parent IS the stamped source_commit: nothing
+//      slipped between the stamp and the scaffold, so no un-published task
+//      work can be silently dropped from a future diff.
+//   3. Every path changed by the scaffold commit is crew-owned
+//      (.orchestration/ or .gitignore).
+//   4. Special case: no provenance was ever stamped (empty repo at create
+//      time) and the scaffold commit is the root commit -> stamp fresh.
+// Anything else yields { ok: true, action: "skipped", reason } — never an
+// error, never a clobber. stdout carries exactly one JSON object; operational
+// failures go to stderr with a non-zero exit (the caller treats failure as
+// best-effort: init continues with the stamped base).
+//
+// No wall-clock reads, no randomness — the published_at on a fresh stamp is
+// left to crew-api's default; on an advance the existing published_at is
+// preserved (a base-pointer move is not a publish).
+
+import { execFileSync } from "node:child_process";
+import { readlinkSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SHA_RE = /^[0-9a-f]{40}$/;
+const RELEASE_RE = /^([0-9a-f]{40}|pkg-\d+\.\d+\.\d+)$/;
+
+function usage() {
+  console.error(
+    "Usage: node lib/advance-publish-base.js --crew-home <path> --repo <path> --scaffold-sha <sha> --project-created"
+  );
+}
+
+function parseArgv(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--crew-home") out.crewHome = argv[++i];
+    else if (a === "--repo") out.repo = argv[++i];
+    else if (a === "--scaffold-sha") out.scaffoldSha = argv[++i];
+    else if (a === "--project-created") out.projectCreated = true;
+    else {
+      console.error("unknown argument: " + a);
+      usage();
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+function git(repo, args) {
+  return execFileSync("git", ["-C", repo].concat(args), {
+    encoding: "utf8",
+    timeout: 15000,
+  }).trim();
+}
+
+function crewApi(crewHome, command, jsonArg) {
+  const apiPath = join(HERE, "crew-api.js");
+  const args = ["--crew-home", crewHome, command];
+  if (jsonArg !== undefined) args.push("--json", jsonArg);
+  const out = execFileSync("node", [apiPath].concat(args), {
+    encoding: "utf8",
+    timeout: 15000,
+  }).trim();
+  return JSON.parse(out);
+}
+
+function resolveActiveRelease(crewHome) {
+  // Mirrors lib/crew-api.js resolveActiveRelease minus the self-path check
+  // (this script is caller-pinned, not release-pinned).
+  const target = readlinkSync(join(crewHome, "current"));
+  return basename(resolve(crewHome, target));
+}
+
+function isCrewOwnedPath(p) {
+  return p === ".gitignore" || p === ".orchestration" || p.startsWith(".orchestration/");
+}
+
+function skip(reason) {
+  console.log(JSON.stringify({ ok: true, action: "skipped", reason }));
+}
+
+function main() {
+  const { crewHome, repo, scaffoldSha, projectCreated } = parseArgv(
+    process.argv.slice(2)
+  );
+  if (!crewHome || !repo || !scaffoldSha) {
+    usage();
+    process.exit(2);
+  }
+  if (!SHA_RE.test(scaffoldSha)) {
+    console.error("scaffold-sha is not a 40-char hex sha");
+    process.exit(2);
+  }
+  if (!projectCreated) {
+    skip("project was not created by this init — provenance left untouched");
+    return;
+  }
+
+  let provenance;
+  try {
+    provenance = crewApi(crewHome, "get-provenance").provenance;
+  } catch (e) {
+    console.error("get-provenance failed: " + (e.message || e));
+    process.exit(1);
+  }
+
+  // The scaffold commit's parent: empty output means S is the root commit.
+  let parent;
+  try {
+    const parents = git(repo, ["rev-list", "--parents", "-n", "1", scaffoldSha]).split(/\s+/);
+    parent = parents.length > 1 ? parents[1] : null;
+  } catch (e) {
+    console.error("rev-list failed: " + (e.message || e));
+    process.exit(1);
+  }
+
+  let changedPaths;
+  try {
+    changedPaths = git(repo, ["diff-tree", "--no-commit-id", "--name-only", "-r", scaffoldSha])
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+  } catch (e) {
+    console.error("diff-tree failed: " + (e.message || e));
+    process.exit(1);
+  }
+  const foreign = changedPaths.filter((p) => !isCrewOwnedPath(p));
+  if (foreign.length > 0) {
+    skip(
+      "scaffold commit touches non-crew-owned paths (" +
+        foreign.slice(0, 5).join(", ") +
+        ") — provenance left untouched"
+    );
+    return;
+  }
+
+  if (provenance === null || provenance === undefined) {
+    // No stamp ever (empty repo at create time): stamp fresh only if the
+    // scaffold commit is the root commit — anything else means history we
+    // did not create, and we do not invent a base over it.
+    if (parent !== null) {
+      skip("no provenance stamped and scaffold commit is not the root commit — provenance left untouched");
+      return;
+    }
+    let crewRelease = null;
+    try {
+      crewRelease = resolveActiveRelease(crewHome);
+    } catch (e) {
+      skip("no provenance stamped and the active crew release is unresolvable (" + (e.message || e) + ")");
+      return;
+    }
+    if (!RELEASE_RE.test(crewRelease)) {
+      skip("no provenance stamped and the active release name is not a valid crew_release (" + crewRelease + ")");
+      return;
+    }
+    const stamped = crewApi(crewHome, "set-provenance", JSON.stringify({
+      source_commit: scaffoldSha,
+      crew_release: crewRelease,
+    }));
+    if (!stamped || stamped.ok !== true) {
+      console.error("set-provenance did not return ok");
+      process.exit(1);
+    }
+    console.log(JSON.stringify({ ok: true, action: "stamped", to: scaffoldSha.slice(0, 12) }));
+    return;
+  }
+
+  const base = provenance.source_commit;
+  if (!SHA_RE.test(base || "")) {
+    skip("existing provenance.source_commit is not a 40-char hex sha — provenance left untouched");
+    return;
+  }
+  if (base === scaffoldSha) {
+    skip("provenance already points at the scaffold commit");
+    return;
+  }
+  if (parent !== base) {
+    skip(
+      "scaffold commit's parent (" +
+        String(parent || "root").slice(0, 12) +
+        ") is not the stamped base (" +
+        base.slice(0, 12) +
+        ") — provenance left untouched"
+    );
+    return;
+  }
+
+  let crewRelease = RELEASE_RE.test(provenance.crew_release || "")
+    ? provenance.crew_release
+    : null;
+  if (!crewRelease) {
+    try {
+      const resolved = resolveActiveRelease(crewHome);
+      if (RELEASE_RE.test(resolved)) crewRelease = resolved;
+    } catch {
+      crewRelease = null;
+    }
+  }
+  if (!crewRelease) {
+    skip("no usable crew_release for the re-stamp — provenance left untouched");
+    return;
+  }
+
+  const stamped = crewApi(crewHome, "set-provenance", JSON.stringify({
+    source_commit: scaffoldSha,
+    crew_release: crewRelease,
+    // A base-pointer move is not a publish: keep the existing published_at.
+    ...(provenance.published_at ? { published_at: provenance.published_at } : {}),
+  }));
+  if (!stamped || stamped.ok !== true) {
+    console.error("set-provenance did not return ok");
+    process.exit(1);
+  }
+  // Exact read-back: the stamp must match what we intended, or it is fiction
+  // (same discipline as lib/verify-publish.js).
+  const recheck = crewApi(crewHome, "get-provenance").provenance;
+  if (!recheck || recheck.source_commit !== scaffoldSha) {
+    console.error("post-stamp read-back mismatch: provenance does not point at the scaffold commit");
+    process.exit(1);
+  }
+  console.log(
+    JSON.stringify({
+      ok: true,
+      action: "advanced",
+      from: base.slice(0, 12),
+      to: scaffoldSha.slice(0, 12),
+    })
+  );
+}
+
+try {
+  main();
+} catch (e) {
+  console.error("advance-publish-base failed: " + (e.message || e));
+  process.exit(1);
+}

package/lib/classify-surface.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// classify-surface.js — deterministic user-facing surface classifier.
+//
+// Room #14 (2026-09-17): the flashcards sample (a TS Space web app —
+// space.json, client/, server/) was registered with environment_type=null
+// and deploy_slug=null because the setup conversation never classified it —
+// SETUP-EXPERIENCE.md doesn't even mention the step. Consequence: Capture
+// skipped ("surface unclassified"), Publish had no artifact target, QA had
+// no runnable surface — J1/J2 parked with "no build, deployed artifact, or
+// runnable probe surface". The setup conversation is an agent; asking it to
+// classify in prose is wording, not a mechanism.
+//
+// This script is the mechanism: a pure, deterministic repo scan. Signals:
+//   space.json present         -> artifact surface (a Space web app).
+//                                 deploy_slug suggestion = space.json's slug
+//                                 (verbatim — the artifact system keys on it).
+//                                 Presence is the signal: an unparseable
+//                                 space.json still means "web app", just with
+//                                 no slug suggestion.
+//   package.json with a "bin"  -> terminal surface (a CLI).
+//   otherwise                  -> null (unclassified — today's behavior).
+// Artifact wins on contradictory signals (space.json + bin): the deployed
+// artifact is what users see (same rule as workflows/standard.js).
+//
+// create-project fills OMITTED environment_type / deploy_type / deploy_slug
+// from this classification; explicit values always win (including an
+// explicit null environment_type, which means "unclassified").
+//
+// Fail-safe: any IO error, bad path, or unparseable file yields
+// { surface: null, ... } — never a throw, never a misclassification.
+//
+// Usage: node lib/classify-surface.js --repo-path <path>
+// Stdout: exactly one JSON object:
+//   { surface: "artifact"|"terminal"|null, deploy_slug: string|null, signals: [...] }
+// Exit codes: 0 ok (always — classification failure is a null result) ·
+// 2 usage/validation. On exit 2 nothing is printed to stdout.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function validSlug(s) {
+  return typeof s === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s);
+}
+
+export function classifySurface(repoPath) {
+  const signals = [];
+  if (typeof repoPath !== "string" || repoPath.length === 0 || !isDir(repoPath)) {
+    return { surface: null, deploy_slug: null, signals };
+  }
+  // Artifact: space.json marks a TS Space web app.
+  if (existsSync(join(repoPath, "space.json"))) {
+    signals.push("space.json");
+    const space = readJson(join(repoPath, "space.json"));
+    const slug = space && validSlug(space.slug) ? space.slug : null;
+    if (slug) signals.push("space.json:slug=" + slug);
+    return { surface: "artifact", deploy_slug: slug, signals };
+  }
+  // Terminal: package.json "bin" declares a CLI entrypoint.
+  const pkg = readJson(join(repoPath, "package.json"));
+  if (pkg && pkg.bin !== undefined && pkg.bin !== null) {
+    const hasBin =
+      typeof pkg.bin === "string"
+        ? pkg.bin.length > 0
+        : typeof pkg.bin === "object" && Object.keys(pkg.bin).length > 0;
+    if (hasBin) {
+      signals.push("package.json:bin");
+      return { surface: "terminal", deploy_slug: null, signals };
+    }
+  }
+  return { surface: null, deploy_slug: null, signals };
+}
+
+const isMainModule = (() => {
+  try {
+    return process.argv[1] === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  const i = process.argv.indexOf("--repo-path");
+  const repoPath = i >= 0 ? process.argv[i + 1] : null;
+  if (!repoPath) {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: "usage", message: "--repo-path is required" }) + "\n"
+    );
+    process.exit(2);
+  }
+  // Never throws: classifySurface is total over string inputs.
+  process.stdout.write(JSON.stringify(classifySurface(repoPath)) + "\n");
+}

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);
+  }
+}