muse-crew 0.11.1 → 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

@@ -182,3 +182,40 @@ 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.
@@ -32,3 +32,6 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `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/compose-evidence-caption.js

@@ -9,7 +9,18 @@
 // caller appends AFTER this caption. Deterministic: every line is extracted
 // mechanically from the Crew API, the task's events, and the merge commit —
 // no LLM prose. The caller (seed/cron-body-template.md Step 6) prints this
-// caption verbatim, then the two attachment lines, then logs delivery.
+// caption verbatim, then the two attachment lines (only when the audit
+// harness actually captured screenshots), then logs delivery.
+//
+// Capture guard (2026-09-17, room #14): the composer must SEE the captures
+// before it claims them. It once fabricated "desktop + mobile captures
+// below" for a terminal-surface task with no audit dir at all, and opened
+// with "these screenshots are dropping in" when no screenshots existed. So
+// it resolves the audit dir itself — <home>/workspace/ts-spaces/<deploy_slug>
+// /audits/<auditDir>/, the same root lib/crew-api.js and lib/readback-disk.js
+// resolve — and checks screenshot.png + screenshot-mobile.png are files.
+// Missing deploy_slug, missing dir, or missing PNGs gets the honest
+// no-captures line; terminal surfaces are named, not assumed.
 //
 // Usage:
 //   node lib/compose-evidence-caption.js --crew-home <home> \
@@ -19,6 +30,7 @@
 
 const { execFileSync } = require("node:child_process");
 const fs = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 
 function usage(msg) {
@@ -76,6 +88,22 @@ try {
 }
 const task = (state.tasks || []).find((t) => t.id === taskId);
 if (!task) usage("task " + taskId + " not found");
+const project = (state.projects || []).find((p) => p.id === task.project);
+
+// Capture guard (2026-09-17, room #14): resolve the audit dir the audit
+// harness actually writes and verify the captures exist before claiming
+// them. A bare --audit-dir name is never trusted on its own.
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+let auditPath = null;
+if (project && project.deploy_slug) {
+  auditPath = path.join(os.homedir(), "workspace", "ts-spaces",
+    project.deploy_slug, "audits", auditDir);
+}
+const hasCaptures = !!(auditPath &&
+  isFile(path.join(auditPath, "screenshot.png")) &&
+  isFile(path.join(auditPath, "screenshot-mobile.png")));
 
 let events = [];
 try {
@@ -149,8 +177,7 @@ if (!commit) {
 // task title when the commit is unknown or unreadable.
 let solution = "";
 if (commit) {
-  const proj = (state.projects || []).find((p) => p.id === task.project);
-  if (proj && proj.repo_path) solution = gitSubject(proj.repo_path, commit);
+  if (project && project.repo_path) solution = gitSubject(project.repo_path, commit);
 }
 if (!solution) solution = task.title;
 
@@ -169,16 +196,37 @@ const newestBaselineNote = notesNewest.find((e) => /^baseline:\s*/i.test(e.messa
 const visualUnavailable = !verdict && !!newestBaselineNote &&
   /^baseline:\s*none/i.test(newestBaselineNote.message || "");
 
+const verdictLine = verdict
+  ? " QA verdict: " + verdict.status + (verdict.summary ? " — " + trimWords(verdict.summary, 200) : "") + "."
+  : " No QA verdict recorded.";
+
 const lines = [];
-lines.push("These screenshots are dropping in out of context — quick transition.");
+if (hasCaptures) {
+  lines.push("These screenshots are dropping in out of context — quick transition.");
+} else {
+  // Honest opener: no screenshots are arriving, so the report says so up
+  // front instead of pretending they are dropping in.
+  lines.push("QA evidence for this task — no screenshots, so this is the whole report.");
+}
 lines.push("");
 lines.push("**" + task.title + "**");
 lines.push("Problem: " + problem);
 lines.push("Shipped: " + trimWords(solution, 160) +
   (commit ? " (commit `" + commit.slice(0, 12) + "`, parent-verified)" : " (provenance not yet stamped)"));
-lines.push("Evidence: desktop + mobile captures below, taken by the platform audit harness after deploy (`" + auditDir + "`)." +
-  (verdict ? " QA verdict: " + verdict.status + (verdict.summary ? " — " + trimWords(verdict.summary, 200) : "") + "." : " No QA verdict recorded."));
-if (visualUnavailable) {
+if (hasCaptures) {
+  lines.push("Evidence: desktop + mobile captures below, taken by the platform audit harness after deploy (`" + auditDir + "`)." + verdictLine);
+} else {
+  // Honest no-captures line (2026-09-17, room #14): never claim captures
+  // that do not exist. Terminal surfaces are named, not assumed.
+  const surfaceNote = project && project.environment_type === "terminal"
+    ? " (terminal surface — QA judges the CLI, not pixels)"
+    : "";
+  lines.push("Evidence: no screenshots captured for this task" + surfaceNote + " — nothing to attach." + verdictLine);
+}
+if (visualUnavailable && hasCaptures) {
+  // The note's premise is the post-deploy capture — without captures it
+  // would fabricate evidence again (2026-09-17: the no-captures line above
+  // already covers the honest case).
   lines.push("Note: the visual protocol is unavailable — these are the post-deploy capture plus QA's mechanical checks, not a QA visual inspection.");
 }
 process.stdout.write(lines.join("\n") + "\n");