muse-crew 0.14.12 → 0.15.0

package/API.md

@@ -489,6 +489,8 @@ Register a new project.
 | `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. Omitted means auto-classify from `repo_path` (see surface classification below); an explicit value, including explicit `null`, always wins. |
+| `versioned_build` | boolean | no | Opt-in to the QA staleness gate (issue #3): when true, Integrate bumps `BUILD_NUMBER` in `version_file` after each merge (separate commit, pushed), and QA verifies the tested bundle's footer `build <n>` is at/past the recorded version before testing. Defaults to false (unversioned); the migration does not backfill. |
+| `version_file` | string or null | no | Repo-relative path of the TypeScript file exporting `BUILD_NUMBER` (e.g. `client/src/buildNumber.ts`). Only meaningful when `versioned_build` is true; defaults to `client/src/buildNumber.ts` when omitted. |
 
 **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.
 

package/docs/decisions/AGENTS.md

@@ -6,6 +6,12 @@ history lives here. One canonical section per `<a id>` anchor — a critic
 re-verified that every `docs/decisions/*.md#anchor` reference in
 `workflows/*.js` resolves (45 unique references).
 
+## dispatch-decision-log.md — Decision history: dispatch decision log (hoverboat)
+
+- `#checksum-vs-hoverboat` — The ferry-corruption problem and the two candidates
+- `#why-hoverboat-won` — Availability, trust, subtraction, primary-source rationale
+- `#what-was-built` — Declaration shape, skip counters, observer ingestion, retirements
+
 ## publish-path.md — Decision history: publish path
 
 - `#fire-and-forget-trigger` — Fire-and-forget trigger + workflow-owned observation

package/docs/decisions/dispatch-decision-log.md

@@ -0,0 +1,69 @@
+# Dispatch decision log (hoverboat) — 2026-09-24
+
+<a id="checksum-vs-hoverboat"></a>
+## The problem
+
+The Gate 2 observer attributed dispatch decisions by ferrying platform
+`scheduler.job_runs` rows through an LLM paste (tick worker: `muse.db`
+result → heredoc → `record_platform.sh --dispatch` → `dispatch_sample`
+rows → `attribute_dispatch.sh` → `dispatch_decision` rows). The paste
+mutated plausible values: a 2026-09-24 consistency scan found 275
+same-`run_id` contradictory `dispatch_sample` rows and 65 derived
+`dispatch_decision` rows based on corrupt data (5.7% of samples
+quarantined; 63.6% of ticks touched). The older `quarantine_suspects.sh`
+handled near-neighbor UUID mutations, not plausible value mutation.
+
+## The two candidates
+
+**Checksum ferry** (containment): keep the ferry; the worker checksums the
+raw tool-result JSON before the paste and `record_platform.sh` verifies
+after. Corrupt pastes become loud absences instead of silent corruption.
+
+**Hoverboat** (local declaration): the dispatcher writes its decision to
+`$CREW_HOME/.dispatch-decisions.jsonl` in its own bytes (deterministic JS,
+same courier shape as the proven §4b tick-release writer); the observer
+reads the file directly and verifies launch declarations mechanically
+against crew DB effects (`platform_run_tasks`, `dispatch_reservations`).
+
+<a id="why-hoverboat-won"></a>
+## Why hoverboat won
+
+1. **Availability.** Corruption touched ~63.6% of ticks. Checksum converts
+   corruption into absence, but the entry demo needs ten consecutive ticks
+   each recording a decision — absence fails the demo as surely as
+   corruption. Hoverboat's channel has no LLM re-emission at all.
+2. **Trust.** The checksum would be computed by the same worker agent that
+   corrupts the paste — asking the corrupting agent to honestly report its
+   own corruption. Hoverboat's declaration is composed by deterministic
+   workflow JS and checked against independent DB effects.
+3. **Subtraction.** Checksum keeps the ferry, the rolling 25h re-record
+   window, and the quarantine machinery permanently busy. Hoverboat deletes
+   the sample→decision attribution entirely; the platform ferry remains
+   only as platform-health telemetry.
+4. **The crew already knows.** Having the platform tell the observer what
+   the crew decided, through an LLM paste, when the crew can write it
+   directly, is the ferry. The declaration is the primary source; the DB
+   effects are the independent verification.
+
+Rejected alternative considered: a deterministic Crew API action for the
+write. It would not remove the agent from the path (workflows reach the
+CLI only through `agent()` shell calls), so it adds API surface for no
+integrity gain. The embedded courier is the proven seam.
+
+<a id="what-was-built"></a>
+## What was built
+
+- `workflows/crew-dispatch.js` §4c: per-tick declaration
+  `{seq, tick_seq, release, decision, launched[], completed[], parked[],
+  board{seen,eligible}, skipped{reason:count sparse}, partial}`.
+  `tick_seq` couples each line to the `.tick-releases.jsonl` line for the
+  same poll — a tick-release line with no decision line means the tick died
+  after poll-ack, visibly.
+- Per-reason ineligibility counters (`countSkipped`) at every skip site in
+  the eligibility loop + the simultaneity-limit skip, so stand-downs are
+  auditable without re-deriving eligibility.
+- Observer: `ingest_decisions.sh` replaces `attribute_dispatch.sh`;
+  `snapshot.sh` dispatch section rewritten around decision rows.
+- Retired: sample→decision attribution, `state/attributed.json` watermark.
+  Kept: `record_platform.sh --dispatch` as platform-health telemetry,
+  `quarantine_suspects.sh` for the health samples' ID mutations.

package/lib/crew-api.js

@@ -73,6 +73,21 @@ function validateEnvironmentType(value) {
   if (value === "artifact" || value === "terminal") return value;
   throw usageError("environment_type must be 'artifact', 'terminal', or null.");
 }
+// versioned_build validation: boolean. undefined means "not provided"
+// (create: defaults to false; update: leaves the field alone). Coerces
+// truthy/falsy to 1/0 for the INTEGER column.
+function validateVersionedBuild(value) {
+  if (value === undefined) return undefined;
+  return value ? 1 : 0;
+}
+// version_file validation: string or null. undefined means "not provided"
+// (create: defaults to null; update: leaves the field alone). Empty string
+// is rejected — use null to clear.
+function validateVersionFile(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === "string" && value.length > 0) return value;
+  throw usageError("version_file must be a non-empty string or null.");
+}
 
 // already_merged_sha validation (room #16 blocker 11, 2026-09-18): the
 // workflow-verified already-merged sha as structured session control state.
@@ -315,6 +330,24 @@ function openDb(crewHome) {
         if (!/duplicate column name/i.test(e.message)) throw e;
       }
     }
+    // Migration: add versioned_build + version_file columns if missing (QA
+    // staleness gate, emojimanegg1/muse-crew#3, 2026-09-24). Same idempotent
+    // PRAGMA-check pattern; versioned_build defaults 0 (unversioned by
+    // design, no backfill), version_file stays NULL.
+    if (!projectCols.some((c) => c.name === "versioned_build")) {
+      try {
+        db.exec("ALTER TABLE projects ADD COLUMN versioned_build INTEGER NOT NULL DEFAULT 0 CHECK (versioned_build IN (0, 1))");
+      } catch (e) {
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
+    if (!projectCols.some((c) => c.name === "version_file")) {
+      try {
+        db.exec("ALTER TABLE projects ADD COLUMN version_file TEXT");
+      } catch (e) {
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
     // Migration: per-project provenance columns (room #15 blocker 8,
     // 2026-09-18). Same idempotent PRAGMA-check pattern; ADD COLUMN without
     // a default leaves existing rows NULL, which is "no provenance yet" by
@@ -446,6 +479,9 @@ function mapProject(row) {
     // environment_type: 'artifact' | 'terminal' | null (unclassified).
     // Null stays null — no coercion, no default.
     environment_type: row.environment_type == null ? null : row.environment_type,
+    // versioned_build: 0/1 INTEGER → boolean. version_file: string or null.
+    versioned_build: !!row.versioned_build,
+    version_file: row.version_file == null ? null : row.version_file,
     created_at: row.created_at,
     updated_at: row.updated_at,
   };
@@ -3074,6 +3110,8 @@ commands["create-project"] = (db, args, ctx) => {
     quiesced: args.quiesced ? 1 : 0,
     visual_protocol: visualProtocol == null ? null : (visualProtocol ? 1 : 0),
     environment_type: environmentType,
+    versioned_build: validateVersionedBuild(args.versioned_build) ?? 0,
+    version_file: validateVersionFile(args.version_file),
     created_at: timestamp, updated_at: timestamp,
   };
   if (!Number.isInteger(row.simultaneity) || row.simultaneity < 1 || row.simultaneity > 100) {
@@ -3081,9 +3119,9 @@ commands["create-project"] = (db, args, ctx) => {
   }
   db.prepare(
     `INSERT INTO projects (id, display_name, repo_path, deploy_type, deploy_slug,
-      description, simultaneity, quiesced, visual_protocol, environment_type, created_at, updated_at)
+      description, simultaneity, quiesced, visual_protocol, environment_type, versioned_build, version_file, created_at, updated_at)
      VALUES (@id, @display_name, @repo_path, @deploy_type, @deploy_slug,
-      @description, @simultaneity, @quiesced, @visual_protocol, @environment_type, @created_at, @updated_at)`).run(row);
+      @description, @simultaneity, @quiesced, @visual_protocol, @environment_type, @versioned_build, @version_file, @created_at, @updated_at)`).run(row);
   // A deferred backfill (zero/ambiguous matches at the last look) gets one
   // more evaluation now that the match set changed: a new project whose
   // repo descends from the legacy commit inherits the attribution instead
@@ -3142,6 +3180,15 @@ commands["update-project"] = (db, args) => {
   if (args.environment_type !== undefined) {
     patch.environment_type = validateEnvironmentType(args.environment_type);
   }
+  // versioned_build / version_file are NOT covered by the context-change guard:
+  // like environment_type, they are read once from launch args at dispatch
+  // time, so a mid-run change only affects future launches.
+  if (args.versioned_build !== undefined) {
+    patch.versioned_build = validateVersionedBuild(args.versioned_build) ?? 0;
+  }
+  if (args.version_file !== undefined) {
+    patch.version_file = validateVersionFile(args.version_file);
+  }
 
   const contextChanged =
     (args.repo_path !== undefined && args.repo_path !== current.repo_path) ||

package/lib/schema.sql

@@ -46,6 +46,13 @@ CREATE TABLE IF NOT EXISTS projects (
   provenance_crew_release TEXT,
   provenance_published_at TEXT,
   provenance_task_id TEXT,
+  -- versioned_build: the QA staleness gate (emojimanegg1/muse-crew#3). When 1,
+  -- Integrate bumps the version file and QA verifies the tested bundle is at
+  -- or past the required version. version_file is the repo-relative path to
+  -- the TS file exporting BUILD_NUMBER. Both nullable/0 by design: existing
+  -- rows stay unversioned (no backfill).
+  versioned_build INTEGER NOT NULL DEFAULT 0 CHECK (versioned_build IN (0, 1)),
+  version_file TEXT,
   created_at    TEXT NOT NULL,
   updated_at    TEXT NOT NULL
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.14.12",
+  "version": "0.15.0",
   "description": "Opinionated orchestration for Muse — workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,

package/workflows/bugfix.js

@@ -563,6 +563,18 @@ function decideIntegrateRetry(o) {
   if (rec.malformed) return "park";
   return ancestor ? "skip-to-publish" : "proceed";
 }
+// QA version gate (issue #3): S=footer build, R=required. S>=R proves the
+// bundle is at/past the merge (single-branch: version order = containment).
+// Pure — pinned by tests/version-gate.test.js. Null = unreadable/missing.
+function decideVersionGate(S, R) {
+  if (!(R > 0)) return { proceed: false, reason: "qa-version-missing",
+    remedy: "no build version recorded — re-run Integrate or record dashboard-version." };
+  if (!(S > 0)) return { proceed: false, reason: "qa-version-unreadable",
+    remedy: "no readable build number in bundle footer — rebuild from versioned source." };
+  if (S >= R) return { proceed: true };
+  return { proceed: false, reason: "qa-bundle-stale",
+    remedy: "bundle build " + S + " behind required " + R + " — builder did not rebuild from current source." };
+}
 // On a dispatcher retry resumed at Integrate, the run-local releaseDecision
 // is null (Build doesn't re-run). Hydrate it from the merge record so the
 // npm Publish gate doesn't park a publishable merge. Pure — pinned by
@@ -1355,10 +1367,26 @@ while (i < STEPS.length) {
   // verdicts.jsonl). No parent verdict gate remains.
   var qaArtifact = false;
   var qaTerminal = false;
+  var qaRequiredVersion = null;
   if (step.name === "QA") {
     var qaExp = (await resolveExperiential()) === "yes";
     qaArtifact = qaExp && SURFACE_ARTIFACT;
     qaTerminal = qaExp && SURFACE_TERMINAL;
+    if (qaArtifact && projectConfig.versioned_build === true) {
+      var vfile = projectConfig.version_file || "client/src/buildNumber.ts";
+      var vgPre = await agent(
+        "Return ONLY JSON. 1. Run, return stdout verbatim:\n" + crewCmd("get-events", { task_id: taskId }) + "\n" +
+        "R = integer after `dashboard-version: ` in newest matching note. 2. If none, run, return stdout verbatim:\n" + crewCmd("get-provenance", { project_id: LAUNCH_PROJECT_ID }) + "\n" +
+        "R = BUILD_NUMBER from: cd " + REPO_PATH + " && git show <source_commit>:" + vfile + " | grep -o 'BUILD_NUMBER = [0-9]*'. If unknown: {\"ok\":false,\"park\":\"qa-version-missing: no build version recorded — re-run Integrate or record dashboard-version.\"}. " +
+        "3. cd " + REPO_PATH + " && git fetch origin && V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfile + " | grep -o '[0-9]*'|head -1); if [ $V -lt R ]; then git pull --ff-only; V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfile + " | grep -o '[0-9]*'|head -1); fi; " +
+        "if [ $V -lt R ]: {\"ok\":false,\"park\":\"qa-bundle-stale: checkout \" + V + \" < required \" + R + \" — sync past the merge, re-run QA.\"}. 4. Else {\"ok\":true,\"R\":R}.",
+        { key: "qa-version-pre-" + taskId, label: "QA version-gate pre-check",
+          schema: { type: "object", required: ["ok"],
+            properties: { ok: { type: "boolean" }, R: { type: "integer" }, park: { type: "string" } } } }
+      );
+      if (!vgPre.ok) return await parkTask(vgPre.park);
+      qaRequiredVersion = vgPre.R;
+    }
   }
 
   // Reproduce-layer routing (2026-09-16): Sage's Triage classifies the bug's
@@ -1687,6 +1715,14 @@ while (i < STEPS.length) {
       "R5-PUSH (manual R5 resolution only — the normal path pushed inline). Run: " + LIFECYCLE_ENV + LIFECYCLE + " push-target " + taskId + "\n" +
       "PUSHED — report the merged hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; PUSH_SKIPPED — no push attempted (no record + no lock); NO_REMOTE_PUSH — no remote; VERDICT: PASS; ERROR or CONFLICT — report it, VERDICT: FAIL.\n" +
       "NEVER force-push.\n\n" +
+      (projectConfig.versioned_build === true ?
+      "VERSION BUMP (issue #3): after MERGED+PUSHED, bump so QA can prove the bundle contains this fix — QA parks without it.\n" +
+      "1. cd " + REPO_PATH + " && git fetch origin; BR=<branch-from-integration-target>; F=" + (projectConfig.version_file || "client/src/buildNumber.ts") + "\n" +
+      "2. N=$(git show origin/$BR:$F | grep -o 'BUILD_NUMBER = [0-9]*' | grep -o '[0-9]*'); if missing/unparsable: VERDICT: FAIL.\n" +
+      "3. Edit $F: `export const BUILD_NUMBER = $N;` → `export const BUILD_NUMBER = $((N+1));` (keep header comment).\n" +
+      "4. git add $F && git commit -m \"build-number: $((N+1)) - QA version gate\" (SEPARATE commit, never amend).\n" +
+      "5. git push origin $BR; if rejected retry 3x (fetch, re-read N, re-bump, re-commit, push). NEVER force-push. Push MUST succeed or VERDICT: FAIL.\n" +
+      "6. Run, return stdout verbatim:\n" + crewCmd("log-event", { task_id: taskId, type: "note", identity: step.identity, message: "dashboard-version: <new> — QA must test a bundle built from source at or after the merge that recorded this (build <new> or later)." }) + "\n(substitute <new>).\n\n" : "") +
       "Report what happened at each step, ending with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
 
 } else if (step.name === "Publish") {
@@ -2140,6 +2176,8 @@ while (i < STEPS.length) {
         "c3. Start with: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ shot — READ the screenshot, log the step. Act on what you see: click, scroll, type, then re-observe, logging each step. Prefer aria (cheap text) to find controls; screenshot when the view changes and for your final verdict frames (one desktop, one mobile). If a click exits non-zero, do NOT retry the same ref blindly: re-run aria first (refs go stale between invocations), then click the fresh ref exactly once. If it still fails, log the failure and move on — a flaky control is a finding, not a loop.\n" +
         "d. Reach: with the session protocol, any flow reachable by N in-page actions is drivable — open the dialog, then confirm it, then judge the result. Without a session (one-shot invocations), anything reachable by (navigate, one action) is testable and sequences needing prior in-page state are not — use a session for those. Report NOT POSSIBLE only when the tooling itself fails (session-start exits 3): a flow you could not reach is not NOT POSSIBLE — name the exact step that stopped you in verdict.json's missing evidence and continue with the mechanical checks.\n" +
         "e. Judge as a user against the task description: is the reported bug fixed AND is nothing else visibly broken? Look for broken layout, overflow, missing or wrong content, stale data, and console errors. Compare against the task's expected behavior, never against source code (you are code-blind). Every frame you captured is already archived under " + crewHome + "/task-evidence/" + taskId + "/postchange/ and indexed in ooda-log.jsonl. A frame you did not read is not evidence. Loading, error, or blank frames never pass. If you cannot complete the loop, say exactly which steps are missing — unknown is not PASS.\n" +
+        (projectConfig.versioned_build === true ?
+        "e2. VERSION (issue #3): footer shows `build <n>` — report `footer_build: <n>` on its own line, or `footer_build: unreadable`. Required — the gate cannot pass without it.\n" : "") +
         "f. Kill ONLY the server you started: pkill -f 'serve-artifact[.]js.*--tag " + taskId + "-qa' — never another task's server. (The [.] keeps pkill from matching its own command line.) Do not leave it running.\n" +
         "Then continue with the mechanical checks below. Your VERDICT covers both the visual and the mechanical checks.\n\n" +
         "MECHANICAL CHECKS:\n" +
@@ -2622,6 +2660,20 @@ while (i < STEPS.length) {
   // reports FAIL, it stands — finding attribution informs follow-up
   // filing only.
   if (step.name === "QA") {
+    if (projectConfig.versioned_build === true && qaArtifact && qaRequiredVersion !== null) {
+      var vgM = /footer_build:\s*(\d+|unreadable)/i.exec(workerText || "");
+      var vgS = (vgM && /^\d+$/.test(vgM[1])) ? parseInt(vgM[1], 10) : null;
+      var vgD = decideVersionGate(vgS, qaRequiredVersion);
+      if (!vgD.proceed) {
+        return await parkTask(vgD.reason + ": " + vgD.remedy + " [built=" + vgS + " required=" + qaRequiredVersion + "]");
+      }
+      await agent(
+        "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
+          task_id: taskId, type: "note", identity: step.identity,
+          message: "version-check: built=" + vgS + " >= required=" + qaRequiredVersion + " → testing now" }),
+        { key: "record-version-check-" + taskId, label: "Recording version-gate pass" }
+      );
+    }
     var contentFindings = extractContentFindings(workerText);
     if (!contentFindings.ok) {
       // Unknown attribution fails closed: a missing or malformed

package/workflows/crew-dispatch.js

@@ -476,7 +476,13 @@ for (var pi = 0; pi < projects.length; pi++) {
     // The user-facing surface for experiential QA routing (artifact |
     // terminal | null=unclassified). Carried alongside deploy_type — it is a
     // separate axis, not a redeclaration of the deployment target.
-    environment_type: proj.environment_type || null
+    environment_type: proj.environment_type || null,
+    // QA staleness gate (emojimanegg1/muse-crew#3): versioned_build opts the
+    // project into the Integrate version bump + QA bundle-freshness gate;
+    // version_file is the repo-relative path of the TS file exporting
+    // BUILD_NUMBER (null when unversioned).
+    versioned_build: !!proj.versioned_build,
+    version_file: proj.version_file || null
   };
 }
 
@@ -561,6 +567,12 @@ const eligible = [];
 const retryCandidates = [];
 const rejectionCandidates = [];
 
+// Dispatch-decision log (2026-09-24): per-reason ineligibility counters for
+// the .dispatch-decisions.jsonl declaration. Sparse — only non-zero keys are
+// emitted. Additive only; the eligibility decisions below are unchanged.
+var decisionSkipped = {};
+function countSkipped(reason) { decisionSkipped[reason] = (decisionSkipped[reason] || 0) + 1; }
+
 // ── Retry cap ────────────────────────────────────────────────────────
 // Symphony owns phase-redispatch policy (coordination layer): the spec
 // defines backoff but no attempt cap ("implementation-defined"), so the
@@ -591,12 +603,13 @@ var MAX_CONSECUTIVE_REJECTIONS = configInt(config, "maxConsecutiveRejections", 2
 
 for (var t = 0; t < allTasks.length; t++) {
   var task = allTasks[t];
-  if (task.blocked) continue;
+  if (task.blocked) { countSkipped("blocked"); continue; }
 
   // Skip tasks with an active dispatch reservation: the worker launched a
   // workflow for this task on a previous tick, but the workflow has not yet
   // self-claimed (claims can take 15+ minutes for cron-launched runs).
   if (reservedTaskIds.has(task.id)) {
+    countSkipped("reserved");
     log("Skipped \"" + task.title + "\" — active dispatch reservation (workflow launched, claim pending)");
     continue;
   }
@@ -604,6 +617,7 @@ for (var t = 0; t < allTasks.length; t++) {
   // Skip tasks from quiesced projects
   var taskProject = task.project || DEFAULT_PROJECT;
   if (quiescedProjects[taskProject]) {
+    countSkipped("quiesced");
     log("Skipped \"" + task.title + "\" — project " + taskProject + " is quiesced");
     continue;
   }
@@ -614,6 +628,7 @@ for (var t = 0; t < allTasks.length; t++) {
   // task never moves. Set repo_path via updateproject to re-enable.
   var taskProjCfg = PROJECTS[taskProject];
   if (!taskProjCfg || !taskProjCfg.repo_path) {
+    countSkipped("no_repo");
     log("Skipped \"" + task.title + "\" — project " + taskProject + " has no repo_path configured");
     continue;
   }
@@ -633,12 +648,14 @@ for (var t = 0; t < allTasks.length; t++) {
   // (clears) next_phase on its successful self-claim, exactly once.
   if (task.next_phase) {
     if (task.state !== "todo" && task.state !== "in_progress") {
+      countSkipped("next_phase_state");
       log("Skipped \"" + task.title + "\" — next_phase \"" + task.next_phase + "\" set but state is " + task.state + "; left set for inspection");
       continue;
     }
-    if (latest && latest.status === "running") continue; // work in flight
+    if (latest && latest.status === "running") { countSkipped("in_flight"); continue; } // work in flight
     var npIdx = steps.indexOf(task.next_phase);
     if (npIdx < 0) {
+      countSkipped("next_phase_bad_step");
       log("Skipped \"" + task.title + "\" — next_phase \"" + task.next_phase + "\" not in " + workflow + " step registry; left set for a corrected recover-task");
       continue;
     }
@@ -654,19 +671,20 @@ for (var t = 0; t < allTasks.length; t++) {
     continue;
   }
 
-  if (task.state !== "in_progress") continue;
+  if (task.state !== "in_progress") { countSkipped("terminal_state"); continue; }
 
   if (!latest) {
     eligible.push({ task: task, startStep: 0, reason: "no_session", workflow: workflow });
     continue;
   }
 
-  if (latest.status === "running") continue; // work in flight
+  if (latest.status === "running") { countSkipped("in_flight"); continue; } // work in flight
 
   if (latest.status === "completed") {
     var stepName = latest.step || "";
     var stepIndex = steps.indexOf(stepName);
     if (stepIndex < 0) {
+      countSkipped("unknown_step");
       log("Skipped \"" + task.title + "\" — step \"" + stepName + "\" not in " + workflow + " step registry");
       continue;
     }
@@ -695,6 +713,7 @@ for (var t = 0; t < allTasks.length; t++) {
     var failedStep = latest.step || "";
     var retryIdx = steps.indexOf(failedStep);
     if (retryIdx < 0) {
+      countSkipped("unknown_step");
       log("Skipped \"" + task.title + "\" — step \"" + failedStep + "\" not in " + workflow + " step registry");
       continue;
     }
@@ -756,6 +775,7 @@ if (rejectionCandidates.length > 0) {
 // the task stays retryable and is re-parked next tick, so this is
 // fail-safe. The dashboard stamps retry_reset_at on parked→todo, which
 // restarts both counters mechanically.
+var parkedTaskIds = [];
 if (parkJobs.length > 0) {
   var parkSteps = [];
   for (var pji = 0; pji < parkJobs.length; pji++) {
@@ -775,6 +795,7 @@ if (parkJobs.length > 0) {
       { key: "park-batch", label: "Parking " + parkJobs.length + " task(s) at retry cap" }
     );
     log("Parked " + parkJobs.length + " task(s)");
+    parkedTaskIds = parkJobs.map(function(pj) { return pj.task.id; });
   } catch (parkErr) {
     log("WARNING: park batch failed (" + (parkErr.message || String(parkErr)).slice(0, 200) + ") — tasks remain retryable");
   }
@@ -959,6 +980,7 @@ for (var ei = 0; ei < eligible.length; ei++) {
     toProcess.push(eitem);
     inFlightByProject[ep] = current + 1;
   } else {
+    countSkipped("at_limit");
     log("Skipped \"" + eitem.task.title + "\" — project " + ep + " at simultaneity limit (" + limit + ")");
   }
 }
@@ -1164,6 +1186,63 @@ if (recommended.length > 0) {
   recommended = acquired;
 }
 
+// ── 4c. Dispatch-decision log ──────────────────────────────────
+// Hoverboat (2026-09-24): the dispatcher declares its own decision, in its
+// own bytes, on crew-home disk — one append-only line per completed tick in
+// $CREW_HOME/.dispatch-decisions.jsonl. The observer reads the file
+// directly (no LLM re-emission, no platform ferry), so the plausible-value
+// mutation that poisoned the old dispatch_sample attribution cannot occur.
+// Launch declarations are verified mechanically against crew DB effects
+// (platform_run_tasks / dispatch_reservations); a stand-down is the
+// dispatcher's explicit declaration with board context, auditable without
+// re-deriving eligibility. tick_seq couples each line to the .tick-releases
+// line for the same poll — a tick-release line with no decision line means
+// the tick died after poll-ack and is visible as such.
+// seq is the non-empty line count + 1 of this file (file order is the
+// proof — no wall-clock calls, see tests/determinism.test.js).
+// Fire-and-forget: the script swallows its own errors and exits 0, the
+// agent call carries no schema, and the whole call is wrapped in
+// try/catch — a failed write can never fail the tick. The script echoes
+// the appended line (same rooms #12–#14 empty-result contract as §4b).
+var dispatchDecisionScript = [
+  "var crewHome=process.argv[1];",
+  "var decisionJson=process.argv[2];",
+  "try{",
+  "var fs=require(\"fs\"),path=require(\"path\");",
+  "var decision=JSON.parse(decisionJson);",
+  "if(!decision||typeof decision.decision!==\"string\"||!Array.isArray(decision.launched)){throw new Error(\"bad decision payload\");}",
+  "var release=path.basename(path.resolve(crewHome,fs.readlinkSync(path.join(crewHome,\"current\"))));",
+  "var file=path.join(crewHome,\".dispatch-decisions.jsonl\");",
+  "var count=0;",
+  "try{var lines=fs.readFileSync(file,\"utf8\").split(\"\\n\");for(var i=0;i<lines.length;i++){if(lines[i].trim()!==\"\"){count++;}}}catch(e){}",
+  "var tickSeq=0;",
+  "try{var tlines=fs.readFileSync(path.join(crewHome,\".tick-releases.jsonl\"),\"utf8\").split(\"\\n\");for(var j=0;j<tlines.length;j++){if(tlines[j].trim()!==\"\"){tickSeq++;}}}catch(e){}",
+  "var line=JSON.stringify({seq:count+1,tick_seq:tickSeq,release:release,decision:decision.decision,launched:decision.launched,completed:decision.completed||[],parked:decision.parked||[],board:decision.board||null,skipped:decision.skipped||{},partial:!!decision.partial});",
+  "fs.appendFileSync(file,line+\"\\n\");",
+  "process.stdout.write(line+\"\\n\");",
+  "}catch(e){}",
+  "process.exit(0);"
+].join("");
+var launchedRecs = recommended.map(function(r) { return { task_id: r.task_id, workflow: r.workflow, step: r.step }; });
+var decisionObj = {
+  decision: launchedRecs.length > 0 ? "launch" : "stand_down",
+  launched: launchedRecs,
+  completed: completed.map(function(r) { return r.task_id; }),
+  parked: parkedTaskIds,
+  board: { seen: allTasks.length, eligible: eligible.length },
+  skipped: decisionSkipped,
+  partial: partial
+};
+var dispatchDecisionCmd = "node -e '" + dispatchDecisionScript + "' '" + crewHome.replace(/'/g, "'\\''") + "' '" + JSON.stringify(decisionObj).replace(/'/g, "'\\''") + "'";
+try {
+  await agent(
+    "Record this tick's dispatch decision.\nRun in shell and return the stdout verbatim:\n" + dispatchDecisionCmd,
+    { key: "dispatch-decision", label: "Recording dispatch decision" }
+  );
+} catch (e) {
+  log("WARNING: dispatch-decision log write failed (tick continues): " + e.message);
+}
+
 var msg = "Dispatch complete.";
 if (recommended.length > 0) {
   msg += " Recommended: " + recommended.map(function(r) { return r.workflow + "/" + r.step + " for " + r.task_id; }).join(", ") + ".";

package/workflows/standard.js

@@ -571,6 +571,18 @@ function decideIntegrateRetry(o) {
   if (rec.malformed) return "park";
   return ancestor ? "skip-to-publish" : "proceed";
 }
+// QA version gate (issue #3): S=footer build, R=required. S>=R proves the
+// bundle is at/past the merge (single-branch: version order = containment).
+// Pure — pinned by tests/version-gate.test.js. Null = unreadable/missing.
+function decideVersionGate(S, R) {
+  if (!(R > 0)) return { proceed: false, reason: "qa-version-missing",
+    remedy: "no build version recorded — re-run Integrate or record dashboard-version." };
+  if (!(S > 0)) return { proceed: false, reason: "qa-version-unreadable",
+    remedy: "no readable build number in bundle footer — rebuild from versioned source." };
+  if (S >= R) return { proceed: true };
+  return { proceed: false, reason: "qa-bundle-stale",
+    remedy: "bundle build " + S + " behind required " + R + " — builder did not rebuild from current source." };
+}
 // On a dispatcher retry resumed at Integrate, the run-local releaseDecision
 // is null (Build doesn't re-run). Hydrate it from the merge record so the
 // npm Publish gate doesn't park a publishable merge. Pure — pinned by
@@ -1300,6 +1312,22 @@ while (i < STEPS.length) {
   var qaExperiential = false;
   if (step.name === "QA") {
     qaExperiential = (await resolveExperiential()) === "yes" && SURFACE_CLASSIFIED;
+    var qaRequiredVersion = null;
+    if (qaExperiential && SURFACE_ARTIFACT && projectConfig.versioned_build === true) {
+      var vfileStd = projectConfig.version_file || "client/src/buildNumber.ts";
+      var vgPreStd = await agent(
+        "Return ONLY JSON. 1. Run, return stdout verbatim:\n" + crewCmd("get-events", { task_id: taskId }) + "\n" +
+        "R = integer after `dashboard-version: ` in newest matching note. 2. If none, run, return stdout verbatim:\n" + crewCmd("get-provenance", { project_id: LAUNCH_PROJECT_ID }) + "\n" +
+        "R = BUILD_NUMBER from: cd " + REPO_PATH + " && git show <source_commit>:" + vfileStd + " | grep -o 'BUILD_NUMBER = [0-9]*'. If unknown: {\"ok\":false,\"park\":\"qa-version-missing: no build version recorded — re-run Integrate or record dashboard-version.\"}. " +
+        "3. cd " + REPO_PATH + " && git fetch origin && V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfileStd + " | grep -o '[0-9]*'|head -1); if [ $V -lt R ]; then git pull --ff-only; V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfileStd + " | grep -o '[0-9]*'|head -1); fi; " +
+        "if [ $V -lt R ]: {\"ok\":false,\"park\":\"qa-bundle-stale: checkout \" + V + \" < required \" + R + \" — sync past the merge, re-run QA.\"}. 4. Else {\"ok\":true,\"R\":R}.",
+        { key: "qa-version-pre-" + taskId, label: "QA version-gate pre-check",
+          schema: { type: "object", required: ["ok"],
+            properties: { ok: { type: "boolean" }, R: { type: "integer" }, park: { type: "string" } } } }
+      );
+      if (!vgPreStd.ok) return await parkTask(vgPreStd.park);
+      qaRequiredVersion = vgPreStd.R;
+    }
   }
 
   // Step-specific instructions
@@ -1576,6 +1604,14 @@ while (i < STEPS.length) {
       "R5-PUSH (manual R5 resolution only — the normal path pushed inline). Run: " + LIFECYCLE_ENV + LIFECYCLE + " push-target " + taskId + "\n" +
       "PUSHED — report the merged hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; PUSH_SKIPPED — no push attempted (no record + no lock); NO_REMOTE_PUSH — no remote; VERDICT: PASS; ERROR or CONFLICT — report it, VERDICT: FAIL.\n" +
       "NEVER force-push.\n\n" +
+      (projectConfig.versioned_build === true ?
+      "VERSION BUMP (issue #3): after MERGED+PUSHED, bump so QA can prove the bundle contains this fix — QA parks without it.\n" +
+      "1. cd " + REPO_PATH + " && git fetch origin; BR=<branch-from-integration-target>; F=" + (projectConfig.version_file || "client/src/buildNumber.ts") + "\n" +
+      "2. N=$(git show origin/$BR:$F | grep -o 'BUILD_NUMBER = [0-9]*' | grep -o '[0-9]*'); if missing/unparsable: VERDICT: FAIL.\n" +
+      "3. Edit $F: `export const BUILD_NUMBER = $N;` → `export const BUILD_NUMBER = $((N+1));` (keep header comment).\n" +
+      "4. git add $F && git commit -m \"build-number: $((N+1)) - QA version gate\" (SEPARATE commit, never amend).\n" +
+      "5. git push origin $BR; if rejected retry 3x (fetch, re-read N, re-bump, re-commit, push). NEVER force-push. Push MUST succeed or VERDICT: FAIL.\n" +
+      "6. Run, return stdout verbatim:\n" + crewCmd("log-event", { task_id: taskId, type: "note", identity: step.identity, message: "dashboard-version: <new> — QA must test a bundle built from source at or after the merge that recorded this (build <new> or later)." }) + "\n(substitute <new>).\n\n" : "") +
       "Report what happened at each step, ending with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
 
 } else if (step.name === "Publish") {
@@ -2029,6 +2065,8 @@ while (i < STEPS.length) {
         "c3. Start with: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ shot — READ the screenshot, log the step. Act on what you see: click, scroll, type, then re-observe, logging each step. Prefer aria (cheap text) to find controls; screenshot when the view changes and for your final verdict frames (one desktop, one mobile). If a click exits non-zero, do NOT retry the same ref blindly: re-run aria first (refs go stale between invocations), then click the fresh ref exactly once. If it still fails, log the failure and move on — a flaky control is a finding, not a loop.\n" +
         "d. Reach: with the session protocol, any flow reachable by N in-page actions is drivable — open the deck, then click Study, then judge the study view. Without a session (one-shot invocations), anything reachable by (navigate, one action) is testable and sequences needing prior in-page state are not — use a session for those. Report NOT POSSIBLE only when the tooling itself fails (session-start exits 3): a flow you could not reach is not NOT POSSIBLE — name the exact step that stopped you in verdict.json's missing evidence and judge what you did reach.\n" +
         "e. Judge as a user against the task description: does the change render correctly? Look for broken layout, overflow, missing or wrong content, stale data, and console errors. Compare against the task's expected behavior, never against source code (you are code-blind). Every frame you captured is already archived under " + crewHome + "/task-evidence/" + taskId + "/postchange/ and indexed in ooda-log.jsonl. A frame you did not read is not evidence. Loading, error, or blank frames never pass. If you cannot complete the loop, say exactly which steps are missing — unknown is not PASS.\n" +
+        (projectConfig.versioned_build === true ?
+        "e2. VERSION (issue #3): footer shows `build <n>` — report `footer_build: <n>` on its own line, or `footer_build: unreadable`. Required — the gate cannot pass without it.\n" : "") +
         "f. Kill ONLY the server you started: pkill -f 'serve-artifact[.]js.*--tag " + taskId + "-qa' — never another task's server. (The [.] keeps pkill from matching its own command line.) Do not leave it running.\n" +
         "Then continue with the mechanical checks below. Your VERDICT covers both the visual and the mechanical checks.\n\n" +
         "STEP 2: Verify data integrity via the crew API.\n" +
@@ -2374,6 +2412,20 @@ while (i < STEPS.length) {
   // reports FAIL, it stands — finding attribution informs follow-up
   // filing only.
   if (step.name === "QA") {
+    if (projectConfig.versioned_build === true && SURFACE_ARTIFACT && qaRequiredVersion !== null) {
+      var vgM = /footer_build:\s*(\d+|unreadable)/i.exec(workerText || "");
+      var vgS = (vgM && /^\d+$/.test(vgM[1])) ? parseInt(vgM[1], 10) : null;
+      var vgD = decideVersionGate(vgS, qaRequiredVersion);
+      if (!vgD.proceed) {
+        return await parkTask(vgD.reason + ": " + vgD.remedy + " [built=" + vgS + " required=" + qaRequiredVersion + "]");
+      }
+      await agent(
+        "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
+          task_id: taskId, type: "note", identity: step.identity,
+          message: "version-check: built=" + vgS + " >= required=" + qaRequiredVersion + " → testing now" }),
+        { key: "record-version-check-" + taskId, label: "Recording version-gate pass" }
+      );
+    }
     var contentFindings = extractContentFindings(workerText);
     if (!contentFindings.ok) {
       // Unknown attribution fails closed: a missing or malformed