muse-crew 0.14.13 → 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/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.13",
+  "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
   };
 }
 

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