muse-crew 0.11.1 → 0.13.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`
 
@@ -472,18 +474,49 @@ Set a global configuration value.
 
 ### `setprovenance`
 
-Stamp publication provenance. Called by the crew Publish phase after rebuilding the artifact, and after installing/activating a crew release (npm path): in the release case Publish refreshes `crew_release` to the live release identity while preserving the existing `source_commit`.
+Stamp publication provenance. Provenance is per-project (2026-09-18): each
+project row carries its own publish base (`provenance_source_commit`,
+`provenance_crew_release`, `provenance_published_at`, `provenance_task_id`);
+a crew home with N artifact projects carries N independent bases. There are
+two stamp call paths, and they are different operations on the same row:
+
+- **Full stamp** — called by the parent's publish verification (`lib/verify-publish.js`)
+  after independently verifying the rebuilt artifact: `source_commit` is the
+  verified build commit, `crew_release` the active release at publish time.
+- **Refresh** — called by the release installer (`lib/advance-publish-base.js`)
+  after installing/activating a crew release: `crew_release` is refreshed to
+  the live release identity while preserving the existing `source_commit`.
+  A base-pointer move is not a publish.
+
+Both paths flow through the single writer in `lib/crew-api.js`; an unknown
+`project_id` fails closed (exit 3), and omitting `project_id` is a usage
+error (exit 2) — there is no silent global fallback.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
+| `project_id` | string | yes | The project whose publish base is stamped |
 | `source_commit` | 40-char hex | yes | Repo commit the artifact was built from |
-| `crew_release` | 40-char hex | yes | Active crew release (`$CREW_HOME/current`) at publish time |
-| `published_at` | ISO 8601 datetime (UTC) | yes | |
+| `crew_release` | 40-char hex, or `pkg-<semver>` | yes | Active crew release (`$CREW_HOME/current`) at stamp time |
+| `published_at` | ISO 8601 datetime (UTC) | yes | Defaults to now when omitted |
 | `task_id` | string | no | Publishing task, for traceability |
 
+A one-time migration attributes a pre-per-project legacy `config.provenance.*`
+triple to a project row only when its `source_commit` is an ancestor of
+exactly one project's repo HEAD (verified with git); zero or ambiguous
+matches are recorded as `deferred:<reason>` and never attributed. A triple
+that matches exactly one project but violates the writer's shape rules
+(e.g. a hand-written abbreviated sha, which git resolves for the ancestor
+check but which fails the 40-char storage rule) is recorded as
+`deferred:stamp-failed:<reason>` — the migration never throws, so a bad
+triple can never brick the home. A `deferred:*` watermark is re-evaluated
+when a project is created (the only event that changes the match set), so
+a triple that predates the home's first project is attributed once a
+descendant project exists. The legacy keys are inert dead storage after a
+successful migration — new code never reads them.
+
 ### `getprovenance`
 
-Read the last publication provenance. Returns `{ "provenance": { "source_commit", "crew_release", "published_at", "task_id" } }`, or `{ "provenance": null }` when nothing has been published yet. `task_id` is the publishing task, for traceability — present when `setprovenance` was called with one, absent otherwise.
+Read a project's publication provenance. Returns `{ "provenance": { "source_commit", "crew_release", "published_at", "task_id" } }`, or `{ "provenance": null }` when nothing has been published yet. A project that was never stamped reads `null` — another project's stamp is never visible here. `task_id` is the publishing task, for traceability — present when `setprovenance` was called with one, absent otherwise. `project_id` is required (exit 2 when omitted); an unknown `project_id` fails closed (exit 3).
 
 ---
 

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
@@ -210,7 +223,9 @@ For a task parked with `publish: verification-requested <commit>`:
    slug (the project's publish target).
 2. **Expected change.** The publish delta is `git diff <base> <commit>`
    in `repo_path`, where `<base>` is the previously-stamped provenance
-   `source_commit` (read it via `get-provenance`; use the empty-tree sha
+   `source_commit` for this project (read it via
+   `get-provenance --json '{"project_id":"<id>"}'` — provenance is
+   per-project; without `project_id` the call exits 2; use the empty-tree sha
    `4b825dc642cb6eb9a060e54bf8d69288fbee4904` when no provenance is
    stamped yet — a first publish). Never use `commit^1` as the base and
    never take the expected change from the builder's report: push-time
@@ -280,9 +295,15 @@ For a task parked with `publish: verification-requested <commit>`:
      (the crew-owned store). Do NOT use the artifact's `setprovenance`
      action — it writes a different, non-authoritative store that QA never
      reads, so the stamp would be invisible to every gate:
-     `set-provenance --json '{"source_commit":"<commit>","crew_release":"<release>","task_id":"<task>"}'`
+     `set-provenance --json '{"project_id":"<id>","source_commit":"<commit>","crew_release":"<release>","task_id":"<task>"}'`
      (crew_release is the basename of the active release, e.g.
-     `pkg-0.7.10`). Then read the stamp back with `get-provenance`
+     `pkg-0.7.10`). This is the full publish-verification stamp — it
+     records a verified publish. Do not confuse it with the
+     provenance *refresh* (re-pointing `crew_release` at the active
+     release after a crew upgrade without a new publish), which also goes
+     through `set-provenance` but keeps the existing `source_commit`.
+     Then read the stamp back with
+     `get-provenance --json '{"project_id":"<id>"}'`
      and confirm source_commit, crew_release, and task_id match exactly
      what was sent — a stamp that cannot be read back is not a stamp. Only
      then log the task note event

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

@@ -3,18 +3,18 @@
 Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, and the release system.
 
 - `build-registry.js` — deterministic extractor that generates `workflows/registry.json` (workflow step registry) from the workflow files' `meta` blocks at release time; invoked by `crew-release.sh` deploy
-- `crew-api.js` — the crew-owned task-service API (dependency inversion, 2026-09-11): a zero-dependency Node CLI implementing the API.md contract against `$CREW_HOME/crew-state.db` (schema in `schema.sql`). Workflows call it through their agents' shell; the dashboard delegates to it. All state-machine invariants live as CHECK constraints in the schema, never in client prose. Includes the `record-phase` composite (session + event in one transaction) and a one-time `migrate` import from a dashboard app.db.
+- `crew-api.js` — the crew-owned task-service API (dependency inversion, 2026-09-11): a zero-dependency Node CLI implementing the API.md contract against `$CREW_HOME/crew-state.db` (schema in `schema.sql`). Workflows call it through their agents' shell; the dashboard delegates to it. All state-machine invariants live as CHECK constraints in the schema, never in client prose. Includes the `record-phase` composite (session + event in one transaction) and a one-time `migrate` import from a dashboard app.db. Active-release resolution is split in two (room #15): `resolveActiveReleaseName` (symlink-only — writers like the initial-provenance stamp record the active release without proving they are it) and `resolveActiveRelease` (symlink + self-path cross-check — verifiers like `scan-verification-pending` refuse to stamp claims when the running code isn't the active release's own). Provenance is per-project (2026-09-18, room #15 blocker 8): nullable `provenance_*` columns on the projects row, a single `stampProvenance()` writer, `set-provenance`/`get-provenance` require `project_id` (no silent global fallback), and a watermarked openDb backfill that attributes the legacy `config.provenance.*` triple to exactly-one ancestor match — never fabricated, otherwise deferred.
 - `schema.sql` — the crew-owned state schema: projects, tasks, poll_state, config, agent_sessions, events. Vocabularies enforced by CHECK constraints; `rejected` is a valid event type (the 2026-09-11 crash was a stored session whose event was rejected). Column names match the historical dashboard tables for a verbatim migration.
 - `crew-release.sh` — immutable release manager: deploy, rollback, prune
 - `merge-lock.sh` — serialized merge lock for concurrent agents: time-based holder lease (bug 2fc8f52f — an unexpired lease is held regardless of process liveness; only an expired lease may be broken). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset). Lock file is key=value: task_id, opaque holder identity (never a PID), acquired_at epoch, lease_seconds (default 600, override via MERGE_LOCK_LEASE_SECONDS). acquire/refresh/release/status/force-release; holder-only refresh and release; every op appends to $CREW_HOME/.merge-lock.log
-- `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/verify-merge/status/post-deploy/terminal-cleanup/refresh-lock/lock-status over git worktrees (`integrate` reconciles `origin/main` under the merge lock after the task merge — canary `a6d8b0c8`, 2026-09-11 — so the push is a fast-forward; fail-soft with no remote, fail closed on conflict) (`.worktrees/<id>`, branch `task/<id>`). Branch resolution order: the crew registry (`<repo>/.worktrees/.registry/<id>`), then the canonical `task/<full-id>` ref, then a `task/<id-prefix>` ref matched by strict prefix enumeration (task 4e1a1bba — a Build agent may create the branch with raw git from an abbreviated id, bypassing prepare; prefix names are tolerated, never created; ambiguous prefixes fail closed). `resolve-branch` prints the resolved branch for agent-side one-liners. Nothing reconstructs the branch name — every command resolves it. Prepare fails closed on dirty `main`; cleanup is forgiving. `terminal-cleanup` is the run's last act at every park/fail boundary (called from `parkTask` in standard/bugfix/chore): releases the merge lock unconditionally and reclaims the worktree+branch only when the task branch is fully merged into main — unmerged work is preserved for the human by design, and a dirty worktree is reported, never force-removed. `post-deploy` reports worktree removal honestly (a lying "removed" echo hid real leftovers — canary run 9, 2026-09-12). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset); `CREW_REPO` is exported so internal merge-lock.sh calls inherit the repo being worked on; `LIB_DIR` defaults to `$CREW_HOME/lib` (`CREW_LIB` override). `lock-status` reports the merge-lock state explicitly (`UNLOCKED`, or key=value: locked=true, task_id, holder, acquired_at, lease_seconds, age_seconds, remaining_seconds — always exit 0) so Publish can distinguish an empty-diff Integrate (no lock taken) from a refresh failure.
+- `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/verify-merge/status/post-deploy/terminal-cleanup/refresh-lock/lock-status over git worktrees (`integrate` reconciles `origin/main` under the merge lock after the task merge — canary `a6d8b0c8`, 2026-09-11 — so the push is a fast-forward; fail-soft with no remote, fail closed on conflict) (`.worktrees/<id>`, branch `task/<id>`). Branch resolution order: the crew registry (`<repo>/.worktrees/.registry/<id>`), then the canonical `task/<full-id>` ref, then a `task/<id-prefix>` ref matched by strict prefix enumeration (task 4e1a1bba — a Build agent may create the branch with raw git from an abbreviated id, bypassing prepare; prefix names are tolerated, never created; ambiguous prefixes fail closed). `resolve-branch` prints the resolved branch for agent-side one-liners. Nothing reconstructs the branch name — every command resolves it. Prepare fails closed on dirty `main`; cleanup is forgiving. `terminal-cleanup` is the run's last act at every park/fail boundary (called from `parkTask` in standard/bugfix/chore): releases the merge lock unconditionally and reclaims the worktree+branch only when the task branch is fully merged into main — unmerged work is preserved for the human by design, and a dirty worktree is reported, never force-removed. `post-deploy` reports worktree removal honestly (a lying "removed" echo hid real leftovers — canary run 9, 2026-09-12). Requires both `CREW_REPO` and `CREW_HOME` (fail closed: BLOCKED, exit 2 when either is unset); `CREW_REPO` is exported so internal merge-lock.sh calls inherit the repo being worked on; `LIB_DIR` defaults to `$CREW_HOME/lib` (`CREW_LIB` override). `lock-status` reports the merge-lock state explicitly (`UNLOCKED`, or key=value: locked=true, task_id, holder, acquired_at, lease_seconds, age_seconds, remaining_seconds — always exit 0) so Publish can distinguish an empty-diff Integrate (no lock taken) from a refresh failure. post-deploy's `.worktrees/` guard is add-then-reset, never an all-negative pathspec: `git add -A -- ':!.worktrees/'` still exits 1 on git 2.43.0 against the crew's own gitignored non-empty `.worktrees/` (room #15 J3), killing post-deploy under `set -e` — a plain `add -A` never errors on ignored paths and the follow-up `git reset -q -- .worktrees/` keeps stray lock files out of main even on pre-gitignore-entry repos.
 - `test-worktree-backend.sh` — regression tests for the lifecycle script (validate, prepare/reuse, inspect, status, cleanup, idempotent cleanup, dirty-main preflight, integrate remote-reconcile with fixture sensitivity + no-remote fail-soft) on scratch repos
 - `test-version-write.sh` — regression tests for the escape-preserving step-8 version write in publish-npm.sh (fixture: current package.json with the \\u2014 escape; extracts the shipped block by anchor)
 - `test-publish-verify.sh` — regression tests for the retry-tolerant step-12 verification in publish-npm.sh (canary 5a027278): extracts the shipped block by anchor and runs it against a fake npm whose read replica lags (non-zero exits, then the old version, then the target) — requires convergence on success, fail-closed `PUBLISH_FAILED=verify` on exhaustion, and `--prefer-online` on every read
 - `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 task's project-scoped 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). Provenance is per-project (room #15 blocker 8): `--project-id` is required and every read/stamp is project-scoped. CLI: `--crew-home <path> --repo <path> --scaffold-sha <sha> --project-id <id> [--project-created]`.

