superbee 0.4.2-pre.1 → 0.4.2-pre.2

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.2-pre.1" }, source: { commit: "04faac2c7e20ffa33e5738fc471e941484303ce8", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.2-pre.2" }, source: { commit: "baa7ac9c51c8c91ae3a17579f19910dddd6a406e", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -9475,6 +9475,26 @@ var init_mutation = __esm({
   }
 });
 
+// ../core/src/managed-document-metadata.ts
+function isManagedDocumentMetadataField(field) {
+  return MANAGED_DOCUMENT_METADATA_FIELDS.has(field);
+}
+var MANAGED_DOCUMENT_METADATA_FIELDS;
+var init_managed_document_metadata = __esm({
+  "../core/src/managed-document-metadata.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    MANAGED_DOCUMENT_METADATA_FIELDS = /* @__PURE__ */ new Set([
+      "generated",
+      "verified",
+      "superbee_updated_by",
+      "actor",
+      "timestamp"
+    ]);
+  }
+});
+
 // ../core/src/kinds.ts
 function isConventionId(id) {
   return id.startsWith(CONVENTIONS_PREFIX);
@@ -9616,18 +9636,32 @@ function projectKindForAuthoring(okfVersion, kind2) {
     }
   };
 }
+function isKindFieldValidationWarning(warning) {
+  return warning.code === "KIND_FIELD_MISSING" || warning.code === "KIND_FIELD_VALUE" || warning.code === "KIND_FIELD_ARITY";
+}
+function kindFieldWarningPrefix(code3, kind2, field) {
+  switch (code3) {
+    case "KIND_FIELD_MISSING":
+      return `'${kind2.governs}' requires a non-empty '${field}' field `;
+    case "KIND_FIELD_VALUE":
+      return `'${field}' value `;
+    case "KIND_FIELD_ARITY":
+      return `'${field}' is enum-restricted and takes exactly ONE value for '${kind2.governs}'; `;
+  }
+}
 function projectKindValidationWarnings(okfVersion, kind2, warnings) {
   const progress = progressStatusCoordinate(okfVersion, kind2);
   if (!progress) return warnings;
-  const stored = `'${progress.storageField}'`;
-  const logical = `'${progress.logicalField}'`;
-  return warnings.map((warning) => warning.field === progress.storageField ? {
-    ...warning,
-    field: progress.logicalField,
-    // Core's Kind warnings name the field first. Replace that one coordinate only; a later
-    // occurrence may be the user's literal value and must remain byte-truthful.
-    message: warning.message.replace(stored, logical)
-  } : warning);
+  return warnings.map((warning) => {
+    if (!isKindFieldValidationWarning(warning) || warning.field !== progress.storageField) return warning;
+    const storedPrefix = kindFieldWarningPrefix(warning.code, kind2, progress.storageField);
+    const logicalPrefix = kindFieldWarningPrefix(warning.code, kind2, progress.logicalField);
+    return {
+      ...warning,
+      field: progress.logicalField,
+      message: warning.message.startsWith(storedPrefix) ? logicalPrefix + warning.message.slice(storedPrefix.length) : warning.message
+    };
+  });
 }
 function isPlainObject2(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
@@ -10111,7 +10145,7 @@ function validateAgainstKind(doc2, kind2) {
     if (!hasOwn2(fm, field) || !isPresent(fm[field])) {
       warnings.push({
         code: "KIND_FIELD_MISSING",
-        message: `'${kind2.governs}' requires a non-empty '${field}' field (declared by ${kind2.id}).`,
+        message: kindFieldWarningPrefix("KIND_FIELD_MISSING", kind2, field) + `(declared by ${kind2.id}).`,
         field,
         severity: "warning"
       });
@@ -10124,7 +10158,7 @@ function validateAgainstKind(doc2, kind2) {
     if (Array.isArray(raw)) {
       warnings.push({
         code: "KIND_FIELD_ARITY",
-        message: `'${field}' is enum-restricted and takes exactly ONE value for '${kind2.governs}'; got ${raw.length} (${raw.map((v2) => String(v2)).join(", ")}).`,
+        message: kindFieldWarningPrefix("KIND_FIELD_ARITY", kind2, field) + `got ${raw.length} (${raw.map((v2) => String(v2)).join(", ")}).`,
         field,
         severity: "warning"
       });
@@ -10135,7 +10169,7 @@ function validateAgainstKind(doc2, kind2) {
       if (!allowedStrs.includes(v2)) {
         warnings.push({
           code: "KIND_FIELD_VALUE",
-          message: `'${field}' value '${v2}' is not one of the allowed values for '${kind2.governs}': ${allowedStrs.join(", ")}.`,
+          message: kindFieldWarningPrefix("KIND_FIELD_VALUE", kind2, field) + `'${v2}' is not one of the allowed values for '${kind2.governs}': ${allowedStrs.join(", ")}.`,
           field,
           severity: "warning"
         });
@@ -10295,7 +10329,7 @@ function assertOrdinaryPatch(existing, proposed) {
   }
 }
 function assertAssignmentName(field) {
-  if (managed.has(field)) throw new InvalidInputError(`'${field}' is managed metadata and cannot be assigned by a field action.`);
+  if (isManagedDocumentMetadataField(field)) throw new InvalidInputError(`'${field}' is managed metadata and cannot be assigned by a field action.`);
   if (field === "tags" || field === "sources") throw new InvalidInputError(`'${field}' requires an explicit collection add/remove/replace-all action.`);
 }
 function prepareDocumentAssignments(existing, assignments) {
@@ -10369,7 +10403,7 @@ function prepareDocumentFieldAction(existing, action, context) {
         ...context.okfVersion === "0.2" ? v02 : [],
         ...kind2 ? kindInputFieldNames(context.okfVersion, kind2) : []
       ])].filter((field) => {
-        if (managed.has(field) || field === "tags" || field === "sources") return false;
+        if (isManagedDocumentMetadataField(field) || field === "tags" || field === "sources") return false;
         if (context.okfVersion === "0.1" && (field === "stale_after" || field === "usage_window")) return false;
         const storage = kind2 && resolveKindFieldCoordinate(context.okfVersion, kind2, field);
         return !containsCollection(existing.frontmatter[storage?.storageField ?? field]);
@@ -10512,12 +10546,13 @@ function prepareDocumentFieldAction(existing, action, context) {
   if (scope.outcome !== "unchanged" && context.okfVersion === "0.1") candidate.frontmatter.timestamp = (context.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
   return { candidate, scope, storageField };
 }
-var FieldActionError, managed, standard, v02;
+var FieldActionError, standard, v02;
 var init_document_field_actions = __esm({
   "../core/src/document-field-actions.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    init_managed_document_metadata();
     init_errors();
     init_okf_authored_values();
     init_kinds();
@@ -10530,7 +10565,6 @@ var init_document_field_actions = __esm({
         this.details = details;
       }
     };
-    managed = /* @__PURE__ */ new Set(["generated", "verified", "superbee_updated_by", "actor", "timestamp"]);
     standard = /* @__PURE__ */ new Set(["title", "description", "type", "resource"]);
     v02 = /* @__PURE__ */ new Set(["status", "stale_after", "usage_window"]);
   }
@@ -10801,6 +10835,14 @@ function validateCandidate(id, candidate, registry2, strict, okfVersion, now, ex
   }
   return result3;
 }
+function validateUnchangedDocument(existing, registry2, strict, okfVersion) {
+  const kind2 = registry2.kinds.get(String(existing.frontmatter.type));
+  const warnings = kind2 ? validateAgainstKind(existing, kind2) : [];
+  if (strict && kind2 && warnings.length > 0) {
+    throw new KindConformanceError(existing.id, kind2.governs, warnings, okfVersion);
+  }
+  return warnings;
+}
 function withV02Metadata(candidate, existing, okfVersion, registry2, now, seedGenerationClock, actor, compareTimestamp, producer) {
   if (okfVersion !== "0.2") return candidate;
   const kind2 = registry2.kinds.get(String(candidate.frontmatter.type));
@@ -10848,7 +10890,7 @@ function prepareDocumentMutationCandidate(existing, rawCandidate, opts) {
     opts.okfVersion === "0.2" && persistActor && opts.actor !== void 0,
     opts.registry.kinds.get(String(comparison.frontmatter.type))?.fields.required.includes("actor") ?? false
   )) {
-    return { candidate: { frontmatter: structuredClone(existing.frontmatter), body: existing.body }, changed: false, warnings: [] };
+    return { candidate: { frontmatter: structuredClone(existing.frontmatter), body: existing.body }, changed: false, warnings: validateUnchangedDocument(existing, opts.registry, opts.strict, opts.okfVersion) };
   }
   const candidate = attributeCandidate(comparison, opts.actor, persistActor, opts.okfVersion, opts.registry);
   const { warnings } = validateCandidate(opts.id, candidate, opts.registry, opts.strict, opts.okfVersion, decisionNow, existing);
@@ -10992,6 +11034,17 @@ async function mutateDocument(opts) {
           okfVersion,
           opts.registry
         );
+        if (existing && isNoopMutation(
+          existing,
+          candidate,
+          compareTimestamp,
+          okfVersion,
+          persistActor && opts.actor !== void 0,
+          opts.registry.kinds.get(String(candidate.frontmatter.type))?.fields.required.includes("actor") ?? false
+        )) {
+          warnings = validateUnchangedDocument(existing, opts.registry, opts.strict, okfVersion);
+          return { action: "done", result: { doc: existing } };
+        }
         const validated = validateCandidate(
           opts.id,
           candidate,
@@ -11005,16 +11058,6 @@ async function mutateDocument(opts) {
         if (!opts.strict && existing && warnings.length > 0 && conforms(existing, opts.registry)) {
           throw new KindConformanceError(opts.id, validated.kind.governs, warnings, okfVersion);
         }
-        if (existing && isNoopMutation(
-          existing,
-          candidate,
-          compareTimestamp,
-          okfVersion,
-          persistActor && opts.actor !== void 0,
-          validated.kind?.fields.required.includes("actor") ?? false
-        )) {
-          return { action: "done", result: { doc: existing } };
-        }
         return { action: "write", next: { id: opts.id, ...candidate }, result: {} };
       },
       write: async (next, expectedVersion) => {
@@ -11056,7 +11099,7 @@ async function mutateDocument(opts) {
         compareTimestamp,
         seedGenerationClock: seedClock
       });
-      if (!changed) return { action: "done", result: { doc: existing, warnings: [] } };
+      if (!changed) return { action: "done", result: { doc: existing, warnings } };
       return { action: "write", next: { id: opts.id, ...candidate }, result: { warnings } };
     },
     write: async (next, expectedVersion) => {
@@ -11070,7 +11113,7 @@ async function mutateDocument(opts) {
     maxAttempts: hardCas ? 1 : maxAttempts
   });
   const scoped = { ...scope ? { scope } : {}, ...scopes ? { scopes } : {} };
-  return outcome.wrote ? { doc: savedDoc, changed: true, version: outcome.version, warnings: outcome.result.warnings, ...scoped } : { doc: outcome.result.doc, changed: false, version: outcome.version, warnings: [], ...scoped };
+  return outcome.wrote ? { doc: savedDoc, changed: true, version: outcome.version, warnings: outcome.result.warnings, ...scoped } : { doc: outcome.result.doc, changed: false, version: outcome.version, warnings: outcome.result.warnings, ...scoped };
 }
 var DEFAULT_MAX_ATTEMPTS, KindConformanceError, DocumentNotFoundError;
 var init_document_mutation = __esm({
@@ -11727,6 +11770,7 @@ var init_src = __esm({
     init_document_field_actions();
     init_document_mutation();
     init_kind_field_mutation();
+    init_managed_document_metadata();
   }
 });
 
@@ -11749,6 +11793,16 @@ function hasRejectedReason(text5, reasons) {
   }
   return false;
 }
+function hasLostRefLock(text5) {
+  for (const line2 of text5.split("\n")) {
+    const lower = line2.toLowerCase();
+    const remote = lower.indexOf("[remote rejected]");
+    if (remote !== -1 && lower.indexOf("(incorrect old value provided)", remote) !== -1) return true;
+    const at = lower.indexOf("cannot lock ref");
+    if (at !== -1 && lower.indexOf("but expected", at) !== -1) return true;
+  }
+  return false;
+}
 function hasUnmergeableOriginRef(text5) {
   const suffix = " - not something we can merge";
   for (const line2 of text5.split("\n")) {
@@ -11790,7 +11844,7 @@ ${f2.stdout}`;
       { details: { op: op2, retryable: true } }
     );
   }
-  if (op2 === "push" && (hasRejectedReason(text5, ["fetch first", "non-fast-forward"]) || /Updates were rejected because (?:the remote contains work|the tip of your current branch is behind)/i.test(text5))) {
+  if (op2 === "push" && (hasRejectedReason(text5, ["fetch first", "non-fast-forward"]) || /Updates were rejected because (?:the remote contains work|the tip of your current branch is behind)/i.test(text5) || hasLostRefLock(text5))) {
     return new BoardGitError(
       "TRANSIENT",
       "a teammate pushed to the board at the same time \u2014 re-run sync to incorporate their changes and retry",
@@ -11930,6 +11984,68 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import path6 from "node:path";
+function isBoardBranchName(name) {
+  return name === BOARD_BRANCH || name.length <= 100 && NAMED_BOARD_BRANCH.test(name) && !RESERVED_BOARD_LIKE_BRANCHES.has(name);
+}
+function declaredBoardBranchAtRef(dir, ref) {
+  const entry = runGit(dir, ["ls-tree", "-z", ref, "--", BOARD_MARKER_FILE]);
+  if (entry.status !== 0 || !/^100644 blob [0-9a-f]+\t\.superbee-board\.json\0$/.test(entry.stdout)) return null;
+  const size = runGit(dir, ["cat-file", "-s", `${ref}:${BOARD_MARKER_FILE}`]);
+  if (size.status !== 0 || Number(size.stdout.trim()) > BOARD_MARKER_BYTES) return null;
+  const shown2 = runGit(dir, ["show", `${ref}:${BOARD_MARKER_FILE}`]);
+  if (shown2.status !== 0) return null;
+  try {
+    const parsed2 = JSON.parse(shown2.stdout);
+    if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2)) return null;
+    const { schema, branch } = parsed2;
+    if (schema !== BOARD_MARKER_SCHEMA || typeof branch !== "string") return null;
+    return branch !== BOARD_BRANCH && isBoardBranchName(branch) ? branch : null;
+  } catch {
+    return null;
+  }
+}
+function isDeclaredBoardBranch(dir, branch) {
+  if (branch === BOARD_BRANCH) return declaredBoardBranchAtRef(dir, `refs/heads/${BOARD_BRANCH}`) === null;
+  if (!isBoardBranchName(branch)) return false;
+  return declaredBoardBranchAtRef(dir, `refs/heads/${branch}`) === branch;
+}
+function namedBoardRecoveryHelp(dir, branch) {
+  const restore = `restore ${BOARD_MARKER_FILE} with {"schema": ${BOARD_MARKER_SCHEMA}, "branch": "${branch}"} in a new commit (git log -- ${BOARD_MARKER_FILE} shows who changed it)`;
+  if (declaredBoardBranchAtRef(dir, `refs/remotes/${BOARD_REMOTE}/${branch}`) === branch) {
+    return `${BOARD_REMOTE}/${branch} still declares the board: git pull --rebase ${BOARD_REMOTE} ${branch} restores ${BOARD_MARKER_FILE} here, then re-run sync`;
+  }
+  return `git fetch ${BOARD_REMOTE} ${branch}; if ${BOARD_REMOTE}/${branch} declares the board again, git pull --rebase ${BOARD_REMOTE} ${branch} restores the marker, otherwise ${restore}; then re-run sync`;
+}
+function rebaseStartBranch(dir) {
+  for (const state of ["rebase-merge", "rebase-apply"]) {
+    const headNamePath = path6.join(worktreeGitPath(dir, state), "head-name");
+    if (!existsSync2(headNamePath)) continue;
+    try {
+      const name = readFileSync4(headNamePath, "utf8").trim();
+      if (name.startsWith("refs/heads/")) return name.slice("refs/heads/".length);
+    } catch {
+    }
+  }
+  return null;
+}
+function boardBranchOf(boardPath) {
+  const attached = runGit(boardPath, ["symbolic-ref", "-q", "--short", "HEAD"]);
+  const name = attached.status === 0 ? attached.stdout.trim() : rebaseStartBranch(boardPath);
+  if (name === null || name === BOARD_BRANCH || !isBoardBranchName(name)) return BOARD_BRANCH;
+  if (isDeclaredBoardBranch(boardPath, name)) return name;
+  if (!hasTrackedBundleRootAtRef(boardPath, `refs/heads/${name}`)) return BOARD_BRANCH;
+  throw new BoardGitError(
+    "CONFLICT",
+    `this checkout is on the named board branch '${name}', but its tip no longer declares it: ${BOARD_MARKER_FILE} is missing or names another branch \u2014 sync will not guess which board to use`,
+    {
+      details: { path: boardPath, state: "named-board-undeclared", branch: name },
+      help: namedBoardRecoveryHelp(boardPath, name)
+    }
+  );
+}
+function boardRefOf(boardPath) {
+  return `${BOARD_REMOTE}/${boardBranchOf(boardPath)}`;
+}
 function recognizedBundlePath(name, sourcePath) {
   try {
     const link4 = lstatSync(sourcePath);
@@ -12168,28 +12284,32 @@ function hasTrackedBundleRootAtRef(top, ref) {
 function hasTrackedBundleRootAtHead(top) {
   return hasTrackedBundleRootAtRef(top, "HEAD");
 }
-function boardBranchTracksOrigin(top) {
-  const remote = runGit(top, ["config", "--get", `branch.${BOARD_BRANCH}.remote`]);
-  const merge2 = runGit(top, ["config", "--get", `branch.${BOARD_BRANCH}.merge`]);
-  return remote.status === 0 && remote.stdout.trim() === BOARD_REMOTE && merge2.status === 0 && merge2.stdout.trim() === `refs/heads/${BOARD_BRANCH}`;
+function boardBranchTracksOrigin(top, branch = BOARD_BRANCH) {
+  const remote = runGit(top, ["config", "--get", `branch.${branch}.remote`]);
+  const merge2 = runGit(top, ["config", "--get", `branch.${branch}.merge`]);
+  return remote.status === 0 && remote.stdout.trim() === BOARD_REMOTE && merge2.status === 0 && merge2.stdout.trim() === `refs/heads/${branch}`;
 }
-function standaloneHistoryBase(top) {
-  const r2 = runGit(top, ["merge-base", `refs/heads/${BOARD_BRANCH}`, `refs/remotes/${BOARD_REF}`]);
+function standaloneHistoryBase(top, branch = BOARD_BRANCH) {
+  const r2 = runGit(top, ["merge-base", `refs/heads/${branch}`, `refs/remotes/${BOARD_REMOTE}/${branch}`]);
   return r2.status === 0 && r2.stdout.trim().length > 0 ? r2.stdout.trim() : null;
 }
 function resolveStandaloneBoardCheckout(dir, opts = {}) {
   const top = repoTopLevel(dir);
-  if (!top || currentBranch(top) !== BOARD_BRANCH) return null;
-  if (!hasTrackedBundleRootAtRef(top, `refs/heads/${BOARD_BRANCH}`) || !boardBranchTracksOrigin(top)) return null;
-  const remote = runGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]);
+  if (!top) return null;
+  const branch = currentBranch(top);
+  if (!isDeclaredBoardBranch(top, branch)) return null;
+  if (!hasTrackedBundleRootAtRef(top, `refs/heads/${branch}`) || !boardBranchTracksOrigin(top, branch)) return null;
+  const remote = runGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REMOTE}/${branch}`]);
   if (remote.status !== 0) return opts.requireRemoteRef === false ? top : null;
-  return standaloneHistoryBase(top) ? top : null;
+  return standaloneHistoryBase(top, branch) ? top : null;
 }
 function isRecoverableStandaloneBoardCheckout(dir) {
   const top = repoTopLevel(dir);
-  if (!top || !detectStaleRebase(top) || !rebaseWasFromBoardBranch(top)) return false;
-  if (!hasTrackedBundleRootAtRef(top, `refs/heads/${BOARD_BRANCH}`) || !boardBranchTracksOrigin(top)) return false;
-  return standaloneHistoryBase(top) !== null;
+  if (!top || !detectStaleRebase(top)) return false;
+  const branch = rebaseStartBranch(top);
+  if (branch === null || !isDeclaredBoardBranch(top, branch)) return false;
+  if (!hasTrackedBundleRootAtRef(top, `refs/heads/${branch}`) || !boardBranchTracksOrigin(top, branch)) return false;
+  return standaloneHistoryBase(top, branch) !== null;
 }
 function resolveProvisionedBoardPath(dir, hostPolicy) {
   const policy = captureBoardHostPolicy(hostPolicy);
@@ -12200,13 +12320,24 @@ function resolveProvisionedBoardPath(dir, hostPolicy) {
   return conventionalProvisionedBoardPath(top, policy);
 }
 function standaloneRootWrongBranch(top, branch) {
+  const stray = branch === BOARD_BRANCH ? declaredBoardBranchAtRef(top, `refs/heads/${BOARD_BRANCH}`) : null;
+  if (stray !== null) {
+    return new BoardGitError(
+      "CONFLICT",
+      `this '${BOARD_BRANCH}' checkout's tip carries ${BOARD_MARKER_FILE} declaring the named board '${stray}' \u2014 a named board's marker does not belong on the default board, so sync will not publish this tree`,
+      {
+        details: { path: top, state: "default-board-carries-named-marker", branch, declares: stray },
+        help: `if this clone is the named board, rename it back (git branch -m ${stray} and track ${BOARD_REMOTE}/${stray}); otherwise remove the stray marker (git rm ${BOARD_MARKER_FILE} && git commit; git log -- ${BOARD_MARKER_FILE} shows who added it), then re-run sync`
+      }
+    );
+  }
   const shown2 = branch === "HEAD" ? "detached HEAD" : `'${branch}'`;
   return new BoardGitError(
     "CONFLICT",
-    `this repository root is an OKF bundle, but it is checked out at ${shown2}; a standalone root checkout may sync only when it is attached to the dedicated '${BOARD_BRANCH}' branch`,
+    `this repository root is an OKF bundle, but it is checked out at ${shown2}; a standalone root checkout may sync only when it is attached to the dedicated '${BOARD_BRANCH}' branch or to a named board branch (board-<name>) whose committed ${BOARD_MARKER_FILE} declares that name`,
     {
       details: { path: top, state: "standalone-board-wrong-branch", branch },
-      help: `use a separate checkout attached to '${BOARD_BRANCH}', or run sync from the repository's code checkout and let it provision the conventional bundle worktree`
+      help: branch !== BOARD_BRANCH && isBoardBranchName(branch) ? namedBoardRecoveryHelp(top, branch) : `use a separate checkout attached to '${BOARD_BRANCH}' (or to the named board branch), or run sync from the repository's code checkout and let it provision the conventional bundle worktree`
     }
   );
 }
@@ -12439,11 +12570,13 @@ function provisionBoardWorktree(dir, budget = {}, hostPolicy) {
   if (!top) return { kind: "no_repo" };
   const rootIsBundle = hasTrackedBundleRootAtHead(top);
   const rootBranch = rootIsBundle ? currentBranch(top) : void 0;
-  if (rootBranch !== void 0 && rootBranch !== BOARD_BRANCH) {
+  if (rootBranch !== void 0 && !isDeclaredBoardBranch(top, rootBranch)) {
     throw standaloneRootWrongBranch(top, rootBranch);
   }
-  const rootOriginBefore = rootBranch === BOARD_BRANCH ? runGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]) : null;
-  const rootCheckout = rootBranch === BOARD_BRANCH ? resolveStandaloneBoardCheckout(top, { requireRemoteRef: false }) : null;
+  const branch = rootBranch ?? BOARD_BRANCH;
+  const remoteRef = `refs/remotes/${BOARD_REMOTE}/${branch}`;
+  const rootOriginBefore = rootBranch !== void 0 ? runGit(top, ["rev-parse", "--verify", "--quiet", remoteRef]) : null;
+  const rootCheckout = rootBranch !== void 0 ? resolveStandaloneBoardCheckout(top, { requireRemoteRef: false }) : null;
   const rootCachedBaseline = rootCheckout !== null && rootOriginBefore?.status === 0 ? rootOriginBefore.stdout.trim() : null;
   const bundleDir = bundleDirNameForProject(top);
   const boardPath = path6.join(top, bundleDir);
@@ -12475,13 +12608,13 @@ function provisionBoardWorktree(dir, budget = {}, hostPolicy) {
       "ls-remote",
       "--exit-code",
       BOARD_REMOTE,
-      `refs/heads/${BOARD_BRANCH}`
+      `refs/heads/${branch}`
     ]);
     if (probe?.status === 0) {
       const children = runGit(top, [
         "for-each-ref",
         "--format=%(refname)",
-        `refs/remotes/${BOARD_REF}/`
+        `${remoteRef}/`
       ]);
       let namespaceReady = children.status === 0;
       for (const child of children.stdout.split("\n").filter(Boolean)) {
@@ -12493,7 +12626,7 @@ function provisionBoardWorktree(dir, budget = {}, hostPolicy) {
           "--prune",
           "--no-tags",
           BOARD_REMOTE,
-          `+refs/heads/${BOARD_BRANCH}:refs/remotes/${BOARD_REF}`
+          `+refs/heads/${branch}:${remoteRef}`
         ]);
         remoteState = fetch2?.status === 0 ? "absent" : "unknown";
         liveFetch = fetch2?.status === 0;
@@ -12502,23 +12635,23 @@ function provisionBoardWorktree(dir, budget = {}, hostPolicy) {
       }
     } else if (probe?.status === 2) {
       remoteBoardKnownAbsent = true;
-      runGit(top, ["update-ref", "-d", `refs/remotes/${BOARD_REF}`]);
+      runGit(top, ["update-ref", "-d", remoteRef]);
     } else {
       remoteState = "unknown";
     }
   }
-  const localBoard = runGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${BOARD_BRANCH}`]);
-  const remoteBoard = runGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]);
+  const localBoard = runGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+  const remoteBoard = runGit(top, ["rev-parse", "--verify", "--quiet", remoteRef]);
   const hasLocal = localBoard.status === 0;
   const hasRemote = remoteBoard.status === 0 && !remoteBoardKnownAbsent;
-  if (rootIsBundle && rootBranch === BOARD_BRANCH) {
+  if (rootIsBundle && rootBranch !== void 0) {
     if (remoteState === "unknown" && !liveFetch) {
       return { kind: "no_board", remoteState: "unknown" };
     }
     const standaloneCheckout = hasRemote ? resolveStandaloneBoardCheckout(top) : null;
     if (standaloneCheckout !== null) {
       const fetchedOrigin = remoteBoard.stdout.trim();
-      const originBaseline = rootCachedBaseline !== null ? rootCachedBaseline === fetchedOrigin ? null : rootCachedBaseline : standaloneHistoryBase(top);
+      const originBaseline = rootCachedBaseline !== null ? rootCachedBaseline === fetchedOrigin ? null : rootCachedBaseline : standaloneHistoryBase(top, branch);
       return originBaseline === null ? { kind: "already", boardPath: top } : { kind: "already", boardPath: top, originBaseline };
     }
     return { kind: "local_board", boardPath: top, remoteExists: hasRemote };
@@ -12953,13 +13086,14 @@ ${bodyLines2.join("\n")}
 }
 function fetchRebaseResolving(boardPath, exportDir) {
   mustGit(boardPath, ["fetch", "--prune", BOARD_REMOTE], { timeoutMs: NETWORK_TIMEOUT_MS });
-  if (runGit(boardPath, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]).status !== 0) {
+  const boardRef = boardRefOf(boardPath);
+  if (runGit(boardPath, ["rev-parse", "--verify", "--quiet", `refs/remotes/${boardRef}`]).status !== 0) {
     return { status: "no_upstream" };
   }
   const idFlags = identityFlags(boardPath);
-  const r2 = runGit(boardPath, [...idFlags, "rebase", BOARD_REF], { rebase: true, timeoutMs: NETWORK_TIMEOUT_MS });
+  const r2 = runGit(boardPath, [...idFlags, "rebase", boardRef], { rebase: true, timeoutMs: NETWORK_TIMEOUT_MS });
   if (r2.status === 0) return { status: "clean" };
-  if (!detectStaleRebase(boardPath)) throw classifyGitError(failureOf(["rebase", BOARD_REF], r2));
+  if (!detectStaleRebase(boardPath)) throw classifyGitError(failureOf(["rebase", boardRef], r2));
   const listConflicted = () => mustGit(boardPath, ["diff", "--name-only", "-z", "--diff-filter=U"]).split("\0").filter((l) => l.length > 0);
   const byPath = /* @__PURE__ */ new Map();
   try {
@@ -12998,8 +13132,8 @@ function fetchRebaseResolving(boardPath, exportDir) {
             }
           }
         }
-        if (runGit(boardPath, ["cat-file", "-e", `refs/remotes/${BOARD_REF}:${relPath}`]).status === 0) {
-          mustGit(boardPath, ["checkout", BOARD_REF, "--", relPath]);
+        if (runGit(boardPath, ["cat-file", "-e", `refs/remotes/${boardRef}:${relPath}`]).status === 0) {
+          mustGit(boardPath, ["checkout", boardRef, "--", relPath]);
           mustGit(boardPath, ["add", "--", relPath]);
         } else {
           mustGit(boardPath, ["rm", "-f", "--", relPath]);
@@ -13026,8 +13160,9 @@ function fetchRebaseResolving(boardPath, exportDir) {
   }
   return { status: "resolved", conflicts: [...byPath.values()] };
 }
-function push(boardPath) {
-  mustGit(boardPath, ["push", BOARD_REMOTE, BOARD_BRANCH], { timeoutMs: NETWORK_TIMEOUT_MS });
+function push(boardPath, commit, branch = boardBranchOf(boardPath)) {
+  const refspec = commit === void 0 ? branch : `${commit}:refs/heads/${branch}`;
+  mustGit(boardPath, ["push", BOARD_REMOTE, refspec], { timeoutMs: NETWORK_TIMEOUT_MS });
 }
 function pushBoardUpstream(top) {
   mustGit(top, ["push", "-u", BOARD_REMOTE, BOARD_BRANCH], { timeoutMs: NETWORK_TIMEOUT_MS });
@@ -13121,7 +13256,7 @@ function ffPull(boardPath, budget = {}) {
     if (fetched.status !== 0) {
       fetchReason = swallowReason(classifyGitError(failureOf(["fetch", "--prune"], fetched)));
     }
-    const merged = runGit(boardPath, ["merge", "--ff-only", BOARD_REF]);
+    const merged = runGit(boardPath, ["merge", "--ff-only", boardRefOf(boardPath)]);
     if (merged.status !== 0) {
       const text5 = `${merged.stderr}
 ${merged.stdout}`;
@@ -13143,10 +13278,11 @@ ${merged.stdout}`;
   }
 }
 function unpushedCount(boardPath) {
-  if (runGit(boardPath, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]).status !== 0) {
+  const boardRef = boardRefOf(boardPath);
+  if (runGit(boardPath, ["rev-parse", "--verify", "--quiet", `refs/remotes/${boardRef}`]).status !== 0) {
     return null;
   }
-  const out = mustGit(boardPath, ["rev-list", "--count", `${BOARD_REF}..HEAD`]).trim();
+  const out = mustGit(boardPath, ["rev-list", "--count", `${boardRef}..HEAD`]).trim();
   const n = Number.parseInt(out, 10);
   return Number.isFinite(n) ? n : 0;
 }
@@ -13177,7 +13313,7 @@ function readDocBytesAtRef(dir, ref, relPath) {
   }
   return shown2.stdout;
 }
-var BOARD_BRANCH, BOARD_REMOTE, BOARD_REF, BUNDLE_DIR, LEGACY_BUNDLE_DIR, BUNDLE_DIRS, RELATIVE_WORKTREE_CONFIG, SCRUBBED_GIT_VARS, LOCAL_TIMEOUT_MS, NETWORK_TIMEOUT_MS, IDENTITY_FALLBACK_ACTOR, IGNORABLE_BOARD_DIR_ENTRIES, UNKNOWN2, MAX_REBASE_STOPS, GITIGNORE_ENTRIES;
+var BOARD_BRANCH, BOARD_REMOTE, BOARD_REF, BOARD_MARKER_FILE, BOARD_MARKER_SCHEMA, BOARD_MARKER_BYTES, NAMED_BOARD_BRANCH, RESERVED_BOARD_LIKE_BRANCHES, BUNDLE_DIR, LEGACY_BUNDLE_DIR, BUNDLE_DIRS, RELATIVE_WORKTREE_CONFIG, SCRUBBED_GIT_VARS, LOCAL_TIMEOUT_MS, NETWORK_TIMEOUT_MS, IDENTITY_FALLBACK_ACTOR, IGNORABLE_BOARD_DIR_ENTRIES, UNKNOWN2, MAX_REBASE_STOPS, GITIGNORE_ENTRIES;
 var init_porcelain = __esm({
   "../board-git/src/porcelain.ts"() {
     "use strict";
@@ -13190,6 +13326,11 @@ var init_porcelain = __esm({
     BOARD_BRANCH = "board";
     BOARD_REMOTE = "origin";
     BOARD_REF = `${BOARD_REMOTE}/${BOARD_BRANCH}`;
+    BOARD_MARKER_FILE = ".superbee-board.json";
+    BOARD_MARKER_SCHEMA = 1;
+    BOARD_MARKER_BYTES = 4 * 1024;
+    NAMED_BOARD_BRANCH = /^board-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+    RESERVED_BOARD_LIKE_BRANCHES = /* @__PURE__ */ new Set(["board-cleanup"]);
     BUNDLE_DIR = ".superbee";
     LEGACY_BUNDLE_DIR = ".agentstate-lite";
     BUNDLE_DIRS = [BUNDLE_DIR, LEGACY_BUNDLE_DIR];
@@ -13223,7 +13364,7 @@ function localBranchExists(top, name) {
   return runGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`]).status === 0;
 }
 function resolveOriginRef(boardPath) {
-  const r2 = runGit(boardPath, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]);
+  const r2 = runGit(boardPath, ["rev-parse", "--verify", "--quiet", `refs/remotes/${boardRefOf(boardPath)}`]);
   return r2.status === 0 ? r2.stdout.trim() : null;
 }
 function hasLocalOnlyBundle(dir) {
@@ -13932,7 +14073,10 @@ function hasStandaloneBoardSignature(p2) {
   try {
     if (!statSync3(path10.join(p2, ".git")).isDirectory()) return false;
     if (!statSync3(path10.join(p2, "index.md")).isFile()) return false;
-    return readFileSync6(path10.join(p2, ".git", "HEAD"), "utf8").trim() === `ref: refs/heads/${BOARD_BRANCH}`;
+    const head = readFileSync6(path10.join(p2, ".git", "HEAD"), "utf8").trim();
+    if (head === `ref: refs/heads/${BOARD_BRANCH}`) return true;
+    const branch = head.startsWith("ref: refs/heads/") ? head.slice("ref: refs/heads/".length) : "";
+    return isBoardBranchName(branch) && statSync3(path10.join(p2, BOARD_MARKER_FILE)).isFile();
   } catch {
     return false;
   }
@@ -14386,6 +14530,7 @@ var init_errors4 = __esm({
       NO_UPSTREAM: EXIT.RUNTIME,
       GIT_BUSY: EXIT.RUNTIME,
       CONFLICT: EXIT.CONFLICT,
+      GATE_FAILED: EXIT.CONFLICT,
       CREDENTIAL_STORE_UNAVAILABLE: EXIT.RUNTIME
     };
     CliError = class extends Error {
@@ -17189,7 +17334,7 @@ var init_command_spec = __esm({
             id: "sync",
             leaves: [publicLeaf("sync", "sync", zero, 22, DIR_SYNC_SURFACE)],
             usage: "sync [--establish [--yes] | --pull-only | --show-incoming <id> [--out <file> | --body-out <file>] | --inspect --doc <id> [--out <file>] | --resolve keep|take|revise --doc <id> | --restore-deletes | --accept-deletes <token> | --take-host-deletions <token>] [--dir <path>] [--limit <n>]",
-            summary: "Share the board branch with a remote \u2014 commits, pulls, and pushes (git tier; --pull-only skips commit+push). The remote repository must already exist: Superbee does not create it. After confirming the repository exists and origin/board does not, --establish is the separate explicit act that creates/pushes the board branch; it needs repository-specific push capability and branch-create policy clearance. If origin/board exists, plain `sync` joins it. Works both from a project's conventional bundle worktree and from a standalone clone whose tracked OKF root is attached to the shared board branch. A bundle folder already committed on the code branch is the same flag's hard case: preview first, --yes executes, and the folder's removal from the code branch rides a prepared side-branch commit you push and open as a PR. A bundle committed with code and NO board branch anywhere is the IN-TREE mode (read-side): full sync refuses (sharing rides your normal commit/push), --pull-only fetches the branch's tracking upstream and reports incoming board docs ('git pull' delivers them), and --establish converts to a dedicated board branch. A doc changed on both sides converges: teammate's version kept, yours exported; --show-incoming <id> (exclusive with --pull-only) prints the incoming version as of the last fetch; --inspect --doc <id> and --resolve keep|take|revise --doc <id> settle that saved conflict with the same verbs as a hosted checkout. Board-reading commands (list/doc read/status/home/link show) auto-run the ff-only pull when board state is >~5m stale \u2014 silent, bounded (~2s), never a push; SUPERBEE_NO_AUTOPULL=<any value, even 0> disables it. Hosted checkout (a folder made by `checkout`): sync instead sends each edited file as one whole document under your own access and refreshes documents changed on the host, with one row per document (committed, conflict, held, refused, unknown, paused; non-zero exit until all are committed). A change to one document and a host change to another both land; a document changed on both sides is never merged but comes back as a conflict, resolved with --inspect --doc <id> then --resolve keep|take|revise --doc <id> (a resolution is recorded, then sent by the next plain sync). A held mass delete is accepted only by the person, typing the count in their own terminal (--accept-deletes); --restore-deletes puts the files back; --take-host-deletions takes a mass deletion the pull refused."
+            summary: "Share the board branch with a remote \u2014 commits, pulls, and pushes (git tier; --pull-only skips commit+push). The remote repository must already exist: Superbee does not create it. After confirming the repository exists and origin/board does not, --establish is the separate explicit act that creates/pushes the board branch; it needs repository-specific push capability and branch-create policy clearance. If origin/board exists, plain `sync` joins it. Works both from a project's conventional bundle worktree and from a standalone clone whose tracked OKF root is attached to the shared board branch; a named board-<name> branch that commits a .superbee-board.json declaring that name is a second board in the same repository, synced from its own standalone clone against origin/board-<name>. A bundle folder already committed on the code branch is the same flag's hard case: preview first, --yes executes, and the folder's removal from the code branch rides a prepared side-branch commit you push and open as a PR. A bundle committed with code and NO board branch anywhere is the IN-TREE mode (read-side): full sync refuses (sharing rides your normal commit/push), --pull-only fetches the branch's tracking upstream and reports incoming board docs ('git pull' delivers them), and --establish converts to a dedicated board branch. A doc changed on both sides converges: teammate's version kept, yours exported; --show-incoming <id> (exclusive with --pull-only) prints the incoming version as of the last fetch; --inspect --doc <id> and --resolve keep|take|revise --doc <id> settle that saved conflict with the same verbs as a hosted checkout. A clone may declare a pre-push gate with git config superbee.syncGate '<command>': it runs on the rebased tree before every push that sends commits, and a failure holds the push (work committed locally, exit 5, code GATE_FAILED). A push that loses a race to another writer re-fetches, rebases, re-gates and retries (up to 5 attempts) and is reported as a race, never as a permission problem. Board-reading commands (list/doc read/status/home/link show) auto-run the ff-only pull when board state is >~5m stale \u2014 silent, bounded (~2s), never a push; SUPERBEE_NO_AUTOPULL=<any value, even 0> disables it. Hosted checkout (a folder made by `checkout`): sync instead sends each edited file as one whole document under your own access and refreshes documents changed on the host, with one row per document (committed, conflict, held, refused, unknown, paused; non-zero exit until all are committed). A change to one document and a host change to another both land; a document changed on both sides is never merged but comes back as a conflict, resolved with --inspect --doc <id> then --resolve keep|take|revise --doc <id> (a resolution is recorded, then sent by the next plain sync). A held mass delete is accepted only by the person, typing the count in their own terminal (--accept-deletes); --restore-deletes puts the files back; --take-host-deletions takes a mass deletion the pull refused."
           }
         ]
       },
@@ -19191,7 +19336,9 @@ duplication \u2014 a plain overwrite that converges to the same on-disk state).
 
 If a declared Kind governs the document type, prefer 'superbee new "<Kind>" <id> ...'; its
 authoring is strict and create-only. Use 'doc write' for a generic type or a deliberate full
-replacement.
+replacement. Kind validation is advisory by default: violations appear as warnings, including on
+no-ops. --strict rejects violations without writing. A changed replacement of a previously conforming
+document cannot be nonconforming, even in advisory mode.
 
 Options:
   --type <t>           OKF concept type (non-empty)                          [required]
@@ -19252,6 +19399,10 @@ Only the fields you pass change; everything else \u2014 including the body when
 is preserved verbatim. Idempotent: a patch that changes NOTHING (ignoring the auto-refreshed
 timestamp) converges to changed:false (no write, no timestamp refresh).
 
+Standard-field patches use advisory Kind validation by default, returning warnings even on no-ops;
+--strict rejects violations without writing. Dynamic declared fields are always strict: passing a
+--<field> flag requires the whole resulting document to satisfy its Kind, even for a same-value patch.
+
 Options:
   --title <t>            Replace the title
   --description <d>      Replace the description
@@ -19507,7 +19658,7 @@ function buildCompletingUpdateCommand(id, violations, kind2, okfVersion) {
   const flags = [];
   for (const violation of violations) {
     const field = violation.field;
-    if (!field || seen.has(field) || !declaredFields.has(field)) continue;
+    if (!isKindFieldValidationWarning(violation) || !field || seen.has(field) || !declaredFields.has(field)) continue;
     seen.add(field);
     const allowed = kind2.fields.values[field];
     const placeholder = allowed && allowed.length > 0 ? commandToken(`<${allowed.join("|")}>`) : commandLiteral("<value>");
@@ -19722,6 +19873,7 @@ async function translateMutationError(error51, opts) {
 }
 async function mutateDoc(opts) {
   try {
+    let okfVersion;
     const result3 = await mutateDocument({
       ...opts.seedGenerationClock === void 0 ? {} : { seedGenerationClock: opts.seedGenerationClock },
       bundle: opts.bundle,
@@ -19731,7 +19883,8 @@ async function mutateDoc(opts) {
       strict: opts.strict,
       buildCandidate: opts.buildCandidate,
       input: opts.input,
-      assertCandidate: (existing, candidate) => {
+      assertCandidate: (existing, candidate, context) => {
+        okfVersion = context.okfVersion;
         if (existing) guardBodyReplace(opts.bundle, existing, candidate.body, opts.bodyReplace);
       },
       onAbsent: opts.onAbsent,
@@ -19742,7 +19895,8 @@ async function mutateDoc(opts) {
       expectedVersion: opts.expectedVersion
     });
     if (result3.changed) await firePostPersist(opts.onPersisted);
-    return result3;
+    const kind2 = opts.registry.kinds.get(String(result3.doc.frontmatter.type));
+    return kind2 && result3.warnings.length > 0 ? { ...result3, warnings: projectKindValidationWarnings(okfVersion, kind2, result3.warnings) } : result3;
   } catch (error51) {
     return await translateMutationError(error51, opts);
   }
@@ -29069,8 +29223,9 @@ async function gitBoardAt(canonicalRoot) {
   if (top === null) return null;
   if (top === canonicalRoot) {
     const branch2 = gitText(top, ["symbolic-ref", "-q", "--short", "HEAD"]);
-    if (branch2 !== BOARD_BRANCH) return null;
-    const upstream2 = gitText(top, ["for-each-ref", "--format=%(upstream:short)", `refs/heads/${branch2}`]) ?? (gitText(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]) === null ? null : BOARD_REF);
+    if (branch2 === null || !isDeclaredBoardBranch(top, branch2)) return null;
+    const boardRef = `${BOARD_REMOTE}/${branch2}`;
+    const upstream2 = gitText(top, ["for-each-ref", "--format=%(upstream:short)", `refs/heads/${branch2}`]) ?? (gitText(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${boardRef}`]) === null ? null : boardRef);
     return { channel: "branch", branch: branch2, upstream: upstream2, shared: upstream2 !== null, top, prefix: "" };
   }
   let committed;
@@ -30075,9 +30230,10 @@ async function loadClaimPolicy(boardPath) {
     const bundle = configuredBundle(boardPath);
     const [registry2, okfVersion] = await Promise.all([loadKinds(bundle), readBundleOkfVersion2(bundle)]);
     if (registry2.kinds.size === 0) return INACTIVE_POLICY;
+    const upstreamRef = boardRefOf(boardPath);
     const resolved = /* @__PURE__ */ new Map();
     return {
-      provenance: `${BOARD_UPSTREAM_REF}@${originSha}`,
+      provenance: `${upstreamRef}@${originSha}`,
       forType(type) {
         const name = typeof type === "string" ? type.trim() : "";
         if (name === "") return void 0;
@@ -30088,7 +30244,7 @@ async function loadClaimPolicy(boardPath) {
         return resolved.get(name);
       },
       upstreamFrontmatter(relPath) {
-        const shown2 = runGit(boardPath, ["show", `${BOARD_UPSTREAM_REF}:${relPath}`]);
+        const shown2 = runGit(boardPath, ["show", `${upstreamRef}:${relPath}`]);
         if (shown2.status !== 0) return void 0;
         try {
           return parseMarkdown(shown2.stdout, relPath).frontmatter;
@@ -30112,7 +30268,7 @@ function claimLostStatement(owner, provenance2) {
   const who = owner === void 0 ? CLAIM_NO_OWNER_RECORDED : `owner is ${owner}`;
   return `${who} as of ${provenance2}; ${CLAIM_NOT_ARBITRATED}`;
 }
-var CLAIM_LOST_KEY, CLAIM_NOT_ARBITRATED, CLAIM_NO_OWNER_RECORDED, BOARD_UPSTREAM_REF, ENGINE_STAMPED_FIELDS, INACTIVE_POLICY;
+var CLAIM_LOST_KEY, CLAIM_NOT_ARBITRATED, CLAIM_NO_OWNER_RECORDED, ENGINE_STAMPED_FIELDS, INACTIVE_POLICY;
 var init_claim_conflict = __esm({
   "../cli/src/commands/sync/claim-conflict.ts"() {
     "use strict";
@@ -30124,7 +30280,6 @@ var init_claim_conflict = __esm({
     CLAIM_LOST_KEY = "claim_lost";
     CLAIM_NOT_ARBITRATED = "your claim was not arbitrated";
     CLAIM_NO_OWNER_RECORDED = "no owner is recorded";
-    BOARD_UPSTREAM_REF = `${BOARD_REMOTE}/${BOARD_BRANCH}`;
     ENGINE_STAMPED_FIELDS = /* @__PURE__ */ new Set([
       "timestamp",
       "generated",
@@ -30465,11 +30620,12 @@ async function showIncoming(id, values, deps, route) {
     if (path27.isAbsolute(id) || id.split("/").some((seg) => seg === "..")) {
       throw new CliError("USAGE", `--show-incoming needs a repo-relative doc id or path without '..' segments: ${id}`);
     }
-    let readRef = `refs/remotes/${BOARD_REF}`;
+    const boardBranch = boardBranchOf(top);
+    let readRef = `refs/remotes/${BOARD_REMOTE}/${boardBranch}`;
     let pathPrefix = "";
     let inTreeBundleDir = bundleDirNameForProject(top);
-    if (runGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]).status !== 0) {
-      if (runGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${BOARD_BRANCH}`]).status === 0) {
+    if (runGit(top, ["rev-parse", "--verify", "--quiet", readRef]).status !== 0) {
+      if (runGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${boardBranch}`]).status === 0) {
         throw ffSwallowToError("no-upstream", inv, top);
       }
       const committed = committedBundleAtHead(top);
@@ -30773,7 +30929,7 @@ async function locateBoard(args, cwd) {
     throw new CliError("CONFLICT", "the selected private board has a board-origin rebase pending; run sync first to recover it", { help: `${inv} sync${dirSuffix(args)}` });
   }
   const root = route.kind === "bound-board" ? route.owner.bundleRoot : route.bundle.root;
-  if (repoTopLevel(root) === null || runGit(root, ["rev-parse", "--verify", "--quiet", `refs/remotes/${BOARD_REF}`]).status !== 0) {
+  if (repoTopLevel(root) === null || runGit(root, ["rev-parse", "--verify", "--quiet", `refs/remotes/${boardRefOf(root)}`]).status !== 0) {
     throw new CliError("USAGE", "--inspect and --resolve apply to a shared Git board or a hosted checkout; this bundle is neither, so sync has no conflicts to show", {
       details: { bundle: root },
       help: `${inv} sync --help`
@@ -30842,7 +30998,7 @@ function commandFor(args, choice) {
 }
 async function runInspect(args, board, cwd) {
   const local = await fs10.readFile(board.exportPath);
-  const remote = readDocBytesAtRef(board.root, `refs/remotes/${BOARD_REF}`, board.relPath);
+  const remote = readDocBytesAtRef(board.root, `refs/remotes/${boardRefOf(board.root)}`, board.relPath);
   if (args.out !== void 0) {
     if (remote === null) throw new CliError("NOT_FOUND", `the teammate's side has no version of '${args.id}' to write: it was deleted there`, { details: { id: args.id } });
     const outHelp = `${cliInvocation()} sync --inspect --doc ${commandToken(args.id)} --out <file outside the bundle>`;
@@ -30885,7 +31041,7 @@ async function runInspect(args, board, cwd) {
     file: board.file,
     reason: deleted ? "deleted_remotely" : "changed_remotely",
     local: { version: versionOfBytes(localText), saved_at: board.exportPath, ...preview(localText) },
-    remote: { version: remoteText === null ? null : versionOfBytes(remoteText), ref: `${BOARD_REF} (as of the last fetch)`, ...deleted ? { deleted: true } : {}, ...preview(remoteText) },
+    remote: { version: remoteText === null ? null : versionOfBytes(remoteText), ref: `${boardRefOf(board.root)} (as of the last fetch)`, ...deleted ? { deleted: true } : {}, ...preview(remoteText) },
     ...claimFields(divergence),
     ...differs.length > 0 ? { frontmatter_differs: differs } : {},
     ...args.out !== void 0 ? { remote_written_to: path28.resolve(cwd, args.out) } : {},
@@ -30919,7 +31075,7 @@ async function discardSavedCopy(board) {
 }
 async function runResolve(args, choice, board, cwd) {
   const inv = cliInvocation();
-  const remote = readDocBytesAtRef(board.root, `refs/remotes/${BOARD_REF}`, board.relPath);
+  const remote = readDocBytesAtRef(board.root, `refs/remotes/${boardRefOf(board.root)}`, board.relPath);
   const bundleDir = conflictBundleDir(args.dir, cwd);
   const dirArgs = bundleDir !== void 0 ? ["--dir", bundleDir] : [];
   const local = await fs10.readFile(board.exportPath);
@@ -30965,7 +31121,7 @@ async function runResolve(args, choice, board, cwd) {
     } else if (present !== null && present.equals(remote)) {
       fileState = "unchanged";
     } else {
-      const restored = runGit(board.root, ["restore", `--source=refs/remotes/${BOARD_REF}`, "--worktree", "--", board.relPath]);
+      const restored = runGit(board.root, ["restore", `--source=refs/remotes/${boardRefOf(board.root)}`, "--worktree", "--", board.relPath]);
       if (restored.status !== 0) {
         throw new CliError("RUNTIME", `could not restore the teammate's version of '${args.id}'; your saved copy was kept`, {
           details: { id: args.id, git: restored.stderr.trim() },
@@ -32252,6 +32408,7 @@ __export(sync_exports, {
   SYNC_IN_TREE_CURRENT: () => SYNC_IN_TREE_CURRENT,
   SYNC_IN_TREE_NO_BASIS: () => SYNC_IN_TREE_NO_BASIS,
   SYNC_LOCAL_ONLY_MESSAGE: () => SYNC_LOCAL_ONLY_MESSAGE,
+  SYNC_PUSH_ATTEMPTS: () => SYNC_PUSH_ATTEMPTS,
   SYNC_REMOTE_STATE_UNKNOWN_MESSAGE: () => SYNC_REMOTE_STATE_UNKNOWN_MESSAGE,
   SYNC_USAGE: () => SYNC_USAGE,
   buildConvergeError: () => buildConvergeError,
@@ -32314,7 +32471,11 @@ ${HOSTED_SYNC_USAGE}`));
   }
   if (requestsHostedOnlyVerb(argv2)) throw hostedOnlyVerbError(await targetHome(argv2, deps.cwd ?? process.cwd(), home2), argv2);
   if (requestsConflictVerb(argv2)) {
-    await gitConflictVerb(argv2, deps);
+    try {
+      await gitConflictVerb(argv2, deps);
+    } catch (err) {
+      throw isBoardGitError(err) ? cliErrorFromBoardGit(err) : err;
+    }
     return;
   }
   await sync(argv2, deps);
@@ -32346,6 +32507,7 @@ var init_sync = __esm({
     init_converge();
     init_show_incoming();
     init_sync_outcomes();
+    init_src2();
     init_errors4();
     init_output2();
     init_sync2();
@@ -32654,7 +32816,7 @@ async function gitTurnEnd(dir, home2, partial2, stopHookActive) {
     await run([...dir === void 0 ? [] : ["--dir", dir], "--limit", String(REASON_ROWS), "--json"], () => {
     });
   } catch (error51) {
-    if (error51 instanceof CliError && (error51.code === "CONFLICT" || error51.code === "AUTH_REQUIRED" || error51.details?.reason === "board_moved")) blocking = error51;
+    if (error51 instanceof CliError && (error51.code === "CONFLICT" || error51.code === "GATE_FAILED" || error51.code === "AUTH_REQUIRED" || error51.details?.reason === "board_moved")) blocking = error51;
   }
   if (!blocking) {
     if (await readGitBlock(home2, board.root) !== null) await recordGitBlock(home2, board.root, null).catch(() => {
@@ -34530,6 +34692,9 @@ async function establishBoard(dir, inv, mode, stdout, deps, opts = {}) {
     throw syncOutcomeError("establish.origin-unconfigured", { inv });
   }
   assertNotLinkedWorktree(top, inv);
+  if (currentBranch(top) !== BOARD_BRANCH && resolveStandaloneBoardCheckout(top, { requireRemoteRef: false }) !== null) {
+    return { already: true };
+  }
   const committed = committedBundleAtHead(top);
   if (committed !== null) {
     assertBundleOutsidePrivateState(path31.join(top, committed.bundleDir));
@@ -34598,6 +34763,114 @@ var init_establish = __esm({
   }
 });
 
+// ../cli/src/commands/sync/gate.ts
+import { spawn as spawn4 } from "node:child_process";
+function declaredSyncGate(boardPath) {
+  const configured = runGit(boardPath, ["config", "--get", SYNC_GATE_CONFIG]);
+  const command = configured.status === 0 ? configured.stdout.trim() : "";
+  if (command === "") return null;
+  const timeout = runGit(boardPath, ["config", "--get", SYNC_GATE_TIMEOUT_CONFIG]);
+  const raw = timeout.status === 0 ? timeout.stdout.trim() : "";
+  const seconds = /^\d+$/.test(raw) && Number(raw) > 0 ? Number(raw) : DEFAULT_SYNC_GATE_TIMEOUT_SECONDS;
+  return { command, timeoutSeconds: seconds };
+}
+async function runSyncGate(boardPath, branch, gate, attempt) {
+  const head = currentHead(boardPath);
+  const upstreamSha = resolveOriginRef(boardPath) ?? "";
+  const base = {
+    command: gate.command,
+    attempt,
+    head,
+    upstream: `origin/${branch}`,
+    ...upstreamSha ? { upstream_sha: upstreamSha } : {}
+  };
+  const result3 = await runInOwnGroup(gate.command, boardPath, gate.timeoutSeconds * 1e3, {
+    ...gateBaseEnv(),
+    SUPERBEE_SYNC_GATE: "1",
+    SUPERBEE_BOARD_PATH: boardPath,
+    SUPERBEE_BOARD_BRANCH: branch,
+    SUPERBEE_BOARD_UPSTREAM_REF: `origin/${branch}`,
+    SUPERBEE_BOARD_UPSTREAM_SHA: upstreamSha,
+    SUPERBEE_BOARD_HEAD_SHA: head,
+    SUPERBEE_SYNC_ATTEMPT: String(attempt)
+  });
+  const tail = outputTail(result3.output);
+  const failed = (reason, extra) => ({
+    passed: false,
+    reason,
+    details: { ...base, ...extra, ...tail ? { output_tail: tail } : {} }
+  });
+  if (result3.timedOut) {
+    return failed(`timed out after ${gate.timeoutSeconds}s`, { timed_out: true, timeout_seconds: gate.timeoutSeconds });
+  }
+  if (result3.spawnError) return failed(`could not run (${result3.spawnError})`, { spawn_error: result3.spawnError });
+  if (result3.signal) return failed(`was killed by ${result3.signal}`, { signal: result3.signal });
+  if (result3.status !== 0) return failed(`exited ${result3.status}`, { exit_status: result3.status });
+  const attached = runGit(boardPath, ["symbolic-ref", "-q", "--short", "HEAD"]);
+  if (runGit(boardPath, ["rev-parse", "HEAD"]).stdout.trim() !== head || attached.status !== 0 || attached.stdout.trim() !== branch || countUncommitted(boardPath) > 0) {
+    return failed("changed the board (a gate must only inspect it)", { modified_board: true });
+  }
+  return { passed: true, details: { ...base, exit_status: 0 } };
+}
+function runInOwnGroup(command, cwd, timeoutMs, env) {
+  return new Promise((resolve2) => {
+    let output = "";
+    let timedOut = false;
+    let settled = false;
+    const child = spawn4(command, { cwd, env, shell: true, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const killGroup = () => {
+      if (child.pid === void 0) return;
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {
+      }
+    };
+    const collect = (chunk) => {
+      output += chunk.toString("utf8");
+      if (output.length > OUTPUT_MAX_CHARS) output = output.slice(-OUTPUT_MAX_CHARS);
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup();
+    }, timeoutMs);
+    const finish = (run) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      killGroup();
+      resolve2({ ...run, output, timedOut });
+    };
+    child.on("error", (error51) => finish({ status: null, signal: null, spawnError: error51.code ?? error51.message }));
+    child.on("close", (status2, signal) => finish({ status: status2, signal }));
+  });
+}
+function gateBaseEnv() {
+  const env = { ...process.env };
+  for (const name of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"]) delete env[name];
+  return env;
+}
+function outputTail(output) {
+  const lines = output.replace(/\s+$/, "").split("\n");
+  if (lines.length === 1 && lines[0] === "") return "";
+  return lines.slice(-OUTPUT_TAIL_LINES).join("\n");
+}
+var SYNC_GATE_CONFIG, SYNC_GATE_TIMEOUT_CONFIG, DEFAULT_SYNC_GATE_TIMEOUT_SECONDS, OUTPUT_TAIL_LINES, OUTPUT_MAX_CHARS;
+var init_gate = __esm({
+  "../cli/src/commands/sync/gate.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_src2();
+    SYNC_GATE_CONFIG = "superbee.syncGate";
+    SYNC_GATE_TIMEOUT_CONFIG = "superbee.syncGateTimeoutSeconds";
+    DEFAULT_SYNC_GATE_TIMEOUT_SECONDS = 600;
+    OUTPUT_TAIL_LINES = 40;
+    OUTPUT_MAX_CHARS = 256 * 1024;
+  }
+});
+
 // ../cli/src/bound-board-recovery.ts
 function recoveryFailure(target3, stage, message) {
   return new CliError("CONFLICT", `project binding cannot recover its private board: ${message}`, {
@@ -34799,6 +35072,7 @@ __export(orchestrate_exports, {
   SYNC_IN_TREE_CURRENT: () => SYNC_IN_TREE_CURRENT,
   SYNC_IN_TREE_NO_BASIS: () => SYNC_IN_TREE_NO_BASIS,
   SYNC_LOCAL_ONLY_MESSAGE: () => SYNC_LOCAL_ONLY_MESSAGE,
+  SYNC_PUSH_ATTEMPTS: () => SYNC_PUSH_ATTEMPTS,
   SYNC_REMOTE_STATE_UNKNOWN_MESSAGE: () => SYNC_REMOTE_STATE_UNKNOWN_MESSAGE,
   SYNC_USAGE: () => SYNC_USAGE,
   inTreePullHint: () => inTreePullHint,
@@ -35109,7 +35383,7 @@ async function commitPhase(board, pullOnly2) {
   return commitResult;
 }
 async function pullPhase(run, board, commitResult) {
-  const { boardPath, key: key2, outcome } = board;
+  const { boardPath, outcome } = board;
   if (run.pullOnly) {
     const ff = ffPull(boardPath);
     if (ff.swallowed) {
@@ -35117,7 +35391,11 @@ async function pullPhase(run, board, commitResult) {
     }
     return;
   }
-  const fail4 = (err) => throwPostCommitFailure(withProvisionAnnouncement(err, outcome), commitResult.committed, key2, boardPath);
+  await convergingRebase(run, board, commitResult.committed);
+}
+async function convergingRebase(run, board, committedThisRun) {
+  const { boardPath, key: key2, outcome } = board;
+  const fail4 = (err) => throwPostCommitFailure(withProvisionAnnouncement(err, outcome), committedThisRun, key2, boardPath);
   let rebaseOutcome;
   try {
     rebaseOutcome = fetchRebaseResolving(boardPath, defaultSyncStore.exportsDir(key2));
@@ -35150,29 +35428,94 @@ async function deltaPhase(board, baseline) {
   );
   return { originDelta, changes: [], reanchorNote: REANCHOR_NOTE };
 }
-async function pushPhase(run, board, commitResult, delta) {
-  if (run.pullOnly) return { commits: 0, documents: 0 };
-  const ahead = unpushedCount(board.boardPath) ?? 0;
-  const outgoing = ahead > 0 ? new Set(originDocsBetween(board.boardPath, resolveOriginRef(board.boardPath), currentHead(board.boardPath)).map((change) => change.docId)).size : 0;
-  try {
-    push(board.boardPath);
-    return { commits: ahead, documents: outgoing };
-  } catch (err) {
-    const classified = withSharingDetails(toCliError(err, "push"), { operation: "update-board" });
-    const warning = pushFailureMessage(classified);
-    const partial2 = buildPushFailurePartial(
-      board.outcome,
-      warning,
-      commitResult.docs,
-      delta.originDelta,
-      run.limit,
-      delta.reanchorNote,
-      classified.details
-    );
-    run.stdout(render(withSyncEnvelope(partial2, syncEnvelope("git", { received: delta.originDelta.length })), run.mode));
-    await writeAwarenessCache(board.key, board.boardPath, delta.changes, delta.reanchorNote);
-    throw asHandled(new CliError(classified.code, warning, { details: classified.details }));
-  }
+function raceBackoffMs(attempt) {
+  return Math.floor(250 * attempt + Math.random() * 750 * attempt);
+}
+async function pushPhase(run, board, commitResult, delta, baseline) {
+  if (run.pullOnly) return { commits: 0, documents: 0, delta };
+  const gate = declaredSyncGate(board.boardPath);
+  const branch = boardBranchOf(board.boardPath);
+  let gateDetails;
+  for (let attempt = 1; ; attempt += 1) {
+    const head = currentHead(board.boardPath);
+    const counted = unpushedCount(board.boardPath);
+    const ahead = counted ?? 0;
+    const outgoing = ahead > 0 ? new Set(originDocsBetween(board.boardPath, resolveOriginRef(board.boardPath), head).map((change) => change.docId)).size : 0;
+    if (gate && (counted === null || ahead > 0)) {
+      const judged = await runSyncGate(board.boardPath, branch, gate, attempt);
+      if (!judged.passed) await failGate(run, board, commitResult, delta, judged.reason ?? "failed", judged.details);
+      gateDetails = judged.details;
+    }
+    try {
+      push(board.boardPath, head, branch);
+      return { commits: ahead, documents: outgoing, delta, ...gateDetails ? { gate: gateDetails } : {} };
+    } catch (err) {
+      const classified = withSharingDetails(toCliError(err, "push"), { operation: "update-board" });
+      const raced = classified.code === "TRANSIENT" && classified.details?.reason === "non-fast-forward";
+      if (raced && attempt < SYNC_PUSH_ATTEMPTS) {
+        await new Promise((resolve2) => setTimeout(resolve2, raceBackoffMs(attempt)));
+        if (boardBranchOf(board.boardPath) !== branch) {
+          throw new CliError("CONFLICT", `the board checkout left '${branch}' during sync; nothing more was pushed`, {
+            details: { state: "board-branch-moved", branch },
+            help: `check out '${branch}' in ${board.boardPath}, then ${run.inv} sync`
+          });
+        }
+        await convergingRebase(run, board, commitResult.committed);
+        refuseMovedBoard(board.boardPath);
+        delta = await deltaPhase(board, baseline);
+        holdMalformedCommitted(run, board, delta);
+        continue;
+      }
+      const details = raced ? { ...classified.details, attempts: attempt } : classified.details;
+      const exhausted = raced ? new CliError(
+        classified.code,
+        `another writer pushed to the board each time sync tried (${attempt} attempts, each re-fetched and rebased${gate ? " and re-gated" : ""}) \u2014 re-run sync to try again`,
+        { details }
+      ) : classified;
+      const warning = pushFailureMessage(exhausted);
+      const partial2 = buildPushFailurePartial(
+        board.outcome,
+        warning,
+        commitResult.docs,
+        delta.originDelta,
+        run.limit,
+        delta.reanchorNote,
+        details
+      );
+      run.stdout(render(withSyncEnvelope(partial2, syncEnvelope("git", { received: delta.originDelta.length })), run.mode));
+      await writeAwarenessCache(board.key, board.boardPath, delta.changes, delta.reanchorNote);
+      throw asHandled(new CliError(exhausted.code, warning, { details }));
+    }
+  }
+}
+function holdMalformedCommitted(run, board, delta) {
+  const originRef = resolveOriginRef(board.boardPath);
+  if (originRef === null) return;
+  const held2 = malformedCommittedDocuments(board.boardPath, originRef, "HEAD");
+  if (held2.length > 0) reportHeld(run, board, delta, held2, "committed locally");
+}
+async function failGate(run, board, commitResult, delta, reason, details) {
+  const warning = `committed to the board locally \u2014 your work is saved. The sync gate ${reason} on the rebased board, so nothing was pushed; fix what it reports, then re-run sync`;
+  const help2 = `run the gate yourself from ${board.boardPath} (git config --get ${SYNC_GATE_CONFIG}), fix what it reports, then ${run.inv} sync`;
+  const partial2 = buildPushFailurePartial(
+    board.outcome,
+    warning,
+    commitResult.docs,
+    delta.originDelta,
+    run.limit,
+    delta.reanchorNote,
+    { gate: details }
+  );
+  partial2.code = "GATE_FAILED";
+  partial2.help = help2;
+  const envelope2 = syncEnvelope("git", { received: delta.originDelta.length, next: [`${run.inv} sync`] });
+  run.stdout(render(withSyncEnvelope(partial2, envelope2), run.mode));
+  await writeAwarenessCache(board.key, board.boardPath, delta.changes, delta.reanchorNote);
+  throw new CliError("GATE_FAILED", `the sync gate ${reason}; nothing was pushed`, {
+    help: help2,
+    details: { gate: details },
+    handled: true
+  });
 }
 async function receiptPhase(run, board, commitResult, delta, pushed, establishAlreadyNote) {
   await writeAwarenessCache(board.key, board.boardPath, delta.changes, delta.reanchorNote);
@@ -35187,6 +35530,7 @@ async function receiptPhase(run, board, commitResult, delta, pushed, establishAl
     reanchorNote: delta.reanchorNote,
     hookHint
   });
+  if (pushed.gate) receipt3.gate = `passed: ${String(pushed.gate.command)} (attempt ${String(pushed.gate.attempt)})`;
   run.stdout(render(withSyncEnvelope(receipt3, syncEnvelope("git", { sent: pushed.documents, received: delta.originDelta.length })), run.mode));
 }
 async function heldRun(run, board, baseline, held2) {
@@ -35279,15 +35623,11 @@ async function syncCommand(argv2, deps = {}) {
   await pullPhase(run, board, commitResult);
   if (!run.pullOnly) refuseMovedBoard(board.boardPath);
   const delta = await deltaPhase(board, baseline);
-  const originRef = run.pullOnly ? null : resolveOriginRef(board.boardPath);
-  if (originRef !== null) {
-    const held2 = malformedCommittedDocuments(board.boardPath, originRef, "HEAD");
-    if (held2.length > 0) reportHeld(run, board, delta, held2, "committed locally");
-  }
-  const pushed = await pushPhase(run, board, commitResult, delta);
-  await receiptPhase(run, board, commitResult, delta, pushed, establishAlreadyNote);
+  if (!run.pullOnly) holdMalformedCommitted(run, board, delta);
+  const pushed = await pushPhase(run, board, commitResult, delta, baseline);
+  await receiptPhase(run, board, commitResult, pushed.delta, pushed, establishAlreadyNote);
 }
-var SYNC_USAGE, DEFAULT_LIMIT, SYNC_LOCAL_ONLY_MESSAGE, SYNC_REMOTE_STATE_UNKNOWN_MESSAGE, SYNC_IN_TREE_BOARD_LINE, SYNC_IN_TREE_NO_BASIS, SYNC_IN_TREE_CURRENT;
+var SYNC_USAGE, DEFAULT_LIMIT, SYNC_LOCAL_ONLY_MESSAGE, SYNC_REMOTE_STATE_UNKNOWN_MESSAGE, SYNC_IN_TREE_BOARD_LINE, SYNC_IN_TREE_NO_BASIS, SYNC_IN_TREE_CURRENT, SYNC_PUSH_ATTEMPTS;
 var init_orchestrate = __esm({
   "../cli/src/commands/sync/orchestrate.ts"() {
     "use strict";
@@ -35302,6 +35642,7 @@ var init_orchestrate = __esm({
     init_establish();
     init_converge();
     init_show_incoming();
+    init_gate();
     init_sync_outcomes();
     init_errors4();
     init_args();
@@ -35349,6 +35690,11 @@ board changes.
 The same verb also works when an automation or chat agent clones the shared \`board\` branch as
 the repository root: a tracked OKF root index plus the exact attached \`board\` branch identifies
 that standalone checkout, so sync operates there directly and never creates a nested bundle.
+A repository can carry more than one board: a NAMED board lives on its own \`board-<name>\` branch
+(lowercase letters, digits and hyphens) whose root commits \`.superbee-board.json\` containing
+\`{"schema": 1, "branch": "board-<name>"}\`. A standalone clone of that branch, tracking
+\`origin/board-<name>\`, syncs exactly as above against \`origin/board-<name>\` and never touches
+\`origin/board\`; the conventional \`.superbee\` worktree always uses \`board\`.
 \`--establish\` on an already-established project is a safe no-op that notes \`already established\`
 and proceeds as an ordinary sync.
 
@@ -35392,7 +35738,25 @@ any error envelope) on stderr. A doc absent upstream renders as an expected stat
 
 If the push fails after a local commit already landed (offline, revoked/expired credentials, or a
 locked repository), the receipt still reports what committed/pulled successfully \u2014 your work is
-saved locally either way, and re-running sync retries the push.
+saved locally either way, and re-running sync retries the push. A push that loses a race to
+another writer (non-fast-forward, including the remote's "incorrect old value" refusal) is not a
+permission problem: sync re-fetches, rebases with the same converging mechanic, re-runs the gate,
+and pushes again, up to 5 attempts in all, then exits 1 with \`details.reason: non-fast-forward\`.
+
+A clone can declare a SYNC GATE: a command sync runs on the converged tree after rebasing onto
+the remote board and before every push that sends commits (\`git config superbee.syncGate
+'<command>'\`, any Git config scope; an empty value declares none; \`superbee.syncGateTimeoutSeconds\`
+overrides the 600s timeout). It runs through the shell from the board root with
+SUPERBEE_BOARD_BRANCH, SUPERBEE_BOARD_UPSTREAM_REF, SUPERBEE_BOARD_UPSTREAM_SHA (the remote tip
+rebased onto), SUPERBEE_BOARD_HEAD_SHA (what would be pushed) and SUPERBEE_SYNC_ATTEMPT set. A
+non-zero exit, a timeout, or any edit to the board holds the push: the work stays committed
+locally and sync exits 5 with code GATE_FAILED and the gate's last output lines. Exactly the
+judged commit is pushed. The command comes from Git configuration, never from board files, so
+board content cannot choose the command; keep the gate's code outside the board too (a script
+inside the board runs whatever a teammate last pushed). A gate must leave the board as it found
+it: an untracked, non-ignored file it writes counts as an edit. The opt-in turn-end sync runs
+the gate as well, inside the agent host's hook time limit, so keep a gate fast there.
+\`--pull-only\` never runs it, and neither does \`--establish\`'s first publication of a board.
 
 A board can also ride IN-TREE: \`.superbee/\` or legacy \`.agentstate-lite/\` committed WITH the code on the current
 branch, with no dedicated \`board\` branch anywhere. That is a supported, read-side mode \u2014 sync
@@ -35462,6 +35826,7 @@ Options:
     SYNC_IN_TREE_BOARD_LINE = syncInTreeBoardLine(BUNDLE_DIR);
     SYNC_IN_TREE_NO_BASIS = "no-comparison-basis";
     SYNC_IN_TREE_CURRENT = "checkout is current with upstream";
+    SYNC_PUSH_ATTEMPTS = 5;
   }
 });
 
@@ -83884,6 +84249,9 @@ bundle's compatible storage coordinate through each document's declared Kind.
 
 // ../cli/src/kind-draft.ts
 import { createHash as createHash15 } from "node:crypto";
+function excludedInferenceField(field) {
+  return EXCLUDED_FIELDS.has(field) || isManagedDocumentMetadataField(field) || field.startsWith("superbee_") && field !== SUPERBEE_PROGRESS_STATUS_FIELD;
+}
 function kindDeclaresAnything(kind2) {
   return Object.values(DECLARES).some((declares) => declares(kind2));
 }
@@ -83934,7 +84302,7 @@ function inferKindCandidate(type, instances, stats = collectInstanceStats(instan
   const optional2 = [];
   const values = {};
   for (const [key2, present] of Object.entries(stats.keyPresence)) {
-    if (EXCLUDED_FIELDS.has(key2)) continue;
+    if (excludedInferenceField(key2)) continue;
     if (present === count5 && count5 > 0) {
       required2.push(key2);
       if (count5 >= ENUM_MIN_INSTANCES && everyValueScalarString(instances, key2)) {
@@ -84010,7 +84378,7 @@ var init_kind_draft = __esm({
     ENUM_MIN_DISTINCT = 2;
     ENUM_MAX_DISTINCT = 6;
     SECTION_PROMOTION_FLOOR = 0.6;
-    EXCLUDED_FIELDS = /* @__PURE__ */ new Set([...RESERVED_KIND_FIELD_NAMES, SUPERBEE_UPDATED_BY_FIELD]);
+    EXCLUDED_FIELDS = /* @__PURE__ */ new Set([...RESERVED_KIND_FIELD_NAMES, "head_version"]);
     FIELDS_DECLARES = {
       required: (f2) => f2.required.length > 0,
       optional: (f2) => f2.optional.length > 0,
@@ -84147,9 +84515,9 @@ function renderKindHelp(kind2, registry2, inv) {
 ${sectionLines}
 ` + linksBlock + `${pathLine}
 
-Repeat a flag to set an array value (e.g. --tag a --tag b). Validation is STRICT.
+Repeat a flag to set an array value (e.g. --tag a --tag b). Validation is STRICT; violations reject without creating a document.
 ` + (req.includes("timestamp") || opt.includes("timestamp") ? `In OKF v0.2, --timestamp requires a real ISO-8601 date and time with an explicit UTC offset (Z or numeric).
-` : "") + `To ADD a field to this kind, edit its convention doc (${inv} kinds names it; then pull \u2192 edit fields.optional \u2192 promote).
+` : "") + `To ADD a field: ${inv} kind field ${commandToken(kind2.governs)} add <name> [--required] [--values <a,b,c>].
 
 Options:
   --stale-after <iso>  Expiration instant (OKF v0.2 only); valid date, time, and zone required
@@ -85937,7 +86305,7 @@ async function prepareRecipeEvolution(bundle, sourceRecipe) {
           id: doc2.id,
           current_version: contentVersion(doc2)
         });
-        for (const warning of validateAgainstKind(doc2, kind2)) {
+        for (const warning of projectKindValidationWarnings(okfVersion, kind2, validateAgainstKind(doc2, kind2))) {
           evolutionBlocker(
             blockers,
             "RECIPE_EVOLUTION_INSTANCE_INVALID",
@@ -86555,9 +86923,9 @@ async function status(argv2, deps = {}) {
   for (const doc2 of docs) {
     const kind2 = registry2.kinds.get(docType2(doc2));
     if (!kind2) continue;
-    for (const w2 of validateAgainstKind(doc2, kind2)) {
+    for (const w2 of projectKindValidationWarnings(okfVersion, kind2, validateAgainstKind(doc2, kind2))) {
       lintRows.push({ id: doc2.id, field: w2.field ?? "", code: w2.code });
-      if (FRONTMATTER_VIOLATION_CODES.has(w2.code) && !conformanceDebtDocs.has(doc2.id)) {
+      if (isKindFieldValidationWarning(w2) && !conformanceDebtDocs.has(doc2.id)) {
         conformanceDebtDocs.set(doc2.id, docType2(doc2));
       }
     }
@@ -86856,7 +87224,7 @@ async function status(argv2, deps = {}) {
   }
   stdout(render({ home: "local", sync: "none (local only)", ...unboundCopyOf(facts), ...out }, resolveMode(values)));
 }
-var STATUS_USAGE, DEFAULT_LIMIT3, FRONTMATTER_VIOLATION_CODES;
+var STATUS_USAGE, DEFAULT_LIMIT3;
 var init_status2 = __esm({
   "../cli/src/commands/status.ts"() {
     "use strict";
@@ -87037,7 +87405,6 @@ Options:
   -h, --help              Show this help
 `;
     DEFAULT_LIMIT3 = 20;
-    FRONTMATTER_VIOLATION_CODES = /* @__PURE__ */ new Set(["KIND_FIELD_MISSING", "KIND_FIELD_VALUE", "KIND_FIELD_ARITY"]);
   }
 });
 
@@ -125254,9 +125621,9 @@ function manifestContent(assets) {
   return `${JSON.stringify(manifest, null, 2)}
 `;
 }
-function unmanagedExtras(dir, managed2) {
+function unmanagedExtras(dir, managed) {
   return listFilesRelative(dir).filter(
-    (f2) => f2 !== SKILL_MANIFEST_FILENAME && !managed2.has(f2) && !isManagedDebris(f2, managed2)
+    (f2) => f2 !== SKILL_MANIFEST_FILENAME && !managed.has(f2) && !isManagedDebris(f2, managed)
   );
 }
 function isDirectory(p2) {
@@ -125304,10 +125671,10 @@ function preflightInstallIntoDir(dir, assets) {
           reason: `installed skill uses newer compatibility contract ${manifest.compatibility_contract}; running CLI contract ${assets.compatibilityContract} will not downgrade it`
         };
       }
-      const managed2 = /* @__PURE__ */ new Set([...manifest.files, ...assets.files, SKILL_MANIFEST_FILENAME]);
-      const obstructed = directoryObstructions(dir, managed2);
+      const managed = /* @__PURE__ */ new Set([...manifest.files, ...assets.files, SKILL_MANIFEST_FILENAME]);
+      const obstructed = directoryObstructions(dir, managed);
       if (obstructed.length > 0) return directoryObstructionRefusal(obstructed);
-      const extras = unmanagedExtras(dir, managed2);
+      const extras = unmanagedExtras(dir, managed);
       if (extras.length > 0) {
         return {
           ok: false,
@@ -125396,10 +125763,10 @@ function preflightUninstallFromDir(dir) {
   if (manifest === null) {
     return { ok: false, reason: `${SKILL_MANIFEST_FILENAME} does not prove ownership \u2014 refusing to delete anything from a folder in an unknown state` };
   }
-  const managed2 = /* @__PURE__ */ new Set([...manifest.files, SKILL_MANIFEST_FILENAME]);
-  const obstructed = directoryObstructions(dir, managed2);
+  const managed = /* @__PURE__ */ new Set([...manifest.files, SKILL_MANIFEST_FILENAME]);
+  const obstructed = directoryObstructions(dir, managed);
   if (obstructed.length > 0) return directoryObstructionRefusal(obstructed);
-  const extras = unmanagedExtras(dir, managed2);
+  const extras = unmanagedExtras(dir, managed);
   if (extras.length > 0) {
     return {
       ok: false,
@@ -126863,12 +127230,12 @@ function runPassiveUpdateOrientation(deps = {}) {
     releaseActiveUpdateLease(home2, claimed.lease.token);
     return void 0;
   }
-  const spawn4 = deps.spawn ?? ((command, argv2, options) => currentHost().spawnChild(command, argv2, options));
+  const spawn5 = deps.spawn ?? ((command, argv2, options) => currentHost().spawnChild(command, argv2, options));
   if (!activeLeaseAuthority(home2, claimed.lease.token, now())) {
     return void 0;
   }
   try {
-    const child = spawn4(
+    const child = spawn5(
       process.execPath,
       [entry, "__update-refresh-v1", claimed.lease.token],
       { detached: true, stdio: "ignore" }