package/lib/advance-publish-base.js

@@ -0,0 +1,271 @@
+#!/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-id <id> --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-id") out.projectId = 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, projectId, projectCreated } = parseArgv(
+    process.argv.slice(2)
+  );
+  if (!crewHome || !repo || !scaffoldSha || !projectId) {
+    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", JSON.stringify({ project_id: projectId })).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;
+    }
+    let stamped;
+    try {
+      stamped = crewApi(crewHome, "set-provenance", JSON.stringify({
+        project_id: projectId,
+        source_commit: scaffoldSha,
+        crew_release: crewRelease,
+      }));
+    } catch (e) {
+      console.error("set-provenance failed: " + (e.message || e));
+      process.exit(1);
+    }
+    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;
+  }
+
+  let stamped;
+  try {
+    stamped = crewApi(crewHome, "set-provenance", JSON.stringify({
+      project_id: projectId,
+      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 } : {}),
+    }));
+  } catch (e) {
+    console.error("set-provenance failed: " + (e.message || e));
+    process.exit(1);
+  }
+  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).
+  let recheck;
+  try {
+    recheck = crewApi(crewHome, "get-provenance", JSON.stringify({ project_id: projectId })).provenance;
+  } catch (e) {
+    console.error("post-stamp get-provenance failed: " + (e.message || e));
+    process.exit(1);
+  }
+  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");
+}